290 lines
11 KiB
Plaintext
290 lines
11 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_combinebackup.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pgcombinebackup">
|
|
<indexterm zone="app-pgcombinebackup">
|
|
<primary>pg_combinebackup</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle><application>pg_combinebackup</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_combinebackup</refname>
|
|
<refpurpose>reconstruct a full backup from an incremental backup and dependent backups</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_combinebackup</command>
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
|
<arg rep="repeat"><replaceable>backup_directory</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
<application>pg_combinebackup</application> is used to reconstruct a
|
|
synthetic full backup from an
|
|
<link linkend="backup-incremental-backup">incremental backup</link> and the
|
|
earlier backups upon which it depends.
|
|
</para>
|
|
|
|
<para>
|
|
Specify all of the required backups on the command line from oldest to newest.
|
|
That is, the first backup directory should be the path to the full backup, and
|
|
the last should be the path to the final incremental backup
|
|
that you wish to restore. The reconstructed backup will be written to the
|
|
output directory specified by the <option>-o</option> option.
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_combinebackup</application> will attempt to verify
|
|
that the backups you specify form a legal backup chain from which a correct
|
|
full backup can be reconstructed. However, it is not designed to help you
|
|
keep track of which backups depend on which other backups. If you remove
|
|
one or more of the previous backups upon which your incremental
|
|
backup relies, you will not be able to restore it. Moreover,
|
|
<application>pg_combinebackup</application> only attempts to verify that the
|
|
backups have the correct relationship to each other, not that each
|
|
individual backup is intact; for that, use
|
|
<xref linkend="app-pgverifybackup" />.
|
|
</para>
|
|
|
|
<para>
|
|
Since the output of <application>pg_combinebackup</application> is a
|
|
synthetic full backup, it can be used as an input to a future invocation of
|
|
<application>pg_combinebackup</application>. The synthetic full backup would
|
|
be specified on the command line in lieu of the chain of backups from which
|
|
it was reconstructed.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-d</option></term>
|
|
<term><option>--debug</option></term>
|
|
<listitem>
|
|
<para>
|
|
Print lots of debug logging output on <filename>stderr</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<term><option>--dry-run</option></term>
|
|
<listitem>
|
|
<para>
|
|
The <option>-n</option>/<option>--dry-run</option> option instructs
|
|
<command>pg_combinebackup</command> to figure out what would be done
|
|
without actually creating the target directory or any output files.
|
|
It is particularly useful in combination with <option>--debug</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-N</option></term>
|
|
<term><option>--no-sync</option></term>
|
|
<listitem>
|
|
<para>
|
|
By default, <command>pg_combinebackup</command> will wait for all files
|
|
to be written safely to disk. This option causes
|
|
<command>pg_combinebackup</command> to return without waiting, which is
|
|
faster, but means that a subsequent operating system crash can leave
|
|
the output backup corrupt. Generally, this option is useful for testing
|
|
but should not be used when creating a production installation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o <replaceable class="parameter">outputdir</replaceable></option></term>
|
|
<term><option>--output=<replaceable class="parameter">outputdir</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the output directory to which the synthetic full backup
|
|
should be written. Currently, this argument is required.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-T <replaceable class="parameter">olddir</replaceable>=<replaceable class="parameter">newdir</replaceable></option></term>
|
|
<term><option>--tablespace-mapping=<replaceable class="parameter">olddir</replaceable>=<replaceable class="parameter">newdir</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Relocates the tablespace in directory <replaceable>olddir</replaceable>
|
|
to <replaceable>newdir</replaceable> during the backup.
|
|
<replaceable>olddir</replaceable> is the absolute path of the tablespace
|
|
as it exists in the first backup specified on the command line,
|
|
and <replaceable>newdir</replaceable> is the absolute path to use for the
|
|
tablespace in the reconstructed backup. If either path needs to contain
|
|
an equal sign (<literal>=</literal>), precede that with a backslash.
|
|
This option can be specified multiple times for multiple tablespaces.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--manifest-checksums=<replaceable class="parameter">algorithm</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Like <xref linkend="app-pgbasebackup"/>,
|
|
<application>pg_combinebackup</application> writes a backup manifest
|
|
in the output directory. This option specifies the checksum algorithm
|
|
that should be applied to each file included in the backup manifest.
|
|
Currently, the available algorithms are <literal>NONE</literal>,
|
|
<literal>CRC32C</literal>, <literal>SHA224</literal>,
|
|
<literal>SHA256</literal>, <literal>SHA384</literal>,
|
|
and <literal>SHA512</literal>. The default is <literal>CRC32C</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--no-manifest</option></term>
|
|
<listitem>
|
|
<para>
|
|
Disables generation of a backup manifest. If this option is not
|
|
specified, a backup manifest for the reconstructed backup will be
|
|
written to the output directory.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--sync-method=<replaceable class="parameter">method</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
When set to <literal>fsync</literal>, which is the default,
|
|
<command>pg_combinebackup</command> will recursively open and synchronize
|
|
all files in the backup directory. When the plain format is used, the
|
|
search for files will follow symbolic links for the WAL directory and
|
|
each configured tablespace.
|
|
</para>
|
|
<para>
|
|
On Linux, <literal>syncfs</literal> may be used instead to ask the
|
|
operating system to synchronize the whole file system that contains the
|
|
backup directory. When the plain format is used,
|
|
<command>pg_combinebackup</command> will also synchronize the file systems
|
|
that contain the WAL files and each tablespace. See
|
|
<xref linkend="guc-recovery-init-sync-method"/> for information about
|
|
the caveats to be aware of when using <literal>syncfs</literal>.
|
|
</para>
|
|
<para>
|
|
This option has no effect when <option>--no-sync</option> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--clone</option></term>
|
|
<listitem>
|
|
<para>
|
|
Use efficient file cloning (also known as <quote>reflinks</quote> on
|
|
some systems) instead of copying files to the new data directory,
|
|
which can result in near-instantaneous copying of the data files.
|
|
</para>
|
|
|
|
<para>
|
|
If a backup manifest is not available or does not contain checksum of
|
|
the right type, file cloning will be used to copy the file, but the
|
|
file will be also read block-by-block for the checksum calculation.
|
|
</para>
|
|
|
|
<para>
|
|
File cloning is only supported on some operating systems and file
|
|
systems. If it is selected but not supported, the
|
|
<application>pg_combinebackup</application> run will error. At present,
|
|
it is supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on
|
|
file systems created with reflink support), and on macOS with APFS.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--copy-file-range</option></term>
|
|
<listitem>
|
|
<para>
|
|
Use the <function>copy_file_range</function> system call for efficient
|
|
copying. On some file systems this gives results similar to
|
|
<option>--clone</option>, sharing physical disk blocks, while on others
|
|
it may still copy blocks, but do so via an optimized path. At present,
|
|
it is supported on Linux and FreeBSD.
|
|
</para>
|
|
|
|
<para>
|
|
If a backup manifest is not available or does not contain checksum of
|
|
the right type, <function>copy_file_range</function> will be used to
|
|
copy the file, but the file will be also read block-by-block for the
|
|
checksum calculation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-V</option></term>
|
|
<term><option>--version</option></term>
|
|
<listitem>
|
|
<para>
|
|
Prints the <application>pg_combinebackup</application> version and
|
|
exits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-?</option></term>
|
|
<term><option>--help</option></term>
|
|
<listitem>
|
|
<para>
|
|
Shows help about <application>pg_combinebackup</application> command
|
|
line arguments, and exits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<para>
|
|
This utility, like most other <productname>PostgreSQL</productname> utilities,
|
|
uses the environment variables supported by <application>libpq</application>
|
|
(see <xref linkend="libpq-envars"/>).
|
|
</para>
|
|
|
|
<para>
|
|
The environment variable <envar>PG_COLOR</envar> specifies whether to use
|
|
color in diagnostic messages. Possible values are
|
|
<literal>always</literal>, <literal>auto</literal> and
|
|
<literal>never</literal>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="app-pgbasebackup"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|