可选地移动旧集群

如果您使用的是特定版本的安装目录，例如 /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 还是其他来源，都使用共享对象文件（或 DLL），例如 pgcrypto.so。如果旧集群使用了这些文件，则必须将与新服务器二进制文件匹配的共享对象文件安装到新集群中，通常通过操作系统命令。不要加载模式定义，例如 CREATE EXTENSION pgcrypto，因为这些定义将从旧集群复制。如果有可用的扩展更新，pg_upgrade 将报告这一点，并创建一个可以稍后运行以更新它们的脚本。

复制自定义全文搜索文件

将任何自定义全文搜索文件（词典、同义词、词库、停用词）从旧集群复制到新集群。

调整身份验证

pg_upgrade 将多次连接到旧服务器和新服务器，因此您可能希望在 pg_hba.conf 中将身份验证设置为 peer 或使用 ~/.pgpass 文件（请参阅第 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

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

准备备用服务器升级

如果您使用步骤 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 将退出，并且您必须按照下面的步骤 19中所述恢复到旧集群。要再次尝试 pg_upgrade，您需要修改旧集群，以便 pg_upgrade 模式恢复成功。如果问题是 contrib 模块，则您可能需要从旧集群卸载 contrib 模块，并在升级后将其安装到新集群中，前提是该模块未用于存储用户数据。

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

如果您使用了链接模式并且有流复制（请参阅 第 26.2.5 节）或日志传送（请参阅 第 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 后，您希望恢复到旧集群，则有以下几种选择：