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

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

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

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

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

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

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

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

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

最初の同期プロセス（完全なダンプ）中は、ALTER TABLE や DROP TABLE などの ACCESS EXCLUSIVE ロックを必要とする DDL またはプログラムをテーブルで使用しないでください。そうでない場合、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 の宛先に大量のデータをインポートすると、時間がかかることがあります。
  • 宛先を作成するときに、データディスクサイズを最終的なサイズに近づけるように設定します。完全ダンプ フェーズでは I/O 書き込み負荷の高いワークロードが使用されます。ディスクサイズが大きいほど、I/O パフォーマンスが向上します。詳細については、ブロック ストレージのパフォーマンスをご覧ください。
  • 使用可能なネットワーク帯域幅とディスク帯域幅を最大限にするには、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 に設定してタイムアウト メカニズムを無効にすることを検討してください。

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

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

  • 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 コマンドを実行します。