Amazon RDS for PostgreSQL または Aurora PostgreSQL 互換のメジャーバージョンアップグレードに関する問題をトラブルシューティングする方法を教えてください。

簡単な説明

メジャーバージョンのアップグレードには、既存のアプリケーションとの下位互換性のないデータベース変更が含まれます。これらのアップグレードにより、システムテーブル、データファイル、データストレージの内部形式が変更される可能性があります。Amazon RDS は pg_upgrade を使用してメジャーバージョンのアップグレードを行います。詳細については、PostgreSQL のウェブサイトで pg_upgrade を参照してください。

メジャーバージョンのアップグレード中、Amazon RDS は、事前チェック手順を実行し、アップグレードの失敗を引き起こす可能性のある問題を特定します。すべてのデータベースで、互換性のない条件である可能性があるものをチェックします。Amazon RDS は事前チェックプロセス中に問題を特定すると、事前チェックで発生した問題に関するログイベントを作成します。ログイベントには、ファイル名、タイムスタンプ、およびアップグレード失敗の原因が含まれます。すべてのデータベースでの事前チェックプロセスについては、pg_upgrade_precheck.log ログを確認してください。エンジン固有の問題については、Amazon RDS for PostgreSQL または Aurora PostgreSQL のデータベースログファイルを確認する必要があります。

解決策

メジャーバージョンアップグレードを行う pg_upgrade ユーティリティにより、pg_upgrade_internal.log ログおよび pg_upgrade_server.log ログが生成されます。Amazon RDS は、これらのログのファイル名にタイムスタンプを追加します。これらのログを参照すると、アップグレード中に発生する問題とエラーに関する詳細情報を確認できます。詳細については、「Amazon RDS ログファイルのモニタリング」または「Amazon Aurora ログファイルのモニタリング」を参照してください。

アップグレードに長時間かかる場合

保留中のメンテナンスアクティビティを確認する

AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

Amazon RDS は、エンジンバージョンのアップグレードを自動的に実行し、Amazon RDS インスタンスのオペレーティングシステム (OS) パッチなどの保留中のメンテナンスアクティビティを適用します。Amazon RDS は保留中のアクティビティを最初に適用してから、エンジンバージョンをアップグレードします。Amazon RDS が OS のメンテナンスアクティビティを実行する必要がある場合、アップグレード時間は長くなります。

Amazon RDS インスタンスがマルチ AZ 配置にある場合、OS のメンテナンスによりフェイルオーバーが発生します。マルチ AZ 環境でインスタンスを設定すると、Amazon RDS は通常、セカンダリインスタンスにインスタンスのバックアップを作成します。フェイルオーバーでは、Amazon RDS はアップグレード後に新しいセカンダリインスタンスにバックアップを作成します。新しいセカンダリインスタンスにおいて、このバックアップは最新のバックアップではない可能性があるため、Amazon RDS は増分バックアップではなく完全バックアップを実行します。完全バックアップは、特にデータベースが大規模な場合に時間がかかる場合があります。

この問題を回避するには、RDS DB インスタンスまたは Aurora DB インスタンスの保留中のメンテナンスアクティビティを検索します。または、インスタンスで次の AWS CLI コマンド describe-pending-maintenance-actions を実行します。

aws rds describe-pending-maintenance-actions --resource-identifier example-arn

注: example-arn を DB インスタンスの ARN に置き換えてください。

データベースエンジンのバージョンをアップグレードする前に、保留中のメンテナンス作業を完了してください。

アップグレードを行う前にスナップショットを作成する

バージョンをアップグレードする前に、RDS DB インスタンスまたは Aurora DB クラスターのスナップショットを作成することをおすすめします。インスタンスではバックアップが既に有効な場合、Amazon RDS はアップグレードプロセスの一環として自動的にスナップショットを作成します。スナップショットを使用すると、Amazon RDS はアップグレードの一環として増分バックアップを作成するだけで済むため、アップグレード処理時間を短縮できます。

リードレプリカのアップグレードを待機する

プライマリ DB インスタンスのメジャーバージョンアップグレードを実行すると、Amazon RDS は同じ AWS リージョンのすべてのリードレプリカを自動的にアップグレードします。アップグレードワークフローの開始後、リードレプリカはプライマリ DB インスタンスで pg_upgrade が正常に完了するまで待機します。その後、プライマリ DB インスタンスのアップグレードは、リードレプリカのアップグレードが完了するまで待機します。DB インスタンスは、すべてのアップグレードが完了するまでシャットダウンします。アップグレードのダウンタイム期間が短い場合は、レプリカインスタンスをプロモートするか削除し、アップグレードの完了後にリードレプリカを再作成します。

Aurora DB クラスターでは、pg_upgrade は最初にライターインスタンスをアップグレードします。その後、各リーダー DB インスタンスは、pg_upgrade により新しいメジャーバージョンにアップグレードされる間、シャットダウンします。

注: Aurora グローバルデータベースをアップグレードする場合、追加の要件とプロセスが適用されます。

アップグレード前に長時間実行トランザクションや高負荷を解決する

トランザクションが長く実行していたり、ワークロードが高くなったりすると、Amazon RDS がデータベースをシャットダウンしてデータベースエンジンをアップグレードするのにかかる時間が長くなる可能性があります。

長時間実行トランザクションを特定するには、次のクエリを実行します。

SQL>SELECT pid, datname, application_name, state, age(query_start, clock_timestamp()), usename, query
FROM pg_stat_activity
WHERE query NOT ILIKE '%pg_stat_activity%' AND
usename!='rdsadmin'
ORDER BY query_start desc;

長時間実行トランザクションが見つかった場合は、pg_cancel_backend または pg_terminate_backend を使用してそのトランザクションを終了します。pg_cancel_backend と pg_terminate_backend の詳細については、PostgreSQL のウェブサイトで「サーバーシグナル送信関数」を参照してください。

十分な計算能力を確保する

pg_upgrade ユーティリティでは計算負荷が高くなる場合があります。本番データベースをアップグレードする前に、アップグレードをテストし、計算能力やメモリ容量が十分かどうかを確認することをおすすめします。アップグレードをテストすると、事前チェックまたはアップグレードでエラーが発生する可能性も確認できます。本番インスタンスのスナップショットを復元し、本番データベースのインスタンスクラスと同じインスタンスクラスでテストを実行します。

アップグレードの失敗

サポートされていない DB インスタンスクラスを使用していないか確認する

DB インスタンスのインスタンスクラスがアップグレード先の PostgreSQL バージョンと互換性がない場合、アップグレードは失敗します。エンジンバージョンと、Amazon RDS または Amazon Aurora のインスタンスクラスとの互換性を確認してください。

オープンな準備済みトランザクションがないか確認する

データベースにオープンな準備済みトランザクションが存在する場合、アップグレードは失敗します。pg_upgrade.log ファイルに「There are uncommitted prepared transactions」エラーが記録されます。アップグレードを開始する前に、オープンな準備済みトランザクションをすべてコミットするか、ロールバックしてください。

インスタンスにオープンな準備済みトランザクションが存在しないかを確認するには、次のクエリを実行します。

SELECT count(*) FROM pg_catalog.pg_prepared_xacts;

サポートされているデータ型を使用する

regclass、regrole、regtype データ型でのみ、バージョンをアップグレードできます。pg_upgrade ユーティリティは、reg* オブジェクト識別子 (OID) 参照タイプを使用するテーブル列を含むデータベースをアップグレードできません。regcollation、regconfig、regdictionary、regnamespace、regoper、regoperator、regproc、regprocedure データ型を使用している場合、アップグレードは失敗します。

この問題を解決するには、データエンジンをアップグレードする前に、regclass、regrole、regtype 以外のすべての reg* データ型の使用を廃止します。サポートされていない reg* データ型がテーブルに配置されていないかを確認するには、次のクエリを実行します。

SELECT count(*) FROM pg_catalog.pg_class c, pg_catalog.pg_namespace n, pg_catalog.pg_attribute a  WHERE c.oid = a.attrelid
      AND NOT a.attisdropped
      AND a.atttypid IN ('pg_catalog.regproc'::pg_catalog.regtype,
                         'pg_catalog.regprocedure'::pg_catalog.regtype,
                         'pg_catalog.regoper'::pg_catalog.regtype,
                         'pg_catalog.regoperator'::pg_catalog.regtype,
                         'pg_catalog.regconfig'::pg_catalog.regtype,
                         'pg_catalog.regdictionary'::pg_catalog.regtype)
      AND c.relnamespace = n.oid
      AND n.nspname NOT IN ('pg_catalog', 'information_schema');

論理レプリケーションスロットの有無を確認する

インスタンスに論理レプリケーションスロットが含まれる場合、そのインスタンスはアップグレードできず、pg_upgrade.log ファイルに次のエラーメッセージが表示されます。

「The instance could not be upgraded because one or more databases have logical replication slots.Please drop all logical replication slots and try again. (1 つ以上のデータベースに論理レプリケーションスロットが含まれるため、インスタンスをアップグレードできません。すべての論理レプリケーションスロットを削除してから、再試行してください)」

論理レプリケーションスロットは通常、AWS Database Migration Service (AMS DMS) の移行を行ったり、データベースからデータレイク、ビジネスインテリジェンスツール、その他のターゲットにテーブルを複製したりする目的で使用します。使用中の論理レプリケーションスロットの目的を把握し、削除できるかどうかを判断してください。使用中の論理レプリケーションスロットは、削除しないでください。論理レプリケーションスロットを削除できるようになるまで、バージョンのアップグレードを保留する必要があります。

論理レプリケーションスロットが不要な場合は、次のコマンドを実行して削除します。

SELECT * FROM pg_replication_slots;

SELECT pg_drop_replication_slot(slot_name);

注: slot_name を論理レプリケーションスロットの名前に置き換えてください。

ストレージの問題がないか確認する

pg_upgrade スクリプトの実行時にインスタンスの容量が枯渇すると、アップグレードは失敗し、次のエラーメッセージが表示されます。

「pg_restore: [archiver (db)] Error while PROCESSING TOC: pg_restore: [archiver (db)] could not execute query: ERROR: could not create file "base/12345/12345678": No space keyword" left on device」

この問題を解決するには、アップグレードを開始する前に、インスタンスに十分な空きストレージがあることを確認してください。

unknown データ型が存在しないか確認する

PostgreSQL バージョン 10 以降では、unknown データ型を使用できません。たとえば、PostgreSQL バージョン 9.6 のデータベースが unknown データ型を使用している場合、バージョン 10 にアップグレードすると次のエラーメッセージが表示されます。

「The instance could not be upgraded because the 'unknown' data type is used in user tables.Please remove all usages of the 'unknown' data type and try again. ('unknown' データ型の使用をすべて削除してから、再試行してください)」

この問題を解決するには、unknown データ型を使用する列を手動で削除するか、サポートされているデータ型に変更します。unknown データ型を使用しているデータベース内の列を見つけるには、次のクエリを実行します。

SELECT DISTINCT data_type FROM information_schema.columns WHERE data_type ILIKE 'unknown';

(RDS for PostgreSQL のみ) リードレプリカのアップグレードが失敗したかどうかを確認する

PostgreSQL インスタンスにリードレプリカがある場合、リードレプリカのアップグレードが失敗すると、プライマリインスタンスのアップグレードが停止したり失敗したりする可能性があります。Amazon RDS は、障害が発生したリードレプリカを非互換復元状態に設定し、DB インスタンスでのレプリケーションを停止します。

リードレプリカのアップグレードは、次のいずれかの理由で失敗する可能性があります。

• リードレプリカが、待機時間が経過してもプライマリ DB インスタンスに追いつくことができない。
• ストレージがいっぱいになったり、互換性がない状態で復元されたりするなど、リードレプリカがライフサイクルの終端または非互換状態になっている。
• プライマリ DB インスタンスのアップグレード開始時に、リードレプリカで別のマイナーバージョンアップグレードが実行されている。
• リードレプリカが互換性のないパラメータを使用している。
• リードレプリカがプライマリ DB インスタンスと通信してデータフォルダを同期できない。

この問題を解決するには、リードレプリカを削除します。次に、アップグレード後に、アップグレードしたプライマリインスタンスに基づく新しいリードレプリカを再作成します。

プライマリユーザー名が正確であることを確認する

プライマリユーザー名が pg_ で始まる場合、アップグレードは失敗し、次のエラーメッセージが表示されます。

「PreUpgrade checks failed: The instance could not be upgraded because one or more role names start with 'pg_'.Please rename all roles with names that start with 'pg_' and try again. (名前が 'pg_' で始まるすべてのロールの名前を変更してから、再試行してください)」

この問題を解決するには、先頭が pg_ ではなく、rds_superuser ロールを持つ別のユーザーを作成します。

非互換パラメータがないか確認する

shared_buffer、work_memory などのメモリに関連するパラメータ値が、使用する構成では高すぎる場合、「incompatible parameters」エラーが発生します。このエラーが発生すると、アップグレードスクリプトを実行できません。問題を解決するには、これらのパラメータの値を減らしてから、再度アップグレードを行います。

アップグレード前に拡張機能を更新する

メジャーバージョンのアップグレードでは、PostgreSQL の拡張機能はアップグレードされません。メジャーバージョンアップグレードの前に拡張機能を更新しなかった場合、pg_upgrade.log ファイルに次の例に類似したエラーメッセージが記録されます。

「The Logs indicates that the RDS instance ''abcd'' has older version of PostGIS extension or its dependent extensions (address_standardizer,address_standardizer_data_us, postgis_tiger_geocoder, postgis_topology, postgis_raster) installed as against the current version required for the upgrade. (RDS インスタンスに古いバージョンの PostGIS 拡張機能または、その依存拡張機能がインストールされています。アップグレードには現在のバージョンが必要です)」

上記のエラーメッセージ例は、PostGIS 拡張機能に問題があることを示しています。この問題を解決するには、次のクエリを実行し、PostGIS とその依存拡張機能のデフォルトバージョンとインストールバージョンを確認します。

SELECT name, default_version, installed_versionFROM pg_available_extensions WHERE installed_version IS NOT NULL AND
name LIKE 'postgis%' OR name LIKE 'address%';

注: postgis% を実際の拡張機能に置き換えてください。

installed_version の値が default_version の値よりも低い場合は、PostGIS をデフォルトバージョンに更新する必要があります。拡張機能をアップグレードするには、次のコマンドを実行します。

ALTER EXTENSION extension_name UPDATE TO 'default_version_number';

注: default_version_number を default_version の値に置き換えます。

詳細については、「RDS for PostgreSQL DB エンジンのアップグレード」または「Amazon Aurora PostgreSQL DB クラスターのアップグレード」を参照してください。

ビューで問題を引き起こしているターゲットバージョンのシステムカタログにおいて、変更の有無を確認する

一部のビューの列は、PostgreSQL のバージョンによって異なります。次のエラーメッセージ例に類似したメッセージが表示される場合があります。

「PreUpgrade checks failed: 1 つ以上のデータベースに 'pg_stat_activity' に依存するビューまたはマテリアライズドビューがあるため、インスタンスをアップグレードできませんでした。それらを削除してから、再試行してください。」

このエラーは、データベースをバージョン 9.5 から 9.6 にアップグレードする際に発生します。上記のエラーメッセージ例では、pg_stat_activity ビューが問題の原因となっています。バージョン 9.6 では、PostgreSQL の waiting 列が wait_event_type 列と wait_event 列に置き換えられました。

または、次のエラーメッセージ例に類似したメッセージが表示される場合があります。

「pg_restore: from TOC entry abc; abc abcd VIEW sys_user_constraints art pg_restore: error: could not execute query: ERROR: column c.consrc does not exist LINE 18: "c"."consrc" AS "search_condition", ^ HINT: Perhaps you meant to reference the column "c.conkey" or the column "c.conbin". (存在しない列が参照されました。正しい列の候補を示します)」

上記のエラーメッセージ例は、PostgreSQL バージョン 12 で pg_constraint カタログの構造が変更されたことが原因でエラーが発生したことを示しています。

これらの問題を解決するには、ターゲットバージョンのシステムカタログに基づいてビューを削除してください。

重要: ビューを削除する前に、pgdump を使用してビューをバックアップするか、ビューの定義をキャプチャすることをおすすめします。ビューを削除する場合、バージョンのアップグレード後に、ユーザーまたはデータベース管理者が手動でビューを再作成する必要があります。

アップグレードの完了

アップグレードの完了後、すべてのユーザーデータベースに ANALYZE を実行し、pg_statistics テーブルを更新します。メジャーアップグレードでは、pg_statistics テーブルのコンテンツは新しいバージョンに移動されません。コンテンツを移動しなかった場合、クエリの実行速度が遅くなる可能性があります。

関連情報

Aurora PostgreSQL のアップグレードプロセスの概要