pg_verifybackup

pg_verifybackup — 验证 PostgreSQL 集簇基础备份的完整性

当前查看 PostgreSQL 18.6。

说明

pg_verifybackup — 验证 PostgreSQL 集簇基础备份的完整性

手册中的可执行程序: 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 命令行参数的帮助并退出。

手册定义

pg_verifybackup

pg_verifybackup — 验证PostgreSQL集簇基础备份的完整性

大纲

pg_verifybackup [option...]

说明

pg_verifybackup 根据备份时由服务器生成的 backup_manifest，检查使用 pg_basebackup 制作的数据库集群备份的完整性。备份可以采用 "plain" 或 "tar" 格式，也包括使用 pg_basebackup 支持的任何算法压缩的 tar 格式备份。不过，目前只有 plain 格式的备份支持 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命令行参数的帮助并退出。

示例

要为位于mydbserver的服务器创建基础备份，并验证该备份的完整性：

$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
$ pg_verifybackup /usr/local/pgsql/data

要为位于mydbserver的服务器创建基础备份，将备份清单移到备份目录之外的位置，然后验证该备份：

$ pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234
$ mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234
$ pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234

要在验证备份时忽略一个手工添加到备份目录中的文件，并同时跳过校验和验证：

$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
$ edit /usr/local/pgsql/data/note.to.self
$ pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data

另见

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 @@
         "--exit-on-error"
       ],
       "signature": "-e --exit-on-error"
+    },
+    {
+      "description": "Specifies the format of the backup. format can be one of the following: p plain Backup consists of plain files with the same layout as the source server's data directory and tablespaces. t tar Backup consists of tar files, which may be compressed. A valid backup includes the main data directory in a file named base.tar , the WAL files in pg_wal.tar , and separate tar files for each tablespace, named after the tablespace's OID. If the backup is compressed, the relevant compression extension is added to the end of each file name.",
+      "names": [
+        "-F format",
+        "--format= format"
+      ],
+      "signature": "-F format --format= format"
     },
     {
       "description": "Ignore the specified file or directory, which should be expressed as a relative path name, when comparing the list of data files actually present in the backup to those listed in the backup_manifest file. If a directory is specified, this option affects the entire subtree rooted at that location. Complaints about extra files, missing files, file size differences, or checksum mismatches will be suppressed if the relative path name matches the specified path name. This option can be specified multiple times.",

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

快速链接

pg_verifybackup

说明

用法

手册中的选项

手册定义

pg_verifybackup

大纲

说明

选项

示例

另见

文档与源码

版本比较

相关条目