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