1PG_VERIFYBACKUP(1) PostgreSQL 15.4 Documentation PG_VERIFYBACKUP(1)
2
6 pg_verifybackup - verify the integrity of a base backup of a PostgreSQL
7 cluster
8
10 pg_verifybackup [option...]
11
13 pg_verifybackup is used to check the integrity of a database cluster
14 backup taken using pg_basebackup against a backup_manifest generated by
15 the server at the time of the backup. The backup must be stored in the
16 "plain" format; a "tar" format backup can be checked after extracting
17 it.
18 It is important to note that the validation which is performed by
20 pg_verifybackup does not and cannot include every check which will be
21 performed by a running server when attempting to make use of the
22 backup. Even if you use this tool, you should still perform test
23 restores and verify that the resulting databases work as expected and
24 that they appear to contain the correct data. However, pg_verifybackup
25 can detect many problems that commonly occur due to storage problems or
26 user error.
27 Backup verification proceeds in four stages. First, pg_verifybackup
29 reads the backup_manifest file. If that file does not exist, cannot be
30 read, is malformed, or fails verification against its own internal
31 checksum, pg_verifybackup will terminate with a fatal error.
32 Second, pg_verifybackup will attempt to verify that the data files
34 currently stored on disk are exactly the same as the data files which
35 the server intended to send, with some exceptions that are described
36 below. Extra and missing files will be detected, with a few exceptions.
37 This step will ignore the presence or absence of, or any modifications
38 to, postgresql.auto.conf, standby.signal, and recovery.signal, because
39 it is expected that these files may have been created or modified as
40 part of the process of taking the backup. It also won't complain about
41 a backup_manifest file in the target directory or about anything inside
42 pg_wal, even though these files won't be listed in the backup manifest.
43 Only files are checked; the presence or absence of directories is not
44 verified, except indirectly: if a directory is missing, any files it
45 should have contained will necessarily also be missing.
46 Next, pg_verifybackup will checksum all the files, compare the
48 checksums against the values in the manifest, and emit errors for any
49 files for which the computed checksum does not match the checksum
50 stored in the manifest. This step is not performed for any files which
51 produced errors in the previous step, since they are already known to
52 have problems. Files which were ignored in the previous step are also
53 ignored in this step.
54 Finally, pg_verifybackup will use the manifest to verify that the
56 write-ahead log records which will be needed to recover the backup are
57 present and that they can be read and parsed. The backup_manifest
58 contains information about which write-ahead log records will be
59 needed, and pg_verifybackup will use that information to invoke
60 pg_waldump to parse those write-ahead log records. The --quiet flag
61 will be used, so that pg_waldump will only report errors, without
62 producing any other output. While this level of verification is
63 sufficient to detect obvious problems such as a missing file or one
64 whose internal checksums do not match, they aren't extensive enough to
65 detect every possible problem that might occur when attempting to
66 recover. For instance, a server bug that produces write-ahead log
67 records that have the correct checksums but specify nonsensical actions
68 can't be detected by this method.
69 Note that if extra WAL files which are not required to recover the
71 backup are present, they will not be checked by this tool, although a
72 separate invocation of pg_waldump could be used for that purpose. Also
73 note that WAL verification is version-specific: you must use the
74 version of pg_verifybackup, and thus of pg_waldump, which pertains to
75 the backup being checked. In contrast, the data file integrity checks
76 should work with any version of the server that generates a
77 backup_manifest file.
78
80 pg_verifybackup accepts the following command-line arguments:
81 -e
83 --exit-on-error
84 Exit as soon as a problem with the backup is detected. If this
85 option is not specified, pg_verifybackup will continue checking the
86 backup even after a problem has been detected, and will report all
87 problems detected as errors.
88 -i path
90 --ignore=path
91 Ignore the specified file or directory, which should be expressed
92 as a relative path name, when comparing the list of data files
93 actually present in the backup to those listed in the
94 backup_manifest file. If a directory is specified, this option
95 affects the entire subtree rooted at that location. Complaints
96 about extra files, missing files, file size differences, or
97 checksum mismatches will be suppressed if the relative path name
98 matches the specified path name. This option can be specified
99 multiple times.
100 -m path
102 --manifest-path=path
103 Use the manifest file at the specified path, rather than one
104 located in the root of the backup directory.
105 -n
107 --no-parse-wal
108 Don't attempt to parse write-ahead log data that will be needed to
109 recover from this backup.
110 -q
112 --quiet
113 Don't print anything when a backup is successfully verified.
114 -s
116 --skip-checksums
117 Do not verify data file checksums. The presence or absence of files
118 and the sizes of those files will still be checked. This is much
119 faster, because the files themselves do not need to be read.
120 -w path
122 --wal-directory=path
123 Try to parse WAL files stored in the specified directory, rather
124 than in pg_wal. This may be useful if the backup is stored in a
125 separate location from the WAL archive.
126 Other options are also available:
128 -V
130 --version
131 Print the pg_verifybackup version and exit.
132 -?
134 --help
135 Show help about pg_verifybackup command line arguments, and exit.
136
138 To create a base backup of the server at mydbserver and verify the
139 integrity of the backup:
140 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
142 $ pg_verifybackup /usr/local/pgsql/data
143 To create a base backup of the server at mydbserver, move the manifest
145 somewhere outside the backup directory, and verify the backup:
146 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234
148 $ mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234
149 $ pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234
150 To verify a backup while ignoring a file that was added manually to the
152 backup directory, and also skipping checksum verification:
153 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
155 $ edit /usr/local/pgsql/data/note.to.self
156 $ pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data
157
159 pg_basebackup(1)
160PostgreSQL 15.4 2023 PG_VERIFYBACKUP(1)