diff options
Diffstat (limited to 'doc/src/sgml/ref/pg_verifybackup.sgml')
| -rw-r--r-- | doc/src/sgml/ref/pg_verifybackup.sgml | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/pg_verifybackup.sgml b/doc/src/sgml/ref/pg_verifybackup.sgml new file mode 100644 index 0000000..5f83c98 --- /dev/null +++ b/doc/src/sgml/ref/pg_verifybackup.sgml @@ -0,0 +1,289 @@ +<!-- +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>-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> |