移动旧集簇（可选）

如果你在使用一个与版本相关的安装目录（例如 /opt/PostgreSQL/17），你就不需要移动旧的集簇。 图形化的安装程序会使用版本相关的安装目录。

如果你的安装目录不是版本相关的（例如/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标志。许多预编译的 安装程序会自动做这个步骤。这里没有必要启动新集簇。

安装扩展共享对象文件

许多扩展和自定义模块，无论是来自contrib或其他源，使用共享对象文件(或DLLs)，例如， pgcrypto.so。 如果旧集群使用过这些，匹配新服务器二进制的共享对象文件，必须安装在新集群中。 通常是通过操作系统命令。 不要加载模式定义，例如CREATE EXTENSION pgcrypto，因为这些将从旧集群复制。 如果扩展更新是可用的，pg_upgrade将报告这一点，并创建一个脚本，可以稍后运行来更新它们。

拷贝定制的全文本检索文件

从旧集群向新集群拷贝任何定制化全文本检索文件(词典、同义词、辞典、停用词)

调整认证

pg_upgrade将会多次连接到旧服务器和新服务器，因此 你可能想要在pg_hba.conf中把认证设置成 peer或者使用一个~/.pgpass文件（见 Section 32.16）。

准备发布者升级

pg_upgrade 尝试迁移逻辑槽。这有助于避免在新发布者上手动定义相同的 逻辑槽。仅当旧集群版本为17.0或更高版本时，才支持逻辑槽的迁移。 版本低于17.0的集群上的逻辑槽将被静默忽略。

在开始升级发布者集群之前，确保通过执行 ALTER SUBSCRIPTION ... DISABLE暂时禁用订阅。 升级完成后重新启用订阅。

有一些前提条件需要满足，pg_upgrade才能升级逻辑槽。 如果这些条件未满足，将会报告错误。

准备订户升级

设置新的订阅者中的 订阅者配置。pg_upgrade尝试迁移订阅依赖， 包括订阅表信息，该信息存在于 pg_subscription_rel系统目录中，以及订阅的复制源。这允许新订阅者上的逻辑复制 从旧订阅者停止的位置继续。仅当旧集群版本为17.0或更高时，才支持订阅依赖的迁移。 版本低于17.0的集群上的订阅依赖将被静默忽略。

有一些先决条件需要满足，pg_upgrade才能升级订阅。 如果这些条件未满足，将会报告错误。

停止两个服务器

确保两个数据库服务器都已停止，在 Unix 上，例如：

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

或者在 Windows 上，使用正确的服务名称：

NET STOP postgresql-12
NET STOP postgresql-17

流复制和日志传送备用服务器必须在此关闭期间运行，以便它们接收所有更改。

为后备服务器升级做准备

如果您正在使用第Step 13节中概述的方法升级备用服务器，请通过运行pg_controldata命令检查旧的备用服务器和主服务器集群是否同步。 确保所有集群中“最新检查点位置”的值匹配。此外，请确保在新的主服务器集群的postgresql.conf文件中未将wal_level设置为minimal。

运行 pg_upgrade

总是应该运行新服务器而不是旧服务器的pg_upgrade二进制文件。 pg_upgrade要求制定新旧集簇的数据和可执行文件（bin）目录。 你也可以指定用户和端口值，以及你是否想要用链接或克隆来取代默认的复制行为对数据文件进行处理。

如果你使用链接模式，升级将会快很多（不需要文件拷贝）并且将使用 更少的磁盘空间，但是在升级后一旦启动新集簇，旧集簇就无法被访问。 链接模式也要求新旧集簇数据目录位于同一个文件系统中（表空间和 pg_wal可以在不同的文件系统中）。 克隆模式提供了相同的速度以及磁盘空间优势，但不会导致新群集启动后旧群集不可用。 克隆模式还需要新旧数据目录位于同一文件系统中。 此模式仅在某些操作系统和文件系统上可用。

--jobs选项允许多个CPU核用于文件的复制/链接以及并行转储和恢复数据库模式；一个好的起点是CPU核数和表空间数的最大值。这个选项可以显著减少在多处理器机器上运行的多数据库服务器升级所需的时间。

对于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"

启动后，pg_upgrade会验证两个集群是否兼容，然后执行升级。 您可以使用pg_upgrade --check仅执行检查，即使旧服务器仍在运行。 pg_upgrade --check还会列出升级后需要手动调整的内容。 如果您打算使用链接或克隆模式，应结合--check选项使用 --link或--clone以启用特定模式的检查。 pg_upgrade需要在当前目录具有写权限。

显然，没有人可以在升级期间访问这些集簇。pg_upgrade 默认会在端口 50432 上运行服务器来避免意外的客户端连接。在做升级时， 可以对两个集簇使用相同的端口号，因为新旧集簇不会在同时被运行。不过， 在检查一个旧的运行中服务器时，新旧端口号必须不同。

如果在恢复数据库模式时发生错误，pg_upgrade将会退出 并且你必须按照下文Step 19中所说的恢复 旧集簇。要再次尝试pg_upgrade，你将需要修改 旧集簇，这样 pg_upgrade 模式会成功恢复。如果问题是一个 contrib模块， 你可能需要从旧集簇中卸载该模块并且在升级后重新把它安装在新集簇中，不过 这样做的前提是该模块没有被用来存储用户数据。

升级流复制和日志传送后备服务器

如果使用链接模式并且有流复制（见Section 26.2.5）或者日志 传送（见Section 26.2）后备服务器，你可以遵照下面的 步骤对它们进行快速的升级。你将不用在这些后备服务器上运行 pg_upgrade，而是在主服务器上运行rsync。 到这里还不要启动任何服务器。

如果你没有使用链接模式、没有或不想使用rsync或者想用一种更容易的解决方案，请跳过这一节中的过程并且在pg_upgrade完成并且新的主集簇开始运行后重建后备服务器。

恢复 pg_hba.conf

如果你修改了pg_hba.conf，则要将其恢复到原始的设置。 也可能需要调整新集簇中的其他配置文件来匹配旧集簇，例如 postgresql.conf（以及它包含的任何文件）和 postgresql.auto.conf。

启动新服务器

现在可以安全地启动新的服务器，并且可以接着启动任何 rsync过的后备服务器。

升级后处理

如果需要做任何升级后处理，pg_upgrade 将在完成后发出警告。它也将 生成必须由管理员运行的脚本文件。这些脚本文件将连接到每一个需要做 升级后处理的数据库。每一个脚本应该这样运行：

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

这些脚本可以以任何顺序运行并且在运行之后立即删除。

统计信息

由于pg_upgrade并未传输优化器统计信息，在升级的尾声 你将被指示运行一个命令来生成这些信息。你可能需要设置连接参数来匹配你 的新集簇。

使用 vacuumdb --all --analyze-only 可以高效地生成此类统计信息， 并且使用 --jobs 可以加快速度。选项 --analyze-in-stages 可用于快速生成最小统计信息。如果 vacuum_cost_delay 设置为非零值， 则可以使用 PGOPTIONS 覆盖此设置以加快统计信息生成速度， 例如，PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ...。

删除旧集簇

一旦你对升级表示满意，你就可以通过运行 pg_upgrade完成时提到的脚本来删除旧集簇的 数据目录（如果在旧数据目录中有用户定义的表空间就不可能实现自动删除）。 你也可以删除旧安装目录（例如bin、share）。

恢复到旧集簇

在运行pg_upgrade之后，如果你希望恢复到 旧集簇，有几个选项：