PostgreSQL から AlloyDB への移行に関する問題を診断する

移行エラーのトラブルシューティング

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

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

エラーが発生すると、移行ジョブのステータスが Failed に変わり、サブステータスには失敗する前の最後のステータスが反映されます。

エラーのトラブルシューティングを行うには、失敗した移行ジョブに移動してエラーを表示し、エラー メッセージに記載されている手順に沿って操作します。

エラーの詳細を表示するには、移行ジョブのリンクを使用して Cloud Monitoring に移動します。ログは、特定の移行ジョブにフィルタされます。

次の表に、問題の例と解決方法を示します。

症状 考えられる原因 次の方法をお試しください
ソース データベース インスタンスに接続できません。 ソース データベース インスタンスと移行先インスタンスの間に接続の問題がありました。 接続のデバッグの手順に沿って操作します。
ソース データベースと移行先データベースのバージョンに互換性がないため、移行ジョブを実行できません。 ソース データベースと移行先データベースのバージョンが、サポートされている組み合わせではありません。具体的には、指定されたソース データベースのバージョンが移行先データベースのバージョンと互換性がありません。 移行先データベースのバージョンが、ソース データベースのバージョンと同じか、1 つ上のメジャー バージョンであることを確認します。次に、新しい移行ジョブを作成します。
ソースでデータ定義言語（DDL）またはデータ操作言語（DML）がブロックされています。 ACCESS EXCLUSIVE ロックを必要とし、完全なダンプフェーズ中に実行される DDL はブロックされます。

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

たとえば、テーブルが最初の同期プロセスにあり、同じテーブルで ALTER TABLE コマンドが実行された場合、コマンドは実行されず、最初の同期が完了するまで後続の DDL コマンドと DML コマンドがブロックされます。
エラー メッセージ: No pglogical extension installed on databases (X) 1 つ以上のソース データベースに pglogical がインストールされていません。 移行元インスタンスのデータベースに pglogical をインストールするには、次のガイドラインに沿って操作します。
エラー メッセージ: 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.

構成されているソースが復旧モードになっています。 復旧モードではないソースを構成します。
完全なダンプに時間がかかります。 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 より上のすべてのレベルに設定します。最初のエラーログが失敗の根本原因である可能性があります。
  • 完全なダンプフェーズ中に、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 に設定してタイムアウト メカニズムを無効にすることを検討してください。
選択したデータベースを移行し、移行ジョブが 1 つ以上のデータベースにデータをレプリケートできない場合、データベースのリストに [失敗] ステータスが表示されます。 移行ジョブのエラーはさまざまです。

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

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

レプリケーション スロットをクリーンアップする

次のいずれかのメッセージが表示されます。

  • 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. エラー メッセージからレプリケーション スロット名を取得し、次のコマンドを実行してスロットを 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 クラスタが削除されず、ブートストラップ モードのままになっていることがあります。AlloyDB のクラスタ削除用の gcloud コマンドと --force オプションを組み合わせて使用すると、クラスタを削除できます。

移行ジョブで使用されているブートストラップ クラスタを削除すると、動作が未定義になることに注意してください。

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

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

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

alloydbexternalsync ユーザーについて

移行中、AlloyDB プライマリのすべてのオブジェクトは alloydbexternalsync ユーザーが所有します。データの移行後、次の手順を完了して、オブジェクトの所有権を他のユーザーに変更できます。

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