pg_verifybackup

当前查看 PostgreSQL 18。

中文定义与说明

命令行工具 pg_verifybackup [ option ...]。

同版本中文手册节选

描述

pg_verifybackup 用于依据服务器在备份时生成的 backup_manifest，检查使用 pg_basebackup 获取的数据库集簇备份的完整性。备份既可以采用“普通文件”格式，也可以采用“tar”格式；其中也包括使用 pg_basebackup 支持的任意算法压缩的 tar 格式备份。不过，目前仅支持对普通文件格式备份执行 WAL 验证。因此，如果备份采用 tar 格式存储，应使用 -n, --no-parse-wal 选项。

需要注意，pg_verifybackup 执行的验证并未、也不可能涵盖运行中的服务器在尝试使用该备份时会执行的每一项检查。即使使用了此工具，你仍应进行测试恢复，并确认生成的数据库按预期工作且看起来包含正确的数据。不过，pg_verifybackup 能够检测出许多因存储问题或用户错误而常见的问题。

备份验证分为四个阶段。首先，pg_verifybackup 读取 backup_manifest 文件。如果该文件不存在、无法读取、格式不正确、其系统标识符与备份目录中的 pg_control 不匹配，或者未能通过其自身内部校验和的验证，pg_verifybackup 就会以致命错误终止。

其次，pg_verifybackup 将尝试验证当前存储在磁盘上的数据文件与服务器原本打算发送的数据文件完全一致，但下文所述的少数例外情况除外。除了少数例外情况之外，多余文件和缺失文件都会被检测出来。此步骤会忽略 postgresql.auto.conf、standby.signal 和 recovery.signal 的存在或缺失，以及对它们的任何修改，因为预计这些文件可能是在执行备份的过程中创建或修改的。它也不会因目标目录中的 backup_manifest 文件，或 pg_wal 中的任何内容而报告问题，尽管这些文件不会列在备份清单中。这里只检查文件；除间接情况外，不会验证目录是否存在：如果某个目录缺失，则它本应包含的任何文件也必然会缺失。

接着，pg_verifybackup 会为所有文件计算校验和，将其与备份清单中的值进行比较，并对计算结果与备份清单中保存的校验和不匹配的文件报错。对于上一步已产生错误的文件，不会执行这一步，因为这些文件已经确定存在问题。在上一步中被忽略的文件，在这一步中也会被忽略。

最后，pg_verifybackup 会利用备份清单验证从该备份执行恢复所需的预写式日志记录是否存在，并且能够被读取和解析。backup_manifest 包含关于所需预写式日志记录的信息，pg_verifybackup 会利用这些信息调用 pg_waldump 来解析这些预写式日志记录。调用时会使用 --quiet 标志，这样 pg_waldump 只会报告错误，而不会产生其他输出。这个层次的验证足以发现诸如文件缺失或文件内部校验和不匹配之类的明显问题，但还不够全面，无法检测恢复时可能发生的每一种问题。例如，如果服务器中的 bug 生成了校验和正确、但指定的动作毫无意义的预写式日志记录，这种方法就无法检测出来。

另请注意，如果存在恢复该备份并不需要的额外 WAL 文件，此工具不会检查它们；不过，可以为此单独调用一次 pg_waldump。还要注意，WAL 验证与版本相关：你必须使用与被检查备份对应版本的 pg_verifybackup，因此也必须使用对应版本的 pg_waldump。相比之下，数据文件完整性检查应当适用于任何能够生成 backup_manifest 文件的服务器版本。

选项

pg_verifybackup 接受以下命令行参数：

-e --exit-on-error

一旦检测到备份存在问题就立即退出。如果未指定此选项，pg_verifybackup 即使在发现问题之后也会继续检查备份，并将检测到的所有问题报告为错误。

-F format --format=format

指定备份格式。format 可以是下列值之一：

p plain: 备份由普通文件组成，其布局与源服务器的数据目录和表空间相同。
t tar: 备份由 tar 文件组成，这些文件可以经过压缩。有效的备份包括存放在 base.tar 文件中的主数据目录、存放在 pg_wal.tar 中的 WAL 文件，以及每个表空间对应的单独 tar 文件，这些文件以该表空间的 OID 命名。如果备份被压缩，则会在每个文件名末尾追加相应的压缩扩展名。

-i path --ignore=path

在将备份中实际存在的数据文件列表与 backup_manifest 文件中列出的数据文件列表进行比较时，忽略指定的文件或目录；它们应以相对路径名表示。如果指定的是目录，则此选项会影响以该位置为根的整个子树。如果相对路径名与指定的路径名匹配，则关于额外文件、缺失文件、文件大小差异或校验和不匹配的报错将被抑制。此选项可指定多次。

-m path --manifest-path=path

使用指定路径上的备份清单文件，而不是位于备份目录根部的那份文件。

-n --no-parse-wal

不要尝试解析从此备份执行恢复所需的预写式日志数据。

-P --progress

启用进度报告。启用此选项后，在验证校验和时会输出进度报告。

此选项不能与 --quiet 一起使用。

-q --quiet

当备份成功通过验证时不输出任何内容。

-s --skip-checksums

不验证数据文件的校验和。仍会检查文件是否存在以及这些文件的大小。这样会快得多，因为不需要读取文件本身。

-w path --wal-directory=path

尝试解析存储在指定目录中的 WAL 文件，而不是 pg_wal 中的 WAL 文件。如果备份与 WAL 归档分开存放，这会很有用。

其他选项也可用：

-V --version: 打印 pg_verifybackup 版本并退出。
-? --help: 显示有关 pg_verifybackup 命令行参数的帮助并退出。

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

说明

描述 pg_verifybackup 用于依据服务器在备份时生成的 backup_manifest ，检查使用 pg_basebackup 获取的数据库集簇备份的完整性。备份既可以采用“普通文件”格式，也可以采用“tar”格式；其中也包括使用 pg_basebackup 支持的任意算法压缩的 tar 格式备份。不过，目前仅支持对普通文件格式备份执行 WAL 验证。因此，如果备份采用 tar 格式存储，应使用 -n, --no-parse-wal 选项。需要注意， pg_verifybackup 执行的验证并未、也不可能涵盖运行中的服务器在尝试使用该备份时会执行的每一项检查。即使使用了此工具，你仍应进行测试恢复，并确认生成的数据库按预期工作且看起来包含正确的数据。不过， pg_verifybackup 能够检测出许多因存储问题或用户错误而常见的问题。备份验证分为四个阶段。首先， pg_verifybackup 读取 backup_manifest 文件。如果该文件不存在、无法读取、格式不正确、其系统标识符与备份目录中的 pg_control 不匹配，或者未能通过其自身内部校验和的验证， pg_verifybackup 就会以致命错误终止。其次， pg_verifybackup 将尝试验证当前存储在磁盘上的数据文件与服务器原本打算发送的数据文件完全一致，但下文所述的少数例外情况除外。除了少数例外情况之外，多余文件和缺失文件都会被检测出来。此步骤会忽略 postgresql.auto.conf 、 standby.signal 和 recovery.signal 的存在或缺失，以及对它们的任何修改，因为预计这些文件可能是在执行备份的过程中创建或修改的。它也不会因目标目录中的 backup_manifest 文件，或 pg_wal 中的任何内容而报告问题，尽管这些文件不会列在备份清单中。这里只检查文件；除间接情况外，不会验证目录是否存在：如果某个目录缺失，则它本应包含的任何文件也必然会缺失。接着， pg_verifybackup 会为所有文件计算校验和，将其与备份清单中

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

用法

pg_verifybackup [ option ...]

手册中的选项

选项与参数	说明
-e --exit-on-error	一旦检测到备份存在问题就立即退出。如果未指定此选项， pg_verifybackup 即使在发现问题之后也会继续检查备份，并将检测到的所有问题报告为错误。
-F format --format= format	指定备份格式。 format 可以是下列值之一：
-i path --ignore= path	在将备份中实际存在的数据文件列表与 backup_manifest 文件中列出的数据文件列表进行比较时，忽略指定的文件或目录；它们应以相对路径名表示。如果指定的是目录，则此选项会影响以该位置为根的整个子树。如果相对路径名与指定的路径名匹配，则关于额外文件、缺失文件、文件大小差异或校验和不匹配的报错将被抑制。此选项可指定多次。
-m path --manifest-path= path	使用指定路径上的备份清单文件，而不是位于备份目录根部的那份文件。
-n --no-parse-wal	不要尝试解析从此备份执行恢复所需的预写式日志数据。
-P --progress	启用进度报告。启用此选项后，在验证校验和时会输出进度报告。
-q --quiet	当备份成功通过验证时不输出任何内容。
-s --skip-checksums	不验证数据文件的校验和。仍会检查文件是否存在以及这些文件的大小。这样会快得多，因为不需要读取文件本身。
-w path --wal-directory= path	尝试解析存储在指定目录中的 WAL 文件，而不是 pg_wal 中的 WAL 文件。如果备份与 WAL 归档分开存放，这会很有用。
-V --version	打印 pg_verifybackup 版本并退出。
-? --help	显示有关 pg_verifybackup 命令行参数的帮助并退出。

文档与源码

来源构建

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

版本比较

PostgreSQL 15 → 16: 属性变化。

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

--- PostgreSQL 15
+++ PostgreSQL 16
@@ -32,6 +32,14 @@
         "--no-parse-wal"
       ],
       "signature": "-n --no-parse-wal"
+    },
+    {
+      "description": "Enable progress reporting. Turning this on will deliver a progress report while verifying checksums. This option cannot be used together with the option --quiet .",
+      "names": [
+        "-P",
+        "--progress"
+      ],
+      "signature": "-P --progress"
     },
     {
       "description": "Don't print anything when a backup is successfully verified.",

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

快速链接