306 lines
11 KiB
Plaintext
306 lines
11 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_verifybackup.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pgverifybackup">
|
|
<indexterm zone="app-pgverifybackup">
|
|
<primary>pg_verifybackup</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle><application>pg_verifybackup</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_verifybackup</refname>
|
|
<refpurpose>verify the integrity of a base backup of a
|
|
<productname>PostgreSQL</productname> cluster</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_verifybackup</command>
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
<application>pg_verifybackup</application> is used to check the
|
|
integrity of a database cluster backup taken using
|
|
<command>pg_basebackup</command> against a
|
|
<literal>backup_manifest</literal> generated by the server at the time
|
|
of the backup. The backup must be stored in the "plain"
|
|
format; a "tar" format backup can be checked after extracting it.
|
|
</para>
|
|
|
|
<para>
|
|
It is important to note that the validation which is performed by
|
|
<application>pg_verifybackup</application> does not and cannot include
|
|
every check which will be performed by a running server when attempting
|
|
to make use of the backup. Even if you use this tool, you should still
|
|
perform test restores and verify that the resulting databases work as
|
|
expected and that they appear to contain the correct data. However,
|
|
<application>pg_verifybackup</application> can detect many problems
|
|
that commonly occur due to storage problems or user error.
|
|
</para>
|
|
|
|
<para>
|
|
Backup verification proceeds in four stages. First,
|
|
<literal>pg_verifybackup</literal> reads the
|
|
<literal>backup_manifest</literal> file. If that file
|
|
does not exist, cannot be read, is malformed, fails to match the system
|
|
identifier with <filename>pg_control</filename> of the backup directory or
|
|
fails verification against its own internal checksum,
|
|
<literal>pg_verifybackup</literal> will terminate with a fatal error.
|
|
</para>
|
|
|
|
<para>
|
|
Second, <literal>pg_verifybackup</literal> will attempt to verify that
|
|
the data files currently stored on disk are exactly the same as the data
|
|
files which the server intended to send, with some exceptions that are
|
|
described below. Extra and missing files will be detected, with a few
|
|
exceptions. This step will ignore the presence or absence of, or any
|
|
modifications to, <literal>postgresql.auto.conf</literal>,
|
|
<literal>standby.signal</literal>, and <literal>recovery.signal</literal>,
|
|
because it is expected that these files may have been created or modified
|
|
as part of the process of taking the backup. It also won't complain about
|
|
a <literal>backup_manifest</literal> file in the target directory or
|
|
about anything inside <literal>pg_wal</literal>, even though these
|
|
files won't be listed in the backup manifest. Only files are checked;
|
|
the presence or absence of directories is not verified, except
|
|
indirectly: if a directory is missing, any files it should have contained
|
|
will necessarily also be missing.
|
|
</para>
|
|
|
|
<para>
|
|
Next, <literal>pg_verifybackup</literal> will checksum all the files,
|
|
compare the checksums against the values in the manifest, and emit errors
|
|
for any files for which the computed checksum does not match the
|
|
checksum stored in the manifest. This step is not performed for any files
|
|
which produced errors in the previous step, since they are already known
|
|
to have problems. Files which were ignored in the previous step are also
|
|
ignored in this step.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, <literal>pg_verifybackup</literal> will use the manifest to
|
|
verify that the write-ahead log records which will be needed to recover
|
|
the backup are present and that they can be read and parsed. The
|
|
<literal>backup_manifest</literal> contains information about which
|
|
write-ahead log records will be needed, and
|
|
<literal>pg_verifybackup</literal> will use that information to
|
|
invoke <literal>pg_waldump</literal> to parse those write-ahead log
|
|
records. The <literal>--quiet</literal> flag will be used, so that
|
|
<literal>pg_waldump</literal> will only report errors, without producing
|
|
any other output. While this level of verification is sufficient to
|
|
detect obvious problems such as a missing file or one whose internal
|
|
checksums do not match, they aren't extensive enough to detect every
|
|
possible problem that might occur when attempting to recover. For
|
|
instance, a server bug that produces write-ahead log records that have
|
|
the correct checksums but specify nonsensical actions can't be detected
|
|
by this method.
|
|
</para>
|
|
|
|
<para>
|
|
Note that if extra WAL files which are not required to recover the backup
|
|
are present, they will not be checked by this tool, although
|
|
a separate invocation of <literal>pg_waldump</literal> could be used for
|
|
that purpose. Also note that WAL verification is version-specific: you
|
|
must use the version of <literal>pg_verifybackup</literal>, and thus of
|
|
<literal>pg_waldump</literal>, which pertains to the backup being checked.
|
|
In contrast, the data file integrity checks should work with any version
|
|
of the server that generates a <literal>backup_manifest</literal> file.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
<application>pg_verifybackup</application> accepts the following
|
|
command-line arguments:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-e</option></term>
|
|
<term><option>--exit-on-error</option></term>
|
|
<listitem>
|
|
<para>
|
|
Exit as soon as a problem with the backup is detected. If this option
|
|
is not specified, <literal>pg_verifybackup</literal> will continue
|
|
checking the backup even after a problem has been detected, and will
|
|
report all problems detected as errors.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-i <replaceable class="parameter">path</replaceable></option></term>
|
|
<term><option>--ignore=<replaceable class="parameter">path</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
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
|
|
<literal>backup_manifest</literal> 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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-m <replaceable class="parameter">path</replaceable></option></term>
|
|
<term><option>--manifest-path=<replaceable class="parameter">path</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Use the manifest file at the specified path, rather than one located
|
|
in the root of the backup directory.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<term><option>--no-parse-wal</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't attempt to parse write-ahead log data that will be needed
|
|
to recover from this backup.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-P</option></term>
|
|
<term><option>--progress</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enable progress reporting. Turning this on will deliver a progress
|
|
report while verifying checksums.
|
|
</para>
|
|
<para>
|
|
This option cannot be used together with the option
|
|
<option>--quiet</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-q</option></term>
|
|
<term><option>--quiet</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't print anything when a backup is successfully verified.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-s</option></term>
|
|
<term><option>--skip-checksums</option></term>
|
|
<listitem>
|
|
<para>
|
|
Do not verify data file checksums. The presence or absence of
|
|
files and the sizes of those files will still be checked. This is
|
|
much faster, because the files themselves do not need to be read.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-w <replaceable class="parameter">path</replaceable></option></term>
|
|
<term><option>--wal-directory=<replaceable class="parameter">path</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Try to parse WAL files stored in the specified directory, rather than
|
|
in <literal>pg_wal</literal>. This may be useful if the backup is
|
|
stored in a separate location from the WAL archive.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Other options are also available:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-V</option></term>
|
|
<term><option>--version</option></term>
|
|
<listitem>
|
|
<para>
|
|
Print the <application>pg_verifybackup</application> version and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-?</option></term>
|
|
<term><option>--help</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show help about <application>pg_verifybackup</application> command
|
|
line arguments, and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
To create a base backup of the server at <literal>mydbserver</literal> and
|
|
verify the integrity of the backup:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</userinput>
|
|
<prompt>$</prompt> <userinput>pg_verifybackup /usr/local/pgsql/data</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To create a base backup of the server at <literal>mydbserver</literal>, move
|
|
the manifest somewhere outside the backup directory, and verify the
|
|
backup:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234</userinput>
|
|
<prompt>$</prompt> <userinput>mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234</userinput>
|
|
<prompt>$</prompt> <userinput>pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To verify a backup while ignoring a file that was added manually to the
|
|
backup directory, and also skipping checksum verification:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</userinput>
|
|
<prompt>$</prompt> <userinput>edit /usr/local/pgsql/data/note.to.self</userinput>
|
|
<prompt>$</prompt> <userinput>pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data</userinput>
|
|
</screen></para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="app-pgbasebackup"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|