Cloud SQL for PostgreSQL への同種移行に関する問題を診断する

移行ジョブ プロセスでは、ランタイム中にエラーが発生することがあります。

  • エラーには、ソース データベースの不正なパスワードなど、回復可能なものもあります。つまり、エラーを修正して移行ジョブを自動的に再開できます。
  • データ レプリケーションのエラーなど、回復できないものもあります。この場合、移行ジョブを最初から再起動する必要があります。

エラーが発生すると、移行ジョブのステータスが 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 インスタンスに余分なデータが含まれている。移行できるのは、空の既存のインスタンスのみです。 既知の制限事項をご覧ください。 移行先インスタンスを読み取り/書き込みインスタンスにプロモートし、余分なデータを削除して、移行ジョブを再試行します。 既存の宛先インスタンスから余分なデータを削除するをご覧ください。
ソース データベース インスタンスへの接続エラー。 移行元データベース インスタンスと移行先インスタンス間の接続に問題がありました。 接続のデバッグの手順に沿って操作します。
移行元データベースと移行先データベースのバージョンに互換性がないため、移行ジョブを実行できません。 移行元と移行先のデータベース バージョンがサポートされている組み合わせではありません。具体的には、指定されたソース データベース バージョンが宛先データベース バージョンと互換性がありません。 移行先のデータベース バージョンが、移行元のデータベース バージョンと同じか、1 つ上のメジャー バージョンであることを確認します。次に、新しい移行ジョブを作成します。
データ定義言語（DDL）またはデータ操作言語（DML）がソースでブロックされている。 ACCESS EXCLUSIVE ロックを必要とし、完全なダンプフェーズ中に実行されている DDL はブロックされます。

最初の同期プロセス（完全なダンプ）中に、テーブルで ACCESS EXCLUSIVE ロック（ALTER TABLE や DROP TABLE など）を必要とする DDL やプログラムは避ける必要があります。それ以外の場合、DDL またはプログラムは初期同期が完了するまで待機します。

たとえば、テーブルが初期同期プロセス中に同じテーブルで ALTER TABLE コマンドが実行されると、コマンドは実行されず、初期同期が完了するまで後続の DDL コマンドと DML コマンドがブロックされます。
エラー メッセージ: No pglogical extension installed on databases (X) 1 つ以上のソース データベースに 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. Database Migration Service を使用しているユーザーに、指定されたオペレーションを実行するために必要な権限がありません。 こちらのガイドラインに沿って、このユーザーに必要な権限が付与されていることを確認してください。
エラー メッセージ: Unable to connect to source database server. Database Migration Service が移行元データベース サーバーへの接続を確立できません。 移行元と移行先のデータベース インスタンスが相互に通信できること、および移行ジョブの設定を定義したときに表示された必要な前提条件をすべて満たしていることを確認します。
エラー メッセージ: 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.

Database Migration Service に提供されるソース CA 証明書には、ルート証明書のみが含まれている場合があります。ただし、ソース証明書にはルート証明書と中間証明書の両方が必要です。

たとえば、Amazon Relational Database Service で rds-ca-2019-root.pem 証明書を使用すると、この問題が発生する可能性があります。

ルート証明書と必要なすべての中間証明書の両方を含む、結合されたソース CA 証明書を作成します。

Amazon Relational Database Service のユースケースでは、rds-ca-2019-root.pem 証明書の代わりに rds-combined-ca-bundle.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 コンソールの [ログ エクスプローラ] ページに移動します。
  2. リソースリストから、Cloud SQL レプリカを選択します。レプリカの最新のログのリストが表示されます。
  3. ログファイル名から postgres.log を選択します。
  4. ログの重大度レベルを Warning より上のすべてのレベルに設定します。最初のエラーログが障害の根本原因である可能性があります。
  • 完全ダンプ フェーズ中に Database Migration Service が常に移行元データベース インスタンスに接続できることを確認します。
  • 移行元データベース インスタンスの wal_sender_timeout パラメータの値が大きな数値（0 など）に設定されているかどうかを確認します。
  • 移行ジョブを再開して、もう一度お試しください。
エラー メッセージ: ERROR: unknown column name {column_name}

プライマリ ノードのレプリケートされたテーブルに列が追加されたが、レプリカ ノードには追加されていない。

継続的移行中に自動的に更新されるのは、データ操作言語（DML）の変更のみです。移行元と移行先のデータベースの互換性を保つようにデータ定義言語（DDL）の変更を管理する作業は、ユーザーの責任で行う必要があり、次の 2 つの方法があります。

  • 移行元データベースへの書き込みを停止し、移行元と移行先の両方で DDL コマンドを実行します。移行先で DDL コマンドを実行する前に、DDL 変更を適用する Cloud SQL ユーザーに cloudsqlexternalsync ロールを付与します。
  • 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.

移行元に、サポートが制限されているテーブル（主キーのないテーブルなど）がある。

これは警告メッセージです。移行を続行できますが、サポートされていないエンティティ（主キーのないテーブルなど）は移行されません。詳細については、 移行元データベースを構成するをご覧ください。
選択したデータベースを移行し、移行ジョブが 1 つ以上のデータベースにデータを複製できない場合、データベースのリストに [失敗] ステータスが表示されます。 さまざまな移行ジョブのエラー。

[エラー] 列で、[エラーを表示] をクリックしてエラーを修正します。移行ジョブから失敗したデータベースを削除することもできます。

移行ジョブから失敗したデータベースを削除する方法については、移行ジョブを管理するをご覧ください。

既存の移行先インスタンスから余分なデータを削除する

既存の宛先インスタンスに移行すると、次のエラー メッセージが表示されます。 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. エラー メッセージからレプリケーション スロット名を取得し、次のコマンドを実行してスロットを 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 Issue Tracker をご覧ください。

次の方法をお試しください

新しい移行先インスタンスを使用して移行ジョブを再度実行する

問題が発生した移行先データベースを削除して、移行ジョブを再作成してみてください。手順は次のとおりです。

  1. 問題が発生した移行先インスタンスを削除します。Cloud SQL for PostgreSQL のドキュメントのインスタンスを削除するをご覧ください。
  2. 失敗した移行ジョブを削除します。 移行ジョブを確認するをご覧ください。
  3. 移行ジョブを再作成します。 移行ジョブの作成をご覧ください。

中間バージョンに移行する

PostgreSQL 14 などの以前の PostgreSQL バージョンへの移行を検討してください。移行が成功したら、目的の PostgreSQL 15 インスタンスへのアップグレードを試すことができます。Cloud SQL for PostgreSQL のドキュメントのデータを移行してデータベースのメジャー バージョンをアップグレードするをご覧ください。

ユーザーとロールを管理する

既存のユーザーを移行する

現在、Database Migration Service は、既存のユーザーを移行元インスタンスから移行先 Cloud SQL インスタンスに移行することをサポートしていません。この移行は、Cloud SQL でユーザーを手動で作成することで管理できます。

cloudsqlexternalsync ユーザーについて

移行中、Cloud SQL レプリカ上のすべてのオブジェクトは cloudsqlexternalsync ユーザーが所有します。データの移行後、次の手順でオブジェクトの所有権を他のユーザーに変更できます。

  • GRANT cloudsqlexternalsync to {USER} コマンドを実行します。
  • 各データベースで reassign owned by cloudsqlexternalsync to {USER}; コマンドを実行します。
  • cloudsqlexternalsync ユーザーを削除するには、drop role cloudsqlexternalsync コマンドを実行します。

新しい Cloud SQL インスタンスにデータをインポートする

Database Migration Service が移行した Cloud SQL インスタンスから Cloud Storage にデータをエクスポートし、Cloud Storage からスタンドアロンの Cloud SQL インスタンスにデータをインポートすると、移行先インスタンスに cloudsqlexternalsync ユーザーが存在しないため、インポートが失敗する可能性があります。

この問題を軽減するには、移行先インスタンスに cloudsqlexternalsync ユーザーを作成するか、移行したインスタンスからユーザーを削除します。