（可选）移动旧集群

如果您使用的是特定于版本的安装目录，例如 /opt/PostgreSQL/16，则无需移动旧集群。图形化安装程序都使用特定于版本的安装目录。

如果您的安装目录不是特定于版本的，例如 /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 文件（请参阅 第 34.16 节）。

停止两个服务器

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

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

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

NET STOP postgresql-12
NET STOP postgresql-16

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

准备备用服务器升级

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

运行 pg_upgrade

始终运行新服务器的 pg_upgrade 二进制文件，而不是旧服务器的二进制文件。 pg_upgrade 需要指定旧集群和新集群的数据和可执行文件 (bin) 目录。您还可以指定用户和端口值，以及您希望链接数据文件还是克隆数据文件，而不是默认的复制行为。

如果您使用链接模式，升级将更快（无需复制文件）且使用更少的磁盘空间，但您在升级后启动新集群后将无法访问旧集群。链接模式还要求旧集群和新集群数据目录位于同一文件系统中。（表空间和 pg_wal 可以位于不同的文件系统中。）克隆模式提供相同的速度和磁盘空间优势，但不会导致旧集群在新集群启动后无法使用。克隆模式还要求旧数据目录和新数据目录位于同一文件系统中。此模式仅适用于某些操作系统和文件系统。

--jobs 选项允许使用多个 CPU 内核并行复制/链接文件以及转储和还原数据库架构；一个好的起点是 CPU 内核和表空间的最大数量。此选项可以显著减少在多处理器机器上运行的多数据库服务器的升级时间。

对于 Windows 用户，您必须登录到管理帐户，然后以 postgres 用户身份启动 shell 并设置正确的路径

RUNAS /USER:postgres "CMD.EXE"
SET PATH=%PATH%;C:\Program Files\PostgreSQL\16\bin;

然后使用带引号的目录运行 pg_upgrade，例如

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

启动后，pg_upgrade 将验证两个集群是否兼容，然后进行升级。您可以使用 pg_upgrade --check 仅执行检查，即使旧服务器仍在运行。 pg_upgrade --check 还会概述升级后您需要进行的任何手动调整。如果您要使用链接或克隆模式，您应该将选项 --link 或 --clone 与 --check 一起使用以启用特定于模式的检查。 pg_upgrade 要求在当前目录中具有写入权限。

显然，在升级期间，任何人都不应访问集群。 pg_upgrade 默认在端口 50432 上运行服务器，以避免意外的客户端连接。在执行升级时，您可以为两个集群使用相同的端口号，因为旧集群和新集群不会同时运行。但是，在检查旧的正在运行的服务器时，旧端口号和新端口号必须不同。

如果在还原数据库架构时发生错误，pg_upgrade 将退出，您将不得不按照 步骤 17 中概述的步骤还原到旧集群。要再次尝试 pg_upgrade，您需要修改旧集群，以便 pg_upgrade 架构还原成功。如果问题是 contrib 模块，您可能需要从旧集群卸载 contrib 模块，并在升级后在新的集群中安装它，前提是该模块未用于存储用户数据。

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

如果您使用了链接模式，并且有流复制（请参阅第 27.2.5 节）或日志传送（请参阅第 27.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 传输，因此您将被指示在升级结束时运行一个命令来重新生成该信息。您可能需要设置连接参数以匹配您的新集群。

删除旧集群

在您对升级感到满意后，您可以通过在 pg_upgrade 完成时运行提到的脚本来删除旧集群的数据目录。（如果您在旧数据目录中有用户定义的表空间，则无法自动删除。）您还可以删除旧的安装目录（例如 bin、share）。

还原到旧集群

如果您在运行 pg_upgrade 后希望还原到旧集群，则有几个选项