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

移行ジョブのプロセスで、実行時にエラーが発生することがあります。

• 移行元データベースのパスワードが間違っているなどの一部のエラーは、修正可能であり、修正すると移行ジョブが自動的に再開されます。
• データの破損やスキーマの非互換性など、回復不能なエラーもあります。この場合、移行ジョブを最初から再開する必要があります。

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

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

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

次の表に、一般的な問題とその解決策を示します。

この問題については...	次のような問題が考えられます...	次のことを試します...
既存の宛先クラスタに移行すると、次のエラー メッセージが表示されます。 The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.	をご覧ください。 移行先の AlloyDB for PostgreSQL クラスタに、余分なユーザーデータが含まれています。移行できるのは、空の既存のクラスタのみです。 既知の制限事項をご覧ください。	移行先クラスタから競合するデータまたは余分なデータを消去し、移行ジョブを再試行します。既存の宛先クラスタから余分なデータを消去するをご覧ください。
ソース データベース インスタンスへの接続エラー。	移行元データベース インスタンスと移行先の AlloyDB for PostgreSQL クラスタの間に接続の問題がありました。	接続性のデバッグの手順に沿って操作します。
移行元データベースと移行先データベースのバージョンに互換性がないため、移行ジョブを実行できません。	移行元と移行先のデータベース バージョンの組み合わせがサポートされていません。具体的には、指定されたソース データベースのバージョンが、宛先データベースのバージョンと互換性がありません。	移行先データベースのバージョンが、移行元データベースのバージョンと同じか、それ以降のサポートされているメジャー バージョンであることを確認します。次に、新しい移行ジョブを作成します。
データ定義言語（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 をインストールします。
PostgreSQL バージョン 15 に移行するときに、その後の接続の再試行を複数回行った後、次のいずれかの症状が発生します。 Cannot connect to invalid database エラー メッセージが表示される。 移行ジョブがデータベースの完全なダンプを実行しているときに、移行先ストレージの合計使用量の移行ジョブ指標が長時間経過しても進行状況が表示されない。	この問題は、pglogical 拡張機能のデッドロックの問題が原因であることがよくあります。詳細については、GitHub の pglogical Issue Tracker をご覧ください。	移行ジョブを再試行するか、まず 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 に設定します。WAL レベルの構成をご覧ください。
エラー メッセージ: 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 RDS の場合、証明書バンドルではなくスタンドアロンのルート証明書を使用すると、この問題が発生する可能性があります。	ルート証明書と必要なすべての中間証明書の両方を含む、結合されたソース CA 証明書を作成します。 Amazon RDS ソースの場合は、中間証明書とルート証明書の両方を含む証明書バンドルを使用します。詳細については、Amazon RDS ドキュメントの証明書バンドルをダウンロードするをご覧ください。
エラー メッセージ: 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 パッケージが移行元インスタンスに正しくインストールされていない。	このパッケージを適切にインストールする方法については、ソース データベースを構成するをご覧ください。
エラー メッセージ: Cannot assign TransactionIds during recovery.	構成されているソースがリカバリ モードになっています。	リカバリモードでないソースを構成します。
完全なダンプが遅い。	AlloyDB for PostgreSQL 移行先クラスタのプライマリ インスタンスで、移行元データベースからの大規模なデータのインポートに時間がかかることがあります。	移行先の AlloyDB for PostgreSQL プライマリ インスタンスに、より高いマシンティアを選択して、使用可能なネットワーク帯域幅と CPU 容量を最大化します。 宛先の max_wal_size フラグを調整します。通常、このフラグに設定する値は 32 GB または 64 GB が適しています。このフラグを更新しても、データベース サーバーを再起動する必要はありません。
エラー メッセージ: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again	完全ダンプフェーズ中に移行ジョブが失敗し、ジョブを復元できません。ソース データベース インスタンスが再起動されたか、リカバリモードになっているか、wal_sender_timeout パラメータに設定された値が不十分なため、レプリケーション接続が終了しました。 問題の根本原因を特定するには: Google Cloud コンソールの [ログ エクスプローラ] ページに移動します。 リソースリストから、AlloyDB for PostgreSQL インスタンスを選択します。インスタンスの最新のログのリストが表示されます。 ログファイル名から postgres.log を選択します。 ログの重大度レベルを Warning より上のすべてのレベルに設定します。最初のエラーログが、障害の根本原因である可能性があります。	フルダンプ フェーズ中に Database Migration Service がソース データベース インスタンスに常に接続できることを確認します。 移行元データベース インスタンスで、wal_sender_timeout パラメータの値がより大きな数値（0 など）に設定されているかどうかを確認します。 移行ジョブを再起動してから、もう一度お試しください。
エラー メッセージ: ERROR: unknown column name {column_name}	プライマリ ノードのレプリケートされたテーブルに列が追加されたが、レプリカノードには追加されていない。	継続的な移行中に自動的に更新されるのは、データ操作言語（DML）の変更のみです。ソース データベースと宛先データベースの互換性を維持するために、データ定義言語（DDL）の変更を管理する必要があります。これには次の 2 つの方法があります。 移行元データベースへの書き込みを停止し、移行元と移行先の両方で DDL コマンドを実行します。移行先で DDL コマンドを実行する前に、DDL の変更を適用する AlloyDB for PostgreSQL ユーザーに alloydbexternalsync ロールを付与します。 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 パラメータに設定された値が不十分なため、レプリケーション接続が終了しました。このエラーは通常、最初のダンプが成功した後のレプリケーション フェーズで発生します。	wal_sender_timeout パラメータ値を増やすか、ソース データベース インスタンスで値を 0 に設定してタイムアウト メカニズムを無効にすることを検討してください。
警告メッセージ: migration job test configuration has returned the following warnings: Some table(s) have limited support.	ソースに、サポートが制限されているテーブル（主キーのないテーブルなど）がある。	これは警告メッセージです。移行を続行できますが、標準の移行では、主キーのないテーブルは、変更データ キャプチャ（CDC）フェーズ中に初期スナップショットと INSERT ステートメントのみを複製します。UPDATE ステートメントと DELETE ステートメントは複製されません。詳細については、ソース データベースを構成するをご覧ください。
選択したデータベースを移行し、移行ジョブが 1 つ以上のデータベースにデータを複製できない場合、データベースのリストに [失敗] ステータスが表示されます。	さまざまな移行ジョブエラー。	[エラー] 列で [エラーを表示] をクリックし、エラーを修正します。失敗したデータベースを移行ジョブから削除することもできます。 移行ジョブから失敗したデータベースを削除する方法については、移行ジョブを管理するをご覧ください。

---

既存の宛先クラスタから余分なデータを消去する

既存の宛先クラスタに移行すると、次のエラー メッセージが表示されます。 The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job. を参照

この問題は、宛先クラスタに余分なデータが含まれている場合に発生することがあります。移行できるのは、空の既存のクラスタのみです。 既知の制限事項をご覧ください。

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

移行先クラスタから競合するデータまたは余分なデータを消去し、次の手順で移行ジョブを再度開始します。

1. 移行ジョブを停止します。
2. psql または AlloyDB Studio を使用して、移行先の AlloyDB for PostgreSQL クラスタのプライマリ インスタンスに接続します。
3. 宛先クラスタ データベースから余分なデータを削除します。宛先にはシステム構成データのみを含めることができます。宛先データベースにユーザーデータ（ユーザー定義のテーブルやルーティンなど）を含めることはできません。データベースで実行して、システム以外のデータを検索できる SQL ステートメントは、次のとおりです。

   システム データベース以外のデータベースを取得する SQL ステートメントの例（クリックして展開）

   SELECT datname FROM pg_catalog.pg_database
   WHERE datname NOT IN ('alloydbadmin', '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 NOT IN ('plpgsql', 'alloydb_utility');
       

4. 前の手順で特定したシステム以外のデータベース、ユーザー テーブル、ユーザー定義関数を削除します。
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.

次のような問題が考えられます

AlloyDB for PostgreSQL 移行先クラスタをプロモートするときに、AlloyDB for PostgreSQL クラスタから移行元インスタンスにアクセスできない場合（たとえば、移行元インスタンスが実行されていない、または AlloyDB for PostgreSQL クラスタを移行元インスタンスの許可リストから削除した場合）、移行ジョブのプロモート中にレプリケーションに必要な設定をクリーンアップできません。レプリケーション スロットは手動でクリーンアップする必要があります。

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

各データベースで、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 for PostgreSQL レプリカがない場合は、次のコマンドを実行して pglogical 設定をクリーンアップします。

   SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

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. 失敗した移行ジョブを削除します。移行ジョブを確認するをご覧ください。
2. 問題が発生した宛先クラスタを削除します。AlloyDB クラスタ管理をご覧ください。
3. 移行ジョブを再作成します。移行ジョブを作成するをご覧ください。

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

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

---

ブートストラップ モードで孤立した AlloyDB for PostgreSQL クラスタを削除する

まれなエッジケースでは、移行ジョブが削除されているにもかかわらず、関連付けられている AlloyDB for PostgreSQL クラスタが削除されておらず、まだブートストラップ モードになっていることがあります。クラスタを削除するには、--force オプションを指定して gcloud alloydb clusters delete コマンドを使用します。

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

アクティブな移行ジョブで使用されているブートストラップ クラスタを削除すると、未定義の動作が発生します。

---

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

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

現在、Database Migration Service は、移行元インスタンスから移行先の AlloyDB for PostgreSQL クラスタへの既存のユーザーとロールの自動移行をサポートしていません。この移行は、AlloyDB for PostgreSQL でユーザーを手動で作成することで管理できます。

alloydbexternalsync ユーザーについて

標準移行では、AlloyDB for PostgreSQL レプリカ上のすべてのデータベース オブジェクトは alloydbexternalsync ユーザーが所有します（クイックスタート移行では postgres ユーザーが使用されます）。データが移行され、移行ジョブがプロモートされたら、次の手順でオブジェクトのオーナー権限を他のアプリケーション ユーザーに変更できます。

• GRANT alloydbexternalsync TO USER; コマンドを実行します。
• 各データベースで REASSIGN OWNED BY alloydbexternalsync TO USER; コマンドを実行します。
• alloydbexternalsync ユーザーを削除するには、DROP ROLE alloydbexternalsync; コマンドを実行します。