PostgreSQL upgrades =================== .. raw:: html PostgreSQLのアップグレードは、2つのカテゴリに分類されます。 - :ref:`マイナーバージョンのアップグレード <マイナーバージョンのアップグレード>` 例 18.0から18.1 - :ref:`メジャーバージョンのアップグレード <メジャーバージョンのアップグレード>` 例、16.xから18.0 マイナーバージョンのアップグレード ---------------------------------- PostgreSQLバージョン番号は\ ``major.minor`` 形式に従います。例、バージョン18.1では - ``18`` はメジャーバージョンです - ``1`` はマイナーバージョンです マイナーリリースは、同じメジャーバージョンの以前および後のマイナーリリースと完全な互換性があります。これらにはバグ修正とセキュリティ更新が含まれていますが、内部ストレージ形式への変更は導入されません。 CloudNativePGのマイナーバージョンのアップグレード ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 新しいマイナーバージョンにアップグレードするには、クラスター定義のPostgreSQLコンテナイメージ参照を直接またはイメージカタログを介して更新するだけです。 CloudNativePGは :ref:`rolling update of the cluster ` をトリガーし、各インスタンスをレプリカから1つずつ置き換えます。すべてのレプリカが更新されると、プライマリのスイッチオーバーまたは再起動が実行されてプロセスが完了します。 メジャーバージョンのアップグレード ---------------------------------- PostgreSQLのメジャーリリースでは、内部データストレージ形式の変更が導入され、より構造化されたアップグレードプロセスが必要です。 CloudNativePGは、メジャーアップグレードを実行するための3つの方法をサポートしています。 1. :ref:`Logical dump/restore ` – ブルー/グリーン展開、オフライン。 2. :ref:`Native logical replication ` – ブルー/グリーン展開、オンライン。 3. ``pg_upgrade`` を使用した物理的 – インプレースアップグレード、オフライン 以下の :ref:`PostgreSQLのオフラインインプレースメジャーアップグレード ` でカバーされています。 各方法には、ダウンタイム、複雑さ、データ量の処理の点でトレードオフがあります。最適なアプローチは、アップグレード戦略と操作の制約によって異なります。 .. Note:: 運用アップグレードを続行する前に、制御された環境ですべてのメソッドをテストすることを強くお勧めします。 オフラインインプレースメジャーアップグレード -------------------------------------------- CloudNativePGは、より高いPostgreSQLメジャーバージョンを使用した新しいオペランドコンテナイメージがクラスターで宣言的に要求された場合、 **オフラインインプレースメジャーアップグレード** を実行します。 .. Note:: メジャーアップグレードは、同じオペレーティングシステムディストリビューションに基づくイメージ間でのみサポートされています。たとえば、以前のバージョンで`bullseye` イメージを使用している場合、`bookworm` イメージにアップグレードすることはできません。 .. Warning:: PostgreSQL 17.0〜17.5にはバグがあり、`max_slot_wal_keep_size` パラメーターが`-1` 以外の値に設定されている場合、アップグレードの成功を妨げます。アップグレードプロセスは、レプリケーションスロット構成に関連するエラーで失敗します。この号は `fixed in PostgreSQL 17.6 and 18 or later versions `_ になりました。 PostgreSQL 17.0〜17.5を使用している場合は、メジャーアップグレードを試みる前に少なくともPostgreSQL 17.6にアップグレードするか、クラスター構成で`max_slot_wal_keep_size` パラメーターを`-1` に一時的に設定してください。 次の2つの方法のいずれかでアップグレードをトリガーできます。 - ``.spec.imageName`` オプションを介してイメージタグのメジャーバージョンを更新することにより。 - :ref:`イメージカタログを使用する <イメージカタログを使用する>` を使用してバージョンの変更を管理する。 サポートされているイメージタグの詳細については、 :ref:`イメージタグの要件 <イメージタグの要件>` を参照してください。 .. Warning:: CloudNativePGはPostgreSQL拡張機能については責任を負いません。ソースPostgreSQLイメージの拡張機能がターゲットイメージの拡張機能と互換性があり、アップグレードパスがサポートされていることを確認する必要があります。予期しない問題を回避するために、事前にアップグレードプロセスを徹底的にテストしてください。 :ref:`extensions management feature ` 拡張機能のアップグレードを宣言的に管理するのに役立ちます。 アップグレードプロセス ^^^^^^^^^^^^^^^^^^^^^^ 1. すべてのクラスターポッドをシャットダウンして、データの一貫性を保証します。 2. 以前のPostgreSQLバージョンとイメージを\ ``.status.pgDataImageInfo`` の下のクラスターのステータスに記録します。 3. 新しいアップグレードジョブを開始します。 - イメージのバイナリとデータファイルがメジャーアップグレード要求と一致することを確認します。 - ``PGDATA`` 、および該当する場合はWALファイルとテーブルスペースの新しいディレクトリを作成します。 - 次を使用してアップグレードを実行します。 ``pg_upgrade`` ``--link`` オプションを使用した場合 - 正常に完了すると、元のディレクトリをアップグレードされた対応するディレクトリに置き換えます。 .. Warning:: アップグレードプロセス中、レプリカを含むPostgreSQLクラスター全体は、アプリケーションで使用できません。続行する前に、システムがこのダウンタイムを許容できることを確認してください。 .. Warning:: インプレースアップグレードの実行は、固有のリスクを伴う例外的な操作です。アップグレードプロセスを開始する前に、クラスターの完全なバックアップを作成することを強くお勧めします。 .. Note:: `pg_upgrade` の詳細なガイダンスについては、公式 `PostgreSQL documentation `_ を参照してください。 アップグレード後のアクション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ アップグレードが成功した場合、CloudNativePGは次のことを行います。 - レプリカのPVCを破壊します利用可能な場合。 - 必要に応じて、レプリカをスケールアップします。 .. Warning:: レプリカの再クローン作成は、特に非常に大規模なデータベースの場合、時間がかかる場合があります。潜在的な遅延に対応できるように、それに応じて計画を立てます。アップグレードが完了したら、できるだけ早く新しいベースバックアップを作成します。アップグレード前のバックアップとWALファイルは、メジャーバージョンの境界を越えたポイントインタイムリカバリーPITRに使用できません。 :ref:`バックアップとWALアーカイブの考慮事項 <バックアップとWALアーカイブの考慮事項>` を参照 詳細については、 .. Warning:: `pg_upgrade` は、オプティマイザー統計を転送しません。アップグレードの後、データベースで`ANALYZE` を実行して更新することができます。 アップグレードが失敗した場合は、クラスターの構成のイメージを以前のメジャーバージョンに戻します。オペレーターはロールバックを検出し、失敗したアップグレードジョブを自動的に削除するため、クラスターを元のバージョンで再起動できます。 .. Note:: このプロセスは、アップグレード中にデータが変更されないため、**既存のデータベースをデータ損失から保護します**。アップグレードが失敗した場合、通常はバックアップから完全なリカバリを実行せずにロールバックが可能です。プロセスを注意深く監視し、必要に応じて修正アクションを実行します。 メジャーアップグレード中の拡張機能 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ クラスターがイメージボリューム拡張を宣言すると、アップグレード\ ``Job`` は、ソースバージョンとターゲットバージョンの両方の拡張イメージをサイドバイサイドでマウントします。ソースバージョンの拡張機能が必要であるため、古いサーバーは、既に配置されている既存の共有ライブラリで起動できます。 ``pg_upgrade`` が新しいメジャーへのアップグレードを適切に実行できるように、ターゲットバージョンの拡張機能新しいPostgreSQLメジャー用に構築されたものも存在する必要があります。 - ソースバージョンの拡張機能は\ ``/extensions/`` 定常状態パスにマウントされているため、古い\ ``PGDATA`` の\ ``dynamic_library_path`` および\ ``extension_control_path`` GUCは既存の値を保持します。これにより、メジャーアップグレードが失敗した場合に、古いメジャーバージョンへの復帰がシームレスに機能します。 - ターゲットバージョンの拡張機能は、アップグレードジョブ中に\ ``/new-extensions/`` に一時的にマウントされ、 ``dynamic_library_path`` および\ ``extension_control_path`` は、新しいメジャーの\ ``PGDATA`` に応じて構成されます。 ``LD_LIBRARY_PATH`` および\ ``PATH`` は両方のセットで拡張されているため、どちらのバージョンのバイナリと共有オブジェクトも到達可能です。 ``extensions[].env`` を介して宣言された環境変数は、 :ref:`優先順位と競合の解決 <優先順位と競合の解決>` で説明されているルールに従います。 .. Note:: ターゲットバージョンのエントリは、ソースバージョンのエントリの**後**適用されます。両方に同じ変数が定義されている場合、ターゲットバージョンの値が優先されます。 ``pg_upgrade`` が\ ``update_extensions.sql`` を発行する場合 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``pg_upgrade`` は、ターゲットクラスターに\ ``default_version`` がインストールされたままのバージョン\ ``pg_upgrade`` より新しい拡張機能が含まれている場合、 ``PGDATA`` 内の\ ``update_extensions.sql`` スクリプトを発行します。そのスクリプトが適用されるまで、 ``pg_catalog`` のSQLレベルの拡張メタデータは、実行中のサーバーによって実際にロードされた共有ライブラリよりも遅延します。 スクリプトは、プライマリポッドの\ ``PGDATA`` 内にあります。データベーススーパーユーザー\ ``postgres`` を使用して実行して、すべてのデータベースのこれらの拡張機能を更新できます。 .. code:: sh PRIMARY=$(kubectl get cluster -o jsonpath={.status.currentPrimary}) SCRIPT=/var/lib/postgresql/data/pgdata/update_extensions.sql kubectl exec -i "$PRIMARY" -- psql -f "$SCRIPT" .. Note:: 上記のスクリプトパスは、CloudNativePGオペランドイメージが使用するデフォルトの`PGDATA` の場所を想定しています。オペレーターは、`pg_upgrade` がスクリプトを発行するときに解決されたパスもログに記録するため、オペランドイメージが別の`PGDATA` を使用しているかどうかをオペレーターログに確認します。 バックアップとWALアーカイブの考慮事項 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ メジャーアップグレードを実行すると、\ ``pg_upgrade`` は新しい_System ID_で新しいデータベースシステムを作成し、PostgreSQLタイムラインを1にリセットします。これは、バックアップとWALアーカイブに影響を与えます。 - **タイムラインファイルの競合** 新しいタイムライン1ファイルは、元のクラスターのタイムライン1ファイルを上書きする場合があります。 - **混合バージョンアーカイブ** 介入がなければ、アーカイブにはWALファイルと両方のPostgreSQLバージョンのバックアップが含まれます。 .. Warning:: ポイントインタイムリカバリーPITRは、メジャーPostgreSQLバージョンの境界を超えてサポートされていません。アップグレード前のバックアップを使用して、アップグレード後の特定の時点にリカバリすることはできません。アップグレード後できるだけ早く新しいベースバックアップを取得して、新しいメジャーバージョンのリカバリベースラインを確立します。 バックアップシステムがメジャーアップグレードを処理する方法は、プラグイン実装によって異なります。一部のプラグインは、アップグレード中にアーカイブの分離を自動的に管理する場合がありますが、メジャーバージョンごとに異なるアーカイブパスを使用するには手動構成が必要なプラグインもあります。メジャーアップグレード中の特定の動作については、バックアッププラグインのドキュメントを参照してください。 例Barman Cloudプラグインを使用した手動アーカイブパスの分離 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Barman Cloudプラグインは、メジャーアップグレード中にアーカイブを自動的に分離しません。アップグレード前のバックアップを保存し、アーカイブをクリーンな状態に保つには、アップグレードをトリガーするときに\ ``serverName`` パラメーターを変更します。 アップグレード前PostgreSQL 16 .. code:: yaml spec: imageName: ghcr.io/cloudnative-pg/postgresql:16-minimal-trixie plugins: - name: plugin-barman-cloud enabled: true parameters: destinationPath: s3://my-bucket/ serverName: cluster-example-pg16 アップグレードをトリガーするには、 ``imageName`` と\ ``serverName`` の両方を一緒に変更します。 .. code:: yaml spec: imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie plugins: - name: plugin-barman-cloud enabled: true parameters: destinationPath: s3://my-bucket/ serverName: cluster-example-pg18 この構成では、 ``cluster-example-pg16`` の古いアーカイブはアップグレード前リカバリーのためにそのまま残りますが、アップグレードされたクラスターは\ ``cluster-example-pg18`` に書き込みます。 .. Note:: 非推奨のツリー内`barmanObjectStore` 実装では、メジャーアップグレード中に別のアーカイブを手動で`serverName` 変更する必要があります。 例メジャーアップグレードの実行 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ バージョン16を実行している次のPostgreSQLクラスターを検討します。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example spec: imageName: ghcr.io/cloudnative-pg/postgresql:16-minimal-trixie instances: 3 storage: size: 1Gi 次のコマンドを使用して、現在のPostgreSQLバージョンを確認できます。 .. code:: sh kubectl cnpg psql cluster-example -- -qAt -c SELECT version() これにより、次のような出力が返されます。 .. code:: console PostgreSQL 16.x ... クラスターをバージョン18にアップグレードするには、メジャーバージョンタグを\ ``16`` から\ ``18`` に変更して、\ ``imageName`` フィールドを更新します。 .. code:: yaml apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-example spec: imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie instances: 3 storage: size: 1Gi .. _アップグレードプロセス-1: アップグレードプロセス ^^^^^^^^^^^^^^^^^^^^^^ 1. クラスターのシャットダウン – 一貫したアップグレードを保証するために、すべてのクラスターポッドが終了します。 2. アップグレードジョブの実行 – 新しいジョブは、プライマリポッドの名前にサフィックス ``-major-upgrade`` を追加した名前で作成されます。このジョブは、プライマリの永続ボリュームグループで\ ``pg_upgrade`` を実行します。 3. アップグレード後の手順 - レプリカのPVCグループ ``cluster-example-2`` および\ ``cluster-example-3`` が削除されます。 - プライマリポッドが再起動されます。 - 2つの新しいレプリカ ``cluster-example-2`` および\ ``cluster-example-3`` が、アップグレードされたプライマリから再クローンされます。 アップグレードが完了すると、同じコマンドを実行して新しいメジャーバージョンを確認できます。 .. code:: sh kubectl cnpg psql cluster-example -- -qAt -c SELECT version() これにより、次のような出力が返されます。 .. code:: console PostgreSQL 18.x ... ``app`` データベースで\ ``ANALYZE`` を実行することにより、統計を更新できるようになりました。 .. code:: sh kubectl cnpg psql cluster-example -- app -c ANALYZE