pg_upgrade
描述 pg_upgrade （以前称为 pg_migrator ）允许将存储在 PostgreSQL 数据文件中的数据升级到更新的 PostgreSQL 主版本，而无需执行主版本升级通常所需的数据转储/恢复，例如从 12.14 升级到 13.10，或从 14.9 升级到 15.5。次版本升级不需要使用它，例如从 12.7 升级到 12.8 或从 14.1 升级到 14.5。 PostgreSQL 主版本会定期增加新特性，这些特性常常会改变系统表的布局，但内部数据存储格式很少改变。 pg_upg…
当前查看 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 接受下列命令行参数：
-bbindir--old-bindir=bindir旧 PostgreSQL 可执行文件目录；环境变量
PGBINOLD-Bbindir--new-bindir=bindir新 PostgreSQL 可执行文件目录；默认是 pg_upgrade 所在目录；环境变量
PGBINNEW-c--check仅检查集簇，不更改任何数据
-dconfigdir--old-datadir=configdir旧数据库集簇配置目录；环境变量
PGDATAOLD-Dconfigdir--new-datadir=configdir新数据库集簇配置目录；环境变量
PGDATANEW-jnjobs--jobs=njobs要使用的并发连接和进程/线程数
-k--link使用硬链接而不是把文件复制到新集簇
-N--no-sync默认情况下，
pg_upgrade会等待升级后集簇的所有文件都被安全地写入磁盘。该选项会使pg_upgrade不等待即返回，这样更快，但也意味着后续若发生操作系统崩溃，数据目录可能会损坏。通常来说，这个选项适用于测试，但不应在生产安装中使用。-ooptions--old-optionsoptions将直接传递给旧
postgres命令的选项；多次指定会追加-Ooptions--new-optionsoptions将直接传递给新
postgres命令的选项；多次指定会追加-pport--old-port=port旧集簇端口号；环境变量
PGPORTOLD-Pport--new-port=port新集簇端口号；环境变量
PGPORTNEW-r--retain即使成功完成后也保留 SQL 和日志文件
-sdir--socketdir=dir升级期间用于 postmaster 套接字的目录；默认值为当前工作目录；环境变量
PGSOCKETDIR-Uusername--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 14 → 15: 属性变化。
以下差异保留原始字段名与英文源描述。
--- PostgreSQL 14
+++ PostgreSQL 15
@@ -56,6 +56,14 @@
"--link"
],
"signature": "-k --link"
+ },
+ {
+ "description": "By default, pg_upgrade will wait for all files of the upgraded cluster to be written safely to disk. This option causes pg_upgrade to return without waiting, which is faster, but means that a subsequent operating system crash can leave the data directory corrupt. Generally, this option is useful for testing but should not be used on a production installation.",
+ "names": [
+ "-N",
+ "--no-sync"
+ ],
+ "signature": "-N --no-sync"
},
{
"description": "options to be passed directly to the old postgres command; multiple option invocations are appended",比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。
相关条目
导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。