Postgresql 中文操作指南

pg_upgrade

pg_upgrade — 升级 PostgreSQL 服务器实例

Synopsis

pg_upgrade -b oldbindir [ -B newbindir ] -d oldconfigdir -D newconfigdir [ option …​]

Description

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 的当前主要版本，包括 snapshot 和 beta 版本。

Options

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_

    • enable verbose internal logging

  • -V_—​version_

    • 显示版本信息，然后退出

  • —​clone

    • 使用高效文件克隆（在某些系统上也称为“引用链接”）代替将文件复制到新集群。这可能会导致数据文件近乎瞬间复制，从而提供 @ -k @@/@ —​link @@ 的速度优势，同时保持旧集群不变。

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

  • —​copy

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

  • -?_—​help_

    • show help, then exit

Usage

下面是使用 pg_upgrade 执行升级的步骤：

Caution

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

Notes

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

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

如果 pg_upgrade 影响到您的安装，它将报告所有故障、重建和重新索引情况；重建表和索引的后升级脚本会自动生成。如果您尝试自动升级多个集群，您应当发现具有相同数据库模式的集群需要相同的后升级步骤来进行所有集群升级；这是因为后升级步骤基于数据库模式，而不是用户数据。

对于部署测试，创建旧集群的仅模式副本，插入虚拟数据，然后升级副本。

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

（@ regclass @@、@ regrole @@ 和 @ regtype @@ 可以升级。）

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

See Also

initdb ， pg_ctl ， pg_dump ， postgres