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

If you are using a version-specific installation directory, e.g., <filename>/opt/PostgreSQL/&majorversion;</filename>, you do not need to move the old cluster. The graphical installers all use version-specific installation directories. バージョンに関連したインストレーションディレクトリ(例えば/opt/PostgreSQL/18)を使用しているのであれば、古いクラスタを移動する必要はありません。 グラフィカルインストーラはすべて、バージョンに関連したインストレーションディレクトリを使用します。

If your installation directory is not version-specific, e.g., <filename>/usr/local/pgsql</filename>, it is necessary to move the current PostgreSQL install directory so it does not interfere with the new <productname>PostgreSQL</productname> installation. Once the current <productname>PostgreSQL</productname> server is shut down, it is safe to rename the PostgreSQL installation directory; assuming the old directory is <filename>/usr/local/pgsql</filename>, you can do: インストレーションディレクトリがバージョンに関連していない（例えば/usr/local/pgsql）のであれば、新しいPostgreSQLのインストレーションに干渉しないように、現在のPostgreSQLインストレーションディレクトリを移動しなければなりません。 一度現在のPostgreSQLサーバを停止させていれば、PostgreSQLのインストレーションの名前を変更しても安全です。 古いディレクトリが/usr/local/pgsqlであれば、以下のようにディレクトリ名を変更します。

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

to rename the directory.

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

Build the new PostgreSQL source with <command>configure</command> flags that are compatible with the old cluster. <application>pg_upgrade</application> will check <command>pg_controldata</command> to make sure all settings are compatible before starting the upgrade. 古いクラスタと互換性を持つようなconfigureオプションを付けて新しいPostgreSQLソースを構築してください。 pg_upgradeはアップグレードを始める前にすべての設定が互換性を持っていることを確認するためにpg_controldataを検査します。

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

Install the new server's binaries and support files. <application>pg_upgrade</application> is included in a default installation. 新しいサーバのバイナリとサポートファイルをインストールしてください。 pg_upgradeはデフォルトのインストレーションに含まれています。

For source installs, if you wish to install the new server in a custom location, use the <literal>prefix</literal> variable: ソースからインストールする場合、独自の場所に新しいサーバをインストールしたければ、以下のようにprefixを使用してください。

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

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

Initialize the new cluster using <command>initdb</command>. Again, use compatible <command>initdb</command> flags that match the old cluster. Many prebuilt installers do this step automatically. There is no need to start the new cluster. initdbを使用して新しいクラスタを初期化してください。 ここでも、古いクラスタに合うように互換性があるinitdbのオプションを使用してください。 あらかじめ組み込まれたインストーラの多くは、この手順を自動的に実施します。 新しいクラスタを起動する必要はありません。

拡張共有オブジェクトファイルをインストール

Many extensions and custom modules, whether from <filename>contrib</filename> or another source, use shared object files (or DLLs), e.g., <filename>pgcrypto.so</filename>. If the old cluster used these, shared object files matching the new server binary must be installed in the new cluster, usually via operating system commands. Do not load the schema definitions, e.g., <command>CREATE EXTENSION pgcrypto</command>, because these will be duplicated from the old cluster. If extension updates are available, <application>pg_upgrade</application> will report this and create a script that can be run later to update them. contribからのものであろうとその他のソースからのものであろうと、多くの拡張や独自のモジュールは、例えばpgcrypto.soなどの独自の共有オブジェクトファイル(またはDLL)を使います。 古いクラスタがこれらを使用していたのであれば、新しいサーバのバイナリに合った共有オブジェクトファイルを、たいていはオペレーティングシステムのコマンドで、新しいクラスタにインストールしなければなりません。 例えばCREATE EXTENSION pgcryptoなどのスキーマ定義はロードしないでください。これらは古いクラスタから複製されるためです。 拡張アップデートが利用可能であれば、pg_upgradeはこれを報告し、アップデートのために後で実行できるスクリプトを作成します。

独自の全文検索ファイルをコピー

Copy any custom full text search files (dictionary, synonym, thesaurus, stop words) from the old to the new cluster. 独自の全文検索ファイル(辞書、同義語、類語辞書、ストップワード)を古いクラスタから新しいクラスタにコピーしてください。

認証の調整

<command>pg_upgrade</command> will connect to the old and new servers several times, so you might want to set authentication to <literal>peer</literal> in <filename>pg_hba.conf</filename> or use a <filename>~/.pgpass</filename> file (see <xref linkend="libpq-pgpass"/>). pg_upgradeは古いサーバと新しいサーバに複数回接続します。 このため、pg_hba.conf内でpeer認証に設定、あるいは、~/.pgpassファイル(32.16参照)を使用するようにした方が良いかもしれません。

両サーバの停止

Make sure both database servers are stopped using, on Unix, e.g.: 両サーバが停止していることを確実にしてください。 例えばUnixでは以下を使用します。

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

or on Windows, using the proper service names: Windowsでは以下

NET STOP postgresql-12
NET STOP postgresql-18

Streaming replication and log-shipping standby servers must be running during this shutdown so they receive all changes. すべての変更を受信するよう、ストリーミングレプリケーションおよびログシッピングのスタンバイサーバは、このシャットダウン中は実行していなければなりません。

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

If you are upgrading standby servers using methods outlined in section <xref linkend="pgupgrade-step-replicas"/>, verify that the old standby servers are caught up by running <application>pg_controldata</application> against the old primary and standby clusters. Verify that the <quote>Latest checkpoint location</quote> values match in all clusters. Also, make sure <varname>wal_level</varname> is not set to <literal>minimal</literal> in the <filename>postgresql.conf</filename> file on the new primary cluster. スタンバイサーバをステップ 11の節で示した手順でアップグレードする場合は、pg_controldataを実行して、古いスタンバイサーバが、古いプライマリ及びスタンバイのクラスタに同期していることを確認してください。 すべてのクラスタで「Latest checkpoint location」（最終チェックポイント位置）の値が一致することを確認してください。 また、新しいプライマリのクラスタのpostgresql.confファイルでwal_levelをminimalに絶対に設定しないようにしてください。

pg_upgradeの実行

Always run the <application>pg_upgrade</application> binary of the new server, not the old one. <application>pg_upgrade</application> requires the specification of the old and new cluster's data and executable (<filename>bin</filename>) directories. You can also specify user and port values, and whether you want the data files linked, cloned, or swapped instead of the default copy behavior. 古いサーバのものではなく、常に新しいサーバのpg_upgradeバイナリを実行してください。 pg_upgradeは古いクラスタおよび新しいクラスタのデータと実行形式ファイルの格納ディレクトリ（bin）の指定を要求します。 また、ユーザやポート番号の指定や、デフォルト動作のコピーではなくデータファイルのリンクや複製、交換を使用するかどうかを指定することができます。

If you use link mode, the upgrade will be much faster (no file copying) and use less disk space, but you will not be able to access your old cluster once you start the new cluster after the upgrade. Link mode also requires that the old and new cluster data directories be in the same file system. (Tablespaces and <filename>pg_wal</filename> can be on different file systems.) Clone mode provides the same speed and disk space advantages but does not cause the old cluster to be unusable once the new cluster is started. Clone mode also requires that the old and new data directories be in the same file system. This mode is only available on certain operating systems and file systems. Swap mode may be the fastest if there are many relations, but you will not be able to access your old cluster once the file transfer step begins. Swap mode also requires that the old and new cluster data directories be in the same file system. リンクモードを使用する場合、アップグレードは非常に高速になり（ファイルのコピーがありません）、ディスク容量が少なくなりますが、アップグレード後に新しいクラスタを一度でも実行してしまうと、古いクラスタにアクセスすることができなくなります。 リンクモードはまた、古いクラスタと新しいクラスタのデータディレクトリが同じファイルシステムにあることが必要です。 （テーブル空間およびpg_walは異なるファイルシステムに置くことができます。） 複製モードは同じ速度とディスク容量の利点を提供しますが、新しいクラスタを一度実行しても、古いクラスタが使えなくなる訳ではありません。 複製モードはまた、新旧のデータディレクトリが同じファイルシステム内にあることを要求します。 このモードは特定のオペレーティングシステムのファイルシステム上でのみ利用可能です。 リレーションが多い場合は交換モードが一番速いかもしれませんが、ファイル転送ステップが始まると、古いクラスタにアクセスできなくなります。 また、交換モードは古いクラスタと新しいクラスタのデータディレクトリが同じファイルシステムにあることが必要です。

Setting <option>&#45;-jobs</option> to 2 or higher allows pg_upgrade to process multiple databases and tablespaces in parallel. A good starting point is the number of CPU cores on the machine. This option can substantially reduce the upgrade time for multi-database and multi-tablespace servers. --jobsを2以上に設定すると、pg_upgradeは複数のデータベースとテーブル空間に対して並列に処理できます。 まずはマシンのCPUコア数から始めるとよいでしょう。 このオプションを使用すると、複数のデータベースや複数のテーブル空間をもつサーバのアップグレード時間を大幅に削減できます。

For Windows users, you must be logged into an administrative account, and then run <application>pg_upgrade</application> with quoted directories, e.g.: Windowsユーザの場合、管理アカウントでログインし、引用符でくくったディレクトリを付けてpg_upgradeを実行してください。

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

Once started, <command>pg_upgrade</command> will verify the two clusters are compatible and then do the upgrade. You can use <command>pg_upgrade &#45;-check</command> to perform only the checks, even if the old server is still running. <command>pg_upgrade &#45;-check</command> will also outline any manual adjustments you will need to make after the upgrade. If you are going to be using link, clone, copy-file-range, or swap mode, you should use the option <option>&#45;-link</option>, <option>&#45;-clone</option>, <option>&#45;-copy-file-range</option>, or <option>&#45;-swap</option> with <option>&#45;-check</option> to enable mode-specific checks. <command>pg_upgrade</command> requires write permission in the current directory. 起動後、pg_upgradeは2つのクラスタに互換性があるかどうか検証し、その後、アップグレードを行います。 検査のみを行うpg_upgrade --checkを使用することができます。 この場合は古いサーバは稼働中であっても構いません。 またpg_upgrade --checkは、アップグレード後に手作業で行わなければならない調整作業があればその概要を示します。 リンク、複製、ファイル範囲コピー、または交換モードを使用する予定であれば、モード固有の検査を有効にするために--checkを付けて--link、--clone、--copy-file-range、または--swapオプションを使用すべきです。 pg_upgradeは現在のディレクトリに対する書き込み権限を必要とします。

Obviously, no one should be accessing the clusters during the upgrade. <application>pg_upgrade</application> defaults to running servers on port 50432 to avoid unintended client connections. You can use the same port number for both clusters when doing an upgrade because the old and new clusters will not be running at the same time. However, when checking an old running server, the old and new port numbers must be different. 言うまでもありませんが、アップグレード中はクラスタにアクセスしてはいけません。 意図しないクライアント接続を防ぐために、デフォルトではpg_upgradeは50432ポートでサーバを稼働します。 古いクラスタと新しいクラスタが同時に稼働することはありませんので、両クラスタで同じポート番号を使用することができます。 しかし実行中の古いクラスタを検査する時には、新旧で異なるポート番号でなければなりません。

If an error occurs while restoring the database schema, <command>pg_upgrade</command> will exit and you will have to revert to the old cluster as outlined in <xref linkend="pgupgrade-step-revert"/> below. To try <command>pg_upgrade</command> again, you will need to modify the old cluster so the pg_upgrade schema restore succeeds. If the problem is a <filename>contrib</filename> module, you might need to uninstall the <filename>contrib</filename> module from the old cluster and install it in the new cluster after the upgrade, assuming the module is not being used to store user data. データベーススキーマのリストア中にエラーが発生した場合、pg_upgradeは終了しますので、後述のステップ 17で示すように古いクラスタに戻さなければなりません。 再びpg_upgradeを試すためには、pg_upgradeによるスキーマのリストアが成功するように古いクラスタを変更しなければなりません。 問題がcontribモジュールであれば、そのモジュールがユーザデータを格納するために使用されていないことが前提ですが、古いクラスタからそのcontribモジュールをアンインストールし、アップグレードした後に新しいクラスタにそれをインストールする必要があるかもしれません。

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

If you used link mode and have Streaming Replication (see <xref linkend="streaming-replication"/>) or Log-Shipping (see <xref linkend="warm-standby"/>) standby servers, you can follow these steps to quickly upgrade them. You will not be running <application>pg_upgrade</application> on the standby servers, but rather <application>rsync</application> on the primary. Do not start any servers yet. リンクモードを使用した場合で、ストリーミングレプリケーション（26.2.5参照）またはログシッピング（26.2参照）のスタンバイサーバがある場合、以下の手順に従って、素早くアップグレードすることができます。 スタンバイサーバでpg_upgradeは実行せず、代わりにプライマリでrsyncを実行することになります。 どのサーバもまだ起動しないでください。

If you did <emphasis>not</emphasis> use link mode, do not have or do not want to use <application>rsync</application>, or want an easier solution, skip the instructions in this section and simply recreate the standby servers once <application>pg_upgrade</application> completes and the new primary is running. リンクモードを使用しなかった場合、rsyncの機能が使えない場合や使いたくない場合、あるいはもっと容易な方法を望む場合は、この節の手順を読み飛ばし、pg_upgradeが完了して新しいプライマリが起動したら、単純にスタンバイサーバを再作成してください。

pg_hba.confの復旧

If you modified <filename>pg_hba.conf</filename>, restore its original settings. It might also be necessary to adjust other configuration files in the new cluster to match the old cluster, e.g., <filename>postgresql.conf</filename> (and any files included by it), <filename>postgresql.auto.conf</filename>. pg_hba.confを変更している場合は、元の認証設定に戻してください。 また新しいクラスタにおけるこの他の設定ファイル、例えばpostgresql.conf（とそれがインクルードしているファイル）、postgresql.auto.confも古いクラスタに合わせるように調整する必要があります。

新しいサーバの起動

The new server can now be safely started, and then any <application>rsync</application>'ed standby servers. ここで新しいサーバが安全に起動できます。 それからrsyncしたすべてのスタンバイサーバを起動できます。

移行後の処理

If any post-upgrade processing is required, pg_upgrade will issue warnings as it completes. It will also generate script files that must be run by the administrator. The script files will connect to each database that needs post-upgrade processing. Each script should be run using: アップグレード後の処理が必要な場合、pg_upgradeはその終了時に警告を発します。 また、管理者として実行しなければならないスクリプトファイルを生成します。 このスクリプトファイルは、アップグレード後の処理を必要とするデータベースそれぞれに接続します。 各スクリプトは以下を使用して実行しなければなりません。

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

The scripts can be run in any order and can be deleted once they have been run. スクリプトは任意の順番で実行することができ、また、実行が終わったら削除することができます。

統計情報

Unless the <option>&#45;-no-statistics</option> option is specified, <command>pg_upgrade</command> will transfer most optimizer statistics from the old cluster to the new cluster. However, some statistics may not be transferred, such as those created explicitly with <xref linkend="sql-createstatistics"/> or custom statistics added by an extension. --no-statisticsオプションが指定されていなければ、pg_upgradeはほとんどのオプティマイザ統計情報を古いクラスタから新しいクラスタに転送します。 ただし、CREATE STATISTICSを使用して明示的に作成された統計情報や、拡張により追加された独自統計情報など、一部の統計情報は転送されません。

Because not all statistics are transferred by <command>pg_upgrade</command>, you will be instructed to run commands to regenerate that information at the end of the upgrade. You might need to set connection parameters to match your new cluster. すべての統計情報がpg_upgradeにより転送されるわけではないため、アップグレード後に統計情報を再生成するコマンドを実行するように指示されます。 新しいクラスタに合わせた接続パラメータを設定する必要があるかもしれません。

First, use <command>vacuumdb &#45;-all &#45;-analyze-in-stages &#45;-missing-stats-only</command> to quickly generate minimal optimizer statistics for relations without any. Then, use <command>vacuumdb &#45;-all &#45;-analyze-only</command> to ensure all relations have updated cumulative statistics for triggering vacuum and analyze. For both commands, the use of <option>&#45;-jobs</option> can speed it up. If <varname>vacuum_cost_delay</varname> is set to a non-zero value, this can be overridden to speed up statistics generation using <envar>PGOPTIONS</envar>, e.g., <literal>PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ...</literal>. まず、vacuumdb --all --analyze-in-stages --missing-stats-onlyを使用して、オプティマイザ用の統計情報がないリレーションに対して最小限の統計情報を高速に生成します。 次に、vacuumdb --all --analyze-onlyを使用して、バキュームと解析を起動するための累積統計をすべてのリレーションで更新します。 どちらのコマンドも、--jobsを使用すると処理を高速化できます。 vacuum_cost_delayが0以外の値に設定されている場合、PGOPTIONSを使用して、例えばPGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ...のように、これを上書きして統計情報の生成を高速化できます。

古いクラスタの削除

Once you are satisfied with the upgrade, you can delete the old cluster's data directories by running the script mentioned when <command>pg_upgrade</command> completes. (Automatic deletion is not possible if you have user-defined tablespaces inside the old data directory.) You can also delete the old installation directories (e.g., <filename>bin</filename>, <filename>share</filename>). アップグレード処理が満足いくものであれば、pg_upgradeの終了時に示されたスクリプトを使用して、古いクラスタのデータディレクトリを削除することができます。 （古いデータディレクトリ内にユーザ定義のテーブル空間がある場合には、自動削除は不可能です。） （bin、shareなど）古いインストレーションディレクトリも削除できます。

古いクラスタへの戻し

If, after running <command>pg_upgrade</command>, you wish to revert to the old cluster, there are several options: pg_upgradeを実行した後に古いクラスタに戻したい場合、いくつかの選択肢があります。