診斷從 PostgreSQL 遷移至 AlloyDB for PostgreSQL 的問題

遷移工作程序在執行階段可能會發生錯誤。

  • 部分錯誤 (例如來源資料庫密碼錯誤) 可以復原，也就是說，修正錯誤後，遷移工作會自動恢復。
  • 有些錯誤無法復原，例如資料損毀或結構定義不相容，這表示遷移工作必須從頭重新啟動。

發生錯誤時，遷移工作狀態會變更為「Failed」，子狀態則會反映失敗前的最後狀態。

如要排解錯誤，請前往失敗的遷移工作查看錯誤，並按照錯誤訊息中的步驟操作。

如要查看錯誤的詳細資料，請使用遷移工作中的連結前往 Cloud Monitoring。系統會篩選記錄，只顯示特定遷移工作的記錄。

下表列出常見問題和解決方法：

針對這個問題... 問題可能出在... 不如說
遷移至現有目的地叢集時，您會收到下列錯誤訊息： The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job. 目的地 AlloyDB for PostgreSQL 叢集含有額外的使用者資料。您只能遷移至現有的空叢集。請參閱 已知限制。 請清除目的地叢集中衝突或多餘的資料，然後重試遷移工作。請參閱「清除現有目的地叢集中的多餘資料」。
無法連線至來源資料庫執行個體。 來源資料庫執行個體與 AlloyDB for PostgreSQL 目的地叢集之間的連線發生問題。 請按照「偵錯連線能力」中的步驟操作。
來源和目的地資料庫版本不相容，因此無法執行遷移工作。 不支援來源和目的地資料庫版本的組合。具體來說，您提供的來源資料庫版本與目的地資料庫版本不相容。 確認目的地資料庫版本與來源資料庫版本相同，或為支援的較新主要版本。接著，建立新的遷移工作。
來源端封鎖了資料定義語言 (DDL) 或 data manipulation language (DML)。 如果 DDL 需要 ACCESS EXCLUSIVE 鎖定，且在完整轉儲階段執行，則會遭到封鎖。

在初始同步處理程序 (完整 dump) 期間，請避免在資料表上執行 DDL 或需要 ACCESS EXCLUSIVE 鎖定的程式，例如 ALTER TABLE 或 DROP TABLE。否則，DDL 或程式會等到初始同步作業完成後才執行。

舉例來說，如果資料表仍在初始同步處理程序中，且對同一個資料表執行 ALTER TABLE 指令，則該指令不會執行，且後續的 DDL 和 DML 指令會遭到封鎖，直到初始同步處理完成為止。
錯誤訊息：No pglogical extension installed on databases (X) 一或多個來源資料庫未安裝 pglogical。 請按照這些指南，在來源執行個體的資料庫上安裝 pglogical。
遷移至 PostgreSQL 15 版時，如果多次嘗試連線後仍失敗，會出現下列其中一種情況： 這個問題通常是因為 pglogical 擴充功能中的死結問題所致。詳情請參閱 GitHub 中的 pglogical Issue Tracker。 請重試遷移工作，或先遷移至中繼 PostgreSQL 版本。詳情請參閱「錯誤訊息：Cannot connect to invalid database」。
錯誤訊息：Replication user 'x' doesn't have sufficient privileges. 使用資料庫遷移服務的使用者不具備必要權限，無法執行指定作業。 請按照這些指南操作，確保該使用者具備必要權限。
錯誤訊息：Unable to connect to source database server. 資料庫遷移服務無法與來源資料庫伺服器建立連線。 請確認來源和目的地資料庫執行個體可以互相通訊，且您已完成定義遷移工作設定時顯示的所有必要條件。
錯誤訊息：The source database 'wal_level' configuration must be equal to 'logical'. 來源資料庫的 wal_level 設為 logical 以外的值。 將 wal_level 設為 logical。請參閱「WAL 層級設定」。
錯誤訊息：The source database 'max_replication_slots' configuration is not sufficient. max_replication_slots 參數設定有誤。 請按照這些規範正確設定這項參數。
錯誤訊息：The source database 'max_wal_senders' configuration is not sufficient. max_wal_senders 參數設定有誤。 請按照這些規範正確設定這項參數。
錯誤訊息：The source database 'max_worker_processes' configuration is not sufficient. max_worker_processes 參數設定有誤。 請按照這些規範正確設定這項參數。

錯誤訊息：Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

OR

錯誤訊息：Error promoting EM replica: finished drop replication with errors.

在遷移工作升級期間，無法清除複製作業所需的設定。

針對每個資料庫，以具備 superuser 權限的使用者身分執行指令。

如要進一步瞭解要執行的指令，請參閱「清除複製運算單元」。

錯誤訊息：x509 certificate signed by unknown authority.

提供給資料庫遷移服務的來源 CA 憑證可能只包含根憑證。不過，來源憑證需要根憑證和任何中繼憑證。

舉例來說，在 Amazon RDS 中，使用獨立根憑證而非憑證套裝組合，可能會導致這個問題。

建立合併的來源 CA 憑證，其中包含根憑證和所有必要的中繼憑證。

如果是 Amazon RDS 來源，請使用包含中繼憑證和根憑證的憑證套裝組合。詳情請參閱 Amazon RDS 說明文件中的「下載憑證套件」。

錯誤訊息：ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

max_locks_per_transaction 參數設定的值不夠。 請將這個參數的值設為至少 {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions)。

錯誤訊息：ERROR: no data left in message.

來源執行個體未正確安裝 pglogical 套件。 如要進一步瞭解如何正確安裝這個套件，請參閱「設定來源資料庫」。

錯誤訊息：Cannot assign TransactionIds during recovery.

設定的來源處於復原模式。 請設定非復原模式的來源。
完整轉儲速度緩慢。 AlloyDB for PostgreSQL 目的地叢集主要執行個體從來源資料庫匯入大量資料時，速度可能會變慢。
  • 為目的地 AlloyDB for PostgreSQL 主要執行個體選擇較高的機器級別，盡可能提高可用的網路頻寬和 CPU 容量。
  • 調整目的地的 max_wal_size 旗標。一般來說，建議將這個旗標設為 32 GB 或 64 GB。更新這個旗標時，不必重新啟動資料庫伺服器。
錯誤訊息：subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

遷移工作在完整 dump 階段失敗，且無法復原。來源資料庫執行個體已重新啟動或處於復原模式，或 wal_sender_timeout 參數設定的值不足，導致複製連線終止。

如要找出問題的根本原因，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Logs Explorer」頁面。
  2. 從資源清單中選取 AlloyDB for PostgreSQL 執行個體。系統會列出執行個體的最新記錄。
  3. 從記錄檔名稱中選取 postgres.log。
  4. 將記錄檔的嚴重性等級設為 Warning 以上的所有等級。第一個錯誤記錄可能是失敗的根本原因。
  • 在完整轉儲階段，請確保資料庫遷移服務一律能連線至來源資料庫執行個體。
  • 檢查來源資料庫執行個體的 wal_sender_timeout 參數值是否設為較大的數字 (例如 0)。
  • 重新啟動遷移工作，然後再試一次。
錯誤訊息：ERROR: unknown column name {column_name}

資料欄已新增至主要節點上的複製資料表，但未新增至副本節點。

連續遷移期間，系統只會自動更新 data manipulation language (DML) 變更。您必須管理資料定義語言 (DDL) 變更，確保來源和目的地資料庫保持相容。有兩種方法可以做到這一點：

  • 停止寫入來源資料庫，並在來源和目的地執行 DDL 指令。在目的地執行 DDL 指令前，請將 alloydbexternalsync 角色授予套用 DDL 變更的 AlloyDB for PostgreSQL 使用者。
  • 使用 pglogical.replicate_ddl_command，允許 DDL 指令在來源和目的地的一致時間點執行。執行指令的使用者在來源和目的地必須使用相同的使用者名稱，且應為超級使用者或要遷移的構件 (例如資料表、序列、檢視表或資料庫) 的擁有者。

如需使用 pglogical.replicate_ddl_command 的範例，請參閱「持續遷移」。
錯誤訊息：ERROR: cannot truncate a table referenced in a foreign key constraint

使用者嘗試截斷具有外鍵限制的資料表。

請先移除外鍵限制，再截斷資料表。
錯誤訊息：ERROR: connection to other side has died

wal_sender_timeout 參數設定的值不足，因此複製連線已結束。這項錯誤通常會在初始轉儲成功後的複製階段發生。

建議您提高 wal_sender_timeout 參數值，或在來源資料庫執行個體上將該值設為 0，停用逾時機制。
警告訊息：migration job test configuration has returned the following warnings: Some table(s) have limited support.

來源資料表僅提供部分支援，例如沒有主鍵的資料表。

這是一則警告訊息。您可以繼續遷移，但請注意，在標準遷移作業中，沒有主鍵的資料表只會在變更資料擷取 (CDC) 階段複製初始快照和 INSERT 陳述式，不會複製 UPDATE 和 DELETE 陳述式。詳情請參閱「設定來源資料庫」。

如果遷移所選資料庫時，遷移工作無法將資料複製到一或多個資料庫，資料庫清單中會顯示「失敗」狀態。 各種遷移工作錯誤。

在「錯誤」欄中，按一下「查看錯誤」並修正錯誤。您也可以從遷移工作中移除失敗的資料庫。

如要進一步瞭解如何從遷移工作中移除失敗的資料庫，請參閱「管理遷移工作」。

清除現有目的地叢集中的額外資料

遷移至現有目的地叢集時，會收到下列錯誤訊息： The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.

如果目的地叢集包含額外資料，就可能發生這個問題。您只能遷移至現有的空叢集。請參閱 已知限制。

推薦主題

請清除目的地叢集中衝突或多餘的資料，然後按照下列步驟重新啟動遷移工作：

  1. 停止遷移工作。
  2. 使用 psql 或 AlloyDB Studio，連線至 AlloyDB for PostgreSQL 目的地叢集的主要執行個體。
  3. 從目的地叢集資料庫移除多餘資料。目的地只能包含系統設定資料。目的地資料庫不得包含使用者資料 (例如使用者定義的資料表或常式)。您可以在資料庫中執行不同的 SQL 陳述式，找出非系統資料：

    用於擷取非系統資料庫的 SQL 陳述式範例 (點選即可展開)

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('alloydbadmin', 'template1', 'template0', 'postgres');

    用於擷取 postgres 資料庫中非系統資料的 SQL 陳述式範例 (點選即可展開)

    postgres 資料庫是系統資料庫，但可以包含非系統資料。請務必在 postgres 資料庫執行這些陳述式。如果您使用 psql 用戶端連線至目的地叢集，可以使用 \connect {database_name_here} 指令切換至其他資料庫，而不必重設連線。

    SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema != 'information_schema' AND table_schema not like 'pg\_%';

SELECT routine_schema, routine_name FROM information_schema.routines
WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\_%';

SELECT extname FROM pg_extension WHERE extname NOT IN ('plpgsql', 'alloydb_utility');
  4. 刪除上一步識別出的所有非系統資料庫、使用者資料表和 user-defined function。
  5. 啟動遷移工作。

清理複製運算單元

您會看到下列其中一則訊息：

  • Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.
  • Error promoting EM replica: finished drop replication with errors.

問題可能在於

升級 AlloyDB for PostgreSQL 目的地叢集時，如果 AlloyDB for PostgreSQL 叢集無法連線至來源執行個體 (例如來源執行個體未運作，或您已從來源執行個體的許可清單中移除 AlloyDB for PostgreSQL 叢集)，則在升級遷移工作期間，系統無法清除複製所需的設定。您必須手動清除。

推薦主題

針對每個資料庫，以具備 superuser 權限的使用者身分執行下列指令：

  1. 從錯誤訊息中取得複製運算單元名稱，然後執行下列指令，逐一捨棄運算單元：

    SELECT pg_drop_replication_slot('slot_name');

  2. 如果錯誤訊息中未提供複製運算單元名稱，請執行下列指令，查詢現有的複製運算單元：

    SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name LIKE '%alloydb%' AND active = 'f';

  3. 如果沒有任何 AlloyDB for PostgreSQL 副本使用來源執行個體，請執行下列指令，清除 pglogical 設定：

    SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

  4. 如果不再需要 pglogical 擴充功能，請執行下列指令，解除安裝擴充功能：

    DROP EXTENSION IF EXISTS pglogical;

錯誤訊息：Cannot connect to invalid database

遷移至 PostgreSQL 15 版時，如果多次嘗試連線後仍失敗，會出現下列其中一種情況：

問題可能在於

這個問題通常是因為 pglogical 擴充功能發生死結。詳情請參閱 GitHub 中的 pglogical Issue Tracker。

推薦主題

使用新的目的地叢集再次執行遷移工作

請嘗試刪除發生問題的目的地叢集，然後重新建立遷移工作。步驟如下：

  1. 刪除失敗的遷移工作。請參閱「查看遷移工作」。
  2. 刪除發生問題的目的地叢集。請參閱「AlloyDB 叢集管理」。
  3. 重新建立遷移工作。請參閱「建立遷移工作」。
遷移至中繼版本

建議您改用較早的 PostgreSQL 版本，例如 PostgreSQL 14。成功遷移後，即可升級至所需的 PostgreSQL 15 執行個體。請參閱 AlloyDB for PostgreSQL 說明文件的「升級資料庫主要版本」一節。

刪除處於啟動模式的孤立 AlloyDB for PostgreSQL 叢集

在極少數情況下，您可能會發現遷移工作已刪除，但相關聯的 AlloyDB for PostgreSQL 叢集並未刪除，且仍處於啟動模式。您可以使用 gcloud alloydb clusters delete 指令搭配 --force 選項，刪除叢集：

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

請注意，如果刪除正在執行遷移工作的啟動叢集，會導致未定義的行為。

管理使用者和角色

遷移現有使用者

資料庫遷移服務目前不支援自動將現有使用者和角色，從來源執行個體遷移至 AlloyDB for PostgreSQL 目的地叢集。您可以手動在 AlloyDB for PostgreSQL 建立使用者，管理這項遷移作業。

關於alloydbexternalsync使用者

在標準遷移期間，AlloyDB for PostgreSQL 副本上的所有資料庫物件都由 alloydbexternalsync 使用者擁有 (快速啟動遷移則使用 postgres 使用者)。資料遷移完畢且遷移工作升級後，您可以按照下列步驟，將物件擁有權轉移給其他應用程式使用者：

  • 請執行 GRANT alloydbexternalsync TO USER; 指令。
  • 在每個資料庫上執行 REASSIGN OWNED BY alloydbexternalsync TO USER; 指令。
  • 如要移除 alloydbexternalsync 使用者，請執行 DROP ROLE alloydbexternalsync; 指令。