Debian Codegraph @

doc/src/sgml/ref/pg_verifybackup.sgml

raw
1 <!--
2 doc/src/sgml/ref/pg_verifybackup.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="app-pgverifybackup">
7 <indexterm zone="app-pgverifybackup">
8 <primary>pg_verifybackup</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle><application>pg_verifybackup</application></refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>pg_verifybackup</refname>
19 <refpurpose>verify the integrity of a base backup of a
20 <productname>PostgreSQL</productname> cluster</refpurpose>
21 </refnamediv>
22
23 <refsynopsisdiv>
24 <cmdsynopsis>
25 <command>pg_verifybackup</command>
26 <arg rep="repeat"><replaceable>option</replaceable></arg>
27 </cmdsynopsis>
28 </refsynopsisdiv>
29
30 <refsect1>
31 <title>Description</title>
32 <para>
33 <application>pg_verifybackup</application> is used to check the
34 integrity of a database cluster backup taken using
35 <command>pg_basebackup</command> against a
36 <literal>backup_manifest</literal> generated by the server at the time
37 of the backup. The backup may be stored either in the "plain" or the "tar"
38 format; this includes tar-format backups compressed with any algorithm
39 supported by <application>pg_basebackup</application>. However, at present,
40 <literal>WAL</literal> verification is supported only for plain-format
41 backups. Therefore, if the backup is stored in tar-format, the
42 <literal>-n, --no-parse-wal</literal> option should be used.
43 </para>
44
45 <para>
46 It is important to note that the validation which is performed by
47 <application>pg_verifybackup</application> does not and cannot include
48 every check which will be performed by a running server when attempting
49 to make use of the backup. Even if you use this tool, you should still
50 perform test restores and verify that the resulting databases work as
51 expected and that they appear to contain the correct data. However,
52 <application>pg_verifybackup</application> can detect many problems
53 that commonly occur due to storage problems or user error.
54 </para>
55
56 <para>
57 Backup verification proceeds in four stages. First,
58 <literal>pg_verifybackup</literal> reads the
59 <literal>backup_manifest</literal> file. If that file
60 does not exist, cannot be read, is malformed, fails to match the system
61 identifier with <filename>pg_control</filename> of the backup directory or
62 fails verification against its own internal checksum,
63 <literal>pg_verifybackup</literal> will terminate with a fatal error.
64 </para>
65
66 <para>
67 Second, <literal>pg_verifybackup</literal> will attempt to verify that
68 the data files currently stored on disk are exactly the same as the data
69 files which the server intended to send, with some exceptions that are
70 described below. Extra and missing files will be detected, with a few
71 exceptions. This step will ignore the presence or absence of, or any
72 modifications to, <literal>postgresql.auto.conf</literal>,
73 <literal>standby.signal</literal>, and <literal>recovery.signal</literal>,
74 because it is expected that these files may have been created or modified
75 as part of the process of taking the backup. It also won't complain about
76 a <literal>backup_manifest</literal> file in the target directory or
77 about anything inside <literal>pg_wal</literal>, even though these
78 files won't be listed in the backup manifest. Only files are checked;
79 the presence or absence of directories is not verified, except
80 indirectly: if a directory is missing, any files it should have contained
81 will necessarily also be missing.
82 </para>
83
84 <para>
85 Next, <literal>pg_verifybackup</literal> will checksum all the files,
86 compare the checksums against the values in the manifest, and emit errors
87 for any files for which the computed checksum does not match the
88 checksum stored in the manifest. This step is not performed for any files
89 which produced errors in the previous step, since they are already known
90 to have problems. Files which were ignored in the previous step are also
91 ignored in this step.
92 </para>
93
94 <para>
95 Finally, <literal>pg_verifybackup</literal> will use the manifest to
96 verify that the write-ahead log records which will be needed to recover
97 the backup are present and that they can be read and parsed. The
98 <literal>backup_manifest</literal> contains information about which
99 write-ahead log records will be needed, and
100 <literal>pg_verifybackup</literal> will use that information to
101 invoke <literal>pg_waldump</literal> to parse those write-ahead log
102 records. The <literal>--quiet</literal> flag will be used, so that
103 <literal>pg_waldump</literal> will only report errors, without producing
104 any other output. While this level of verification is sufficient to
105 detect obvious problems such as a missing file or one whose internal
106 checksums do not match, they aren't extensive enough to detect every
107 possible problem that might occur when attempting to recover. For
108 instance, a server bug that produces write-ahead log records that have
109 the correct checksums but specify nonsensical actions can't be detected
110 by this method.
111 </para>
112
113 <para>
114 Note that if extra WAL files which are not required to recover the backup
115 are present, they will not be checked by this tool, although
116 a separate invocation of <literal>pg_waldump</literal> could be used for
117 that purpose. Also note that WAL verification is version-specific: you
118 must use the version of <literal>pg_verifybackup</literal>, and thus of
119 <literal>pg_waldump</literal>, which pertains to the backup being checked.
120 In contrast, the data file integrity checks should work with any version
121 of the server that generates a <literal>backup_manifest</literal> file.
122 </para>
123 </refsect1>
124
125 <refsect1>
126 <title>Options</title>
127
128 <para>
129 <application>pg_verifybackup</application> accepts the following
130 command-line arguments:
131
132 <variablelist>
133 <varlistentry>
134 <term><option>-e</option></term>
135 <term><option>--exit-on-error</option></term>
136 <listitem>
137 <para>
138 Exit as soon as a problem with the backup is detected. If this option
139 is not specified, <literal>pg_verifybackup</literal> will continue
140 checking the backup even after a problem has been detected, and will
141 report all problems detected as errors.
142 </para>
143 </listitem>
144 </varlistentry>
145
146 <varlistentry>
147 <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
148 <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
149 <listitem>
150 <para>
151 Specifies the format of the backup. <replaceable>format</replaceable>
152 can be one of the following:
153
154 <variablelist>
155 <varlistentry>
156 <term><literal>p</literal></term>
157 <term><literal>plain</literal></term>
158 <listitem>
159 <para>
160 Backup consists of plain files with the same layout as the
161 source server's data directory and tablespaces.
162 </para>
163 </listitem>
164 </varlistentry>
165
166 <varlistentry>
167 <term><literal>t</literal></term>
168 <term><literal>tar</literal></term>
169 <listitem>
170 <para>
171 Backup consists of tar files, which may be compressed. A valid
172 backup includes the main data directory in a file named
173 <filename>base.tar</filename>, the WAL files in
174 <filename>pg_wal.tar</filename>, and separate tar files for
175 each tablespace, named after the tablespace's OID. If the backup
176 is compressed, the relevant compression extension is added to the
177 end of each file name.
178 </para>
179 </listitem>
180 </varlistentry>
181 </variablelist></para>
182 </listitem>
183 </varlistentry>
184
185 <varlistentry>
186 <term><option>-i <replaceable class="parameter">path</replaceable></option></term>
187 <term><option>--ignore=<replaceable class="parameter">path</replaceable></option></term>
188 <listitem>
189 <para>
190 Ignore the specified file or directory, which should be expressed
191 as a relative path name, when comparing the list of data files
192 actually present in the backup to those listed in the
193 <literal>backup_manifest</literal> file. If a directory is
194 specified, this option affects the entire subtree rooted at that
195 location. Complaints about extra files, missing files, file size
196 differences, or checksum mismatches will be suppressed if the
197 relative path name matches the specified path name. This option
198 can be specified multiple times.
199 </para>
200 </listitem>
201 </varlistentry>
202
203 <varlistentry>
204 <term><option>-m <replaceable class="parameter">path</replaceable></option></term>
205 <term><option>--manifest-path=<replaceable class="parameter">path</replaceable></option></term>
206 <listitem>
207 <para>
208 Use the manifest file at the specified path, rather than one located
209 in the root of the backup directory.
210 </para>
211 </listitem>
212 </varlistentry>
213
214 <varlistentry>
215 <term><option>-n</option></term>
216 <term><option>--no-parse-wal</option></term>
217 <listitem>
218 <para>
219 Don't attempt to parse write-ahead log data that will be needed
220 to recover from this backup.
221 </para>
222 </listitem>
223 </varlistentry>
224
225 <varlistentry>
226 <term><option>-P</option></term>
227 <term><option>--progress</option></term>
228 <listitem>
229 <para>
230 Enable progress reporting. Turning this on will deliver a progress
231 report while verifying checksums.
232 </para>
233 <para>
234 This option cannot be used together with the option
235 <option>--quiet</option>.
236 </para>
237 </listitem>
238 </varlistentry>
239
240 <varlistentry>
241 <term><option>-q</option></term>
242 <term><option>--quiet</option></term>
243 <listitem>
244 <para>
245 Don't print anything when a backup is successfully verified.
246 </para>
247 </listitem>
248 </varlistentry>
249
250 <varlistentry>
251 <term><option>-s</option></term>
252 <term><option>--skip-checksums</option></term>
253 <listitem>
254 <para>
255 Do not verify data file checksums. The presence or absence of
256 files and the sizes of those files will still be checked. This is
257 much faster, because the files themselves do not need to be read.
258 </para>
259 </listitem>
260 </varlistentry>
261
262 <varlistentry>
263 <term><option>-w <replaceable class="parameter">path</replaceable></option></term>
264 <term><option>--wal-directory=<replaceable class="parameter">path</replaceable></option></term>
265 <listitem>
266 <para>
267 Try to parse WAL files stored in the specified directory, rather than
268 in <literal>pg_wal</literal>. This may be useful if the backup is
269 stored in a separate location from the WAL archive.
270 </para>
271 </listitem>
272 </varlistentry>
273 </variablelist>
274 </para>
275
276 <para>
277 Other options are also available:
278
279 <variablelist>
280 <varlistentry>
281 <term><option>-V</option></term>
282 <term><option>--version</option></term>
283 <listitem>
284 <para>
285 Print the <application>pg_verifybackup</application> version and exit.
286 </para>
287 </listitem>
288 </varlistentry>
289
290 <varlistentry>
291 <term><option>-?</option></term>
292 <term><option>--help</option></term>
293 <listitem>
294 <para>
295 Show help about <application>pg_verifybackup</application> command
296 line arguments, and exit.
297 </para>
298 </listitem>
299 </varlistentry>
300
301 </variablelist>
302 </para>
303
304 </refsect1>
305
306 <refsect1>
307 <title>Examples</title>
308
309 <para>
310 To create a base backup of the server at <literal>mydbserver</literal> and
311 verify the integrity of the backup:
312 <screen>
313 <prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</userinput>
314 <prompt>$</prompt> <userinput>pg_verifybackup /usr/local/pgsql/data</userinput>
315 </screen>
316 </para>
317
318 <para>
319 To create a base backup of the server at <literal>mydbserver</literal>, move
320 the manifest somewhere outside the backup directory, and verify the
321 backup:
322 <screen>
323 <prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234</userinput>
324 <prompt>$</prompt> <userinput>mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234</userinput>
325 <prompt>$</prompt> <userinput>pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234</userinput>
326 </screen>
327 </para>
328
329 <para>
330 To verify a backup while ignoring a file that was added manually to the
331 backup directory, and also skipping checksum verification:
332 <screen>
333 <prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</userinput>
334 <prompt>$</prompt> <userinput>edit /usr/local/pgsql/data/note.to.self</userinput>
335 <prompt>$</prompt> <userinput>pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data</userinput>
336 </screen></para>
337
338 </refsect1>
339
340 <refsect1>
341 <title>See Also</title>
342
343 <simplelist type="inline">
344 <member><xref linkend="app-pgbasebackup"/></member>
345 </simplelist>
346 </refsect1>
347
348 </refentry>