mirror of
https://github.com/postgres/postgres.git
synced 2025-08-28 18:48:04 +03:00
8dfd312902
This also works for compressed tar-format backups. However, -n must be used, because we use pg_waldump to verify WAL, and it doesn't yet know how to verify WAL that is stored inside of a tarfile. Amul Sul, reviewed by Sravan Kumar and by me, and revised by me.
349 lines
13 KiB
Plaintext
349 lines
13 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 may be stored either in the "plain" or the "tar"
|
|
format; this includes tar-format backups compressed with any algorithm
|
|
supported by <application>pg_basebackup</application>. However, at present,
|
|
<literal>WAL</literal> verification is supported only for plain-format
|
|
backups. Therefore, if the backup is stored in tar-format, the
|
|
<literal>-n, --no-parse-wal</literal> option should be used.
|
|
</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>-F <replaceable class="parameter">format</replaceable></option></term>
|
|
<term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the format of the backup. <replaceable>format</replaceable>
|
|
can be one of the following:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>p</literal></term>
|
|
<term><literal>plain</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Backup consists of plain files with the same layout as the
|
|
source server's data directory and tablespaces.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>t</literal></term>
|
|
<term><literal>tar</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Backup consists of tar files, which may be compressed. A valid
|
|
backup includes the main data directory in a file named
|
|
<filename>base.tar</filename>, the WAL files in
|
|
<filename>pg_wal.tar</filename>, 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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></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>
|