pg_upgrade

当前查看 PostgreSQL 18。

中文定义与说明

命令行工具 pg_upgrade -b oldbindir [ -B newbindir ] -d oldconfigdir -D newconfigdir [ 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 主版本，包括快照版和 beta 版。

警告

升级集簇会使目标集簇执行由源集簇超级用户所选择的任意代码。升级前，务必确认源集簇超级用户是受信任的。

选项

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

升级期间用于 postmaster 套接字的目录；默认值为当前工作目录；环境变量 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、--copy-file-range 和 --swap。）

--copy-file-range

使用 copy_file_range 系统调用进行高效复制。在某些文件系统上，这会产生与 --clone 类似的结果，即共享物理磁盘块；在另一些文件系统上，它仍然会复制块，但会通过优化路径完成。目前，它在 Linux 和 FreeBSD 上受支持。

--no-statistics

不要把旧集簇中的统计信息恢复到新集簇中。

--set-char-signedness=option

手工设置新集簇默认的 char 有符号性。可选值为 signed 和 unsigned。

在 C 语言中，char 类型在未显式指定时的默认有符号性因平台而异。例如，在 x86 CPU 上 char 默认是 signed char，而在 ARM CPU 上默认是 unsigned char。

从 PostgreSQL 18 开始，数据库集簇会维护自身默认的 char 有符号性设置，可用于确保在默认 char 有符号性不同的平台之间保持一致行为。默认情况下，pg_upgrade 在从现有集簇升级时会保留该有符号性设置。然而，从 PostgreSQL 17 或更早版本升级时，pg_upgrade 会采用其构建所在平台的 char 有符号性。

该选项允许你显式设置新集簇默认的 char 有符号性，以覆盖任何继承值。在以下两种场景中需要考虑该选项：

如果你计划在升级后迁移到不同平台，则不应使用该选项。在这种情况下，默认行为才是正确的。应当先在原平台上不带此选项完成升级，然后再迁移集簇。这是推荐且最安全的方法。
如果你已经将集簇迁移到了默认 char 有符号性不同的平台上（例如从基于 x86 的系统迁移到基于 ARM 的系统），则应使用该选项来指定与原平台默认 char 有符号性相匹配的值。此外，从迁移数据文件到运行 pg_upgrade 之间，切勿修改任何数据文件。pg_upgrade 应当是新平台上首次启动该集簇的操作。

--swap

将数据目录从旧集簇移动到新集簇，然后用为新集簇生成的系统目录文件替换原有目录文件。该模式的性能可能优于 --link、--clone、--copy 和 --copy-file-range，尤其是在关系很多的集簇上。

但是，这种模式会在旧集簇中产生大量垃圾文件，如果使用 --sync-method=syncfs，可能会延长文件同步步骤。因此，建议在 --swap 模式下使用 --sync-method=fsync。

此外，一旦文件传输步骤开始，旧集簇就会被破坏性修改，因此不再能安全启动。详见步骤 17。

--sync-method=method

设置为 fsync（默认）时，pg_upgrade 会递归打开并同步升级后集簇数据目录中的所有文件。查找文件时会跟随 WAL 目录和各个已配置表空间的符号链接。

在 Linux 上，也可以使用 syncfs，让操作系统同步包含升级后集簇数据目录、其 WAL 文件以及各个表空间的整个文件系统。见 recovery_init_sync_method 了解使用 syncfs 时需要注意的事项。

当使用 --no-sync 时，此选项无效。

-? --help

显示帮助，然后退出

查看完整中文手册与上下文。

说明

描述 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 主版本，包括快照版和 beta 版。警告升级集簇会使目标集簇执行由源集簇超级用户所选择的任意代码。升级前，务必确认源集簇超级用户是受信任的。选项 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 新数据库集簇配置目录；环境变量

手册中的可执行程序: pg_upgrade
程序版本: 18.6
参考清单: 服务端程序
选项定义组: 25

用法

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

手册中的选项

选项与参数	说明
-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	升级期间用于 postmaster 套接字的目录；默认值为当前工作目录；环境变量 PGSOCKETDIR
-U username --username= username	集簇安装用户名称；环境变量 PGUSER
-v --verbose	启用详细的内部日志记录
-V --version	显示版本信息，然后退出
--clone	使用高效的文件克隆（在某些系统中也称为 “ reflinks ” ）代替将文件复制到新集簇。这可以几乎瞬间复制数据文件，从而在保持旧集簇不变的同时，获得 -k / --link 的速度优势。
--copy	将文件复制到新集簇。这是默认行为。（另见 --link 、 --clone 、 --copy-file-range 和 --swap 。）
--copy-file-range	使用 copy_file_range 系统调用进行高效复制。在某些文件系统上，这会产生与 --clone 类似的结果，即共享物理磁盘块；在另一些文件系统上，它仍然会复制块，但会通过优化路径完成。目前，它在 Linux 和 FreeBSD 上受支持。
--no-statistics	不要把旧集簇中的统计信息恢复到新集簇中。
--set-char-signedness= option	手工设置新集簇默认的 char 有符号性。可选值为 signed 和 unsigned 。
--swap	将数据目录从旧集簇移动到新集簇，然后用为新集簇生成的系统目录文件替换原有目录文件。该模式的性能可能优于 --link 、 --clone 、 --copy 和 --copy-file-range ，尤其是在关系很多的集簇上。
--sync-method= method	设置为 fsync （默认）时， pg_upgrade 会递归打开并同步升级后集簇数据目录中的所有文件。查找文件时会跟随 WAL 目录和各个已配置表空间的符号链接。
-? --help	显示帮助，然后退出

环境变量

变量	含义
PGBINOLD	旧 PostgreSQL 可执行文件目录；选项 -b / --old-bindir 。
PGBINNEW	新 PostgreSQL 可执行文件目录；选项 -B / --new-bindir 。
PGDATAOLD	旧数据库集簇配置目录；选项 -d / --old-datadir 。
PGDATANEW	新数据库集簇配置目录；选项 -D / --new-datadir 。
PGPORTOLD	旧集簇端口号；选项 -p / --old-port 。
PGPORTNEW	新集簇端口号；选项 -P / --new-port 。
PGSOCKETDIR	升级期间用于 postmaster 套接字的目录；选项 -s / --socketdir 。
PGUSER	集簇安装用户名称；选项 -U / --username 。

文档与源码

来源构建

版本: 18.6
构建: https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹: ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 11 → 12: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 11
+++ PostgreSQL 12
@@ -98,6 +98,14 @@
       "signature": "-r --retain"
     },
     {
+      "description": "directory to use for postmaster sockets during upgrade; default is current working directory; environment variable PGSOCKETDIR",
+      "names": [
+        "-s",
+        "--socketdir="
+      ],
+      "signature": "-s dir --socketdir= dir"
+    },
+    {
       "description": "cluster's install user name; environment variable PGUSER",
       "names": [
         "-U",
@@ -122,6 +130,13 @@
       "signature": "-V --version"
     },
     {
+      "description": "Use efficient file cloning (also known as “ reflinks ” on some systems) instead of copying files to the new cluster. This can result in near-instantaneous copying of the data files, giving the speed advantages of -k / --link while leaving the old cluster untouched. File cloning is only supported on some operating systems and file systems. If it is selected but not supported, the pg_upgrade run will error. At present, it is supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on file systems created with reflink support), and on macOS with APFS.",
+      "names": [
+        "--clone"
+      ],
+      "signature": "--clone"
+    },
+    {
       "description": "show help, then exit",
       "names": [
         "-?",

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

快速链接