begriffs open source - ai-pg/blob - full-docs/html/app-pgverifybackup.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_verifybackup</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgrestore.html" title="pg_restore" /><link rel="next" href="app-psql.html" title="psql" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_verifybackup</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgrestore.html" title="pg_restore">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-psql.html" title="psql">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGVERIFYBACKUP"><div class="titlepage"></div><a id="id-1.9.4.20.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_verifybackup</span></span></h2><p>pg_verifybackup — verify the integrity of a base backup of a
   3   <span class="productname">PostgreSQL</span> cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.20.4.1"><code class="command">pg_verifybackup</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.4.20.5"><h2>Description</h2><p>
   4    <span class="application">pg_verifybackup</span> is used to check the
   5    integrity of a database cluster backup taken using
   6    <code class="command">pg_basebackup</code> against a
   7    <code class="literal">backup_manifest</code> generated by the server at the time
   8    of the backup. The backup may be stored either in the "plain" or the "tar"
   9    format; this includes tar-format backups compressed with any algorithm
  10    supported by <span class="application">pg_basebackup</span>. However, at present,
  11    <code class="literal">WAL</code> verification is supported only for plain-format
  12    backups. Therefore, if the backup is stored in tar-format, the
  13    <code class="literal">-n, --no-parse-wal</code> option should be used.
  14   </p><p>
  15    It is important to note that the validation which is performed by
  16    <span class="application">pg_verifybackup</span> does not and cannot include
  17    every check which will be performed by a running server when attempting
  18    to make use of the backup. Even if you use this tool, you should still
  19    perform test restores and verify that the resulting databases work as
  20    expected and that they appear to contain the correct data. However,
  21    <span class="application">pg_verifybackup</span> can detect many problems
  22    that commonly occur due to storage problems or user error.
  23   </p><p>
  24    Backup verification proceeds in four stages. First,
  25    <code class="literal">pg_verifybackup</code> reads the
  26    <code class="literal">backup_manifest</code> file. If that file
  27    does not exist, cannot be read, is malformed, fails to match the system
  28    identifier with <code class="filename">pg_control</code> of the backup directory or
  29    fails verification against its own internal checksum,
  30    <code class="literal">pg_verifybackup</code> will terminate with a fatal error.
  31   </p><p>
  32    Second, <code class="literal">pg_verifybackup</code> will attempt to verify that
  33    the data files currently stored on disk are exactly the same as the data
  34    files which the server intended to send, with some exceptions that are
  35    described below. Extra and missing files will be detected, with a few
  36    exceptions.  This step will ignore the presence or absence of, or any
  37    modifications to, <code class="literal">postgresql.auto.conf</code>,
  38    <code class="literal">standby.signal</code>, and <code class="literal">recovery.signal</code>,
  39    because it is expected that these files may have been created or modified
  40    as part of the process of taking the backup. It also won't complain about
  41    a <code class="literal">backup_manifest</code> file in the target directory or
  42    about anything inside <code class="literal">pg_wal</code>, even though these
  43    files won't be listed in the backup manifest. Only files are checked;
  44    the presence or absence of directories is not verified, except
  45    indirectly: if a directory is missing, any files it should have contained
  46    will necessarily also be missing.
  47   </p><p>
  48    Next, <code class="literal">pg_verifybackup</code> will checksum all the files,
  49    compare the checksums against the values in the manifest, and emit errors
  50    for any files for which the computed checksum does not match the
  51    checksum stored in the manifest. This step is not performed for any files
  52    which produced errors in the previous step, since they are already known
  53    to have problems. Files which were ignored in the previous step are also
  54    ignored in this step.
  55   </p><p>
  56    Finally, <code class="literal">pg_verifybackup</code> will use the manifest to
  57    verify that the write-ahead log records which will be needed to recover
  58    the backup are present and that they can be read and parsed. The
  59    <code class="literal">backup_manifest</code> contains information about which
  60    write-ahead log records will be needed, and
  61    <code class="literal">pg_verifybackup</code> will use that information to
  62    invoke <code class="literal">pg_waldump</code> to parse those write-ahead log
  63    records. The <code class="literal">--quiet</code> flag will be used, so that
  64    <code class="literal">pg_waldump</code> will only report errors, without producing
  65    any other output. While this level of verification is sufficient to
  66    detect obvious problems such as a missing file or one whose internal
  67    checksums do not match, they aren't extensive enough to detect every
  68    possible problem that might occur when attempting to recover. For
  69    instance, a server bug that produces write-ahead log records that have
  70    the correct checksums but specify nonsensical actions can't be detected
  71    by this method.
  72   </p><p>
  73    Note that if extra WAL files which are not required to recover the backup
  74    are present, they will not be checked by this tool, although
  75    a separate invocation of <code class="literal">pg_waldump</code> could be used for
  76    that purpose. Also note that WAL verification is version-specific: you
  77    must use the version of <code class="literal">pg_verifybackup</code>, and thus of
  78    <code class="literal">pg_waldump</code>, which pertains to the backup being checked.
  79    In contrast, the data file integrity checks should work with any version
  80    of the server that generates a <code class="literal">backup_manifest</code> file.
  81   </p></div><div class="refsect1" id="id-1.9.4.20.6"><h2>Options</h2><p>
  82     <span class="application">pg_verifybackup</span> accepts the following
  83     command-line arguments:
  84
  85     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--exit-on-error</code></span></dt><dd><p>
  86         Exit as soon as a problem with the backup is detected. If this option
  87         is not specified, <code class="literal">pg_verifybackup</code> will continue
  88         checking the backup even after a problem has been detected, and will
  89         report all problems detected as errors.
  90        </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>format</code></em></code><br /></span><span class="term"><code class="option">--format=<em class="replaceable"><code>format</code></em></code></span></dt><dd><p>
  91         Specifies the format of the backup. <em class="replaceable"><code>format</code></em>
  92         can be one of the following:
  93
  94         </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">p</code><br /></span><span class="term"><code class="literal">plain</code></span></dt><dd><p>
  95             Backup consists of plain files with the same layout as the
  96             source server's data directory and tablespaces.
  97            </p></dd><dt><span class="term"><code class="literal">t</code><br /></span><span class="term"><code class="literal">tar</code></span></dt><dd><p>
  98             Backup consists of tar files, which  may be compressed.  A valid
  99             backup includes the main data directory in a file named
 100             <code class="filename">base.tar</code>, the WAL files in
 101             <code class="filename">pg_wal.tar</code>, and separate tar files for
 102             each tablespace, named after the tablespace's OID. If the backup
 103             is compressed, the relevant compression extension is added to the
 104             end of each file name.
 105            </p></dd></dl></div></dd><dt><span class="term"><code class="option">-i <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--ignore=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
 106         Ignore the specified file or directory, which should be expressed
 107         as a relative path name, when comparing the list of data files
 108         actually present in the backup to those listed in the
 109         <code class="literal">backup_manifest</code> file.  If a directory is
 110         specified, this option affects the entire subtree rooted at that
 111         location. Complaints about extra files, missing files, file size
 112         differences, or checksum mismatches will be suppressed if the
 113         relative path name matches the specified path name. This option
 114         can be specified multiple times.
 115        </p></dd><dt><span class="term"><code class="option">-m <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--manifest-path=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
 116         Use the manifest file at the specified path, rather than one located
 117         in the root of the backup directory.
 118        </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-parse-wal</code></span></dt><dd><p>
 119         Don't attempt to parse write-ahead log data that will be needed
 120         to recover from this backup.
 121        </p></dd><dt><span class="term"><code class="option">-P</code><br /></span><span class="term"><code class="option">--progress</code></span></dt><dd><p>
 122         Enable progress reporting. Turning this on will deliver a progress
 123         report while verifying checksums.
 124        </p><p>
 125         This option cannot be used together with the option
 126         <code class="option">--quiet</code>.
 127        </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
 128         Don't print anything when a backup is successfully verified.
 129        </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--skip-checksums</code></span></dt><dd><p>
 130         Do not verify data file checksums. The presence or absence of
 131         files and the sizes of those files will still be checked. This is
 132         much faster, because the files themselves do not need to be read.
 133        </p></dd><dt><span class="term"><code class="option">-w <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--wal-directory=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
 134         Try to parse WAL files stored in the specified directory, rather than
 135         in <code class="literal">pg_wal</code>. This may be useful if the backup is
 136         stored in a separate location from the WAL archive.
 137        </p></dd></dl></div><p>
 138    </p><p>
 139     Other options are also available:
 140
 141     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
 142        Print the <span class="application">pg_verifybackup</span> version and exit.
 143        </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
 144        Show help about <span class="application">pg_verifybackup</span> command
 145        line arguments, and exit.
 146        </p></dd></dl></div><p>
 147    </p></div><div class="refsect1" id="id-1.9.4.20.7"><h2>Examples</h2><p>
 148    To create a base backup of the server at <code class="literal">mydbserver</code> and
 149    verify the integrity of the backup:
 150 </p><pre class="screen">
 151 <code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</code></strong>
 152 <code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup /usr/local/pgsql/data</code></strong>
 153 </pre><p>
 154   </p><p>
 155    To create a base backup of the server at <code class="literal">mydbserver</code>, move
 156    the manifest somewhere outside the backup directory, and verify the
 157    backup:
 158 </p><pre class="screen">
 159 <code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234</code></strong>
 160 <code class="prompt">$</code> <strong class="userinput"><code>mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234</code></strong>
 161 <code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234</code></strong>
 162 </pre><p>
 163   </p><p>
 164    To verify a backup while ignoring a file that was added manually to the
 165    backup directory, and also skipping checksum verification:
 166 </p><pre class="screen">
 167 <code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</code></strong>
 168 <code class="prompt">$</code> <strong class="userinput"><code>edit /usr/local/pgsql/data/note.to.self</code></strong>
 169 <code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data</code></strong>
 170 </pre></div><div class="refsect1" id="id-1.9.4.20.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgrestore.html" title="pg_restore">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-psql.html" title="psql">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_restore</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">psql</span></td></tr></table></div></body></html>