古いクラスタの移動（省略可能）

バージョンに関連したインストレーションディレクトリ(例えば/opt/PostgreSQL/12)を使用しているのであれば、古いクラスタを移動する必要はありません。 グラフィカルインストーラはすべて、バージョンに関連したインストレーションディレクトリを使用します。

インストレーションディレクトリがバージョンに関連していない（例えば/usr/local/pgsql）のであれば、新しいPostgreSQLのインストレーションに干渉しないように、現在のPostgreSQLインストレーションディレクトリを移動しなければなりません。 一度現在のPostgreSQLサーバを停止させていれば、PostgreSQLのインストレーションの名前を変更しても安全です。 古いディレクトリが/usr/local/pgsqlであれば、以下のようにディレクトリ名を変更します。

mv /usr/local/pgsql /usr/local/pgsql.old

ソースからのインストールの場合の新しいバージョンの構築

古いクラスタと互換性を持つようなconfigureオプションを付けて新しいPostgreSQLソースを構築してください。 pg_upgradeはアップグレードを始める前にすべての設定が互換性を持っていることを確認するためにpg_controldataを検査します。

新しいPostgreSQLのバイナリのインストール

新しいサーバのバイナリとサポートファイルをインストールしてください。 pg_upgradeはデフォルトのインストレーションに含まれています。

ソースからインストールする場合、独自の場所に新しいサーバをインストールしたければ、以下のようにprefixを使用してください。

make prefix=/usr/local/pgsql.new install

新しいPostgreSQLクラスタを初期化

initdbを使用して新しいクラスタを初期化してください。 繰り返しますが、古いクラスタに合うように互換性があるinitdbのオプションを使用してください。 あらかじめ組み込まれたインストーラの多くは、この手順を自動的に実施します。 新しいクラスタを起動する必要はありません。

独自の共有オブジェクトファイルをインストール

例えば、pgcrypto.so、contribや何らかのその他のソースからインストールしたものなど、古いクラスタで使用していた独自の共有オブジェクトファイル(またはDLL)をすべて、新しいクラスタにインストールしてください。 例えばCREATE EXTENSION pgcryptoなどのスキーマ定義はインストールしないでください。 これらは古いクラスタからアップグレードされるためです。 また、独自の全文検索ファイル(辞書、同義語、類語辞書、ストップワード)も新しいクラスタにコピーしなければなりません。

認証の調整

pg_upgradeは古いサーバと新しいサーバに複数回接続します。 このため、pg_hba.conf内でtrustまたはpeer認証に設定、あるいは、~/.pgpassファイル(33.15参照)を使用するようにした方が良いかもしれません。

両サーバの停止

両サーバが停止していることを確実にしてください。 例えばUnixでは以下を使用します。

pg_ctl -D /opt/PostgreSQL/9.6 stop
pg_ctl -D /opt/PostgreSQL/12 stop

Windowsでは以下

NET STOP postgresql-9.6
NET STOP postgresql-12

ストリーミングレプリケーションおよびログシッピングのスタンバイサーバは、後のステップまで実行中のまま残すことができます。

スタンバイサーバのアップグレードの準備

スタンバイサーバをステップ 10の節で示した手順でアップグレードする場合は、pg_controldataを実行して、古いスタンバイサーバが、古いプライマリ及びスタンバイのクラスタに同期していることを確認してください。 すべてのクラスタで「Latest checkpoint location」（最終チェックポイント位置）の値が一致することを確認してください。 （古いスタンバイサーバが、古いプライマリより先にシャットダウンされた場合、もしくは古いスタンバイサーバがまだ稼働中の場合は一致しないでしょう。） また、新しいプライマリのクラスタのpostgresql.confファイルでwal_levelをminimalに絶対に設定しないようにしてください。

pg_upgradeの実行

古いサーバのものではなく、常に新しいサーバのpg_upgradeバイナリを実行してください。 pg_upgradeは古いクラスタおよび新しいクラスタのデータと実行形式ファイルの格納ディレクトリ（bin）の指定を要求します。 また、ユーザやポート番号の指定や、デフォルト動作のコピーではなくデータファイルのリンクや複製を使用するかどうかを指定することができます。

リンクモードを使用する場合、アップグレードは非常に高速になり(ファイルのコピーがありません)、ディスク容量が少なくなりますが、アップグレード後に新しいクラスタを一度でも実行してしまうと、古いクラスタにアクセスすることができなくなります。 リンクモードはまた、古いクラスタと新しいクラスタのデータディレクトリが同じファイルシステムにあることが必要です。 （テーブル空間およびpg_walは異なるファイルシステムに置くことができます。） 複製モードは同じ速度とディスク容量の利点を提供しますが、新しいクラスタを一度実行しても、古いクラスタが使えなくなる訳ではありません。 複製モードはまた、新旧のデータディレクトリが同じファイルシステム内にあることを要求します。 このモードは特定のオペレーティングシステムのファイルシステム上でのみ利用可能です。

--jobsオプションにより複数のCPUコアを使用して、並行してファイルのコピー・リンク、データベーススキーマのダンプと再ロードを行うことができます。 この値の最大値として検討を始める際には、CPUコア数またはテーブル空間数を勧めます。 このオプションはマルチプロセッサを持つマシンで実行している複数のデータベースサーバをアップグレードする時間を大きく減らします。

Windowsユーザの場合、管理者アカウントでログオンしなければなりません。 また、postgresユーザとしてシェルを起動し、適切なパスを設定してください。

RUNAS /USER:postgres "CMD.EXE"
SET PATH=%PATH%;C:\Program Files\PostgreSQL\12\bin;

そして、以下の例のように、引用符でくくったディレクトリを付けてpg_upgradeを実行してください。

pg_upgrade.exe
        --old-datadir "C:/Program Files/PostgreSQL/9.6/data"
        --new-datadir "C:/Program Files/PostgreSQL/12/data"
        --old-bindir "C:/Program Files/PostgreSQL/9.6/bin"
        --new-bindir "C:/Program Files/PostgreSQL/12/bin"

起動後、pg_upgradeは2つのクラスタに互換性があるかどうか検証し、その後、アップグレードを行います。 検査のみを行うpg_upgrade --checkを使用することができます。 この場合は古いサーバは稼動中であっても構いません。 またpg_upgrade --checkは、アップグレード後に手作業で行わなければならない調整作業があればその概要を示します。 リンクまたは複製モードを使用する予定であれば、モード固有の検査を有効にするために--checkを付けて--linkまたは--cloneオプションを使用すべきです。 pg_upgradeは現在のディレクトリに対する書き込み権限を必要とします。

言うまでもありませんが、アップグレード中はクラスタにアクセスしてはいけません。 意図しないクライアント接続を防ぐために、デフォルトではpg_upgradeは50432ポートでサーバを稼働します。 古いクラスタと新しいクラスタが同時に稼動することはありませんので、両クラスタで同じポート番号を使用することができます。 しかし実行中の古いクラスタを検査する時には、新旧で異なるポート番号でなければなりません。

データベーススキーマのリストア中にエラーが発生した場合、pg_upgradeは終了しますので、後述のステップ 16で示すように古いクラスタに戻さなければなりません。 再びpg_upgradeを試すためには、pg_upgradeによるスキーマのリストアが成功するように古いクラスタを変更しなければなりません。 問題がcontribモジュールであれば、そのモジュールがユーザデータを格納するために使用されていないことが前提ですが、古いクラスタからそのcontribモジュールをアンインストールし、アップグレードした後に新しいクラスタにそれをインストールする必要があるかもしれません。

ストリーミングレプリケーションおよびログシッピングのスタンバイサーバのアップグレード

リンクモードを使用した場合で、ストリーミングレプリケーション（26.2.5参照)またはログシッピング（26.2参照）のスタンバイサーバがある場合、以下の手順に従って、素早くアップグレードすることができます。 スタンバイサーバでpg_upgradeは実行せず、代わりにプライマリでrsyncを実行することになります。 どのサーバもまだ起動しないでください。

リンクモードを使用しなかった場合、rsyncの機能が使えない場合や使いたくない場合、あるいはもっと容易な方法を望む場合は、この節の手順を読み飛ばし、pg_upgradeが完了して新しいプライマリが起動したら、単純にスタンバイサーバを再作成してください。

1. PostgreSQLの新しいバイナリをスタンバイサーバにインストール

   すべてのスタンバイサーバで新しいバイナリとサポートファイルがインストールされていることを確実にしてください。

2. 新しいスタンバイのデータディレクトリが存在しないことの確認

   新しいスタンバイのデータディレクトリが存在しないか空であることを確実にしてください。 initdbが実行されている場合は、スタンバイサーバの新しいデータディレクトリを削除してください。

3. カスタム共有オブジェクトファイルのインストール

   新しいプライマリのクラスタにインストールしたのと同じカスタム共有オブジェクトファイルを新しいスタンバイにインストールしてください。

4. スタンバイサーバの停止

   スタンバイサーバがまだ実行中なら、上記の手順に従って停止してください。

5. 設定ファイルの保存

   スタンバイの設定ディレクトリの設定ファイルで保持する必要のあるもの、例えばpostgresql.confやpg_hba.confを保存してください。 これらは次のステップで上書きあるいは削除されるからです。

6. rsyncの実行

   リンクモードを使用する場合、rsyncを使用してスタンバイサーバを素早くアップグレードすることができます。 これを実行するには、古いデータベースクラスタのディレクトリおよび新しいデータベースクラスタのディレクトリより上位にあるプライマリサーバ上のディレクトリで、プライマリ上で各スタンバイサーバに対して以下を実行します。

   rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
   

   ここでold_clusterおよびnew_clusterはプライマリのカレントディレクトリからの相対パス、remote_dirはスタンバイサーバ上の古いクラスタと新しいクラスタのディレクトリの上位のディレクトリです。 プライマリとスタンバイの指定したディレクトリより下のディレクトリ構造は一致しなければなりません。 リモートディレクトリの指定の詳細についてはrsyncのマニュアルを参照してください。 例を示します。

   rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/9.5 \
         /opt/PostgreSQL/9.6 standby.example.com:/opt/PostgreSQL
   

   rsyncの--dry-runオプションを使うことで、そのコマンドが何をするか確認することができます。 rsyncは少なくとも1つのスタンバイに対して、プライマリ上で実行しなければなりませんが、アップグレード済みのスタンバイがまだ起動していなければ、そのスタンバイ上でrsyncを実行して、他のスタンバイをアップグレードすることができます。

   これが実行するのはpg_upgradeのリンクモードが作成したプライマリサーバ上の古いクラスタのファイルと新しいクラスタのファイルを接続するリンクについて記録することです。 次にスタンバイの古いクラスタ内の一致するファイルを探し、スタンバイの新しいクラスタ内に対応するリンクを作成します。 プライマリ上でリンクされなかったファイルは、プライマリからスタンバイにコピーされます。 （それらは通常は小さいです。） これにより高速なアップグレードが可能になります。 残念ながらrsyncは一時テーブルやログを取らないテーブルに関連したファイルを不要であるにも関わらずコピーします。 これらのファイルが通常はスタンバイサーバに存在しないからです。

   テーブル空間を使用している場合は、各テーブル空間のディレクトリについて、同様のrsyncコマンドを実行する必要があります。 例を示します。

   rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 \
         /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp
   

   pg_walをデータディレクトリの外側に移動している場合は、そのディレクトリについてもrsyncを実行しなければなりません。

7. ストリーミングレプリケーションおよびログシッピングのスタンバイサーバの設定

   ログシッピングのためにサーバを設定します。 （スタンバイはまだプライマリと同期されているので、pg_start_backup()とpg_stop_backup()を実行したり、ファイルシステムのバックアップを取得したりする必要はありません。）

pg_hba.confの復旧

pg_hba.confを変更している場合は、元の認証設定に戻してください。 また新しいクラスタにおけるこの他の設定ファイル、例えばpostgresql.conf、も古いクラスタに合わせるように調整する必要があります。

新しいサーバの起動

ここで新しいサーバが安全に起動できます。 それからrsyncしたすべてのスタンバイサーバを起動できます。

移行後の処理

アップグレード後の処理が必要な場合、pg_upgradeはその終了時に警告を発します。 また、管理者として実行しなければならないスクリプトファイルを生成します。 このスクリプトファイルは、アップグレード後の処理を必要とするデータベースそれぞれに接続します。 各スクリプトは以下を使用して実行しなければなりません。

psql --username=postgres --file=script.sql postgres

スクリプトは任意の順番で実行することができ、また、実行が終わったら削除することができます。

統計情報

オプティマイザの統計情報はpg_upgradeにより転送されませんので、アップグレード後に統計情報を再生成するコマンドを実行するように指示されます。 新しいクラスタに合わせるために接続パラメータを設定する必要があるかもしれません。

古いクラスタの削除

アップグレード処理が満足いくものであれば、pg_upgradeの終了時に示されたスクリプトを使用して、古いクラスタのデータディレクトリを削除することができます。 （古いデータディレクトリ内にユーザ定義のテーブル空間がある場合には、自動削除は不可能です。） （bin、shareなど）古いインストレーションディレクトリも削除できます。

古いクラスタへの戻し

pg_upgradeを実行した後に古いクラスタに戻したい場合、いくつかの選択肢があります。