可选地移动旧集群

如果使用版本特定的安装目录，例如 /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 还会概述升级后您需要进行的任何手动调整。如果您要使用链接或克隆模式，则应使用选项 --link 或 --clone 与 --check 一起使用以启用特定于模式的检查。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 后，您希望恢复到旧集群，则有多种选择