如何排解 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 相容版的資料庫日誌檔案。

解決方法

如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤訊息，請參閱「對 AWS CLI 錯誤進行疑難排解」。此外，請確定您使用的是最新的 AWS CLI 版本。

執行主要版本升級的 pg_upgrade 公用程式會產生 pg_upgrade_internal.log 日誌和 pg_upgrade_server.log 日誌。Amazon RDS 會將時間戳記附加到這些日誌的檔案名稱。請查看日誌，以取得升級期間遇到的問題和錯誤的詳細資訊。詳情請參閱「監控 Amazon RDS 日誌檔案」或 “Monitoring Amazon Aurora log files” (監控 Amazon Aurora 日誌檔案)。

長期升級

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

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

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

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

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

**注意：**請將 example-arn 替換成您的資料庫執行個體 ARN。

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

在升級之前建立快照

在升級版本之前，建議先建立 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 結束交易。如需更多 pg_cancel_backend 和 pg_terminate_backend 的資訊，請參閱 PostgreSQL 網站上的伺服器訊號函式說明。

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

pg_upgrade 公用程式可能需要進行大量運算。為了確認運算資源、記憶體和可用儲存空間是否足夠，建議在將正式環境資料庫升級前，先執行測試升級。測試升級也會檢查您是否會遇到預先檢查或升級錯誤。您可以還原正式環境執行個體的快照，並使用與正式環境資料庫相同的執行個體類別執行測試。

升級失敗

檢查是否有不支援的資料庫執行個體類別和引擎版本

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

如要確認哪些引擎版本符合升級的相容要求，請執行以下 describe-db-engine-versions 命令：

aws rds describe-db-engine-versions --engine postgres --engine-version your-version --query "DBEngineVersions[].ValidUpgradeTarget[].{EngineVersion:EngineVersion}" --output text

**注意：**請將 your-version 替換成您的引擎版本。

如果您目前的版本不相容，建議升級到最新的次要版本。或者，您可以升級到其他可用的升級版本。如需引擎版本升級的資訊，請參閱 “Choosing a major version for an RDS for PostgreSQL upgrade” (為 RDS for PostgreSQL 升級選擇主要版本)。

檢查是否有進行中的已就緒交易

如果資料庫上有進行中的已就緒交易，升級便會失敗。您會在 pg_upgrade.log 檔案中，收到 "There are uncommitted prepared transactions" 錯誤訊息。在開始升級之前，請認可或復原所有進行中的已就緒交易。

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

SELECT count(*) FROM pg_catalog.pg_prepared_xacts;

使用支援的資料類型

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

若要解決此問題，請在升級資料引擎之前移除所有 reg* 資料類型 (regclass、regrole 和 regtype 除外)。若要檢查資料表中是否含有不支援的 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"

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

檢查是否有 unknown 資料類型

您無法在 PostgreSQL 版本 10 及更新版本中使用 unknown 資料類型。例如，如果 PostgreSQL 版本 9.6 資料庫使用 unknown 資料類型，則升級至版本 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."

若要解決此問題，請手動移除使用 unknown 資料類型的資料欄，或將其修改為支援的資料類型。

若要尋找資料庫中使用 unknown 資料類型的資料欄，請執行下列查詢：

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

(僅適用於 RDS for PostgreSQL) 檢查是否讀取複寫升級失敗

如果 PostgreSQL 執行個體具有讀取複寫，則讀取複寫升級失敗可能會導致主要執行個體升級卡住或失敗。Amazon RDS 將失敗的讀取複寫設為 incompatible-restore 狀態，然後停止資料庫執行個體上的複寫動作。

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

• 即使在等待時間過後，讀取複寫也無法跟上主要資料庫執行個體的進度。
• 讀取複寫處於終端或不相容的生命週期狀態，例如 storage-full 或 incompatible-restore。
• 主要資料庫執行個體開始升級時，讀取複寫正在執行獨立的次要版本升級作業。
• 讀取複寫使用不相容的參數。
• 讀取複寫無法與主要資料庫執行個體通訊，以同步資料夾。

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

確定主要使用者名稱正確無誤

如果主要使用者名稱以 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_，而且具有 rds_superuser 角色。

檢查是否有不相容的參數

當 shared_buffer 或 work_memory 等記憶體相關參數值對目前的組態而言設定過高，就會出現 "incompatible parameters" 錯誤。此錯誤會導致升級指令碼失敗。若要解決此問題，請減少這些參數的值，然後重新執行升級。

在升級之前更新擴充功能

執行主要版本升級，不會一併升級 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."

上述錯誤訊息範例反映 PostGIS 擴充功能發生問題。若要解決此問題，請執行下列查詢，檢查 PostGIS 及相依擴充功能的預設版本和已安裝版本：

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

**注意：**請將 postgis% 替換成您的擴充功能。

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

ALTER EXTENSION extension_name UPDATE TO 'default_version_number';

**注意：**請將 default_version_number 替換成 default_version 值。

詳情請參閱「RDS for PostgreSQL 資料庫引擎升級」或 “Upgrading Amazon Aurora PostgreSQL-Compatible DB clusters” (升級 Amazon Aurora PostgreSQL 相容版資料庫叢集)。

針對造成檢視表出現問題的版本，檢查系統目錄中的變更

在不同的 PostgreSQL 版本中，某些檢視表的資料欄會有所差異。例如，您可能會收到類似以下內容的錯誤訊息：

"pg_restore: error: could not execute query: ERROR: column reference 'backend_type' is ambiguous"

此錯誤發生於嘗試將資料庫從版本 12.x 升級至 13.x 時，原因是 pg_stat_activity 在版本 12.x 與 13.x 中有不同的結構。

若要解決此問題，請完成下列步驟：

1. 執行下列命令，查詢檢視表定義：

   SELECT pg_get_viewdef('pg_stat_activity_allusers', true);

2. 執行下列命令，刪除檢視表：

   DROP VIEW pg_stat_activity_allusers;

3. 升級引擎版本。

4. 執行下列命令，重新建立檢視表：

   CREATE VIEW pg_stat_activity_allusers AS SELECT * FROM get_sa();
   GRANT SELECT ON pg_stat_activity_allusers TO public;

或者，您可能會收到類似以下內容的錯誤訊息：

"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'."

此錯誤是 PostgreSQL 版本 12 中 pg_constraint 目錄的結構發生變動所導致。

若要解決此問題，請刪除根據目的地版本的系統目錄建立的檢視表。

**重要事項：**在刪除檢視表之前，建議使用 pgdump 備份檢視表或擷取檢視表的定義。刪除檢視表之後，您或您的資料庫管理員必須在版本升級後手動重新建立該檢視表。

檢查是否有已設定 prefetch 值的外部資料表

使用 oracle_fdw 擴充功能，從 Oracle 資料庫預先擷取 0–10,240 列的資料。在外部資料表的 OPTIONS 子句中設定 prefetch 參數。設定較高的值可提升效能，但會消耗較多 PostgreSQL 伺服器的記憶體。為了減少記憶體使用量，建議在主要版本升級的預先檢查期間設定 prefetch。

如果 prefetch 值大於 1,000，可能會收到下列錯誤訊息：

"pg_restore: error: could not execute query: ERROR: invalid value for option 'prefetch'"

**注意：**在此情況下，有效的設定值為 0 至 1,000 之間的整數。

若要解決此問題，請將所有外部資料表的 prefetch 值設定在 1 至 1,000 之間，然後重新嘗試升級。

若要變更外部資料表，請執行下列命令：

ALTER FOREIGN TABLE dwh_ddl_sync.fdw_all_tab_cols OPTIONS (SET prefetch '999');

若要列出所有外部資料表，請執行下列命令：

SELECT * from information_schema.foreign_tables;

若要檢查資料表的 prefetch 值，請執行下列命令：

SELECT * FROM pg_foreign_table;

請確認您是否已將 Babelfish for Aurora PostgreSQL 相容版叢集升級

針對 Babelfish for Aurora PostgreSQL 相容版叢集執行主要引擎版本升級時，您可能會收到類似以下內容的錯誤訊息：

"You can't perform a multi major version upgrade on a Babelfish for Aurora PostgreSQL DB cluster 13.20 and lower versions."

若要解決此問題，請將叢集升級至支援主要版本升級的版本，然後升級為下一個主要版本。

升級完成後

升級完成後，請在所有使用者資料庫中執行 ANALYZE 命令，以更新 pg_statistics 資料表。升級主要版本時，系統不會將 pg\ _statistic 資料表內容移轉到新版本。如果您未移轉內容，可能會遇到查詢執行緩慢的情況。

相關資訊

Aurora PostgreSQL 升級程序概述

Best practices for upgrading Amazon RDS to major and minor versions of PostgreSQL (將 Amazon RDS for PostgreSQL 升級為主要和次要版本的最佳實務)