pg_combinebackup

pg_combinebackup — 从增量备份及其所依赖的备份重建完整备份

当前查看 PostgreSQL 18.6。

说明

pg_combinebackup — 从增量备份及其所依赖的备份重建完整备份

手册中的可执行程序: pg_combinebackup
程序版本: 18.6
参考清单: 客户端程序
选项定义组: 14

用法

pg_combinebackup [ option ...] [ backup_directory ...]

手册中的选项

选项与参数	说明
-d --debug	在 stderr 上输出大量调试日志。
-k --link	在合成备份中使用硬链接，而不是复制文件。这样重建合成备份可能更快（因为无需复制文件），并且占用更少磁盘空间；但在使用输出目录时必须格外小心，因为对该目录的任何修改（例如启动服务器）也可能影响输入目录。同样，对输入目录的更改（例如在完整备份上启动服务器）也可能影响输出目录。因此，此选项最适合输入目录只是副本、并且会在 pg_combinebackup 完成后被删除的场景。
-n --dry-run	-n / --dry-run 会让 pg_combinebackup 确定将要执行哪些操作，而不实际创建目标目录或任何输出文件。该选项与 --debug 组合时尤其有用。
-N --no-sync	默认情况下， pg_combinebackup 会等待所有文件都被安全写入磁盘。此选项会使 pg_combinebackup 不经等待就直接返回，因此速度更快，但这意味着如果随后操作系统崩溃，输出备份可能会损坏。通常，此选项适合测试，但不应用于创建生产环境安装。
-o outputdir --output= outputdir	指定合成完整备份写入的输出目录。当前该参数是必需的。
-T olddir = newdir --tablespace-mapping= olddir = newdir	在重建备份期间，将目录 olddir 中的表空间重定位到 newdir 。 olddir 是命令行指定的最终备份中该表空间的绝对路径， newdir 是重建备份中要使用的绝对路径。若路径中需要包含等号（ = ），请在其前加反斜杠。可多次指定此选项以映射多个表空间。
--clone	使用高效的文件克隆（某些系统将其称为 “ reflink ” ），代替向新数据目录复制文件，这样可能实现几乎瞬时的数据文件复制。
--copy	执行常规文件复制。这是默认行为。（另见 --copy-file-range 、 --clone 和 -k / --link 。）
--copy-file-range	使用 copy_file_range 系统调用进行高效复制。在某些文件系统上，这会得到与 --clone 类似的结果，即共享物理磁盘块；而在其他文件系统上，它仍可能复制数据块，但会通过优化后的路径进行。目前支持 Linux 和 FreeBSD。
--manifest-checksums= algorithm	与 pg_basebackup 一样， pg_combinebackup 会在输出目录中写入备份清单。此选项指定对清单中每个文件使用的校验和算法。当前可用算法为 NONE 、 CRC32C 、 SHA224 、 SHA256 、 SHA384 和 SHA512 。默认值为 CRC32C 。
--no-manifest	禁用备份清单的生成。若未指定该选项，则会将重建备份的清单写入输出目录。
--sync-method= method	当设置为 fsync （这是默认值）时， pg_combinebackup 会递归打开并同步备份目录中的所有文件。使用普通文件格式时，搜索文件时会跟随 WAL 目录和每个已配置表空间的符号链接。
-V --version	打印 pg_combinebackup 版本并退出。
-? --help	显示 pg_combinebackup 命令行参数帮助并退出。

手册定义

pg_combinebackup

pg_combinebackup — 从增量备份及其所依赖的备份重建完整备份

大纲

pg_combinebackup [option...] [backup_directory...]

说明

pg_combinebackup用于从增量备份及其所依赖的更早备份中重建一个合成的完整备份。

请在命令行上按照从旧到新的顺序指定所有必需的备份。也就是说，第一个备份目录应当是完整备份的路径，最后一个应当是您希望恢复的最终增量备份的路径。重建后的备份将写入由-o选项指定的输出目录。

pg_combinebackup会尝试验证您指定的这些备份是否构成一条合法的备份链，并且能否据此重建出正确的完整备份。但它并不是为帮助您跟踪哪些备份依赖于哪些其他备份而设计的。如果您删除了增量备份所依赖的一个或多个先前备份，就无法恢复该增量备份。此外，pg_combinebackup只会尝试验证这些备份相互之间的关系是否正确，而不会验证每个单独备份本身是否完好；如需完成该项验证，请使用pg_verifybackup。

由于pg_combinebackup的输出是一个合成完整备份，因此它可以作为将来调用pg_combinebackup时的输入。在这种情况下，可以在命令行上指定这个合成完整备份，以代替原先用于重建它的那条备份链。

选项

-d --debug

在stderr上输出大量调试日志。

-k --link

在合成备份中使用硬链接，而不是复制文件。这样重建合成备份可能更快（因为无需复制文件），并且占用更少磁盘空间；但在使用输出目录时必须格外小心，因为对该目录的任何修改（例如启动服务器）也可能影响输入目录。同样，对输入目录的更改（例如在完整备份上启动服务器）也可能影响输出目录。因此，此选项最适合输入目录只是副本、并且会在 pg_combinebackup完成后被删除的场景。

要求输入备份和输出目录位于同一文件系统中。

如果备份清单不可用，或者其中不包含正确类型的校验和，仍会创建硬链接，但也会按块读取文件以计算校验和。

-n --dry-run

-n/--dry-run会让 pg_combinebackup确定将要执行哪些操作，而不实际创建目标目录或任何输出文件。该选项与--debug组合时尤其有用。

-N --no-sync

默认情况下，pg_combinebackup会等待所有文件都被安全写入磁盘。此选项会使pg_combinebackup不经等待就直接返回，因此速度更快，但这意味着如果随后操作系统崩溃，输出备份可能会损坏。通常，此选项适合测试，但不应用于创建生产环境安装。

-o outputdir --output=outputdir

指定合成完整备份写入的输出目录。当前该参数是必需的。

-T olddir=newdir --tablespace-mapping=olddir=newdir

在重建备份期间，将目录olddir中的表空间重定位到 newdir。olddir是命令行指定的最终备份中该表空间的绝对路径，newdir是重建备份中要使用的绝对路径。若路径中需要包含等号（=），请在其前加反斜杠。可多次指定此选项以映射多个表空间。

--clone

使用高效的文件克隆（某些系统将其称为“reflink”），代替向新数据目录复制文件，这样可能实现几乎瞬时的数据文件复制。

如果备份清单不可用，或者其中不包含正确类型的校验和，仍会使用文件克隆来复制文件，但也会按块读取该文件以计算校验和。

文件克隆仅在某些操作系统和文件系统上受支持。如果选择了该选项，但系统并不支持，pg_combinebackup运行时将报错。目前，它在 Linux（内核 4.5 及以上）上的 Btrfs 和 XFS（在创建时启用了 reflink 支持的文件系统）以及 macOS 上的 APFS 上受支持。

--copy

执行常规文件复制。这是默认行为。（另见--copy-file-range、--clone 和-k/--link。）

--copy-file-range

使用copy_file_range系统调用进行高效复制。在某些文件系统上，这会得到与--clone类似的结果，即共享物理磁盘块；而在其他文件系统上，它仍可能复制数据块，但会通过优化后的路径进行。目前支持 Linux 和 FreeBSD。

如果备份清单不可用，或者其中不包含正确类型的校验和，仍会使用copy_file_range复制文件，但也会按块读取该文件以计算校验和。

--manifest-checksums=algorithm

与pg_basebackup一样，pg_combinebackup会在输出目录中写入备份清单。此选项指定对清单中每个文件使用的校验和算法。当前可用算法为NONE、CRC32C、SHA224、SHA256、SHA384和SHA512。默认值为CRC32C。

--no-manifest

禁用备份清单的生成。若未指定该选项，则会将重建备份的清单写入输出目录。

--sync-method=method

当设置为fsync（这是默认值）时，pg_combinebackup会递归打开并同步备份目录中的所有文件。使用普通文件格式时，搜索文件时会跟随 WAL 目录和每个已配置表空间的符号链接。

在 Linux 上，也可以改用syncfs，让操作系统同步包含备份目录的整个文件系统。使用普通文件格式时，pg_combinebackup 还会同步包含 WAL 文件和各表空间的文件系统。关于使用syncfs时需要注意的事项，请参见recovery_init_sync_method。

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

-V --version

打印pg_combinebackup版本并退出。

-? --help

显示pg_combinebackup命令行参数帮助并退出。

限制

pg_combinebackup在写入输出目录时不会重新计算页面校验和。因此，如果用于重建的某些备份是在禁用校验和时创建的，而最终备份是在启用校验和时创建的，则生成的目录中可能包含校验和无效的页面。

为避免这个问题，建议在使用pg_checksums更改集簇的校验和状态之后重新创建一次新的完整备份。否则，您也可以对由pg_combinebackup生成的目录先禁用校验和，然后再按需重新启用，以修正这个问题。

环境

与大多数其他PostgreSQL工具一样，此工具也使用libpq支持的环境变量（见第 32.15 节）。

环境变量PG_COLOR指定是否在诊断消息中使用颜色。可能的值为always、auto和never。

另见

pg_basebackup

文档与源码

来源构建

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

版本比较

PostgreSQL 17 → 18: 属性变化。

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

--- PostgreSQL 17
+++ PostgreSQL 18
@@ -8,6 +8,14 @@
         "--debug"
       ],
       "signature": "-d --debug"
+    },
+    {
+      "description": "Use hard links instead of copying files to the synthetic backup. Reconstruction of the synthetic backup might be faster (no file copying) and use less disk space, but care must be taken when using the output directory, because any modifications to that directory (for example, starting the server) can also affect the input directories. Likewise, changes to the input directories (for example, starting the server on the full backup) could affect the output directory. Thus, this option is best used when the input directories are only copies that will be removed after pg_combinebackup has completed. Requires that the input backups and the output directory are in the same file system. If a backup manifest is not available or does not contain checksum of the right type, hard links will still be created, but the file will be also read block-by-block for the checksum calculation.",
+      "names": [
+        "-k",
+        "--link"
+      ],
+      "signature": "-k --link"
     },
     {
       "description": "The -n / --dry-run option instructs pg_combinebackup to figure out what would be done without actually creating the target directory or any output files. It is particularly useful in combination with --debug .",
@@ -49,7 +57,7 @@
       "signature": "--clone"
     },
     {
-      "description": "Perform regular file copy. This is the default. (See also --copy-file-range and --clone .)",
+      "description": "Perform regular file copy. This is the default. (See also --copy-file-range , --clone , and -k / --link .)",
       "names": [
         "--copy"
       ],

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

快速链接

pg_combinebackup

说明

用法

手册中的选项

手册定义

pg_combinebackup

大纲

说明

选项

限制

环境

另见

文档与源码

版本比较

相关条目