MENU

Azure PostgreSQLのメジャー更新失敗を防ぐ｜–validate-only事前検証の手順

Azure

Azure Database for PostgreSQL Flexible Serverでメジャーバージョンアップグレードを予定している場合、最初に行うべき作業は本番アップグレードではありません。Azure portalの「Validate only」またはAzure CLIの--validate-onlyを使い、事前アップグレード検証を実行します。

この機能は、実際のアップグレードを開始せずに、非対応Extension、Replication Slot、Prepared Transaction、設定不一致などのブロッカーを検出します。問題を解消し、検証に合格するまで再実行してから本番アップグレードへ進むのが基本です。

事前アップグレード検証は2026年8月に一般提供されました。Azure Database for PostgreSQLのアップグレードポリシーと、PostgreSQLのpg_upgrade --checkに基づく互換性確認を事前に実行できるため、アップグレード当日に初めて問題が判明するリスクを減らせます。

目次

PostgreSQL Flexible Serverの事前アップグレード検証とは

事前アップグレード検証は、現在のAzure Database for PostgreSQL Flexible Serverが、指定したPostgreSQLメジャーバージョンへ更新できる状態かを確認する機能です。

検証では、主に次のような項目が確認されます。

  • 対象バージョンで利用できないExtension
  • 論理Replication Slot
  • 未解決のPrepared Transaction
  • Event Trigger
  • Extensionやシステムオブジェクトへの依存関係
  • 再起動が必要なまま保留されている設定変更
  • PostgreSQLバージョン間の設定不一致
  • Azure Database for PostgreSQLのアップグレードポリシーに抵触する構成

実際のメジャーバージョンアップグレードでも同様の事前チェックが実行されます。しかし、--validate-onlyを先に実行しておけば、本番停止時間に入る前に問題を洗い出し、修正できます。([Microsoft Learn][1])

検証と実際のアップグレードの違い

項目Validate only実際のアップグレード
PostgreSQLバージョン変更されない指定バージョンへ変更される
サーバー再起動発生しない発生する
ダウンタイム発生しない発生する
主な目的ブロッカーの検出データベースエンジンの更新
問題検出時修正後に再実行できるアップグレードが停止または失敗する
元バージョンへの復帰不要成功後の自動ダウングレードはできない

Validate onlyはあくまで「アップグレード可能性の検証」です。コマンドを実行しても、PostgreSQLのバージョンは変更されません。([Microsoft Learn][2])

Validate onlyを実行する前の確認事項

事前アップグレード検証を開始する前に、以下の条件を確認します。

  • サーバーの状態がReadyになっている
  • バックアップ、スケール変更、再起動など、別のサーバー操作が実行中ではない
  • 検証対象が読み取りレプリカではない
  • サーバー内のすべてのデータベースへ接続できる
  • Azureが現在サポートしているアップグレード先バージョンを選択している
  • Azure CLIを使う場合は、バージョン2.89.0以降を利用している

応答しないデータベースや接続できないデータベースが一つでも存在すると、検証が失敗する可能性があります。また、検証自体にダウンタイムはありませんが、低負荷の時間帯に実行することが推奨されています。([Microsoft Learn][1])

サーバー内のデータベースを確認するSQL

複数のデータベースを運用している場合は、接続可能なデータベースを事前に確認しておきます。

SELECT
    datname,
    datallowconn
FROM pg_database
WHERE NOT datistemplate
ORDER BY datname;

datallowconnがtrueのデータベースには、管理者アカウントで実際に接続できるか確認してください。ExtensionやEvent Triggerはデータベース単位で存在するため、postgresデータベースだけを調べても不十分です。

Azure portalで事前アップグレード検証を実行する手順

Azure portalでは、コマンドを入力せずにValidate onlyを実行できます。

  1. Azure portalで対象のAzure Database for PostgreSQL Flexible Serverを開きます。
  2. リソースメニューから「概要」を選択します。
  3. サーバーの状態が「Ready」であることを確認します。
  4. 「アップグレード」を選択します。
  5. アップグレード先のPostgreSQLメジャーバージョンを選択します。
  6. Actionで「Validate only」を選択します。
  7. 「Start」を選択します。
  8. 検証が完了するまで、検証状況の画面を開いたままにします。
  9. 失敗したチェックと修正方法を確認します。

検証に成功した場合は、結果をCSVファイルとしてダウンロードできます。ブロッカーが検出された場合は、エラーの詳細と推奨される修正方法を確認し、修正後にValidate onlyを再実行します。([Microsoft Learn][2])

Portalが向いているケース

Azure portalは、次のような場合に向いています。

  • 1台または少数のサーバーを手動で更新する
  • 担当者がAzure CLIを日常的に使用していない
  • 検証結果をCSVで保存し、関係者と共有したい
  • エラー内容と修正案を画面上で確認したい

本番変更の申請や作業記録が必要な組織では、CSVを変更管理票に添付しておくと、アップグレード前の確認証跡として利用できます。

Azure CLIの–validate-onlyで検証する手順

複数環境で同じチェックを実行する場合や、検証手順をスクリプト化する場合はAzure CLIが便利です。

Azure CLIはバージョン2.89.0以降が必要です。まず、現在のバージョンを確認します。

az --version

利用するサブスクリプションも確認しておきます。

az account show --output table

サブスクリプションを切り替える場合は、次のコマンドを実行します。

az account set --subscription "<サブスクリプション名またはID>"

事前アップグレード検証は、az postgres flexible-server upgradeコマンドに--validate-onlyを付けて実行します。

az postgres flexible-server upgrade \
  --resource-group <リソースグループ名> \
  --name <サーバー名> \
  --version <アップグレード先バージョン> \
  --validate-only

たとえば、rg-production内のpg-flex-prodをPostgreSQL 17へ更新できるか確認する場合は、次のように実行します。

az postgres flexible-server upgrade \
  --resource-group rg-production \
  --name pg-flex-prod \
  --version 17 \
  --validate-only

コマンド名にはupgradeが含まれていますが、--validate-onlyを付けている限り、実際のアップグレードは実行されません。検証結果にブロッカーが表示された場合は、問題を修正して同じコマンドを再実行します。([Microsoft Learn][2])

注意: --validate-onlyを外すと、実際のメジャーバージョンアップグレードが開始されます。検証用コマンドをコピーするときは、オプションが付いていることを必ず確認してください。

検証結果の読み方

Validate onlyの結果は、概ね次の2種類に分かれます。

No blocking issues detected

アップグレードを妨げる問題が検出されなかった状態です。

ただし、これは「アプリケーションを含めて完全に問題がない」という意味ではありません。サーバー構成上のアップグレードブロッカーが見つからなかったことを示します。

検証後にスキーマ、Extension、サーバーパラメーター、Replication Slotなどを変更した場合は、本番アップグレード前にもう一度検証してください。

Blocking issues detected

アップグレードを開始する前に解消すべき問題が検出された状態です。

複数のエラーが出た場合は、表示された順番に機械的に直すのではなく、次の単位で分類すると作業しやすくなります。

  • Extension関連
  • レプリケーション関連
  • トランザクション関連
  • サーバーパラメーター関連
  • データベースオブジェクト関連
  • ネットワークや接続関連

一つの原因から複数のエラーが派生していることもあります。最初にエラーを分類し、原因ごとに修正してから再検証する方が効率的です。

代表的なアップグレードブロッカーと対応方法

アップグレードの互換性要件は、現在のPostgreSQLバージョンとアップグレード先バージョンの組み合わせによって変わります。固定されたExtension一覧だけで判断せず、Validate onlyが返した結果と最新のMicrosoftドキュメントを基準にしてください。([Microsoft Learn][1])

ブロッカー確認するポイント対応の考え方
非対応ExtensionExtension名、バージョン、依存オブジェクト定義と依存関係を記録し、必要なExtensionだけ一時的に削除する
Replication Slot利用中のスロット、接続元、active状態利用者と停止手順を確認し、必要に応じて削除・再作成する
Prepared TransactionGID、所有者、作成日時、対象DB業務トランザクションの状態を確認し、commitまたはrollbackする
設定不一致再起動待ち、廃止予定パラメーター設定を修正し、必要なら再起動してから再検証する
Event Triggerトリガー名、実行関数、DDL依存定義を保存して一時削除し、更新後に再作成する
オブジェクト依存View、Function、Extensionへの依存依存元を特定し、更新可能な状態へ整理する
DB接続失敗全データベースへの接続可否認証、接続制限、データベース状態を確認する

Extensionを確認する

次のSQLは、接続中のデータベースにインストールされているExtensionを表示します。

SELECT
    extname,
    extversion
FROM pg_extension
ORDER BY extname;

このSQLは、サーバー内のデータベースごとに実行してください。

Validate onlyで非対応と判定されたExtensionは、アップグレード前にDROP EXTENSIONが必要になることがあります。ただし、いきなり削除してはいけません。

事前に次の項目を確認します。

  • アプリケーションがExtensionの関数や型を使用していないか
  • ViewやFunctionがExtensionのオブジェクトに依存していないか
  • アップグレード後のバージョンで再作成できるか
  • Extensionの作成SQLや設定値を記録しているか
  • データを保持するExtensionか、再作成可能な補助Extensionか

DROP EXTENSION ... CASCADEを安易に使うと、依存しているViewやFunctionまで削除される可能性があります。依存関係を確認せずに実行しないでください。

Microsoftのドキュメントでは、非対応Extensionを削除する際、Azureの許可リストからまで削除する必要はなく、データベース上でDROP EXTENSIONを実行することが求められています。([Microsoft Learn][1])

Replication Slotを確認する

Replication Slotは次のSQLで確認できます。

SELECT
    slot_name,
    slot_type,
    active,
    database,
    plugin
FROM pg_replication_slots
ORDER BY slot_name;

スロットが表示された場合は、削除する前に次の情報を整理します。

  • どのサービスやアプリケーションが使用しているか
  • Azure Data FactoryやDebeziumなどのCDC処理で使われていないか
  • スロットを停止した場合にデータ欠落が発生しないか
  • アップグレード後に同じ位置から再開できるか
  • スロットの再作成手順があるか

使用中のReplication Slotを確認せずに削除すると、論理レプリケーションやCDC処理が停止する可能性があります。Validate onlyで指摘されたからといって、直ちに削除するのではなく、レプリケーション利用者と復旧手順を確認してから対応します。

Prepared Transactionを確認する

未解決のPrepared Transactionは、次のSQLで確認できます。

SELECT
    gid,
    prepared,
    owner,
    database
FROM pg_prepared_xacts
ORDER BY prepared;

Prepared Transactionは、二相コミットを利用するシステムで作成されます。古いPrepared Transactionが残っていても、単純にロールバックしてよいとは限りません。

確認すべきポイントは次のとおりです。

  • 対象GIDを作成したアプリケーション
  • 関連する外部システムのトランザクション状態
  • commitすべき処理か、rollbackすべき処理か
  • 長期間残っている理由
  • アプリケーション停止中に再作成されないか

業務上の整合性を確認したうえで、COMMIT PREPAREDまたはROLLBACK PREPAREDを実行します。

再起動待ちの設定を確認する

サーバーパラメーターを変更したものの、まだ再起動していない場合は、設定が保留状態になっていることがあります。

次のSQLで確認できます。

SELECT
    name,
    setting,
    source,
    pending_restart
FROM pg_settings
WHERE pending_restart;

結果が表示された場合は、対象パラメーターの影響を確認し、必要に応じてAzure portalまたはAzure CLIからサーバーを再起動します。

再起動後は、設定が反映されたことを確認してからValidate onlyを再実行します。

Event Triggerを確認する

Event Triggerは、DDL実行時に呼び出され、メジャーバージョン間で変化するシステムカタログを参照している可能性があります。そのため、アップグレード前チェックでブロックされます。([Microsoft Learn][1])

接続中のデータベースにあるEvent Triggerは、次のSQLで確認できます。

SELECT
    evtname,
    evtevent,
    evtenabled
FROM pg_event_trigger
ORDER BY evtname;

削除前に、Event Trigger本体だけでなく、呼び出しているFunctionの定義も保存します。アップグレード後は、新しいPostgreSQLバージョンで動作を確認してから再作成してください。

詳細ログを確認する方法

Portalの検証結果だけでは原因を特定できない場合は、アップグレード検証ログを確認します。

Azure portalで次の順に開きます。

  1. 対象のPostgreSQL Flexible Serverを開きます。
  2. 「Monitoring」配下の「Server logs」を選択します。
  3. 生成されたpg_upgrade関連ログを探します。
  4. ログをダウンロードして詳細を確認します。

検証ログをダウンロードするには、事前にサーバーログを有効にしておく必要があります。PortalからダウンロードできるCSVには、チェック名、成功・失敗、エラー内容、推奨される修正方法が含まれます。([Microsoft Learn][2])

本番作業前には、少なくとも次の証跡を保存しておくと安心です。

  • Validate onlyの実行日時
  • 対象サーバー名
  • 現在のPostgreSQLバージョン
  • アップグレード先バージョン
  • 検証結果のCSV
  • 修正した設定やオブジェクト
  • 最終検証の成功結果

検証に合格するまでの実務的な進め方

Validate onlyは、一度実行して終わりではありません。次の流れで繰り返します。

最初の検証を実行する

まずは現在の状態を変えずにValidate onlyを実行し、ブロッカーをすべて取得します。

エラーを原因別に分類する

Extension、Replication Slot、Prepared Transaction、設定、オブジェクト依存などに分類します。

影響の小さい問題から修正する

再起動待ち設定や未使用Extensionなど、影響範囲を確認しやすいものから対応します。

Validate onlyを再実行する

修正後に同じ対象バージョンを指定して再検証します。新しいエラーが表示される場合もあるため、一度の修正ですべて解消するとは限りません。

最終検証後は構成変更を抑える

検証成功後にExtension、スキーマ、レプリケーション設定、サーバーパラメーターを変更すると、結果が変わる可能性があります。

本番アップグレード直前にもValidate onlyを実行し、「No blocking issues detected」であることを確認するのが安全です。

Validate onlyに合格しても必要なテスト

Validate onlyは、サーバーがメジャーバージョンアップグレード可能な状態かを判定する機能です。アプリケーションのすべての動作を保証するものではありません。

PostgreSQLのメジャーバージョンでは、SQLの動作、システムカタログ、設定パラメーター、Extension、クエリプランなどに互換性のない変更が含まれる可能性があります。([Microsoft Learn][1])

本番前には、検証環境で次の項目も確認します。

  • アプリケーションから正常に接続できる
  • JDBC、Npgsql、psycopgなどのドライバーが対応している
  • ORMが生成するSQLがエラーにならない
  • バッチ処理やストアドFunctionが動作する
  • Extensionを利用する機能が動作する
  • 読み取り・更新・削除の基本処理が成功する
  • バックアップ、監視、ログ収集が動作する
  • クエリ性能が大きく悪化していない
  • レプリケーションやCDC処理を再開できる

可能であれば、本番サーバーのPoint-in-time Restoreで検証用サーバーを作成し、実データに近い状態でアプリケーションテストを行います。

本番アップグレード前のチェックリスト

実際のメジャーバージョンアップグレードを開始する前に、次の項目を確認します。

確認項目判断基準
Validate onlyブロッカーなしで完了している
空きストレージ少なくとも10～20％程度を確保している
メンテナンス時間アプリケーション停止を含む作業枠を確保している
長時間トランザクション事前に終了または停止できる
バッチ・ジョブアップグレード中に起動しない
HA再有効化に必要なリージョン容量とネットワークを確認している
NSG・通信5432、6432および必要なAzure Storage通信を妨げていない
復旧計画PITRで旧バージョン相当の新規サーバーを作る手順がある
アプリケーションテスト接続、主要処理、性能確認の手順がある
作業証跡CSV、ログ、変更内容を保存している

実際のアップグレードでは、一時ログやメタデータ処理により追加のストレージが必要になります。Microsoftは、開始前に10～20％程度の空きストレージを確保するよう案内しています。([Microsoft Learn][1])

高可用性が有効なサーバーでは、アップグレード時にHAが一時的に無効化され、プライマリの更新後に再有効化されます。スタンバイを再作成できるリージョン容量や、NSGによる通信制限も確認してください。([Microsoft Learn][1])

本番アップグレードを実行する際の注意点

Azure CLIでは、検証時のコマンドから--validate-onlyを外すと実際のアップグレードが開始されます。

az postgres flexible-server upgrade \
  --resource-group rg-production \
  --name pg-flex-prod \
  --version 17

このコマンドはサーバー停止を伴う本番操作です。変更承認、利用者への周知、アプリケーション停止、監視の一時抑止などを完了してから実行してください。

アップグレードが成功した後に、以前のPostgreSQLバージョンへそのまま戻す自動的な方法はありません。元のバージョンが必要になった場合は、アップグレード前の時点へPoint-in-time Restoreし、別サーバーとして復元する方法が基本となります。([Microsoft Learn][1])

アップグレード後に実施する作業

メジャーバージョンアップグレードが完了したら、バージョン表示だけを確認して作業を終了してはいけません。

最初に各データベースへ接続し、統計情報を更新します。

ANALYZE;

PostgreSQLでは、統計情報が古いままだと不適切なクエリプランが選択され、アップグレード後に性能が悪化することがあります。Microsoftも、アップグレード後に各データベースでANALYZEを実行するよう案内しています。([Microsoft Learn][1])

続いて、次の項目を確認します。

  • PostgreSQLのバージョン
  • アプリケーションからの接続
  • 主要な検索・登録・更新処理
  • エラーログ
  • CPU、メモリ、ストレージIO
  • 接続数とロック状況
  • バッチ処理
  • Extensionの再作成または更新
  • Replication SlotやCDC処理の再開
  • HAの再有効化状態
  • バックアップの取得状態

アップグレード前に一時削除したExtension、Event Trigger、Replication Slotなどは、定義を確認しながら順番に復元します。

よくある質問

Validate onlyを実行するとサービスは停止しますか

停止しません。検証ではPostgreSQLバージョンの変更、サーバー再起動、ダウンタイムは発生しません。ただし、すべてのデータベースに対する確認が行われるため、低負荷の時間帯に実行するのが安全です。([Microsoft Learn][1])

読み取りレプリカで検証できますか

読み取りレプリカではUpgrade Validation Checksを実行できません。プライマリサーバー側で検証します。実際のインプレースアップグレードでは、構成によってレプリカの削除や再作成が必要になる場合があります。([Microsoft Learn][1])

一度合格すれば本番当日の再検証は不要ですか

検証後に構成変更がなければ結果が変わらない可能性は高いものの、本番直前の再検証を推奨します。

特に次の変更があった場合は、必ず再実行してください。

  • Extensionの追加や更新
  • Replication Slotの作成
  • サーバーパラメーター変更
  • Event Triggerの追加
  • データベースやスキーマの追加
  • アプリケーションのリリース

Validate onlyに合格すればアップグレードは必ず成功しますか

成功率を高めるための重要なチェックですが、絶対的な保証ではありません。

検証後の構成変更、ストレージ不足、ネットワーク制限、リージョン容量、長時間トランザクション、高負荷などにより、実際のアップグレードで問題が発生する可能性があります。また、アプリケーションのSQLやドライバーの互換性は別途テストが必要です。

Extensionの対応可否はどこで判断しますか

Validate onlyの結果と、Microsoftが公開している対象バージョン別の最新ドキュメントで判断します。

Extensionの制約は、アップグレード元とアップグレード先の組み合わせによって変わります。過去に作成した固定一覧や、別バージョンでの成功事例だけを根拠にしないでください。([Microsoft Learn][1])

本番アップグレードは「検証・修正・再検証」の順で進める

Azure Database for PostgreSQL Flexible Serverのメジャーバージョンアップグレードでは、本番作業を開始してからブロッカーに気付く進め方を避ける必要があります。

Azure portalの「Validate only」またはAzure CLIの--validate-onlyを使い、次の順序で進めます。

  1. アップグレード先バージョンを決める
  2. Validate onlyを実行する
  3. 非対応ExtensionやReplication Slotなどを整理する
  4. 問題を修正する
  5. 合格するまでValidate onlyを再実行する
  6. 検証環境でアプリケーションをテストする
  7. 空きストレージと復旧手順を確認する
  8. 本番メンテナンス時間内にアップグレードする
  9. ANALYZEと動作確認を実施する

重要なのは、Validate onlyを単なる事前確認ではなく、アップグレード計画の開始地点として扱うことです。最終検証の成功結果を証跡として残し、サーバー構成とアプリケーションの両方を確認してから本番更新へ進んでください。
[1]: https://learn.microsoft.com/en-us/azure/postgresql/configure-maintain/concepts-major-version-upgrade “Major Version Upgrades – Azure Database for PostgreSQL | Microsoft Learn”
[2]: https://learn.microsoft.com/en-us/azure/postgresql/configure-maintain/how-to-run-upgrade-validation-checks “Upgrade Validation Checks in Azure Database for PostgreSQL Flexible Server – Azure Database for PostgreSQL | Microsoft Learn”

Azure
Azure CLI Azure Database for PostgreSQL PostgreSQL Flexible Server メジャーバージョンアップグレード

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次