如何針對 Amazon RDS for PostgreSQL 或 Aurora PostgreSQL 相容版本中的主要版本升級問題進行疑難排解？

簡短說明

次要版本升級與相同主要版本先前和之後的小型發佈版本相容。但是，主要版本升級包含的資料庫變更，不會與現有應用程式向下相容。這些升級可能會改變系統表格、資料檔和資料儲存的內部格式。Amazon RDS 使用 pg_upgrade 來執行主要版本升級。如需詳細資訊，請參閱 PostgreSQL 網站上的 pg_upgrade。

在主要版本升級期間，Amazon RDS 會執行預先檢查程序，以識別可能導致升級失敗的問題。它會檢查整個資料庫中是否存在潛在不相容的條件。如果 Amazon RDS 在預先檢查過程中識別出問題，則會為失敗的預檢查建立日誌事件。日誌事件包括檔案名稱、時間戳記以及升級失敗的原因。如需有關所有資料庫的預先檢查程序的資訊，請檢查 pg_upgrade_precheck.log 日誌。但是，對於引擎特定的問題，您必須檢查 Amazon RDS for PostgreSQL 或 Aurora PostgreSQL 的資料庫日誌檔。

解決方法

執行主要版本升級的 pg_upgrade 公用程式會產生兩個日誌：pg_upgrade_internal.log 和 pg_upgrade_server.log。Amazon RDS 會將時間戳記附加至這些日誌的檔案名稱。檢視這些日誌，以取得有關升級期間遇到的問題和錯誤詳細資訊。如需詳細資訊，請參閱監控 Amazon RDS 日誌檔或監控 Amazon Aurora 日誌檔。

升級需要很長時間

檢查是否有待處理的維護活動

Amazon RDS 會自動使用引擎版本升級，以套用待處理的維護活動，例如在 RDS 執行個體上的作業系統 (OS) 修補程式。Amazon RDS 會先套用待處理活動，然後再升級引擎版本。如果 Amazon RDS 必須執行作業系統維護活動，則升級需要更長時間。

如果您的 RDS 執行個體位於多可用區域部署中，則作業系統維護會導致容錯移轉。當您在多可用區域中設定執行個體時，Amazon RDS 通常會在次要執行個體上建立執行個體的備份。在容錯移轉中，Amazon RDS 會在升級後於新的次要執行個體上建立備份。新次要執行個體上的此備份可能不是最新的備份，因此 Amazon RDS 會完成完整備份，而不是增量備份。完整備份可能需要很長時間，尤其是如果數據庫很大。

若要避免此問題，請搜尋 RDS 資料庫執行個體或 Aurora 資料庫執行個體的待處理維護活動。或者，在執行個體上執行下列 AWS Command Line Interface (AWS CLI) describe-pending-maintenance-actions 命令：

aws rds describe-pending-maintenance-actions --resource-identifier example-arn

注意： 使用資料庫執行個體 ARN 取代 example-arn。如果您在執行 AWS CLI 命令時收到錯誤，請參閱對 AWS CLI 錯誤進行疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

執行資料庫引擎版本升級之前，完成待處理的維護活動。

在升級之前建立快照

最佳實務是在升級版本之前，建立 RDS 資料庫執行個體或 Aurora 資料庫叢集的快照。如果您已開啟執行個體的備份功能，Amazon RDS 會自動建立快照作為升級程序的一部分。使用快照，您可以縮短升級程序時間，因為 Amazon RDS 只需要在升級的一部分建立增量備份。

等待讀取複本升級

當您執行主要資料庫執行個體的主要版本升級時，Amazon RDS 會自動升級同一 AWS 區域中的所有讀取複本。升級工作流程開始後，讀取複本會等待 pg_upgrade 在主要資料庫執行個體上成功完成。然後，主要資料庫執行個體升級會等待讀取的複本升級完成。在所有升級完成之前遭遇到中斷。如果升級的停機時段很短，請升級或捨棄讀取複本執行個體，然後在升級完成後重新建立讀取複本。

對於 Aurora 資料庫叢集，pg_upgrade 會先升級寫入器執行個體。然後，每個讀取器資料庫執行個體在 pg_upgrade 將其升級到新的主要版本時遭遇中斷。請注意，如果您升級 Aurora 全球資料庫，則會有其他需求和程序。

在升級之前解決長時間執行的交易或高工作負載

長時間執行的交易或高工作負載可能會增加 Amazon RDS 關閉資料庫和升級資料庫引擎所需的時間。

若要識別長時間執行的交易，請執行下列查詢：

SQL>SELECT pid, datname, application_name, state, age(query_start, clock_timestamp()), usename, query
FROM pg_stat_activity
WHERE query NOT ILIKE '%pg_stat_activity%' AND
usename!='rdsadmin'
ORDER BY query_start desc;

如果您識別長時間執行的查詢，請使用 pg_cancel_backend 或 pg_terminate_backend 結束查詢。如需有關這些功能的詳細資訊，請參閱 9.28.2。伺服器訊號功能。

請確保您擁有足夠的運算容量

pg_upgrade 公用程式可能會使用密集運算。最佳實務是在升級生產資料庫之前執行試運行升級，以檢查您是否具有足夠的運算或記憶體容量。試運行升級還會檢查您是否會遇到預先檢查或升級錯誤。您可以還原生產執行個體的快照，並使用與生產資料庫相同的執行個體類別執行試運行。

升級失敗

檢查不支援的資料庫執行個體類別

如果資料庫執行個體的執行個體類別，與您要升級的 PostgreSQL 版本不相容，則會升級失敗。檢查引擎版本與 Amazon RDS 或 Amazon Aurora 執行個體類別的相容性。

檢查已開放的已就緒交易

如果資料庫上有開放的已就緒交易，則會升級失敗。您會在 pg_upgrade.log 檔案中，收到有未認可的已就緒交易錯誤。在開始升級之前，請認可或復原所有開放的已就緒交易。

若要檢查執行個體上是否有開放的已就緒交易，請執行下列查詢：

SELECT count(*) FROM pg_catalog.pg_prepared_xacts;

確定您使用支援的資料類型

您只能升級 regclass、regrole 和 regtype 資料類型的版本。pg_upgrade 公用程式無法升級包含使用 reg* 物件識別碼 (OID) 參考類型表格欄的資料庫。如果您使用 regcollation、regconfig、regdictionary、regnamespace、regoper、regoperator、regproc 或 regprocedure 資料類型，則會升級失敗。

若要解決此問題，請先移除除 regclass、regrole 和 regtype 之外，reg* 資料類型的所有用途，再升級資料引擎。若要檢查表格中不支援的 reg* 資料類型，請執行下列查詢。

SELECT count(*) FROM pg_catalog.pg_class c, pg_catalog.pg_namespace n, pg_catalog.pg_attribute a  WHERE c.oid = a.attrelid
      AND NOT a.attisdropped
      AND a.atttypid IN ('pg_catalog.regproc'::pg_catalog.regtype,
                         'pg_catalog.regprocedure'::pg_catalog.regtype,
                         'pg_catalog.regoper'::pg_catalog.regtype,
                         'pg_catalog.regoperator'::pg_catalog.regtype,
                         'pg_catalog.regconfig'::pg_catalog.regtype,
                         'pg_catalog.regdictionary'::pg_catalog.regtype)
      AND c.relnamespace = n.oid
      AND n.nspname NOT IN ('pg_catalog', 'information_schema');

檢查邏輯複寫插槽

如果您的執行個體具有邏輯複寫插槽，則無法升級執行個體，而且會在 pg_upgrade.log 檔案中收到下列錯誤：

"The instance could not be upgraded because one or more databases have logical replication slots.Please drop all logical replication slots and try again." (無法升級執行個體，因為一個或多個資料庫具有邏輯複寫插槽。請捨棄所有邏輯複製插槽，然後再試一次。)

邏輯複寫插槽通常用於AWS Database Migration Service (AWS DMS) 遷移。它們還用於將資料庫中的表格複製到資料湖、商業智慧工具和其他目標。確保您知道正在使用的邏輯複寫插槽的目的，以檢查是否可以刪除它們。如果邏輯複寫插槽正在使用中，請勿刪除它們。您必須等待版本升級，直到您可以刪除邏輯複寫插槽。

如果您不需要邏輯複寫插槽，請執行下列查詢以刪除它們：

SELECT * FROM pg_replication_slots;

SELECT pg_drop_replication_slot(slot_name);

注意： 用邏輯複製插槽的名稱取代 slot_name。

檢查儲存問題

如果 pg_upgrade 指令碼執行時執行個體空間不足，則會升級失敗，且您會收到下列錯誤：

"pg_restore: [archiver (db)] Error while PROCESSING TOC: pg_restore: [archiver (db)] could not execute query: ERROR: could not create file "base/12345/12345678": No space keyword" left on device" (pg_restore: [archiver (db)] 處理 TOC 時發生錯誤：pg_restore: [archiver (db)] 無法執行查詢：錯誤：無法創建檔案「base/12345/12345678」：沒有空格關鍵字」留存於設備上)

若要解決此問題，請在開始升級之前，確定執行個體具有足夠的可用儲存空間。

檢查未知的資料類型

您無法在 PostgreSQL 版本 10 及更高版本中，使用未知的資料類型。例如，如果 PostgreSQL 版本 9.6 資料庫使用未知的資料類型，則升級至版本 10 時，您會收到下列錯誤：

"The instance could not be upgraded because the 'unknown' data type is used in user tables.Please remove all usages of the 'unknown' data type and try again." (無法升級執行個體，因為使用者表格中使用了「未知」資料類型。請移除「未知」資料類型的所有使用，然後再試一次。)

若要解決此問題，請手動移除使用未知資料類型的資料欄，或將其修改為支援的資料類型。若要尋找資料庫中使用未知資料類型的資料欄，請執行下列查詢：

SELECT DISTINCT data_type FROM information_schema.columns WHERE data_type ILIKE 'unknown';

(僅適用於 PostgreSQL 的 RDS) 檢查是否存在讀取複本升級失敗

如果 PostgreSQL 執行個體具有讀取複本，則讀取複本升級失敗可能會導致主執行個體升級卡住或失敗。Amazon RDS 將失敗的讀取複本設定為不相容的還原狀態，然後停止在資料庫執行個體上的複製。

讀取複本升級可能會因下列其中一個原因而失敗：

• 即使在等待時間後，讀取複本也無法跟上主要資料庫執行個體。
• 讀取複本處於終端或不相容的生命週期狀態，例如儲存空間已滿或不相容的還原。
• 當主要資料庫執行個體升級開始時，讀取複本上執行了個別的次要版本升級。
• 讀取複本使用不相容的參數。
• 讀取複本無法與主要資料庫執行個體通訊，以同步資料夾。

若要解決此問題，請刪除讀取複本。然後在升級後，根據升級的主要執行個體重新建立新的讀取複本。

確保您的主要使用者名稱正確

如果主要使用者名稱以 pg_ 開頭，則會升級失敗，且您會收到下列錯誤訊息：

"PreUpgrade checks failed: The instance could not be upgraded because one or more role names start with 'pg_'.Please rename all roles with names that start with 'pg_' and try again". (升級前檢查失敗：無法升級執行個體，因為一個或多個角色名稱以「pg_」開頭。請重新命名以「pg_」開頭的所有角色，然後再試一次。)

若要解決此問題，請建立另一個使用者，其具有 rds_superuser 角色，且並非以 pg_ 開頭。

檢查不相容的參數

當記憶體相關參數的值對於您的設定來說太高 (例如 shared_buffer 或 work_memory)，就會發生不相容的參數錯誤。此錯誤會導致升級指令碼失敗。若要解決此問題，請減少這些參數的值，然後重新執行升級。

在升級之前更新您的擴充功能

主要版本升級不會升級 PostgreSQL 擴充功能。如果在主要版本升級之前沒有更新擴充功能，則 pg_upgrade.log 檔案中會收到類似下列範例的錯誤：

"The Logs indicates that the RDS instance ''abcd'' has older version of PostGIS extension or its dependent extensions (address_standardizer,address_standardizer_data_us, postgis_tiger_geocoder, postgis_topology, postgis_raster) installed as against the current version required for the upgrade." (日誌顯示 RDS 執行個體「abcd」具有較舊版本的 PostGIS 擴充功能或其安裝的相依擴充功能 (address_standardizer、address_standardizer_data_us、postgis_tiger_geocoder、postgis_topology、postgis_raster) 與升級所需的目前版本衝突。)

上述的範例錯誤顯示了 PostGIS 擴充功能的問題。若要解決此問題，請執行下列查詢以檢查 PostGIS 及其相依擴充功能的預設版本和已安裝版本：

SELECT name, default_version, installed_versionFROM pg_available_extensions WHERE installed_version IS NOT NULL AND
name LIKE 'postgis%' OR name LIKE 'address%';

注意： 用擴充功能取代 postgis%。

如果 installed_version 的值小於default_version 的值，則必須將 PostGIS 更新為預設版本。若要升級擴充功能，請執行下列查詢：

ALTER EXTENSION extension_name UPDATE TO 'default_version_number';

注意： 用 default_version 值取代 default_version_number 值。

如需詳細資訊，請參閱 [PostgreSQL 資料庫引擎的 RDS 升級 或 升級 Amazon Aurora PostgreSQL 資料庫叢集](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.PostgreSQL.html#USER_UpgradeDBInstance.Upgrading.ExtensionUpgrades)。

檢查視觀表中是否有因目標版本的系統目錄變更所造成的問題

在特定視觀表中的資料欄會因不同 PostgreSQL 版本而有所不同。例如，您可能會收到類似下列範例的錯誤：

"PreUpgrade checks failed: The instance could not be upgraded because one or more databases have views or materialized views which depend on 'pg_stat_activity'.Please drop them and try again." (升級前檢查失敗：無法升級執行個體，因為一個或多個資料庫具有視觀表或具體化視觀表，這些視觀表取決於 「pg_stat_activity」。請刪除它們並再試一次。)

當您將資料庫從版本 9.5 升級至 9.6 時，會發生此錯誤。上述的範例中，pg_stat_activity 視觀表正在導致此問題。在版本 9.6 中，PostgreSQL 用 wait_event_type 和 wait_event 資料欄取代 waiting 資料欄。

或您可能會收到類似下列內容的錯誤：

"pg_restore: from TOC entry abc; abc abcd VIEW sys_user_constraints art pg_restore: error: could not execute query: ERROR: column c.consrc does not exist LINE 18: "c"."consrc" AS "search_condition", ^ HINT: Perhaps you meant to reference the column "c.conkey" or the column "c.conbin"." (pg_restore: 從 TOC 項目 abc; abc abcd 視觀表 sys_user_constraints art pg_restore: error：無法執行查詢：錯誤：資料欄 c.consrc 不存在 LINE 18:「c」.「consrc」為「search_condition」, ^ 提示：也許您預期參照資料欄「c.conkey」或資料欄「c.conbin」。)

在此範例中，發生錯誤是因為 pg_constraint 目錄的結構在 PostgreSQL 版本 12 中已變更。

若要解決這些問題，請根據目標版本的系統目錄捨棄視觀表。

重要： 最佳實務是在捨棄視觀表之前，使用 pgdump 備份您的視觀表或擷取視觀表的定義。當您捨棄視觀表時，您需要在版本升級後手動重新建立視觀表。您可能需要與資料庫管理員合作。

升級後

升級完成後，在所有使用者資料庫上執行 ANALYZE 以升級 pg_statistics 表格。主要升級不會將 pg_statistics 表的內容移到新版本。如果您沒有移動內容，則可能會遇到慢速執行查詢。

相關資訊

Aurora PostgreSQL 升級程序概述