diff options
Diffstat (limited to 'doc/src/sgml/html/app-pgverifybackup.html')
| -rw-r--r-- | doc/src/sgml/html/app-pgverifybackup.html | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/doc/src/sgml/html/app-pgverifybackup.html b/doc/src/sgml/html/app-pgverifybackup.html new file mode 100644 index 0000000..3312eb8 --- /dev/null +++ b/doc/src/sgml/html/app-pgverifybackup.html @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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 15.4 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.19.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 + <span class="productname">PostgreSQL</span> cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.19.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.19.5"><h2>Description</h2><p> + <span class="application">pg_verifybackup</span> is used to check the + integrity of a database cluster backup taken using + <code class="command">pg_basebackup</code> against a + <code class="literal">backup_manifest</code> 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. + </p><p> + It is important to note that the validation which is performed by + <span class="application">pg_verifybackup</span> 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, + <span class="application">pg_verifybackup</span> can detect many problems + that commonly occur due to storage problems or user error. + </p><p> + Backup verification proceeds in four stages. First, + <code class="literal">pg_verifybackup</code> reads the + <code class="literal">backup_manifest</code> file. If that file + does not exist, cannot be read, is malformed, or fails verification + against its own internal checksum, <code class="literal">pg_verifybackup</code> + will terminate with a fatal error. + </p><p> + Second, <code class="literal">pg_verifybackup</code> 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, <code class="literal">postgresql.auto.conf</code>, + <code class="literal">standby.signal</code>, and <code class="literal">recovery.signal</code>, + 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 <code class="literal">backup_manifest</code> file in the target directory or + about anything inside <code class="literal">pg_wal</code>, 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. + </p><p> + Next, <code class="literal">pg_verifybackup</code> 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. + </p><p> + Finally, <code class="literal">pg_verifybackup</code> 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 + <code class="literal">backup_manifest</code> contains information about which + write-ahead log records will be needed, and + <code class="literal">pg_verifybackup</code> will use that information to + invoke <code class="literal">pg_waldump</code> to parse those write-ahead log + records. The <code class="literal">--quiet</code> flag will be used, so that + <code class="literal">pg_waldump</code> 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. + </p><p> + 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 <code class="literal">pg_waldump</code> could be used for + that purpose. Also note that WAL verification is version-specific: you + must use the version of <code class="literal">pg_verifybackup</code>, and thus of + <code class="literal">pg_waldump</code>, 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 <code class="literal">backup_manifest</code> file. + </p></div><div class="refsect1" id="id-1.9.4.19.6"><h2>Options</h2><p> + <span class="application">pg_verifybackup</span> accepts the following + command-line arguments: + + </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> + Exit as soon as a problem with the backup is detected. If this option + is not specified, <code class="literal">pg_verifybackup</code> will continue + checking the backup even after a problem has been detected, and will + report all problems detected as errors. + </p></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> + 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 + <code class="literal">backup_manifest</code> 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. + </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> + Use the manifest file at the specified path, rather than one located + in the root of the backup directory. + </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> + Don't attempt to parse write-ahead log data that will be needed + to recover from this backup. + </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> + Don't print anything when a backup is successfully verified. + </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> + 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. + </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> + Try to parse WAL files stored in the specified directory, rather than + in <code class="literal">pg_wal</code>. This may be useful if the backup is + stored in a separate location from the WAL archive. + </p></dd></dl></div><p> + </p><p> + Other options are also available: + + </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> + Print the <span class="application">pg_verifybackup</span> version and exit. + </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p> + Show help about <span class="application">pg_verifybackup</span> command + line arguments, and exit. + </p></dd></dl></div><p> + </p></div><div class="refsect1" id="id-1.9.4.19.7"><h2>Examples</h2><p> + To create a base backup of the server at <code class="literal">mydbserver</code> and + verify the integrity of the backup: +</p><pre class="screen"> +<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</code></strong> +<code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup /usr/local/pgsql/data</code></strong> +</pre><p> + </p><p> + To create a base backup of the server at <code class="literal">mydbserver</code>, move + the manifest somewhere outside the backup directory, and verify the + backup: +</p><pre class="screen"> +<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234</code></strong> +<code class="prompt">$</code> <strong class="userinput"><code>mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234</code></strong> +<code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234</code></strong> +</pre><p> + </p><p> + To verify a backup while ignoring a file that was added manually to the + backup directory, and also skipping checksum verification: +</p><pre class="screen"> +<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</code></strong> +<code class="prompt">$</code> <strong class="userinput"><code>edit /usr/local/pgsql/data/note.to.self</code></strong> +<code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data</code></strong> +</pre></div><div class="refsect1" id="id-1.9.4.19.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 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">psql</span></td></tr></table></div></body></html>
\ No newline at end of file |