PostgreSQL 教程

Appearance

pg_upgrade ​

pg_upgrade — 升级PostgreSQL服务器实例

语法 ​

pg_upgrade``-boldbindir[-Bnewbindir]-doldconfigdir-Dnewconfigdir[option...]

描述 ​

pg_upgrade（以前称为pg_migrator）允许将存储在PostgreSQL数据文件中的数据升级到较新的PostgreSQL主要版本，而无需通常需要进行主要版本升级的数据转储/还原，例如从 12.14 升级到 13.10 或从 14.9 升级到 15.5。对于次要版本升级，例如从 12.7 升级到 12.8 或从 14.1 升级到 14.5，则不需要此工具。

PostgreSQL 主要版本会定期添加新功能，这些功能通常会更改系统表的布局，但内部数据存储格式很少更改。pg_upgrade利用这一事实通过创建新的系统表并简单地重用旧用户数据文件来执行快速升级。如果未来的主要版本以使旧数据格式无法读取的方式更改了数据存储格式，则pg_upgrade将无法用于此类升级。（社区将尝试避免这种情况。）

pg_upgrade会尽力确保旧集群和新集群是二进制兼容的，例如，通过检查兼容的编译时设置，包括 32/64 位二进制文件。重要的是，任何外部模块也必须是二进制兼容的，尽管pg_upgrade无法检查这一点。

pg_upgrade 支持从 9.2.X 及更高版本升级到PostgreSQL的当前主要版本，包括快照和测试版。

选项 ​

pg_upgrade接受以下命令行参数

-b bindir
--old-bindir=bindir

旧 PostgreSQL 可执行文件目录；环境变量 PGBINOLD

-B bindir
--new-bindir=bindir

新 PostgreSQL 可执行文件目录；默认为 pg_upgrade 所在目录；环境变量 PGBINNEW

-c
--check

仅检查集群，不更改任何数据

-d configdir
--old-datadir=configdir

旧数据库集群配置目录；环境变量 PGDATAOLD

-D configdir
--new-datadir=configdir

新数据库集群配置目录；环境变量 PGDATANEW

-j njobs
--jobs=njobs

要使用的同时进程或线程数

-k
--link

使用硬链接，而不是将文件复制到新集群

-N
--no-sync

默认情况下，pg_upgrade 会等待已升级集群的所有文件安全写入磁盘。此选项会导致 pg_upgrade 在不等待的情况下返回，速度更快，但意味着随后的操作系统崩溃可能会导致数据目录损坏。通常，此选项对于测试很有用，但不应在生产安装中使用。

-o options
--old-options options

直接传递给旧 postgres 命令的选项；多个选项调用将被追加

-O options
--new-options options

直接传递给新 postgres 命令的选项；多个选项调用将被追加

-p port
--old-port=port

旧集群端口号；环境变量 PGPORTOLD

-P port
--new-port=port

新集群端口号；环境变量 PGPORTNEW

-r
--retain

即使在成功完成之后，也保留 SQL 和日志文件

-s dir
--socketdir=dir

升级期间用于后端服务器套接字的目录；默认是当前工作目录；环境变量 PGSOCKETDIR

-U username
--username=username

集群的安装用户名；环境变量 PGUSER

-v
--verbose

启用详细内部日志记录

-V
--version

显示版本信息，然后退出

--clone

使用高效文件克隆（在某些系统上也称为““reflinks””）代替将文件复制到新集群。这会导致数据文件几乎立即复制，从而获得 -k/--link 的速度优势，同时保持旧集群不变。

文件克隆仅在某些操作系统和文件系统上受支持。如果选择但不支持，pg_upgrade 运行将出错。目前，它在 Linux（内核 4.5 或更高版本）上受支持，文件系统为 Btrfs 和 XFS（在创建时支持 reflink 的文件系统上），在 macOS 上受支持，文件系统为 APFS。

--copy

将文件复制到新集群。这是默认值。（另请参见 --link 和 --clone。）

-?
--help

显示帮助，然后退出

用法 ​

以下是用pg_upgrade执行升级的步骤

  1. （可选）移动旧集群

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

    如果您的安装目录不是特定于版本的，例如 /usr/local/pgsql，则必须移动当前 PostgreSQL 安装目录，以免它干扰新的 PostgreSQL 安装。一旦当前 PostgreSQL 服务器关闭，就可以安全地重命名 PostgreSQL 安装目录；假设旧目录是 /usr/local/pgsql，您可以执行

    mv /usr/local/pgsql /usr/local/pgsql.old

    来重命名目录。

  2. 对于源安装，构建新版本

    使用与旧集群兼容的 configure 标志构建新的 PostgreSQL 源。pg_upgrade 将检查 pg_controldata 以确保所有设置在开始升级之前都兼容。

  3. 安装新的 PostgreSQL 二进制文件

    安装新服务器的二进制文件和支持文件。pg_upgrade 包含在默认安装中。

    对于源安装，如果您希望在自定义位置安装新服务器，请使用 prefix 变量

    make prefix=/usr/local/pgsql.new install

  4. 初始化新的 PostgreSQL 集群

    使用 initdb 初始化新集群。同样，使用与旧集群匹配的兼容 initdb 标志。许多预构建的安装程序会自动执行此步骤。无需启动新集群。

  5. 安装扩展共享对象文件

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

  6. 复制自定义全文搜索文件

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

  7. 调整身份验证

    pg_upgrade 将多次连接到旧服务器和新服务器，因此您可能希望在 pg_hba.conf 中将身份验证设置为 peer 或使用 ~/.pgpass 文件（请参阅 第 34.16 节）。

  8. 停止两个服务器

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

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

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

    NET STOP postgresql-12
NET STOP postgresql-16

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

  9. 准备备用服务器升级

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

  10. 运行 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/guide/12/data"
        --new-datadir "C:/Program Files/guide/16/data"
        --old-bindir "C:/Program Files/guide/12/bin"
        --new-bindir "C:/Program Files/guide/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 模块，并在升级后在新的集群中安装它，前提是该模块未用于存储用户数据。

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

    如果您使用了链接模式，并且有流复制（请参阅第 27.2.5 节）或日志传送（请参阅第 27.2 节）备用服务器，则可以按照以下步骤快速升级它们。您不会在备用服务器上运行pg_upgrade，而是在主服务器上运行rsync。不要启动任何服务器。

    如果您没有使用链接模式，没有或不想使用rsync，或者想要一个更简单的解决方案，请跳过本节中的说明，并在pg_upgrade完成且新主服务器正在运行后重新创建备用服务器。

    1. 在备用服务器上安装新的 PostgreSQL 二进制文件

      确保在所有备用服务器上安装了新的二进制文件和支持文件。

    2. 确保新的备用数据目录不存在

      确保新的备用数据目录不存在或为空。如果运行了initdb，请删除备用服务器的新数据目录。

    3. 安装扩展共享对象文件

      在新的备用服务器上安装与在新主集群中安装的相同的扩展共享对象文件。

    4. 停止备用服务器

      如果备用服务器仍在运行，请立即使用上述说明停止它们。

    5. 保存配置文件

      从旧备用服务器的配置文件目录中保存您需要保留的任何配置文件，例如 postgresql.conf（以及它包含的任何文件）、postgresql.auto.conf、pg_hba.conf，因为这些文件将在下一步中被覆盖或删除。

    6. 运行rsync

      在使用链接模式时，可以使用rsync快速升级备用服务器。要实现此目的，请从主服务器上一个位于旧数据库集群目录和新数据库集群目录之上的目录中，在主服务器上针对每个备用服务器运行以下命令

      rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir

      其中 old_cluster 和 new_cluster 相对于主服务器上的当前目录，而 remote_dir 在备用服务器上位于旧集群和新集群目录的 上方。主服务器和备用服务器上指定目录下的目录结构必须匹配。有关指定远程目录的详细信息，请查阅 rsync 手册页，例如：

      rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/guide/12 \
      /opt/guide/16 standby.example.com:/opt/PostgreSQL

      你可以使用 rsync 的 --dry-run 选项验证命令将执行的操作。虽然 rsync 必须在主服务器上至少为一个备用服务器运行，但只要升级后的备用服务器尚未启动，就可以在升级后的备用服务器上运行 rsync 以升级其他备用服务器。

      此操作记录了 pg_upgrade 的链接模式创建的链接，该链接连接了主服务器上旧集群和新集群中的文件。然后，它会在备用服务器的旧集群中找到匹配的文件，并在备用服务器的新集群中为它们创建链接。未在主服务器上链接的文件将从主服务器复制到备用服务器。（它们通常很小。）这提供了快速的备用服务器升级。遗憾的是，rsync 会不必要地复制与临时表和未记录表关联的文件，因为这些文件通常不存在于备用服务器上。

      如果你有表空间，则需要为每个表空间目录运行类似的 rsync 命令，例如：

      rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_12_201909212 \
      /vol1/pg_tblsp/PG_16_202307071 standby.example.com:/vol1/pg_tblsp

      如果你已将 pg_wal 重新定位到数据目录之外，则还必须在这些目录上运行 rsync。

    7. 配置流复制和日志传送备用服务器

      为日志传送配置服务器。（你不必运行 pg_backup_start() 和 pg_backup_stop() 或进行文件系统备份，因为备用服务器仍与主服务器同步。）复制槽未复制，必须重新创建。

  12. 还原 pg_hba.conf

    如果您修改了 pg_hba.conf，请恢复其原始设置。可能还需要调整新集群中的其他配置文件以匹配旧集群，例如 postgresql.conf（以及它包含的任何文件）、postgresql.auto.conf。

  13. 启动新服务器

    现在可以安全地启动新服务器，然后启动任何 rsync 备用服务器。

  14. 升级后处理

    如果需要任何升级后处理，pg_upgrade 将在完成时发出警告。它还将生成脚本文件，管理员必须运行这些文件。脚本文件将连接到需要升级后处理的每个数据库。每个脚本都应使用以下命令运行

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

    脚本可以按任何顺序运行，并且在运行后可以删除。

    警告

    通常，在重建脚本运行完成之前，访问重建脚本中引用的表是不安全的；这样做可能会产生不正确的结果或性能不佳。未在重建脚本中引用的表可以立即访问。

  15. 统计信息

    由于优化器统计信息不会由 pg_upgrade 传输，因此您将被指示在升级结束时运行一个命令来重新生成该信息。您可能需要设置连接参数以匹配您的新集群。

  16. 删除旧集群

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

  17. 还原到旧集群

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

    • 如果使用了 --check 选项，则旧集群未被修改；可以重新启动它。

    • 如果 --link 选项未 使用，则旧集群未被修改；可以重新启动它。

    • 如果使用了 --link 选项，数据文件可能会在旧集群和新集群之间共享

      • 如果 pg_upgrade 在链接开始前中止，旧集群将保持不变；可以重新启动它。

      • 如果您没有启动新集群，旧集群将保持不变，除非在链接开始时，.old 后缀被附加到 $PGDATA/global/pg_control。要重新使用旧集群，请从 $PGDATA/global/pg_control 中删除 .old 后缀；然后，您可以重新启动旧集群。

      • 如果您确实启动了新集群，它已写入共享文件，并且使用旧集群是不安全的。在这种情况下，需要从备份中还原旧集群。

备注 ​

pg_upgrade创建各种工作文件，例如模式转储，存储在新集群目录中的pg_upgrade_output.d中。每次运行都会创建一个新的子目录，其名称采用 ISO 8601 格式化的时间戳命名 (%Y%m%dT%H%M%S)，其中存储了所有生成的文件。如果pg_upgrade成功完成，pg_upgrade_output.d及其包含的文件将自动删除；但在出现问题时，那里的文件可能会提供有用的调试信息。

pg_upgrade在旧数据目录和新数据目录中启动短暂的 Postmaster。与这些 Postmaster 通信的临时 Unix 套接字文件默认情况下在当前工作目录中创建。在某些情况下，当前目录的路径名可能太长而无法成为有效的套接字名称。在这种情况下，您可以使用-s选项将套接字文件放在路径名较短的某个目录中。为了安全起见，请确保该目录不可被任何其他用户读取或写入。（Windows 不支持此功能。）

如果pg_upgrade影响您的安装，它将报告所有故障、重建和重新索引案例；将自动生成重建表和索引的升级后脚本。如果您尝试自动化许多集群的升级，您会发现具有相同数据库架构的集群在所有集群升级中需要相同的升级后步骤；这是因为升级后步骤基于数据库架构，而不是用户数据。

对于部署测试，创建一个仅包含架构的旧集群副本，插入虚拟数据并对其进行升级。

pg_upgrade不支持升级包含使用以下reg*OID 引用系统数据类型的表列的数据库

regcollation
regconfig
regdictionary
regnamespace
regoper
regoperator
regproc
regprocedure

(regclass、regrole和regtype可以升级。)

如果您想使用链接模式，并且您不希望在启动新集群时修改旧集群，请考虑使用克隆模式。如果不可用，请复制旧集群并在链接模式下对其进行升级。要创建旧集群的有效副本，请使用rsync在服务器运行时创建旧集群的脏副本，然后关闭旧服务器并再次运行rsync --checksum以使用任何更改更新副本使其保持一致。（--checksum是必需的，因为rsync的文件修改时间粒度仅为一秒。）您可能希望排除某些文件，例如postmaster.pid，如第 26.3.3 节中所述。如果您的文件系统支持文件系统快照或写入时复制文件副本，您可以使用它来备份旧集群和表空间，尽管必须同时创建快照和副本，或在数据库服务器关闭时创建。

另请参见 ​

initdb、pg_ctl、pg_dump、postgres