診斷 PostgreSQL 到 AlloyDB 遷移作業中的問題

排解遷移錯誤

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

  • 部分錯誤 (例如來源資料庫的密碼有誤) 可以復原，也就是說，修正錯誤後，遷移工作就會自動繼續執行。
  • 有些錯誤無法復原，例如資料複製錯誤，這表示遷移工作必須從頭開始。

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

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

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

下表列出一些問題範例和解決方法：

問題 可能原因 建議做法
無法連線至來源資料庫執行個體。 來源資料庫執行個體與目的地執行個體之間的連線發生問題。 請按照「偵錯連線」一文中的步驟操作。
來源和目的地資料庫版本不相容，導致遷移工作無法執行。 來源和目的地資料庫版本不支援搭配使用。具體來說，您提供的來源資料庫版本與目的地資料庫版本不相容。 請確認目標資料庫版本與來源資料庫版本相同，或比來源資料庫版本高一個主要版本。然後建立新的遷移工作。
來源上已封鎖資料定義語言 (DDL) 或資料操縱語言 (DML)。 需要 ACCESS EXCLUSIVE lock 且在完整傾印階段執行的 DDL 會遭到封鎖。

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

舉例來說，如果資料表仍在初始同步程序中，且在同一個資料表上執行 ALTER TABLE 指令，則系統不會執行該指令，且後續的 DDL 和 DML 指令都會遭到封鎖，直到初始同步完成為止。
錯誤訊息：No pglogical extension installed on databases (X) 一或多個來源資料庫未安裝 pglogical。 請按照這些指南，在來源執行個體的資料庫上安裝 pglogical。
錯誤訊息：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。
錯誤訊息：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.

或

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

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

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

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

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

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

舉例來說，使用 rds-ca-2019-root.pem 憑證可能會導致 Amazon Relational Database Service 發生這個問題。

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

如果是 Amazon Relational Database Service 用例，請使用 rds-combined-ca-bundle.pem 憑證，而非 rds-ca-2019-root.pem 憑證。

錯誤訊息：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 套件。 如要進一步瞭解如何正確安裝這個套件，請參閱「在來源執行個體中安裝 pglogical 套件」。

錯誤訊息：Cannot assign TransactionIds during recovery.

設定的來源處於復原模式。 設定未處於復原模式的來源。
完整傾印作業速度緩慢。 從來源資料庫匯入大量資料時，AlloyDB 目的地可能會變慢。
  • 為 AlloyDB 目的地選擇較高的層級，以取得可用的最大網路和磁碟頻寬。
  • 調整 AlloyDB 目的地的 max_wal_size 標記。通常來說，32 GB 或 64 GB 是這項旗標的合適值。更新這個旗標不需要重新啟動伺服器。
錯誤訊息：subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

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

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

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

主要節點上複製的資料表新增了資料欄，但副本節點上沒有。

只有資料操縱語言 (DML) 變更會在連續遷移期間自動更新。使用者有責任管理資料定義語言 (DDL) 變更，確保來源和目的地資料庫保持相容。兩種執行方式如下：

  • 停止寫入來源資料庫，並在來源和目的地中執行 DDL 指令。在目的地執行 DDL 指令之前，請將 cloudsqlexternalsync 角色授予套用 DDL 變更的 Cloud SQL 使用者。
  • 在相同的時間點使用 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 parameter 的值設定不足，因此複製連線已結束。初始傾印成功後，通常會在複製階段發生錯誤。

請考慮增加 wal_sender_timeout 參數值，或在來源資料庫執行個體上將值設為 0，藉此停用逾時機制。
如果您遷移選取的資料庫，但遷移工作無法將資料複製到一或多個資料庫，資料庫清單中就會顯示「失敗」狀態。 各種遷移工作錯誤。

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

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

清除複製運算單元

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

  • 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 執行個體時，如果 AlloyDB 執行個體無法連線至來源執行個體 (例如來源執行個體未執行，或您從來源執行個體的允許清單中移除了 AlloyDB 執行個體)，則在升級遷移工作期間，系統無法清除複製作業所需的設定。您必須手動清除複製位置。

建議做法

請以具備 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 副本，請執行下列指令來清除 pglogical 設定：

    select pglogical.drop_node(node_name) from pglogical.node where node_name like 'alloydb';

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

    DROP EXTENSION IF EXISTS pglogical;

在啟動程序模式下刪除孤立的 AlloyDB 叢集

在少數極端情況下，您可能會發現遷移作業已刪除，但相關聯的 AlloyDB 叢集仍在啟動模式。您可以搭配 --force 選項，使用 AlloyDB 的 gcloud 叢集刪除指令刪除叢集。

請注意，如果遷移作業正在使用啟動程序叢集，刪除該叢集會導致未定義的行為。

管理使用者和角色

遷移現有使用者

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

關於alloydbexternalsync使用者

遷移期間，AlloyDB 主要執行個體上的所有物件都由 alloydbexternalsync 使用者擁有。資料遷移完成後，您可以按照下列步驟，將物件擁有權轉移給其他使用者：

  • 請執行 GRANT alloydbexternalsync to {USER} 指令。
  • 在每個資料庫上執行 reassign owned by alloydbexternalsync to {USER}; 指令。
  • 如要移除 alloydbexternalsync 使用者，請執行 drop role alloydbexternalsync 指令。