postgres/doc/src/sgml/ref/pg_verifybackup.sgml

<!--
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, 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>