可选地移动旧集簇

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

如果你的安装目录不是版本相关的（例如/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 节）。

停止两个服务器

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

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

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

NET STOP postgresql-12
NET STOP postgresql-18

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

为备用服务器升级做准备

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

运行 pg_upgrade

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

如果您使用链接模式，升级将会更快（没有文件 复制）并且使用更少的磁盘空间，但一旦您在升级后 启动新集群，您将无法访问旧集群。链接模式还 要求旧集群和新集群的数据目录位于 同一文件系统中。（表空间和 pg_wal 可以位于 不同的文件系统中。） 克隆模式提供相同的速度和磁盘空间优势，但 一旦启动新集群，不会导致旧集群无法使用。克隆模式 还要求旧数据目录和新数据目录位于同一文件系统中。 此模式仅在某些操作系统和文件系统上可用。 如果有很多关系，交换模式可能是最快的，但一旦文件传输步骤开始， 您将无法访问旧集群。 交换模式还要求旧集群和新集群的数据目录位于 同一文件系统中。

将 --jobs 设置为 2 或更高值允许 pg_upgrade 并行处理多个数据库和表空间。一个好的起始 点是机器上的 CPU 核心数。此选项可以 大幅减少多数据库和 多表空间服务器的升级时间。

对于 Windows 用户，您必须以管理员账户登录， 然后使用带引号的目录运行 pg_upgrade，例如：

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

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

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

如果在恢复数据库模式时发生错误，pg_upgrade将会退出 并且你必须按照下文步骤 17中所说的恢复 旧集簇。要再次尝试pg_upgrade，你将需要修改 旧集簇，这样 pg_upgrade 模式会成功恢复。如果问题是一个 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

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

统计信息

除非指定了 --no-statistics 选项， pg_upgrade 将从旧集群转移大部分优化器统计信息 到新集群。这并不转移 所有统计信息，例如那些通过 CREATE STATISTICS 显式创建的、 扩展添加的自定义统计信息，或由累积统计系统收集的统计信息。

因为并非所有统计信息都由 pg_upgrade 转移，您将在升级结束时被指示运行命令以 重新生成该信息。您可能需要 设置连接参数以匹配您的新集群。

首先，使用 vacuumdb --all --analyze-in-stages --missing-stats-only 快速生成没有任何关系的最小优化器统计信息。 然后，使用 vacuumdb --all --analyze-only 确保 所有关系都有更新的累积统计信息以触发 VACUUM 和 ANALYZE。对于这两个命令，使用 --jobs 可以加快 速度。 如果 vacuum_cost_delay 设置为非零 值，可以通过使用 PGOPTIONS 来覆盖以加快统计信息生成， 例如，PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ...。

删除旧集簇

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

恢复到旧集簇

如果在运行 pg_upgrade 后，您希望恢复到旧集群， 有几种选择：