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

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/17)を使用しているのであれば、古いクラスタを移動する必要はありません。 グラフィカルインストーラはすべて、バージョンに関連したインストレーションディレクトリを使用します。

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参照)を使用するようにした方が良いかもしれません。

Prepare for publisher upgrades

<application>pg_upgrade</application> attempts to migrate logical slots. This helps avoid the need for manually defining the same logical slots on the new publisher. Migration of logical slots is only supported when the old cluster is version 17.0 or later. Logical slots on clusters before version 17.0 will silently be ignored. 《機械翻訳》pg_upgradeは論理スロットの移行を試みます。 これは、新しいパブリッシャ上で同じ論理スロットを手動で定義する必要性を回避するのに役立ちます。 論理スロットの移行は、古いクラスタがバージョン17.0以降の場合にのみサポートされます。 バージョン17.0より前のクラスタ上の論理スロットは、無視されます。

Before you start upgrading the publisher cluster, ensure that the subscription is temporarily disabled, by executing <link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>. Re-enable the subscription after the upgrade. 《機械翻訳》パブリッシャクラスタのアップグレードを開始する前に、ALTER SUBSCRIPTION ... DISABLEを実行して、サブスクリプションが一時的に無効になっていることを確認してください。 アップグレード後にサブスクリプションを再度有効にしてください。

There are some prerequisites for <application>pg_upgrade</application> to be able to upgrade the logical slots. If these are not met an error will be reported. 《機械翻訳》pg_upgradeが論理スロットをアップグレードできるようにするための前提条件がいくつかあります。 これらが満たされていない場合はエラーが報告されます。

Prepare for subscriber upgrades

Setup the <link linkend="logical-replication-config-subscriber"> subscriber configurations</link> in the new subscriber. <application>pg_upgrade</application> attempts to migrate subscription dependencies which includes the subscription's table information present in <link linkend="catalog-pg-subscription-rel">pg_subscription_rel</link> system catalog and also the subscription's replication origin. This allows logical replication on the new subscriber to continue from where the old subscriber was up to. Migration of subscription dependencies is only supported when the old cluster is version 17.0 or later. Subscription dependencies on clusters before version 17.0 will silently be ignored. 《機械翻訳》新しいサブスクライバーにサブスクライバー構成を設定します。 pg_upgradeは、pg_subscription_relシステムカタログに存在するサブスクリプションのテーブル情報と、サブスクリプションのレプリケーション元を含むサブスクリプション依存関係の移行を試みます。 これにより、新しいサブスクライバで論理的なレプリケーションを、古いサブスクライバが存在していた場所から継続できます。 サブスクリプションの依存関係の移行は、古いクラスタがバージョン17.0以降の場合にのみサポートされます。 バージョン 17.0 より前のクラスタに対するサブスクリプションの依存関係は、無視されます。

There are some prerequisites for <application>pg_upgrade</application> to be able to upgrade the subscriptions. If these are not met an error will be reported. 《機械翻訳》pg_upgradeがサブスクリプションをアップグレードできるようにするための前提条件がいくつかあります。 これらが満たされていない場合はエラーが報告されます。

両サーバの停止

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/17 stop

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

NET STOP postgresql-12
NET STOP postgresql-17

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

The <option>&#45;-jobs</option> option allows multiple CPU cores to be used for copying/linking of files and to dump and restore database schemas in parallel; a good place to start is the maximum of the number of CPU cores and tablespaces. This option can dramatically reduce the time to upgrade a multi-database server running on a multiprocessor machine. --jobsオプションにより複数のCPUコアを使用して、並行してファイルのコピー・リンク、データベーススキーマのダンプとリストアを行うことができます。 この値の最大値として検討を始める際には、CPUコア数またはテーブル空間数を勧めます。 このオプションはマルチプロセッサを持つマシンで実行している複数のデータベースサーバをアップグレードする時間を大きく減らします。

For Windows users, you must be logged into an administrative account, and then run <application>pg_upgrade</application> with quoted directories, e.g.: 《マッチ度[56.953642]》そして、以下の例のように、引用符でくくったディレクトリを付けてpg_upgradeを実行してください。 《機械翻訳》Windows ユーザの場合、管理アカウントでログインし、次のように引用符で囲まれたディレクトリを指定してpg_upgradeを実行する必要があります。

pg_upgrade.exe
        --old-datadir "C:/Program Files/PostgreSQL/12/data"
        --new-datadir "C:/Program Files/PostgreSQL/17/data"
        --old-bindir "C:/Program Files/PostgreSQL/12/bin"
        --new-bindir "C:/Program Files/PostgreSQL/17/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 or clone mode, you should use the option <option>&#45;-link</option> or <option>&#45;-clone</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オプションを使用すべきです。 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は終了しますので、後述のステップ 19で示すように古いクラスタに戻さなければなりません。 再び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. スクリプトは任意の順番で実行することができ、また、実行が終わったら削除することができます。

統計情報

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

Using <command>vacuumdb &#45;-all &#45;-analyze-only</command> can efficiently generate such statistics, and the use of <option>&#45;-jobs</option> can speed it up. Option <option>&#45;-analyze-in-stages</option> can be used to generate minimal statistics quickly. 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-onlyを使用すると、このような統計情報を効率的に生成できます。 --jobsを使用すると、統計情報を迅速に生成できます。 --analyze-in-stagesオプションを使用すると、最小限の統計情報を迅速に生成できます。 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を実行した後に古いクラスタに戻したい場合、いくつかの選択肢があります。