pgd node upgrade

pgd node upgrade#

概要#

pgd node upgrade コマンドは、 EDB Postgres分散クラスター内のノードのPostgresバージョンをアップグレードするために使用されます。

動作モード#

pgd node upgrade は、 --prepare または--check が設定されているかどうかに応じて、3つのモードのいずれかで実行されます。 --prepare と--check は一緒に使用できません。

Mode

Flag

Effect

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 アップグレード前の安全性チェック , then pg_upgrade against the new data directory, followed by the BDR post-upgrade steps.

予測可能でダウンタイムの少ないアップグレードを行うには、3つすべてを順番に実行します。メンテナンスウィンドウに先立って新しいデータディレクトリを準備し、アップグレードを予行実行して成功することを確認してから、実際のアップグレードを実行します。実用的な例については、 アップグレードの前に新しいデータディレクトリの準備 を参照してください。

注釈

PGD 6.4以降、pgd node setup は、シングルユーザーモードでBDRオブジェクトを作成する前に`NextOID` カウンターを進め、これらのオブジェクトがアップグレードの失敗の原因となるシステムレンジOID<16384を受信しないようにします。アップグレードを実行する前に、コマンドは、既存のBDRオブジェクトがシステム範囲OIDで作成されたかどうかを確認します。検出された場合、コマンドはすぐに失敗し、影響を受けるオブジェクトを識別する明確なエラーが表示されます。復旧する手順については、 システムレンジのOIDエラーの解決 を参照してください。

ユーザーとロール#

Postgresスーパーユーザー権限とbdr_superuser ロールが必要です。 ユーザーロール を参照してください。

構文#

pgd node <NODE_NAME> upgrade [OPTIONS] --old-bindir <OLD_BINDIR> --new-bindir <NEW_BINDIR> --old-datadir <OLD_DATADIR> --new-datadir <NEW_DATADIR> --database <DATABASE> --username <USER_NAME>

<NODE_NAME> はアップグレードするノードの名前であり、 <OLD_BINDIR> 、<NEW_BINDIR> 、<OLD_DATADIR> 、<NEW_DATADIR> 、<DATABASE> 、および<USER_NAME> は、新旧のPostgresインスタンスのbinディレクトリ、新旧のPostgresインスタンスデータディレクトリ、データベース名、およびクラスターのインストールです。それぞれユーザー名。

オプション#

次の表は、pgd node upgrade コマンドで使用可能なオプションをリストしています。

Short

Long

Default

Env

Description

-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インスタンス pgd node start を参照してください。および残りのアップグレード後のタスクを開始するための次のステップを出力します。

アップグレード前の安全性チェック#

pg_upgrade を呼び出す前に、通常のアップグレードおよび--check パスはいくつかの非破壊チェックを実行します。

  • リーダーステータス アップグレードされるノードがグループの現在の書き込みリーダーまたはRaftリーダーである場合、コマンドはアップグレードを拒否し、最初に実行するスイッチオーバーコマンドたとえば pgd group set-leader または pgd group set-leader を出力します。グループごとにノードリードします。アップグレードするノードからリーダーシップを切り替えることは意図的な手順であり、自動化するものではないため、このチェックをスキップするフラグはありません。

  • 古いクラスターの到達可能性。 古いクラスターが到達可能な場合、コマンドはそれを使用してエンコードと構成パスを検出します。 pg_upgrade の前で既に停止しているなどの理由で到達できない場合、コマンドは古いポストマスターを実行する必要があるのではなく、古いデータディレクトリに対してシングルユーザーモードにフォールバックします。この場合、PGDは既に生き残ったノードの間でリーダーを再選択しているため、リーダーステータスチェックは失敗するのではなくスキップされます。

  • 新しいデータディレクトリが初期化されました。 <new_datadir> が見つからないまたは空の場合、コマンドは失敗し、生のpg_upgrade エラーの代わりに--prepare を指すメッセージが表示されます。

  • BDR拡張機能とバージョンの互換性. BDR拡張機能が古いクラスターの<DATABASE> にインストールされていない場合、または古いクラスターのBDRバージョンがサポートされている最小値より低いか、新しいクラスターのものよりも高い場合、アップグレードは拒否されます。

システムレンジのOIDエラーの解決#

コマンドがシステムレンジOIDエラーで失敗した場合、クラスターは、シングルユーザーモードでBDRオブジェクトを作成する前にNextOID カウンターを進めなかった6.4より前のバージョンのpgd node setup でセットアップされています。影響を受けるオブジェクトに、新しいOIDを再割り当てすることはできません。

エラーを解決するには、ノードを分割し、標準のpsqlセッションシングルユーザーモードではなくでBDR拡張機能をドロップして再作成し、構造を同期せずにクラスターに再参加して既存のデータを保持します。

  1. ノードをクラスターから分離します。

pgd node <node-name> part

  1. BDRデータベースに接続したpsqlセッションで、拡張機能をドロップします。

DROP EXTENSION bdr CASCADE;

  1. 標準のpsqlセッションシングルユーザーモードではなく、拡張機能を再作成します。

CREATE EXTENSION bdr;

  1. bdr.create_node() および bdr.join_node_group() を使用してノードを再作成し、グループに再参加します。synchronize_structure を'none' に設定します。

  2. pgd node upgrade を再度実行します。

例#

次の例では、 “kaolin”は、クイックスタートデモクラスターからアップグレードするノードの名前です。

ノードのPostgresバージョンをアップグレードする#

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バージョンをアップグレードする#

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バージョンをアップグレードする#

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バージョンをアップグレードする#

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 を実行せずに、古いクラスターの構成を新しいデータディレクトリに移行します。

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 を使用して同じコマンドを実行して、データを変更せずにアップグレードが成功することを検証します。

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 にのみ適用されます。

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 は、古いデータを復号して新しい暗号化されたデータディレクトリにブロックごとにコピーするステップであるため、実際のアップグレード時に再び渡されます。

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 <old_datadir>/pg_encryption/key.bin を--prepare ステップに追加します。

目次