pgd node upgrade ================ 概要 ---- ``pgd node upgrade`` コマンドは、 EDB Postgres分散クラスター内のノードのPostgresバージョンをアップグレードするために使用されます。 動作モード ---------- ``pgd node upgrade`` は、 ``--prepare`` または\ ``--check`` が設定されているかどうかに応じて、3つのモードのいずれかで実行されます。 ``--prepare`` と\ ``--check`` は一緒に使用できません。 .. csv-table:: :header: Mode,Flag,Effect :widths: 12,15,15 :align: left :class: longtable Prepare only,`--prepare`,"Runs `initdb` on the new data directory and migrates the old cluster's configuration into it, without running `pg_upgrade`. Idempotent, so it's safe to re-run, for example to change a configuration override." Dry run,`--check`,"Runs `pg_upgrade` in dry-run mode to validate that the upgrade would succeed, without performing it. Requires the new data directory to already be initialized, either manually (for example with `initdb`) or using `--prepare`." Full upgrade,Neither flag,"Runs the :ref:`アップグレード前の安全性チェック<アップグレード前の安全性チェック>` , then `pg_upgrade` against the new data directory, followed by the BDR post-upgrade steps." 予測可能でダウンタイムの少ないアップグレードを行うには、3つすべてを順番に実行します。メンテナンスウィンドウに先立って新しいデータディレクトリを準備し、アップグレードを予行実行して成功することを確認してから、実際のアップグレードを実行します。実用的な例については、 :ref:`アップグレードの前に新しいデータディレクトリの準備 <アップグレードの前に新しいデータディレクトリの準備>` を参照してください。 .. Note:: PGD 6.4以降、`pgd node setup` は、シングルユーザーモードでBDRオブジェクトを作成する前に`NextOID` カウンターを進め、これらのオブジェクトがアップグレードの失敗の原因となるシステムレンジOID<16384を受信しないようにします。アップグレードを実行する前に、コマンドは、既存のBDRオブジェクトがシステム範囲OIDで作成されたかどうかを確認します。検出された場合、コマンドはすぐに失敗し、影響を受けるオブジェクトを識別する明確なエラーが表示されます。復旧する手順については、 :ref:`システムレンジのOIDエラーの解決 <システムレンジのOIDエラーの解決>` を参照してください。 ユーザーとロール ^^^^^^^^^^^^^^^^ Postgresスーパーユーザー権限と\ ``bdr_superuser`` ロールが必要です。 :ref:`ユーザーロール <ユーザーロール>` を参照してください。 構文 ---- .. code:: plaintext pgd node upgrade [OPTIONS] --old-bindir --new-bindir --old-datadir --new-datadir --database --username ```` はアップグレードするノードの名前であり、 ```` 、\ ```` 、\ ```` 、\ ```` 、\ ```` 、および\ ```` は、新旧のPostgresインスタンスのbinディレクトリ、新旧のPostgresインスタンスデータディレクトリ、データベース名、およびクラスターのインストールです。それぞれユーザー名。 オプション ---------- 次の表は、\ ``pgd node upgrade`` コマンドで使用可能なオプションをリストしています。 .. csv-table:: :header: Short,Long,Default,Env,Description :widths: 6,10,8,8,15 :align: left :class: longtable -b,--old-bindir,"",PGBINOLD,古いPostgresインスタンスのbinディレクトリ -B,--new-bindir,"",PGBINNEW,新しいPostgresインスタンスのbinディレクトリ -d,--old-datadir,"",PGDATAOLD,古いPostgresインスタンスデータディレクトリ -D,--new-datadir,"",PGDATANEW,新しいPostgresインスタンスデータディレクトリ "",--database,"",PGDATABASE,PGDデータベース名 -p,--old-port,Read from the old cluster's `postgresql.conf`; falls back to 5432 only if that lookup fails,PGPORTOLD,古いPostgresインスタンスポート "",--socketdir,/var/run/postgresql,PGSOCKETDIR,新旧のインスタンスの両方で、アップグレード中にポストマスターソケットに使用するディレクトリ "",--check,"","",予行演習モードで実行し、アップグレードを実行せずに成功することを検証します。新しいデータディレクトリは、手動などで`initdb`または`--prepare`を使用して、既に初期化されている必要があります。 `--prepare`では使用できません。 "",--prepare,"","",アップグレードを実行せずに、新しいデータディレクトリでアップグレード前の準備 `initdb`および構成移行のみを実行します。 `--check`とは使用できません。 -j,--jobs,1,"",同時に使用するプロセスまたはスレッドの数 -k,--link,"","",新しいクラスターにファイルをコピーする代わりにハードリンクを使用する "",--old-options,"","",古いpostgresコマンドに渡すオプション、複数の呼び出しが追加されます "",--new-options,"","",新しいpostgresコマンドに渡すオプション、複数の呼び出しが追加されます -N,--no-sync,"","",アップグレードされたクラスター内のすべてのファイルがディスクに書き込まれるのを待たない -P,--new-port,5432,PGPORTNEW,新しいPostgresインスタンスのポート番号 -r,--retain,"","",正常に完了した後でもSQLとログファイルを保持する -U,--username,"",PGUSER,クラスターのインストールユーザー名 "",--clone,"","",効率的なファイルのクローン作成を使用する "",--copy-by-block,"","",異なる暗号化設定を使用するクラスター間でデータを移行するために使用されます。このオプションは、透過的データ暗号化TDEを使用するデータベースでサポートされています -y,--data-encryption,"","",新しいデータディレクトリで透過的データ暗号化TDEを有効にします。 `--prepare`でのみ有効です。 "",--data-encryption-keylen,128,"",TDEのAESキー長さ `128`または`256`のいずれか。 `--data-encryption`が必要です。 "",--key-wrap-command,"",PGDATAKEYWRAPCMD,データ暗号化キーをラップする暗号化するコマンド。コマンドには、プレースホルダー `%p`が含まれる必要があります。 `--data-encryption`が必要です。 `--no-key-wrap`では使用できません。 "",--key-unwrap-command,"",PGDATAKEYUNWRAPCMD,データ暗号化キーを解凍し復号化し、コピーするファイルにアクセスするコマンド。コマンドは、`pgd node setup`を使用したサーバーの初期化中に指定されたものと同じである必要があります "",--no-key-wrap,"","",データ暗号化キーをラップせずに生の状態でディスクに保存します。実稼働環境での使用はお勧めしません。 `--data-encryption`が必要です。 "",--copy-key-from,"","",新しいものを生成する代わりに既存のデータ暗号化キーファイルを再利用し、ソースクラスターのキーマテリアルを保持します。 `--data-encryption`と`--key-wrap-command`または`--no-key-wrap`のいずれかと組み合わせて、再利用されたキーをディスクでエンコードする方法を説明する必要があります。 "",--postgresql-conf,"","",新しいノードに使用する`postgresql.conf`ファイルのパス。 `--prepare`でのみ有効です。 "",--postgresql-auto-conf,"","",新しいノードに使用する`postgresql.auto.conf`ファイルのパス。 `--prepare`でのみ有効です。 "",--hba-conf,"","",新しいノードに使用する`pg_hba.conf`ファイルのパス。 `--prepare`でのみ有効です。 -v,--verbose,"","",`--prepare`ステップ中に追加の診断出力を印刷します。 `Global Options `_ も参照してください。 アップグレードが成功すると、コマンドは、完了を確認する終了のサマリーと、新しいPostgresインスタンス :ref:`pgd node start ` を参照してください。および残りのアップグレード後のタスクを開始するための次のステップを出力します。 アップグレード前の安全性チェック -------------------------------- ``pg_upgrade`` を呼び出す前に、通常のアップグレードおよび\ ``--check`` パスはいくつかの非破壊チェックを実行します。 - **リーダーステータス** アップグレードされるノードがグループの現在の書き込みリーダーまたはRaftリーダーである場合、コマンドはアップグレードを拒否し、最初に実行するスイッチオーバーコマンドたとえば :ref:`pgd group set-leader ` または :ref:`pgd group set-leader ` を出力します。グループごとにノードリードします。アップグレードするノードからリーダーシップを切り替えることは意図的な手順であり、自動化するものではないため、このチェックをスキップするフラグはありません。 - **古いクラスターの到達可能性。** 古いクラスターが到達可能な場合、コマンドはそれを使用してエンコードと構成パスを検出します。 ``pg_upgrade`` の前で既に停止しているなどの理由で到達できない場合、コマンドは古いポストマスターを実行する必要があるのではなく、古いデータディレクトリに対してシングルユーザーモードにフォールバックします。この場合、PGDは既に生き残ったノードの間でリーダーを再選択しているため、リーダーステータスチェックは失敗するのではなくスキップされます。 - **新しいデータディレクトリが初期化されました。** ```` が見つからないまたは空の場合、コマンドは失敗し、生の\ ``pg_upgrade`` エラーの代わりに\ ``--prepare`` を指すメッセージが表示されます。 - **BDR拡張機能とバージョンの互換性.** BDR拡張機能が古いクラスターの\ ```` にインストールされていない場合、または古いクラスターのBDRバージョンがサポートされている最小値より低いか、新しいクラスターのものよりも高い場合、アップグレードは拒否されます。 システムレンジのOIDエラーの解決 ------------------------------- コマンドがシステムレンジOIDエラーで失敗した場合、クラスターは、シングルユーザーモードでBDRオブジェクトを作成する前に\ ``NextOID`` カウンターを進めなかった6.4より前のバージョンの\ ``pgd node setup`` でセットアップされています。影響を受けるオブジェクトに、新しいOIDを再割り当てすることはできません。 エラーを解決するには、ノードを分割し、標準のpsqlセッションシングルユーザーモードではなくでBDR拡張機能をドロップして再作成し、構造を同期せずにクラスターに再参加して既存のデータを保持します。 1. ノードをクラスターから分離します。 .. code:: shell pgd node part 2. BDRデータベースに接続したpsqlセッションで、拡張機能をドロップします。 .. code:: sql DROP EXTENSION bdr CASCADE; 3. 標準のpsqlセッションシングルユーザーモードではなく、拡張機能を再作成します。 .. code:: sql CREATE EXTENSION bdr; 4. :ref:`bdr.create_node() ` および :ref:`bdr.join_node_group() ` を使用してノードを再作成し、グループに再参加します。\ ``synchronize_structure`` を\ ``'none'`` に設定します。 5. ``pgd node upgrade`` を再度実行します。 例 -- 次の例では、 “kaolin”は、クイックスタートデモクラスターからアップグレードするノードの名前です。 ノードのPostgresバージョンをアップグレードする ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb ハードリンクを備えたノードのPostgresバージョンをアップグレードする ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb --link 効率的なファイルクローン作成を使用してノードのPostgresバージョンをアップグレードする ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb --clone 別のポート番号を持つノードのPostgresバージョンをアップグレードする ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: shell pgd node kaolin upgrade --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb --old-port 5433 --new-port 5434 アップグレードの前に新しいデータディレクトリの準備 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``--prepare`` を使用して\ ``initdb`` を実行し、 ``pg_upgrade`` を実行せずに、古いクラスターの構成を新しいデータディレクトリに移行します。 .. code:: shell pgd node kaolin upgrade --prepare --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb ``--prepare`` はべき等であるため、後で同じコマンドを再実行すると、既に配置されているファイルはスキップされ、変更されたもののみが更新されます。これにより、メンテナンス時間枠に先立って新しいデータディレクトリを準備し、後で最小限のダウンタイムで実際のアップグレードを実行できます。 準備したアップグレードを実行する前の検証 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 新しいデータディレクトリの準備ができたら、 ``--prepare`` の代わりに\ ``--check`` を使用して同じコマンドを実行して、データを変更せずにアップグレードが成功することを検証します。 .. code:: shell pgd node kaolin upgrade --check --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb チェックが成功した場合は、 ``--prepare`` も\ ``--check`` も使用せずに同じコマンドを再度実行して、準備したデータディレクトリに対してアップグレードを実行します。 カスタム構成ファイルを使用した新しいデータディレクトリの準備 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 通常のアップグレードと\ ``--check`` パスは新しいデータディレクトリの既存の構成をそのまま使用するため、 ``--postgresql-conf`` 、\ ``--postgresql-auto-conf`` 、および\ ``--hba-conf`` オーバーライドは\ ``--prepare`` にのみ適用されます。 .. code:: shell pgd node kaolin upgrade --prepare --old-bindir /usr/pgsql-16/bin --new-bindir /usr/pgsql-17/bin --old-datadir /var/lib/pgsql/16/data --new-datadir /var/lib/pgsql/17/data --database pgddb --username enterprisedb --postgresql-conf /opt/new-configs/postgresql.conf --hba-conf /opt/new-configs/pg_hba.conf これらのオーバーライドを事後変更するには、新しいパスで\ ``--prepare`` を再実行します。実際のアップグレードが実行される前に、これを何回行っても安全です。 透過的データ暗号化TDEを使用してノードのPostgres拡張バージョンをアップグレードする ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``--data-encryption`` とその関連フラグは、新しいデータディレクトリにTDEをプロビジョニングする\ ``--prepare`` 中にのみ有効になります。 ``--key-unwrap-command`` および\ ``--copy-by-block`` は、古いデータを復号して新しい暗号化されたデータディレクトリにブロックごとにコピーするステップであるため、実際のアップグレード時に再び渡されます。 .. code:: shell pgd node kaolin upgrade --prepare --database pgddb -B /usr/lib/edb-pge/16/bin --socketdir /var/run/edb-pge/ --old-bindir /usr/lib/edb-pge/15/bin --old-datadir /var/lib/edb-pge/15/main --new-datadir /var/lib/edb-pge/16/main --username postgres --data-encryption --key-wrap-command "openssl enc -aes-128-cbc -pbkdf2 -pass pass:secret -out %p" --key-unwrap-command "openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:secret -in %p" pgd node kaolin upgrade --database pgddb -B /usr/lib/edb-pge/16/bin --socketdir /var/run/edb-pge/ --old-bindir /usr/lib/edb-pge/15/bin --old-datadir /var/lib/edb-pge/15/main --new-datadir /var/lib/edb-pge/16/main --username postgres --key-unwrap-command "openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:secret -in %p" --copy-by-block 新しい暗号化キーを生成する代わりに、古いクラスターの既存の暗号化キーを保持するには、 ``--key-wrap-command`` または\ ``--no-key-wrap`` とともに ``--copy-key-from /pg_encryption/key.bin`` を\ ``--prepare`` ステップに追加します。