診斷遷移至 PostgreSQL 適用的 Cloud SQL 的單一來源遷移作業問題

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

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

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

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

如要查看錯誤的詳細資訊，請透過遷移工作的連結前往 Cloud Monitoring。系統會將記錄檔篩選為特定遷移工作。

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

針對這個問題... 問題可能出在... 試試這個...
遷移至 現有的目的地執行個體時，您會收到下列錯誤訊息： The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job. 目的地 Cloud SQL 執行個體含有額外資料。您只能遷移至空白的現有執行個體。請參閱 已知限制。 將目的地執行個體升級為讀/寫執行個體、移除額外資料，然後重新嘗試執行遷移工作。請參閱「 從現有的目標執行個體中清除多餘資料」。
無法連線至來源資料庫執行個體。 來源資料庫執行個體和目的地執行個體之間的連線發生問題。 請按照「偵錯連線問題」一文中的步驟操作。
來源和目的地資料庫版本不相容，因此無法執行遷移工作。 來源和目的地資料庫版本不相容。具體來說，提供的來源資料庫版本與目的地資料庫版本不相容。 請確認目的地資料庫版本與來源資料庫版本相同，或比來源版本高一個主要版本。接著，請建立新的遷移工作。
來源已封鎖資料定義語言 (DDL) 或資料操縱語言 (DML)。 需要 ACCESS EXCLUSIVE 鎖定且在完整傾印階段執行的 DDL 會遭到封鎖。

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

舉例來說，如果資料表仍處於初始同步處理程序，且在同一資料表上執行 ALTER TABLE 指令，則系統不會執行該指令，且初始同步作業完成前，後續的 DDL 和 DML 指令都會遭到封鎖。
錯誤訊息：No pglogical extension installed on databases (X) 一或多個來源資料庫未安裝 pglogical。 請按照這些規範，在來源執行個體的資料庫上安裝 pglogical。
遷移至 PostgreSQL 15 版本後，在多次後續連線重試嘗試後，會發生下列任一症狀：
  • 您會收到 Cannot connect to invalid database 錯誤訊息。
  • 當遷移工作執行完整資料庫轉儲作業時，儲存空間用量遷移工作指標顯示長時間後仍未有任何進度。
 這個問題通常是因為 pglogical 擴充功能中的死結問題。詳情請參閱 GitHub 中的 pglogical 問題追蹤器。 請重試遷移工作，或先遷移至中間 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。
錯誤訊息：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 憑證可能只包含根憑證。不過，來源憑證需要根憑證和任何中繼憑證。

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

建立結合來源 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.

已設定的來源處於復原模式。 設定未處於復原模式的來源。
完整傾印作業速度較慢。 Cloud SQL 目的地可能會從來源資料庫匯入大量資料，因此速度可能會變慢。
  • 建立目的地時，請設定資料磁碟大小，以便接近最終大小。完整傾印階段會使用 I/O 寫入密集型工作負載，磁碟大小越大，I/O 效能就越好。詳情請參閱「區塊儲存空間效能」。
  • 請為 Cloud SQL 目的地選擇較高層級，以便取得可用的最高網路和磁碟頻寬。
  • 調整 Cloud SQL 目的地的 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 控制台的「Logs Explorer」頁面。
  2. 在資源清單中選取 Cloud SQL 複本。畫面上會顯示副本的最新記錄清單。
  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，以便停用逾時機制。
警告訊息：migration job test configuration has returned the following warnings: Some table(s) have limited support.

來源資料表支援有限，例如沒有主鍵的資料表。

這是一則警告訊息。您可以繼續遷移，但請注意，系統不會遷移不支援的實體 (例如沒有主鍵的資料表)。詳情請參閱「 設定來源資料庫」。
當您遷移所選資料庫，且遷移工作無法將資料複製到一個或多個資料庫時，資料庫清單中會顯示「失敗」狀態。 各種遷移工作錯誤。

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

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

清除現有目的地執行個體中的額外資料

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

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

建議做法

請按照下列步驟操作，清除目的地執行個體中的額外資料，然後再次啟動遷移工作：

  1. 停止遷移工作。
  2. 此時，目的地 Cloud SQL 執行個體處於「唯讀」模式。 提升目標執行個體，以便取得寫入權限。
  3. 連線至目的地 Cloud SQL 執行個體。
  4. 從目標執行個體資料庫中移除多餘資料。目的地只能包含系統設定資料。目的地資料庫不得包含使用者資料 (例如資料表)。您可以在資料庫上執行不同的 SQL 陳述式，以便尋找非系統資料，例如：

    擷取非系統資料庫的 SQL 陳述式範例 (按一下即可展開)

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('cloudsqladmin', '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 != 'plpgsql';
  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.

問題可能出在：

在升級 Cloud SQL 執行個體時，如果 Cloud SQL 執行個體無法存取來源執行個體 (例如，來源執行個體未執行，或您已從來源執行個體的許可清單中移除 Cloud SQL 執行個體)，則在遷移工作升級期間，無法清除複寫作業所需的設定。您必須手動清理複寫時段。

建議做法

針對每個資料庫，以具有 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 '%cloudsql%' and active = 'f';

  3. 如果沒有使用來源執行個體的 Cloud SQL 備用資源，請執行下列指令來清理 pglogical 設定：

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

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

    DROP EXTENSION IF EXISTS pglogical;

錯誤訊息： Cannot connect to invalid database

遷移至 PostgreSQL 15 版時，在多次後續連線重試嘗試後，會發生下列任一症狀：

  • 您會收到 Cannot connect to invalid database 錯誤訊息。
  • 當遷移工作執行完整資料庫轉儲作業時，儲存空間用量遷移工作指標顯示長時間後仍未有任何進度。

問題可能出在：

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

建議做法

使用新的目的地執行個體再次執行遷移工作

請嘗試刪除發生問題的目的地資料庫，然後重新建立遷移工作。請按照下列步驟操作：

  1. 刪除發生問題的目的地執行個體。請參閱 PostgreSQL 適用的 Cloud SQL 說明文件中的「Delete instances」(刪除執行個體)。
  2. 刪除失敗的遷移工作。請參閱「 查看遷移工作」一節。
  3. 重新建立遷移工作。 請參閱「 建立遷移工作」一節。

遷移至中間版本

建議您遷移至較早的 PostgreSQL 版本，例如 PostgreSQL 14。遷移成功後，您可以嘗試升級至所需的 PostgreSQL 15 執行個體。請參閱 PostgreSQL 適用的 Cloud SQL 說明文件中的「透過遷移資料升級資料庫主要版本」一節。

管理使用者和角色

遷移現有使用者

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

關於 cloudsqlexternalsync 使用者

在遷移期間，Cloud SQL 備援資料庫中的所有物件都由 cloudsqlexternalsync 使用者擁有。資料遷移完成後，您可以完成下列步驟，將物件的擁有權修改為其他使用者：

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

將資料匯入新的 Cloud SQL 執行個體

如果您先從資料庫移轉服務遷移至 Cloud Storage 的 Cloud SQL 執行個體匯出資料，然後再將 Cloud Storage 中的資料匯入至獨立 Cloud SQL 執行個體，由於目的地執行個體中沒有 cloudsqlexternalsync 使用者，匯入作業可能會失敗。

如要緩解這個問題，請在目的地執行個體上建立 cloudsqlexternalsync 使用者，或是從已遷移的執行個體移除使用者。