PostgreSQL upgrades

PostgreSQLのアップグレードは、2つのカテゴリに分類されます。

マイナーバージョンのアップグレード例 18.0から18.1
メジャーバージョンのアップグレード例、16.xから18.0

マイナーバージョンのアップグレード

PostgreSQLバージョン番号はmajor.minor 形式に従います。例、バージョン18.1では

18 はメジャーバージョンです
1 はマイナーバージョンです

マイナーリリースは、同じメジャーバージョンの以前および後のマイナーリリースと完全な互換性があります。これらにはバグ修正とセキュリティ更新が含まれていますが、内部ストレージ形式への変更は導入されません。

CloudNativePGのマイナーバージョンのアップグレード

新しいマイナーバージョンにアップグレードするには、クラスター定義のPostgreSQLコンテナイメージ参照を直接またはイメージカタログを介して更新するだけです。 CloudNativePGは rolling update of the cluster をトリガーし、各インスタンスをレプリカから1つずつ置き換えます。すべてのレプリカが更新されると、プライマリのスイッチオーバーまたは再起動が実行されてプロセスが完了します。

メジャーバージョンのアップグレード

PostgreSQLのメジャーリリースでは、内部データストレージ形式の変更が導入され、より構造化されたアップグレードプロセスが必要です。

CloudNativePGは、メジャーアップグレードを実行するための3つの方法をサポートしています。

Logical dump/restore – ブルー/グリーン展開、オフライン。
Native logical replication – ブルー/グリーン展開、オンライン。
pg_upgrade を使用した物理的 – インプレースアップグレード、オフライン以下の PostgreSQLのオフラインインプレースメジャーアップグレードでカバーされています。

各方法には、ダウンタイム、複雑さ、データ量の処理の点でトレードオフがあります。最適なアプローチは、アップグレード戦略と操作の制約によって異なります。

注釈

運用アップグレードを続行する前に、制御された環境ですべてのメソッドをテストすることを強くお勧めします。

オフラインインプレースメジャーアップグレード

CloudNativePGは、より高いPostgreSQLメジャーバージョンを使用した新しいオペランドコンテナイメージがクラスターで宣言的に要求された場合、 オフラインインプレースメジャーアップグレード を実行します。

注釈

メジャーアップグレードは、同じオペレーティングシステムディストリビューションに基づくイメージ間でのみサポートされています。たとえば、以前のバージョンで`bullseye` イメージを使用している場合、bookworm イメージにアップグレードすることはできません。

警告

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 オプションを介してイメージタグのメジャーバージョンを更新することにより。
イメージカタログを使用するを使用してバージョンの変更を管理する。

サポートされているイメージタグの詳細については、イメージタグの要件を参照してください。

警告

CloudNativePGはPostgreSQL拡張機能については責任を負いません。ソースPostgreSQLイメージの拡張機能がターゲットイメージの拡張機能と互換性があり、アップグレードパスがサポートされていることを確認する必要があります。予期しない問題を回避するために、事前にアップグレードプロセスを徹底的にテストしてください。 extensions management feature

拡張機能のアップグレードを宣言的に管理するのに役立ちます。

アップグレードプロセス

すべてのクラスターポッドをシャットダウンして、データの一貫性を保証します。
以前のPostgreSQLバージョンとイメージを.status.pgDataImageInfo の下のクラスターのステータスに記録します。
新しいアップグレードジョブを開始します。

イメージのバイナリとデータファイルがメジャーアップグレード要求と一致することを確認します。
PGDATA 、および該当する場合はWALファイルとテーブルスペースの新しいディレクトリを作成します。
次を使用してアップグレードを実行します。 pg_upgrade --link オプションを使用した場合
正常に完了すると、元のディレクトリをアップグレードされた対応するディレクトリに置き換えます。

警告

アップグレードプロセス中、レプリカを含むPostgreSQLクラスター全体は、アプリケーションで使用できません。続行する前に、システムがこのダウンタイムを許容できることを確認してください。

警告

インプレースアップグレードの実行は、固有のリスクを伴う例外的な操作です。アップグレードプロセスを開始する前に、クラスターの完全なバックアップを作成することを強くお勧めします。

注釈

pg_upgrade の詳細なガイダンスについては、公式 PostgreSQL documentation を参照してください。

アップグレード後のアクション

アップグレードが成功した場合、CloudNativePGは次のことを行います。

レプリカのPVCを破壊します利用可能な場合。
必要に応じて、レプリカをスケールアップします。

警告

レプリカの再クローン作成は、特に非常に大規模なデータベースの場合、時間がかかる場合があります。潜在的な遅延に対応できるように、それに応じて計画を立てます。アップグレードが完了したら、できるだけ早く新しいベースバックアップを作成します。アップグレード前のバックアップとWALファイルは、メジャーバージョンの境界を越えたポイントインタイムリカバリーPITRに使用できません。バックアップとWALアーカイブの考慮事項を参照

詳細については、

警告

pg_upgrade は、オプティマイザー統計を転送しません。アップグレードの後、データベースで`ANALYZE` を実行して更新することができます。

アップグレードが失敗した場合は、クラスターの構成のイメージを以前のメジャーバージョンに戻します。オペレーターはロールバックを検出し、失敗したアップグレードジョブを自動的に削除するため、クラスターを元のバージョンで再起動できます。

注釈

このプロセスは、アップグレード中にデータが変更されないため、既存のデータベースをデータ損失から保護します。アップグレードが失敗した場合、通常はバックアップから完全なリカバリを実行せずにロールバックが可能です。プロセスを注意深く監視し、必要に応じて修正アクションを実行します。

メジャーアップグレード中の拡張機能

クラスターがイメージボリューム拡張を宣言すると、アップグレードJob は、ソースバージョンとターゲットバージョンの両方の拡張イメージをサイドバイサイドでマウントします。ソースバージョンの拡張機能が必要であるため、古いサーバーは、既に配置されている既存の共有ライブラリで起動できます。 pg_upgrade が新しいメジャーへのアップグレードを適切に実行できるように、ターゲットバージョンの拡張機能新しいPostgreSQLメジャー用に構築されたものも存在する必要があります。

ソースバージョンの拡張機能は/extensions/<name> 定常状態パスにマウントされているため、古いPGDATA のdynamic_library_path およびextension_control_path GUCは既存の値を保持します。これにより、メジャーアップグレードが失敗した場合に、古いメジャーバージョンへの復帰がシームレスに機能します。
ターゲットバージョンの拡張機能は、アップグレードジョブ中に/new-extensions/<name> に一時的にマウントされ、 dynamic_library_path およびextension_control_path は、新しいメジャーのPGDATA に応じて構成されます。

LD_LIBRARY_PATH およびPATH は両方のセットで拡張されているため、どちらのバージョンのバイナリと共有オブジェクトも到達可能です。 extensions[].env を介して宣言された環境変数は、優先順位と競合の解決で説明されているルールに従います。

注釈

ターゲットバージョンのエントリは、ソースバージョンのエントリの**後**適用されます。両方に同じ変数が定義されている場合、ターゲットバージョンの値が優先されます。

`pg_upgrade` が`update_extensions.sql` を発行する場合

pg_upgrade は、ターゲットクラスターにdefault_version がインストールされたままのバージョンpg_upgrade より新しい拡張機能が含まれている場合、 PGDATA 内のupdate_extensions.sql スクリプトを発行します。そのスクリプトが適用されるまで、 pg_catalog のSQLレベルの拡張メタデータは、実行中のサーバーによって実際にロードされた共有ライブラリよりも遅延します。

スクリプトは、プライマリポッドのPGDATA 内にあります。データベーススーパーユーザーpostgres を使用して実行して、すべてのデータベースのこれらの拡張機能を更新できます。

PRIMARY=$(kubectl get cluster <name> -o jsonpath={.status.currentPrimary})
SCRIPT=/var/lib/postgresql/data/pgdata/update_extensions.sql

kubectl exec -i "$PRIMARY" -- psql -f "$SCRIPT"

注釈

上記のスクリプトパスは、CloudNativePGオペランドイメージが使用するデフォルトの`PGDATA` の場所を想定しています。オペレーターは、pg_upgrade がスクリプトを発行するときに解決されたパスもログに記録するため、オペランドイメージが別の`PGDATA` を使用しているかどうかをオペレーターログに確認します。

バックアップとWALアーカイブの考慮事項

メジャーアップグレードを実行すると、pg_upgrade は新しい_System ID_で新しいデータベースシステムを作成し、PostgreSQLタイムラインを1にリセットします。これは、バックアップとWALアーカイブに影響を与えます。

タイムラインファイルの競合 新しいタイムライン1ファイルは、元のクラスターのタイムライン1ファイルを上書きする場合があります。
混合バージョンアーカイブ 介入がなければ、アーカイブにはWALファイルと両方のPostgreSQLバージョンのバックアップが含まれます。

警告

ポイントインタイムリカバリーPITRは、メジャーPostgreSQLバージョンの境界を超えてサポートされていません。アップグレード前のバックアップを使用して、アップグレード後の特定の時点にリカバリすることはできません。アップグレード後できるだけ早く新しいベースバックアップを取得して、新しいメジャーバージョンのリカバリベースラインを確立します。

バックアップシステムがメジャーアップグレードを処理する方法は、プラグイン実装によって異なります。一部のプラグインは、アップグレード中にアーカイブの分離を自動的に管理する場合がありますが、メジャーバージョンごとに異なるアーカイブパスを使用するには手動構成が必要なプラグインもあります。メジャーアップグレード中の特定の動作については、バックアッププラグインのドキュメントを参照してください。

例Barman Cloudプラグインを使用した手動アーカイブパスの分離

Barman Cloudプラグインは、メジャーアップグレード中にアーカイブを自動的に分離しません。アップグレード前のバックアップを保存し、アーカイブをクリーンな状態に保つには、アップグレードをトリガーするときにserverName パラメーターを変更します。

アップグレード前PostgreSQL 16

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 の両方を一緒に変更します。

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 に書き込みます。

注釈

非推奨のツリー内`barmanObjectStore` 実装では、メジャーアップグレード中に別のアーカイブを手動で`serverName` 変更する必要があります。

例メジャーアップグレードの実行

バージョン16を実行している次のPostgreSQLクラスターを検討します。

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バージョンを確認できます。

kubectl cnpg psql cluster-example -- -qAt -c SELECT version()

これにより、次のような出力が返されます。

PostgreSQL 16.x ...

クラスターをバージョン18にアップグレードするには、メジャーバージョンタグを16 から18 に変更して、imageName フィールドを更新します。

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

アップグレードプロセス

クラスターのシャットダウン – 一貫したアップグレードを保証するために、すべてのクラスターポッドが終了します。
アップグレードジョブの実行 – 新しいジョブは、プライマリポッドの名前にサフィックス -major-upgrade を追加した名前で作成されます。このジョブは、プライマリの永続ボリュームグループでpg_upgrade を実行します。
アップグレード後の手順

レプリカのPVCグループ cluster-example-2 およびcluster-example-3 が削除されます。
プライマリポッドが再起動されます。
2つの新しいレプリカ cluster-example-2 およびcluster-example-3 が、アップグレードされたプライマリから再クローンされます。

アップグレードが完了すると、同じコマンドを実行して新しいメジャーバージョンを確認できます。

kubectl cnpg psql cluster-example -- -qAt -c SELECT version()

これにより、次のような出力が返されます。

PostgreSQL 18.x ...

app データベースでANALYZE を実行することにより、統計を更新できるようになりました。

kubectl cnpg psql cluster-example -- app -c ANALYZE

PostgreSQL upgrades

マイナーバージョンのアップグレード

CloudNativePGのマイナーバージョンのアップグレード

メジャーバージョンのアップグレード

オフラインインプレースメジャーアップグレード

アップグレードプロセス

アップグレード後のアクション

メジャーアップグレード中の拡張機能

pg_upgrade がupdate_extensions.sql を発行する場合

バックアップとWALアーカイブの考慮事項

例Barman Cloudプラグインを使用した手動アーカイブパスの分離

例メジャーアップグレードの実行

アップグレードプロセス

`pg_upgrade` が`update_extensions.sql` を発行する場合