db/pg_probackup
db/pg_probackup
1
0
Fork 0
mirror of https://github.com/postgrespro/pg_probackup.git synced 2024-11-28 09:33:54 +02:00
Code Issues Releases Activity
eb5ccf91b8
pg_probackup/doc/pgprobackup.xml
Viktoria Shepard db12a039f6 PBCKP-604 doc add option --destroy-all-other-dbs
2023-05-26 19:38:57 +03:00

6164 lines
260 KiB
XML
Raw Blame History

<!--
doc/src/sgml/pgprobackup.sgml
&project; documentation
-->
<refentry id="app-pgprobackup">
<indexterm zone="app-pgprobackup">
<primary>pg_probackup</primary>
</indexterm>
<refmeta>
<refentrytitle>pg_probackup</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_probackup</refname>
<refpurpose>manage backup and recovery of <productname>PostgreSQL</productname> database clusters</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>version</option></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>help</option></arg>
<arg choice="opt"><replaceable>command</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>init</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>add-instance</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>-D</option> <replaceable>data_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>del-instance</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>set-config</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>set-backup</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg choice="plain"><option>-i</option> <replaceable>backup_id</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>show-config</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg choice="opt"><option>--format=<replaceable>format</replaceable></option></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>show</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>backup</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg choice="plain"><option>-b</option> <replaceable>backup_mode</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>restore</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>checkdb</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg choice="plain"><option>-D</option> <replaceable>data_dir</replaceable></arg>
<arg rep="repeat"><option>option</option></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>validate</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>merge</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg choice="plain"><option>-i</option> <replaceable>backup_id</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>delete</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<group choice="req">
<arg choice="plain"><option>-i</option> <replaceable>backup_id</replaceable></arg>
<arg choice="plain"><option>--delete-wal</option></arg>
<arg choice="plain"><option>--delete-expired</option></arg>
<arg choice="plain"><option>--merge-expired</option></arg>
</group>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>archive-push</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg choice="plain"><option>--wal-file-path</option> <replaceable>wal_file_path</replaceable></arg>
<arg choice="plain"><option>--wal-file-name</option> <replaceable>wal_file_name</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>archive-get</option></arg>
<arg choice="plain"><option>-B</option> <replaceable>backup_dir</replaceable></arg>
<arg choice="plain"><option>--instance</option> <replaceable>instance_name</replaceable></arg>
<arg choice="plain"><option>--wal-file-path</option> <replaceable>wal_file_path</replaceable></arg>
<arg choice="plain"><option>--wal-file-name</option> <replaceable>wal_file_name</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_probackup</command>
<arg choice="plain"><option>catchup</option></arg>
<arg choice="plain"><option>-b</option> <replaceable>catchup_mode</replaceable></arg>
<arg choice="plain"><option>--source-pgdata</option>=<replaceable>path_to_pgdata_on_remote_server</replaceable></arg>
<arg choice="plain"><option>--destination-pgdata</option>=<replaceable>path_to_local_dir</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>
Description
</title>
<para>
<application>pg_probackup</application> is a utility to manage backup and
recovery of <productname>PostgreSQL</productname> database clusters.
It is designed to perform periodic backups of the <productname>PostgreSQL</productname>
instance that enable you to restore the server in case of a failure.
<application>pg_probackup</application> supports PostgreSQL 9.5 or higher.
</para>
<itemizedlist spacing="compact">
<listitem>
<para><link linkend="pbk-overview">Overview</link></para>
</listitem>
<listitem>
<para><link linkend="pbk-install-and-setup">Installation and Setup</link></para>
</listitem>
<listitem>
<para><link linkend="pbk-reference">Command-Line Reference</link></para>
</listitem>
<listitem>
<para><link linkend="pbk-usage">Usage</link></para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="pbk-overview">
<title>
Overview
</title>
<para>
As compared to other backup solutions, <application>pg_probackup</application> offers the
following benefits that can help you implement different backup
strategies and deal with large amounts of data:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
Incremental backup: with three different incremental modes,
you can plan the backup strategy in accordance with your data flow.
Incremental backups allow you to save disk space
and speed up backup as compared to taking full backups.
It is also faster to restore the cluster by applying incremental
backups than by replaying WAL files.
</para>
</listitem>
<listitem>
<para>
Incremental restore: speed up restore from backup by reusing
valid unchanged pages available in PGDATA.
</para>
</listitem>
<listitem>
<para>
Validation: automatic data consistency checks and on-demand
backup validation without actual data recovery.
</para>
</listitem>
<listitem>
<para>
Verification: on-demand verification of <productname>PostgreSQL</productname> instance
with the <command>checkdb</command> command.
</para>
</listitem>
<listitem>
<para>
Retention: managing WAL archive and backups in accordance with
retention policy. You can configure retention policy based on recovery time
or the number of backups to keep, as well as specify time to live (TTL)
for a particular backup. Expired backups can be merged or deleted.
</para>
</listitem>
<listitem>
<para>
Parallelization: running <command>backup</command>,
<command>restore</command>, <command>merge</command>,
<command>delete</command>, <command>validate</command>,
and <command>checkdb</command> processes on multiple parallel threads.
</para>
</listitem>
<listitem>
<para>
Compression: storing backup data in a compressed state to save
disk space.
</para>
</listitem>
<listitem>
<para>
Deduplication: saving disk space by excluding non-data
files (such as <literal>_vm</literal> or <literal>_fsm</literal>)
from incremental backups if these files have not changed since
they were copied into one of the previous backups in this incremental chain.
</para>
</listitem>
<listitem>
<para>
Remote operations: backing up <productname>PostgreSQL</productname>
instance located on a remote system or restoring a backup remotely.
</para>
</listitem>
<listitem>
<para>
Backup from standby: avoiding extra load on master by
taking backups from a standby server.
</para>
</listitem>
<listitem>
<para>
External directories: backing up files and directories
located outside of the <productname>PostgreSQL</productname> data
directory (<envar>PGDATA</envar>), such as scripts, configuration
files, logs, or SQL dump files.
</para>
</listitem>
<listitem>
<para>
Backup catalog: getting the list of backups and the corresponding meta
information in plain text or
<acronym>JSON</acronym> formats.
</para>
</listitem>
<listitem>
<para>
Archive catalog: getting the list of all WAL timelines and
the corresponding meta information in plain text or
<acronym>JSON</acronym> formats.
</para>
</listitem>
<listitem>
<para>
Partial restore: restoring only the specified databases.
</para>
</listitem>
<listitem>
<para>
Catchup: cloning a <productname>PostgreSQL</productname> instance for a fallen-behind standby server to <quote>catch up</quote> with master.
</para>
</listitem>
</itemizedlist>
<para>
To manage backup data, <application>pg_probackup</application> creates a
<firstterm>backup catalog</firstterm>. This is a directory that stores
all backup files with additional meta information, as well as WAL
archives required for point-in-time recovery. You can store
backups for different instances in separate subdirectories of a
single backup catalog.
</para>
<para>
Using <application>pg_probackup</application>, you can take full or incremental
<link linkend="pbk-creating-backup">backups</link>:
</para>
<itemizedlist spacing="compact">
<listitem>
<para id="pbk-modes-full">
FULL backups contain all the data files required to restore
the database cluster.
</para>
</listitem>
<listitem>
<para>
Incremental backups operate at the page level, only storing the data that has changed since
the previous backup. It allows you to save disk space
and speed up the backup process as compared to taking full backups.
It is also faster to restore the cluster by applying incremental
backups than by replaying WAL files. <application>pg_probackup</application> supports
the following modes of incremental backups:
</para>
<itemizedlist spacing="compact">
<listitem>
<para id="pbk-modes-delta">
DELTA backup. In this mode, <application>pg_probackup</application> reads all data
files in the data directory and copies only those pages
that have changed since the previous backup. This
mode can impose read-only I/O pressure equal to a full
backup.
</para>
</listitem>
<listitem>
<para id="pbk-modes-page">
PAGE backup. In this mode, <application>pg_probackup</application> scans all WAL
files in the archive from the moment the previous full or
incremental backup was taken. Newly created backups
contain only the pages that were mentioned in WAL records.
This requires all the WAL files since the previous backup
to be present in the WAL archive. If the size of these
files is comparable to the total size of the database
cluster files, speedup is smaller, but the backup still
takes less space. You have to configure WAL archiving as
explained in <link linkend="pbk-setting-up-continuous-wal-archiving">Setting
up continuous WAL archiving</link> to make PAGE backups.
</para>
</listitem>
<listitem>
<para id="pbk-modes-ptrack">
PTRACK backup. In this mode, <productname>PostgreSQL</productname> tracks page
changes on the fly. Continuous archiving is not necessary
for it to operate. Each time a relation page is updated,
this page is marked in a special PTRACK bitmap. Tracking implies some
minor overhead on the database server operation, but
speeds up incremental backups significantly.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
<application>pg_probackup</application> can take only physical online backups, and online
backups require WAL for consistent recovery. So regardless of the
chosen backup mode (FULL, PAGE or DELTA), any backup taken with
<application>pg_probackup</application> must use one of the following
<firstterm>WAL delivery modes</firstterm>:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<link linkend="pbk-archive-mode">ARCHIVE</link>. Such backups rely
on
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
archiving</link> to ensure consistent recovery. This is the
default WAL delivery mode.
</para>
</listitem>
<listitem>
<para>
<link linkend="pbk-stream-mode">STREAM</link>. Such backups
include all the files required to restore the cluster to a
consistent state at the time the backup was taken. Regardless
of
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
archiving</link> having been set up or not, the WAL segments required
for consistent recovery are streamed via
replication protocol during backup and included into the
backup files. That's why such backups are called
<firstterm>autonomous</firstterm>, or <firstterm>standalone</firstterm>.
</para>
</listitem>
</itemizedlist>
<refsect2 id="pbk-limitations">
<title>Limitations</title>
<para>
<application>pg_probackup</application> currently has the following limitations:
<itemizedlist spacing="compact">
<listitem>
<para>
<application>pg_probackup</application> only supports PostgreSQL 9.5 and higher.
</para>
</listitem>
<listitem>
<para>
The remote mode is not supported on Windows systems.
</para>
</listitem>
<listitem>
<para>
On Unix systems, for <productname>PostgreSQL</productname> 10 or lower,
a backup can be made only by the same OS user that has started the <productname>PostgreSQL</productname>
server. For example, if <productname>PostgreSQL</productname> server is started by
user <literal>postgres</literal>, the <literal>backup</literal> command must also be run
by user <literal>postgres</literal>. To satisfy this requirement when taking backups in the
<link linkend="pbk-remote-backup">remote mode</link> using SSH, you must set
<option>--remote-user</option> option to <literal>postgres</literal>.
</para>
</listitem>
<listitem>
<para>
For <productname>PostgreSQL</productname> 9.5, functions
<function>pg_create_restore_point(text)</function> and
<function>pg_switch_xlog()</function> can be executed only if
the backup role is a superuser, so backup of a
cluster with low amount of WAL traffic by a non-superuser
role can take longer than the backup of the same cluster by
a superuser role.
</para>
</listitem>
<listitem>
<para>
The <productname>PostgreSQL</productname> server from which the backup was taken and
the restored server must be compatible by the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-preset.html#GUC-BLOCK-SIZE">block_size</ulink>
and
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-preset.html#GUC-WAL-BLOCK-SIZE">wal_block_size</ulink>
parameters and have the same major release number.
Depending on cluster configuration, <productname>PostgreSQL</productname> itself may
apply additional restrictions, such as CPU architecture
or <application>libc</application>/<application>icu</application> versions.
</para>
</listitem>
</itemizedlist>
</para>
</refsect2>
</refsect1>
<refsect1 id="pbk-install-and-setup">
<title>Installation and Setup</title>
<para>
Once you have <application>pg_probackup</application> installed, complete the following
setup:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
Initialize the backup catalog.
</para>
</listitem>
<listitem>
<para>
Add a new backup instance to the backup catalog.
</para>
</listitem>
<listitem>
<para>
Configure the database cluster to enable <application>pg_probackup</application> backups.
</para>
</listitem>
<listitem>
<para>
Optionally, configure SSH for running <application>pg_probackup</application> operations
in the remote mode.
</para>
</listitem>
</itemizedlist>
<refsect2 id="pbk-initializing-the-backup-catalog">
<title>Initializing the Backup Catalog</title>
<para>
<application>pg_probackup</application> stores all WAL and backup files in the
corresponding subdirectories of the backup catalog.
</para>
<para>
To initialize the backup catalog, run the following command:
</para>
<programlisting>
pg_probackup init -B <replaceable>backup_dir</replaceable>
</programlisting>
<para>
where <replaceable>backup_dir</replaceable> is the path to the backup
catalog. If the <replaceable>backup_dir</replaceable> already exists,
it must be empty. Otherwise, <application>pg_probackup</application> returns an error.
</para>
<para>
The user launching <application>pg_probackup</application> must have full access to
the <replaceable>backup_dir</replaceable> directory.
</para>
<para>
<application>pg_probackup</application> creates the <replaceable>backup_dir</replaceable> backup
catalog, with the following subdirectories:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<filename>wal/</filename> — directory for WAL files.
</para>
</listitem>
<listitem>
<para>
<filename>backups/</filename> — directory for backup files.
</para>
</listitem>
</itemizedlist>
<para>
Once the backup catalog is initialized, you can add a new backup
instance.
</para>
</refsect2>
<refsect2 id="pbk-adding-new-backup-instance">
<title>Adding a New Backup Instance</title>
<para>
<application>pg_probackup</application> can store backups for multiple database clusters in
a single backup catalog. To set up the required subdirectories,
you must add a backup instance to the backup catalog for each
database cluster you are going to back up.
</para>
<para>
To add a new backup instance, run the following command:
</para>
<programlisting>
pg_probackup add-instance -B <replaceable>backup_dir</replaceable> -D <replaceable>data_dir</replaceable> --instance <replaceable>instance_name</replaceable> [<replaceable>remote_options</replaceable>]
</programlisting>
<para>
where:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<replaceable>data_dir</replaceable> is the data directory of the
cluster you are going to back up. To set up and use
<application>pg_probackup</application>, write access to this directory is required.
</para>
</listitem>
<listitem>
<para>
<replaceable>instance_name</replaceable> is the name of the
subdirectories that will store WAL and backup files for this
cluster.
</para>
</listitem>
<listitem>
<para>
<link linkend="pbk-remote-server-opts">remote_options</link>
are optional parameters that need to be specified only if
<replaceable>data_dir</replaceable> is located
on a remote system.
</para>
</listitem>
</itemizedlist>
<para>
<application>pg_probackup</application> creates the <replaceable>instance_name</replaceable>
subdirectories under the <filename>backups/</filename> and <filename>wal/</filename> directories of
the backup catalog. The
<filename>backups/<replaceable>instance_name</replaceable></filename> directory contains
the <filename>pg_probackup.conf</filename> configuration file that controls
<application>pg_probackup</application> settings for this backup instance. If you run this
command with the
<link linkend="pbk-remote-server-opts">remote_options</link>, the specified
parameters will be added to <filename>pg_probackup.conf</filename>.
</para>
<para>
For details on how to fine-tune <application>pg_probackup</application> configuration, see
<xref linkend="pbk-configuring-pg-probackup"/>.
</para>
<para>
The user launching <application>pg_probackup</application> must have full access to
<replaceable>backup_dir</replaceable> directory and at least read-only
access to <replaceable>data_dir</replaceable> directory. If you
specify the path to the backup catalog in the
<envar>BACKUP_PATH</envar> environment variable, you can
omit the corresponding option when running <application>pg_probackup</application>
commands.
</para>
<note>
<para>
For <productname>PostgreSQL</productname> 11 or higher, it is recommended to use the
<ulink url="https://postgrespro.com/docs/postgresql/current/app-initdb.html#APP-INITDB-ALLOW-GROUP-ACCESS">allow-group-access</ulink>
feature, so that backup can be done by any OS user in the same
group as the cluster owner. In this case, the user should have
read permissions for the cluster directory.
</para>
</note>
</refsect2>
<refsect2 id="pbk-configuring-the-database-cluster">
<title>Configuring the Database Cluster</title>
<para>
Although <application>pg_probackup</application> can be used by a superuser, it is
recommended to create a separate role with the minimum
permissions required for the chosen backup strategy. In these
configuration instructions, the <literal>backup</literal> role
is used as an example.
</para>
<para>
To perform a <xref linkend="pbk-backup"/>, the following
permissions for role <literal>backup</literal> are required
only in the database <emphasis role="strong">used for
connection</emphasis> to the <productname>PostgreSQL</productname> server:
</para>
<para>
For <productname>PostgreSQL</productname> 9.5:
</para>
<programlisting>
BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_start_backup(text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_xlog() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
COMMIT;
</programlisting>
<para>
For <productname>PostgreSQL</productname> 9.6:
</para>
<programlisting>
BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_start_backup(text, boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup(boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_xlog() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_xlog_replay_location() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;
</programlisting>
<para>
For <productname>PostgreSQL</productname> versions 10 &mdash; 14:
</para>
<programlisting>
BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_start_backup(text, boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup(boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;
</programlisting>
<para>
For <productname>PostgreSQL</productname> 15 or higher:
</para>
<programlisting>
BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_start(text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_stop(boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;
</programlisting>
<para>
In the
<ulink url="https://postgrespro.com/docs/postgresql/current/auth-pg-hba-conf.html">pg_hba.conf</ulink>
file, allow connection to the database cluster on behalf of the
<literal>backup</literal> role.
</para>
<para>
Since <application>pg_probackup</application> needs to read cluster files directly,
<application>pg_probackup</application> must be started by (or connected to,
if used in the remote mode) the OS user that has read access to all files and
directories inside the data directory (<envar>PGDATA</envar>) you are going to
back up.
</para>
<para>
Depending on whether you plan to take
<link linkend="pbk-stream-mode">standalone</link> or
<link linkend="pbk-archive-mode">archive</link> backups, <productname>PostgreSQL</productname>
cluster configuration will differ, as specified in the sections
below. To back up the database cluster from a standby server,
run <application>pg_probackup</application> in the remote mode, or create PTRACK backups,
additional setup is required.
</para>
<para>
For details, see the sections
<link linkend="pbk-setting-up-stream-backups">Setting up STREAM
Backups</link>,
<link linkend="pbk-setting-up-continuous-wal-archiving">Setting up
continuous WAL archiving</link>,
<link linkend="pbk-setting-up-backup-from-standby">Setting up Backup
from Standby</link>,
<link linkend="pbk-configuring-the-remote-mode">Configuring the
Remote Mode</link>,
<link linkend="pbk-setting-up-partial-restore">Setting up Partial
Restore</link>, and
<link linkend="pbk-setting-up-ptrack-backups">Setting up PTRACK
Backups</link>.
</para>
</refsect2>
<refsect2 id="pbk-setting-up-stream-backups">
<title>Setting up STREAM Backups</title>
<para>
To set up the cluster for
<link linkend="pbk-stream-mode">STREAM</link> backups, complete the
following steps:
</para>
<itemizedlist>
<listitem>
<para>
Grant the <literal>REPLICATION</literal> privilege to the <literal>backup</literal> role:
</para>
<programlisting>
ALTER ROLE backup WITH REPLICATION;
</programlisting>
</listitem>
<listitem>
<para>
In the
<ulink url="https://postgrespro.com/docs/postgresql/current/auth-pg-hba-conf.html">pg_hba.conf</ulink>
file, allow replication on behalf of the
<literal>backup</literal> role.
</para>
</listitem>
<listitem>
<para>
Make sure the parameter
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</ulink>
is set high enough to leave at least one session available
for the backup process.
</para>
</listitem>
<listitem>
<para>
Set the parameter
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</ulink>
to be higher than <literal>minimal</literal>.
</para>
</listitem>
</itemizedlist>
<para>
If you are planning to take PAGE backups in the STREAM mode or
perform PITR with STREAM backups, you still have to configure
WAL archiving, as explained in the section
<link linkend="pbk-setting-up-continuous-wal-archiving">Setting up
continuous WAL archiving</link>.
</para>
<para>
Once these steps are complete, you can start taking FULL, PAGE,
DELTA, and PTRACK backups in the
<link linkend="pbk-stream-mode">STREAM</link> WAL mode.
</para>
<note>
<para>
If you are planning to rely on
<ulink url="https://postgrespro.com/docs/postgresql/current/libpq-pgpass.html">.pgpass</ulink>
for authentication when running backup in STREAM mode,
then .pgpass must contain credentials for <literal>replication</literal> database,
used to establish connection via replication protocol. Example:
pghost:5432:replication:backup_user:my_strong_password
</para>
</note>
</refsect2>
<refsect2 id="pbk-setting-up-continuous-wal-archiving">
<title>Setting up Continuous WAL Archiving</title>
<para>
Making backups in PAGE backup mode, performing
<link linkend="pbk-performing-point-in-time-pitr-recovery">PITR</link> and
making backups with
<link linkend="pbk-archive-mode">ARCHIVE</link> WAL delivery mode
require
<ulink url="https://postgrespro.com/docs/postgresql/current/continuous-archiving.html">continuous
WAL archiving</ulink> to be enabled. To set up continuous
archiving in the cluster, complete the following steps:
</para>
<itemizedlist>
<listitem>
<para>
Make sure the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</ulink>
parameter is higher than <literal>minimal</literal>.
</para>
</listitem>
<listitem>
<para>
If you are configuring archiving on master,
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</ulink>
must be set to <literal>on</literal> or
<literal>always</literal>. To perform archiving on standby,
set this parameter to <literal>always</literal>.
</para>
</listitem>
<listitem>
<para>
Set the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</ulink>
parameter, as follows:
</para>
<programlisting>
archive_command = '"<replaceable>install_dir</replaceable>/pg_probackup" archive-push -B "<replaceable>backup_dir</replaceable>" --instance <replaceable>instance_name</replaceable> --wal-file-name=%f [<replaceable>remote_options</replaceable>]'
</programlisting>
</listitem>
</itemizedlist>
<para>
where <replaceable>install_dir</replaceable> is the
installation directory of the <application>pg_probackup</application>
version you are going to use, <replaceable>backup_dir</replaceable> and
<replaceable>instance_name</replaceable> refer to the already
initialized backup catalog instance for this database cluster,
and <link linkend="pbk-remote-server-opts">remote_options</link>
only need to be specified to archive WAL on a remote host. For details about all
possible <command>archive-push</command> parameters, see the
section <xref linkend="pbk-archive-push"/>.
</para>
<para>
Once these steps are complete, you can start making backups in the
<link linkend="pbk-archive-mode">ARCHIVE</link> WAL mode, backups in
the PAGE backup mode, as well as perform
<link linkend="pbk-performing-point-in-time-pitr-recovery">PITR</link>.
</para>
<para>
You can view the current state of the WAL archive using the
<xref linkend="pbk-show"/> command. For details, see
<xref linkend="pbk-viewing-wal-archive-information"/>.
</para>
<para>
If you are planning to make PAGE backups and/or backups with
<link linkend="pbk-archive-mode">ARCHIVE</link> WAL mode from a
standby server that generates a small amount of WAL traffic,
without long waiting for WAL segment to fill up, consider
setting the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT">archive_timeout</ulink>
<productname>PostgreSQL</productname> parameter <emphasis role="strong">on
master</emphasis>. The value of this parameter should be slightly
lower than the <option>--archive-timeout</option> setting (5 minutes by default),
so that there is enough time for the rotated
segment to be streamed to standby and sent to WAL archive before the
backup is aborted because of <option>--archive-timeout</option>.
</para>
<note>
<para>
Instead of using the <xref linkend="pbk-archive-push"/>
command provided by <application>pg_probackup</application>, you can use
any other tool to set up continuous archiving as long as it delivers WAL segments into
<filename><replaceable>backup_dir</replaceable>/wal/<replaceable>instance_name</replaceable></filename>
directory. If compression is used, it should be
<literal>gzip</literal>, and <literal>.gz</literal> suffix in filename is
mandatory.
</para>
</note>
<note>
<para>
Instead of configuring continuous archiving by setting the
<varname>archive_mode</varname> and <varname>archive_command</varname>
parameters, you can opt for using the
<ulink url="https://postgrespro.com/docs/postgresql/current/app-pgreceivewal.html">pg_receivewal</ulink>
utility. In this case, <application>pg_receivewal</application> <literal>-D <replaceable>directory</replaceable></literal>
option should point to
<filename><replaceable>backup_dir</replaceable>/wal/<replaceable>instance_name</replaceable></filename>
directory. <application>pg_probackup</application> supports WAL compression
that can be done by <application>pg_receivewal</application>.
<quote>Zero Data Loss</quote> archive strategy can be
achieved only by using <application>pg_receivewal</application>.
</para>
</note>
</refsect2>
<refsect2 id="pbk-setting-up-backup-from-standby">
<title>Setting up Backup from Standby</title>
<para>
For <productname>PostgreSQL</productname> 9.6 or higher, <application>pg_probackup</application> can take backups from
a standby server. This requires the following additional setup:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
On the standby server, set the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</ulink>
parameter to <literal>on</literal>.
</para>
</listitem>
<listitem>
<para>
On the master server, set the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</ulink>
parameter to <literal>on</literal>.
</para>
</listitem>
<listitem>
<para>
To perform standalone backups on standby, complete all steps
in section <link linkend="pbk-setting-up-stream-backups">Setting
up STREAM Backups</link>.
</para>
</listitem>
<listitem>
<para>
To perform archive backups on standby, complete all steps in
section
<link linkend="pbk-setting-up-continuous-wal-archiving">Setting
up continuous WAL archiving</link>.
</para>
</listitem>
</itemizedlist>
<para>
Once these steps are complete, you can start taking FULL, PAGE,
DELTA, or PTRACK backups with appropriate WAL delivery mode:
ARCHIVE or STREAM, from the standby server.
</para>
<para>
Backup from the standby server has the following limitations:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
If the standby is promoted to the master during backup, the
backup fails.
</para>
</listitem>
<listitem>
<para>
All WAL records required for the backup must contain
sufficient full-page writes. This requires you to enable
<literal>full_page_writes</literal> on the master, and not
to use tools like <application>pg_compresslog</application> as
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</ulink>
to remove full-page writes from WAL files.
</para>
</listitem>
</itemizedlist>
</refsect2>
<refsect2 id="pbk-setting-up-cluster-verification">
<title>Setting up Cluster Verification</title>
<para>
Logical verification of a database cluster requires the following
additional setup. Role <literal>backup</literal> is used as an
example:
</para>
<itemizedlist>
<listitem>
<para>
Install the
<ulink url="https://postgrespro.com/docs/postgresql/current/amcheck.html">amcheck</ulink>
or
<ulink url="https://github.com/petergeoghegan/amcheck">amcheck_next</ulink> extension
<emphasis role="strong">in every database</emphasis> of the
cluster:
</para>
<programlisting>
CREATE EXTENSION amcheck;
</programlisting>
</listitem>
<listitem>
<para>
Grant the following permissions to the <literal>backup</literal>
role <emphasis role="strong">in every database</emphasis> of the cluster:
</para>
</listitem>
</itemizedlist>
<programlisting>
GRANT SELECT ON TABLE pg_catalog.pg_am TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_class TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_database TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_namespace TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_extension TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass) TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool) TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool, bool) TO backup;
</programlisting>
</refsect2>
<refsect2 id="pbk-setting-up-partial-restore">
<title>Setting up Partial Restore</title>
<para>
If you are planning to use partial restore, complete the
following additional step:
</para>
<itemizedlist>
<listitem>
<para>
Grant the read-only access to <literal>pg_catalog.pg_database</literal> to the
<literal>backup</literal> role only in the database
<emphasis role="strong">used for connection</emphasis> to
<productname>PostgreSQL</productname> server:
</para>
<programlisting>
GRANT SELECT ON TABLE pg_catalog.pg_database TO backup;
</programlisting>
</listitem>
</itemizedlist>
</refsect2>
<refsect2 id="pbk-configuring-the-remote-mode">
<title>Configuring the Remote Mode</title>
<para>
<application>pg_probackup</application> supports the remote mode that allows to perform
backup, restore and WAL archiving operations remotely. In this
mode, the backup catalog is stored on a local system, while
<productname>PostgreSQL</productname> instance to backup and/or to restore is located on a
remote system. Currently the only supported remote protocol is
SSH.
</para>
<refsect3 id="pbk-setup-ssh">
<title>Set up SSH</title>
<para>
If you are going to use <application>pg_probackup</application> in remote mode via SSH,
complete the following steps:
</para>
<itemizedlist>
<listitem>
<para>
Install <application>pg_probackup</application> on both systems:
<literal>backup_host</literal> and
<literal>db_host</literal>.
</para>
</listitem>
<listitem>
<para>
For communication between the hosts set up the passwordless
SSH connection between <literal>backup</literal> user on
<literal>backup_host</literal> and
<literal>postgres</literal> user on
<literal>db_host</literal>:
</para>
<programlisting>
[backup@backup_host] ssh-copy-id postgres@db_host
</programlisting>
</listitem>
<listitem>
<para>
If you are going to rely on
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
WAL archiving</link>, set up passwordless SSH
connection between <literal>postgres</literal> user on
<literal>db_host</literal> and <literal>backup</literal>
user on <literal>backup_host</literal>:
</para>
<programlisting>
[postgres@db_host] ssh-copy-id backup@backup_host
</programlisting>
</listitem>
</itemizedlist>
<para>
where:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>backup_host</literal> is the system with
<emphasis>backup catalog</emphasis>.
</para>
</listitem>
<listitem>
<para>
<literal>db_host</literal> is the system with <productname>PostgreSQL</productname>
cluster.
</para>
</listitem>
<listitem>
<para>
<literal>backup</literal> is the OS user on
<literal>backup_host</literal> used to run <application>pg_probackup</application>.
</para>
</listitem>
<listitem>
<para>
<literal>postgres</literal> is the OS user on
<literal>db_host</literal> used to start the <productname>PostgreSQL</productname>
cluster. For <productname>PostgreSQL</productname> 11 or higher a
more secure approach can be used thanks to
<ulink url="https://postgrespro.com/docs/postgresql/current/app-initdb.html#APP-INITDB-ALLOW-GROUP-ACCESS">allow-group-access</ulink>
feature.
</para>
</listitem>
</itemizedlist>
<para>
<application>pg_probackup</application> in the remote mode via SSH works
as follows:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
Only the following commands can be launched in the remote
mode: <xref linkend="pbk-add-instance"/>,
<xref linkend="pbk-backup"/>,
<xref linkend="pbk-restore"/>,
<xref linkend="pbk-catchup"/>,
<xref linkend="pbk-archive-push"/>, and
<xref linkend="pbk-archive-get"/>.
</para>
</listitem>
<listitem>
<para>
Operating in remote mode requires <application>pg_probackup</application>
binary to be installed on both local and remote systems.
The versions of local and remote binary must be the same.
</para>
</listitem>
<listitem>
<para>
When started in the remote mode, the main <application>pg_probackup</application> process
on the local system connects to the remote system via SSH and
launches one or more agent processes on the remote system, which are called
<firstterm>remote agents</firstterm>. The number of remote agents
is equal to the <option>-j</option>/<option>--threads</option> setting.
</para>
</listitem>
<listitem>
<para>
The main <application>pg_probackup</application> process uses remote agents to access
remote files and transfer data between local and remote
systems.
</para>
</listitem>
<listitem>
<para>
Remote agents try to minimize the network traffic and the number of
round-trips between hosts.
</para>
</listitem>
<listitem>
<para>
The main process is usually started on
<replaceable>backup_host</replaceable> and connects to
<replaceable>db_host</replaceable>, but in case of
<command>archive-push</command> and
<command>archive-get</command> commands the main process
is started on <replaceable>db_host</replaceable> and connects to
<replaceable>backup_host</replaceable>.
</para>
</listitem>
<listitem>
<para>
Once data transfer is complete, remote agents are
terminated and SSH connections are closed.
</para>
</listitem>
<listitem>
<para>
If an error condition is encountered by a remote agent,
then all agents are terminated and error details are
reported by the main <application>pg_probackup</application> process, which exits
with an error.
</para>
</listitem>
<listitem>
<para>
Compression is always done on
<replaceable>db_host</replaceable>, while decompression is always done on
<replaceable>backup_host</replaceable>.
</para>
</listitem>
</itemizedlist>
<note>
<para>
You can impose
<ulink url="https://man.openbsd.org/OpenBSD-current/man8/sshd.8#AUTHORIZED_KEYS_FILE_FORMAT">additional
restrictions</ulink> on SSH settings to protect the system
in the event of account compromise.
</para>
</note>
</refsect3>
</refsect2>
<refsect2 id="pbk-setting-up-ptrack-backups">
<title>Setting up PTRACK Backups</title>
<para>
The PTRACK backup mode can be used only for <productname>Postgres Pro Standard</productname> and
<productname>Postgres Pro Enterprise</productname> installations, or patched vanilla
PostgreSQL. Links to PTRACK patches can be found
<ulink url="https://github.com/postgrespro/pg_probackup#ptrack-support">here</ulink>.
</para>
<note>
<para>
PTRACK versions lower than 2.0 are deprecated and not supported. Postgres Pro Standard and Postgres Pro Enterprise
versions starting with 11.9.1 contain PTRACK 2.0. Upgrade your server to avoid issues in backups
that you will take in future and be sure to take fresh backups of your clusters with the upgraded
PTRACK since the backups taken with PTRACK 1.x might be corrupt.
</para>
</note>
<para>
If you are going to use PTRACK backups, complete the following
additional steps. The role that will perform PTRACK backups
(the <literal>backup</literal> role in the examples below) must have
access to all the databases of the cluster.
</para>
<para>
For <productname>PostgreSQL</productname> 11 or higher:
</para>
<orderedlist>
<listitem>
<para>
Create PTRACK extension:
<programlisting>
CREATE EXTENSION ptrack;
</programlisting>
</para>
</listitem>
<listitem>
<para>
To enable tracking page updates, set <varname>ptrack.map_size</varname>
parameter to a positive integer and restart the server.
</para>
<para>
For optimal performance, it is recommended to set
<varname>ptrack.map_size</varname> to
<literal><replaceable>N</replaceable> / 1024</literal>, where
<replaceable>N</replaceable> is the size of the
<productname>PostgreSQL</productname> cluster, in MB. If you set this
parameter to a lower value, PTRACK is more likely to map several blocks
together, which leads to false-positive results when tracking changed
blocks and increases the incremental backup size as unchanged blocks
can also be copied into the incremental backup.
Setting <varname>ptrack.map_size</varname> to a higher value does not
affect PTRACK operation, but it is not recommended to set this parameter
to a value higher than 1024.
</para>
</listitem>
</orderedlist>
<note>
<para>
If you change the <varname>ptrack.map_size</varname> parameter value,
the previously created PTRACK map file is cleared,
and tracking newly changed blocks starts from scratch. Thus, you have
to retake a full backup before taking incremental PTRACK backups after
changing <varname>ptrack.map_size</varname>.
</para>
</note>
</refsect2>
</refsect1>
<refsect1 id="pbk-usage">
<title>Usage</title>
<refsect2 id="pbk-creating-backup">
<title>Creating a Backup</title>
<para>
To create a backup, run the following command:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b <replaceable>backup_mode</replaceable>
</programlisting>
<para>
Where <replaceable>backup_mode</replaceable> can take one of the
following values:
<literal><link linkend="pbk-modes-full">FULL</link></literal>,
<literal><link linkend="pbk-modes-delta">DELTA</link></literal>,
<literal><link linkend="pbk-modes-page">PAGE</link></literal>, and
<literal><link linkend="pbk-modes-ptrack">PTRACK</link></literal>.
</para>
<para>
When restoring a cluster from an incremental backup,
<application>pg_probackup</application> relies on the parent full backup and all the
incremental backups between them, which is called
<quote>the backup chain</quote>. You must create at least
one full backup before taking incremental ones.
</para>
<refsect3 id="pbk-archive-mode">
<title>ARCHIVE Mode</title>
<para>
ARCHIVE is the default WAL delivery mode.
</para>
<para>
For example, to make a FULL backup in ARCHIVE mode, run:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL
</programlisting>
<para>
ARCHIVE backups rely on
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
archiving</link> to get WAL segments required to restore
the cluster to a consistent state at the time the backup was
taken.
</para>
<para>
When a backup is taken, <application>pg_probackup</application>
ensures that WAL files containing WAL records between <literal>Start
LSN</literal> and <literal>Stop LSN</literal> actually exist in
<filename><replaceable>backup_dir</replaceable>/wal/<replaceable>instance_name</replaceable></filename>
directory. <application>pg_probackup</application> also ensures that WAL records between
<literal>Start LSN</literal> and <literal>Stop LSN</literal> can be parsed. This precaution
eliminates the risk of silent WAL corruption.
</para>
</refsect3>
<refsect3 id="pbk-stream-mode">
<title>STREAM Mode</title>
<para>
STREAM is the optional WAL delivery mode.
</para>
<para>
For example, to make a FULL backup in the STREAM mode, add the
<option>--stream</option> flag to the command from the
previous example:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL --stream --temp-slot
</programlisting>
<para>
The optional <option>--temp-slot</option> flag ensures that
the required segments remain available if the WAL is rotated
before the backup is complete.
</para>
<para>
Unlike backups in ARCHIVE mode, STREAM backups include all the
WAL segments required to restore the cluster to a consistent
state at the time the backup was taken.
</para>
<para>
During <xref linkend="pbk-backup"/> <application>pg_probackup</application>
streams WAL files containing WAL records between <literal>Start LSN</literal> and
<literal>Stop LSN</literal> to
<filename><replaceable>backup_dir</replaceable>/backups/<replaceable>instance_name</replaceable>/<replaceable>backup_id</replaceable>/database/pg_wal</filename> directory. To eliminate the risk
of silent WAL corruption, <application>pg_probackup</application> also
checks that WAL records between <literal>Start LSN</literal> and
<literal>Stop LSN</literal> can be parsed.
</para>
<para>
Even if you are using
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
archiving</link>, STREAM backups can still be useful in the
following cases:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
STREAM backups can be restored on the server that has no
file access to WAL archive.
</para>
</listitem>
<listitem>
<para>
STREAM backups enable you to restore the cluster state at
the point in time for which WAL files in archive are no
longer available.
</para>
</listitem>
<listitem>
<para>
Backup in STREAM mode can be taken from a standby of a
server that generates small amount of WAL traffic,
without long waiting for WAL segment to fill up.
</para>
</listitem>
</itemizedlist>
</refsect3>
<refsect3 id="pbk-page-validation">
<title>Page Validation</title>
<para>
If
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-preset.html#GUC-DATA-CHECKSUMS">data
checksums</ulink> are enabled in the database cluster,
<application>pg_probackup</application> uses this information to check correctness of
data files during backup. While reading each page,
<application>pg_probackup</application> checks whether the calculated checksum coincides
with the checksum stored in the page header. This guarantees
that the <productname>PostgreSQL</productname> instance and the backup itself have no
corrupt pages. Note that <application>pg_probackup</application> reads database files
directly from the filesystem, so under heavy write load during
backup it can show false-positive checksum mismatches because of
partial writes. If a page checksum mismatch occurs, the page is
re-read and checksum comparison is repeated.
</para>
<para>
A page is considered corrupt if checksum comparison has failed
more than 100 times. In this case, the backup is aborted.
</para>
<para>
Even if data checksums are not enabled, <application>pg_probackup</application>
always performs sanity checks for page headers.
</para>
</refsect3>
<refsect3 id="pbk-external-directories">
<title>External Directories</title>
<para>
To back up a directory located outside of the data directory,
use the optional <option>--external-dirs</option> parameter
that specifies the path to this directory. If you would like
to add more than one external directory, you can provide several paths
separated by colons on Linux systems or semicolons on Windows systems.
</para>
<para>
For example, to include <filename>/etc/dir1</filename> and
<filename>/etc/dir2</filename> directories into the full
backup of your <replaceable>instance_name</replaceable> instance
that will be stored under the <replaceable>backup_dir</replaceable>
directory on Linux, run:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL --external-dirs=/etc/dir1:/etc/dir2
</programlisting>
<para>
Similarly, to include <filename>C:\dir1</filename> and
<filename>C:\dir2</filename> directories into the full backup
on Windows, run:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL --external-dirs=C:\dir1;C:\dir2
</programlisting>
<para>
<application>pg_probackup</application> recursively copies the contents
of each external directory into a separate subdirectory in the backup
catalog. Since external directories included into different backups
do not have to be the same, when you are restoring the cluster from an
incremental backup, only those directories that belong to this
particular backup will be restored. Any external directories
stored in the previous backups will be ignored.
</para>
<para>
To include the same directories into each backup of your
instance, you can specify them in the <filename>pg_probackup.conf</filename>
configuration file using the
<xref linkend="pbk-set-config"/> command with the
<option>--external-dirs</option> option.
</para>
</refsect3>
</refsect2>
<refsect2 id="pbk-verifying-a-cluster">
<title>Performing Cluster Verification</title>
<para>
To verify that <productname>PostgreSQL</productname> database cluster is
not corrupt, run the following command:
</para>
<programlisting>
pg_probackup checkdb [-B <replaceable>backup_dir</replaceable> [--instance <replaceable>instance_name</replaceable>]] [-D <replaceable>data_dir</replaceable>] [<replaceable>connection_options</replaceable>]
</programlisting>
<para>
This command performs physical verification of all data files
located in the specified data directory by running page header
sanity checks, as well as block-level checksum verification if checksums are enabled.
If a corrupt page is detected, <command>checkdb</command>
continues cluster verification until all pages in the cluster
are validated.
</para>
<para>
By default, similar <link linkend="pbk-page-validation">page validation</link>
is performed automatically while a backup is taken by
<application>pg_probackup</application>. The <literal>checkdb</literal>
command enables you to perform such page validation
on demand, without taking any backup copies, even if the cluster
is not backed up using <application>pg_probackup</application> at all.
</para>
<para>
To perform cluster verification, <application>pg_probackup</application>
needs to connect to the cluster to be verified. In general, it is
enough to specify the backup instance of this cluster for
<application>pg_probackup</application> to determine the required
connection options. However, if <literal>-B</literal> and
<literal>--instance</literal> options are omitted, you have to provide
<link linkend="pbk-connection-opts">connection options</link> and
<replaceable>data_dir</replaceable> via environment
variables or command-line options.
</para>
<para>
Physical verification cannot detect logical inconsistencies,
missing or nullified blocks and entire files, or similar anomalies. Extensions
<ulink url="https://postgrespro.com/docs/postgresql/current/amcheck.html">amcheck</ulink>
and
<ulink url="https://github.com/petergeoghegan/amcheck">amcheck_next</ulink>
provide a partial solution to these problems.
</para>
<para>
If you would like, in addition to physical verification, to
verify all indexes in all databases using these extensions, you
can specify the <option>--amcheck</option> flag when running
the <xref linkend="pbk-checkdb"/> command:
</para>
<programlisting>
pg_probackup checkdb -D <replaceable>data_dir</replaceable> --amcheck [<replaceable>connection_options</replaceable>]
</programlisting>
<para>
You can skip physical verification by specifying the
<option>--skip-block-validation</option> flag. In this case,
you can omit <emphasis>backup_dir</emphasis> and
<emphasis>data_dir</emphasis> options, only
<link linkend="pbk-connection-opts">connection options</link> are
mandatory:
</para>
<programlisting>
pg_probackup checkdb --amcheck --skip-block-validation [<replaceable>connection_options</replaceable>]
</programlisting>
<para>
Logical verification can be done more thoroughly with the
<option>--heapallindexed</option> flag by checking that all heap
tuples that should be indexed are actually indexed, but at the
higher cost of CPU, memory, and I/O consumption.
</para>
</refsect2>
<refsect2 id="pbk-validating-backups">
<title>Validating a Backup</title>
<para>
<application>pg_probackup</application> calculates checksums for each file in a backup
during the backup process. The process of checking checksums of
backup data files is called
<firstterm>the backup validation</firstterm>. By default, validation
is run immediately after the backup is taken and right before the
restore, to detect possible backup corruption.
</para>
<para>
If you would like to skip backup validation, you can specify the
<option>--no-validate</option> flag when running
<xref linkend="pbk-backup"/> and
<xref linkend="pbk-restore"/> commands.
</para>
<para>
To ensure that all the required backup files are present and can
be used to restore the database cluster, you can run the
<xref linkend="pbk-validate"/> command with the exact
<link linkend="pbk-recovery-target-opts">recovery target
options</link> you are going to use for recovery.
</para>
<para>
For example, to check that you can restore the database cluster
from a backup copy up to transaction ID 4242, run
this command:
</para>
<programlisting>
pg_probackup validate -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --recovery-target-xid=4242
</programlisting>
<para>
If validation completes successfully, <application>pg_probackup</application> displays the
corresponding message. If validation fails, you will receive an
error message with the exact time, transaction ID, and LSN up to
which the recovery is possible.
</para>
<para>
If you specify <emphasis>backup_id</emphasis> via
<literal>-i/--backup-id</literal> option, then only the backup copy
with specified backup ID will be validated. If
<emphasis>backup_id</emphasis> is specified with
<link linkend="pbk-recovery-target-opts">recovery target
options</link>, the <command>validate</command> command will check whether it is possible
to restore the specified backup to the specified
recovery target.
</para>
<para>
For example, to check that you can restore the database cluster
from a backup copy with the <literal>PT8XFX</literal> backup ID up to the
specified timestamp, run this command:
</para>
<programlisting>
pg_probackup validate -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i PT8XFX --recovery-target-time="2017-05-18 14:18:11+03"
</programlisting>
<para>
If you specify the <replaceable>backup_id</replaceable> of an incremental backup,
all its parents starting from FULL backup will be
validated.
</para>
<para>
If you omit all the parameters, all backups are validated.
</para>
</refsect2>
<refsect2 id="pbk-restoring-a-cluster">
<title>Restoring a Cluster</title>
<para>
To restore the database cluster from a backup, run the <xref linkend="pbk-restore"/>
command with at least the following options:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
</programlisting>
<para>
where:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<replaceable>backup_dir</replaceable> is the backup catalog that
stores all backup files and meta information.
</para>
</listitem>
<listitem>
<para>
<replaceable>instance_name</replaceable> is the backup instance
for the cluster to be restored.
</para>
</listitem>
<listitem>
<para>
<replaceable>backup_id</replaceable> specifies the backup to
restore the cluster from. If you omit this option,
<application>pg_probackup</application> uses the latest valid backup available for the
specified instance. If you specify an incremental backup to
restore, <application>pg_probackup</application> automatically restores the underlying
full backup and then sequentially applies all the necessary
increments.
</para>
</listitem>
</itemizedlist>
<para>
Once the <literal>restore</literal> command is complete, start
the database service.
</para>
<para>
If you restore <link linkend="pbk-archive-mode">ARCHIVE</link> backups,
perform <link linkend="pbk-performing-point-in-time-pitr-recovery">PITR</link>,
or specify the <literal>--restore-as-replica</literal> flag with the
<literal>restore</literal> command to set up a standby server,
<application>pg_probackup</application> creates a recovery configuration
file once all data files are copied into the target directory. This file
includes the minimal settings required for recovery, except for the password in the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-replication.html#GUC-PRIMARY-CONNINFO">primary_conninfo</ulink>
parameter; you have to add the password manually or use
the <literal>--primary-conninfo</literal> option, if required.
For <productname>PostgreSQL</productname> 11 or lower,
recovery settings are written into the <filename>recovery.conf</filename>
file. Starting from <productname>PostgreSQL</productname> 12,
<application>pg_probackup</application> writes these settings into
the <filename>probackup_recovery.conf</filename> file and then includes
it into <filename>postgresql.auto.conf</filename>.
</para>
<para>
If you are restoring a STREAM backup, the restore is complete
at once, with the cluster returned to a self-consistent state at
the point when the backup was taken. For ARCHIVE backups,
<productname>PostgreSQL</productname> replays all available archived WAL
segments, so the cluster is restored to the latest state possible
within the current timeline. You can change this behavior by using the
<link linkend="pbk-recovery-target-opts">recovery target
options</link> with the <literal>restore</literal> command,
as explained in <xref linkend="pbk-performing-point-in-time-pitr-recovery"/>.
</para>
<para>
If the cluster to restore contains tablespaces, <application>pg_probackup</application>
restores them to their original location by default. To restore
tablespaces to a different location, use the
<option>--tablespace-mapping</option>/<option>-T</option> option. Otherwise,
restoring the cluster on the same host will fail if tablespaces
are in use, because the backup would have to be written to the
same directories.
</para>
<para>
When using the <option>--tablespace-mapping</option>/<option>-T</option>
option, you must provide absolute paths to the old and new
tablespace directories. If a path happens to contain an equals
sign (<literal>=</literal>), escape it with a backslash. This option can be
specified multiple times for multiple tablespaces. For example:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -D <replaceable>data_dir</replaceable> -j 4 -i <replaceable>backup_id</replaceable> -T tablespace1_dir=<replaceable>tablespace1_newdir</replaceable> -T tablespace2_dir=<replaceable>tablespace2_newdir</replaceable>
</programlisting>
<para>
To restore the cluster on a remote host, follow the instructions in
<xref linkend="pbk-remote-backup"/>.
</para>
<note>
<para>
By default, the <xref linkend="pbk-restore"/>
command validates the specified backup before restoring the
cluster. If you run regular backup validations and would like
to save time when restoring the cluster, you can specify the
<option>--no-validate</option> flag to skip validation and
speed up the recovery.
</para>
</note>
<refsect3 id="pbk-incremental-restore">
<title>Incremental Restore</title>
<para>
The speed of restore from backup can be significantly improved
by replacing only invalid and changed pages in already
existing <productname>PostgreSQL</productname> data directory using
<link linkend="pbk-incremental-restore-options">incremental
restore options</link> with the <xref linkend="pbk-restore"/>
command.
</para>
<para>
To restore the database cluster from a backup in incremental mode,
run the <xref linkend="pbk-restore"/> command with the following options:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -D <replaceable>data_dir</replaceable> -I <replaceable>incremental_mode</replaceable>
</programlisting>
<para>
Where <replaceable>incremental_mode</replaceable> can take one of the
following values:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
CHECKSUM — read all data files in the data directory, validate
header and checksum in every page and replace only invalid
pages and those with checksum and LSN not matching with
corresponding page in backup. This is the simplest,
the most fool-proof incremental mode. Recommended to use by default.
</para>
</listitem>
<listitem>
<para>
LSN — read the <replaceable>pg_control</replaceable> in the
data directory to obtain redo LSN and redo TLI, which allows
to determine a point in history(shiftpoint), where data directory
state shifted from target backup chain history. If shiftpoint is not within
reach of backup chain history, then restore is aborted.
If shiftpoint is within reach of backup chain history, then read
all data files in the data directory, validate header and checksum in
every page and replace only invalid pages and those with LSN greater
than shiftpoint.
This mode offers a greater speed up compared to CHECKSUM, but rely
on two conditions to be met. First,
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-preset.html#GUC-DATA-CHECKSUMS">
data checksums</ulink> parameter must be enabled in data directory (to avoid corruption
due to hint bits). This condition will be checked at the start of
incremental restore and the operation will be aborted if checksums are disabled.
Second, the <replaceable>pg_control</replaceable> file must be
synched with state of data directory. This condition cannot checked
at the start of restore, so it is a user responsibility to ensure
that <replaceable>pg_control</replaceable> contain valid information.
Therefore it is not recommended to use LSN mode in any situation,
where pg_control cannot be trusted or has been tampered with:
after <replaceable>pg_resetxlog</replaceable> execution,
after restore from backup without recovery been run, etc.
</para>
</listitem>
<listitem>
<para>
NONE — regular restore without any incremental optimizations.
</para>
</listitem>
</itemizedlist>
<para>
Regardless of chosen incremental mode, pg_probackup will check, that postmaster
in given destination directory is not running and <varname>system-identifier</varname> is
the same as in the backup.
</para>
<para>
Suppose you want to return an old master as replica after switchover
using incremental restore in LSN mode:
</para>
<programlisting>
=============================================================================================================================================
Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status
=============================================================================================================================================
node 12 QBRNBP 2020-06-11 17:40:58+03 DELTA ARCHIVE 16/15 40s 194MB 16MB 8.26 15/2C000028 15/2D000128 OK
node 12 QBRIDX 2020-06-11 15:51:42+03 PAGE ARCHIVE 15/15 11s 18MB 16MB 5.10 14/DC000028 14/DD0000B8 OK
node 12 QBRIAJ 2020-06-11 15:51:08+03 PAGE ARCHIVE 15/15 20s 141MB 96MB 6.22 14/D4BABFE0 14/DA9871D0 OK
node 12 QBRHT8 2020-06-11 15:45:56+03 FULL ARCHIVE 15/0 2m:11s 1371MB 416MB 10.93 14/9D000028 14/B782E9A0 OK
pg_probackup restore -B /backup --instance node -R -I lsn
INFO: Running incremental restore into nonempty directory: "/var/lib/pgsql/12/data"
INFO: Destination directory redo point 15/2E000028 on tli 16 is within reach of backup QBRIDX with Stop LSN 14/DD0000B8 on tli 15
INFO: shift LSN: 14/DD0000B8
INFO: Restoring the database from backup at 2020-06-11 17:40:58+03
INFO: Extracting the content of destination directory for incremental restore
INFO: Destination directory content extracted, time elapsed: 1s
INFO: Removing redundant files in destination directory
INFO: Redundant files are removed, time elapsed: 1s
INFO: Start restoring backup files. PGDATA size: 15GB
INFO: Backup files are restored. Transfered bytes: 1693MB, time elapsed: 43s
INFO: Restore incremental ratio (less is better): 11% (1693MB/15GB)
INFO: Restore of backup QBRNBP completed.
</programlisting>
<note>
<para>
Incremental restore is possible only for backups with
<literal>program_version</literal> equal or greater than 2.4.0.
</para>
</note>
</refsect3>
<refsect3 id="pbk-partial-restore">
<title>Partial Restore</title>
<para>
If you have enabled
<link linkend="pbk-setting-up-partial-restore">partial
restore</link> before taking backups, you can restore
only some of the databases using
<link linkend="pbk-partial-restore-options">partial restore
options</link> with the <xref linkend="pbk-restore"/>
commands.
</para>
<para>
To restore the specified databases only, run the <xref linkend="pbk-restore"/> command
with the following options:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --db-include=<replaceable>database_name</replaceable>
</programlisting>
<para>
The <option>--db-include</option> option can be specified
multiple times. For example, to restore only databases
<literal>db1</literal> and <literal>db2</literal>, run the
following command:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --db-include=db1 --db-include=db2
</programlisting>
<para>
To exclude one or more databases from restore, use
the <option>--db-exclude</option> option:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --db-exclude=<replaceable>database_name</replaceable>
</programlisting>
<para>
The <option>--db-exclude</option> option can be specified
multiple times. For example, to exclude the databases
<literal>db1</literal> and <literal>db2</literal> from
restore, run the following command:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --db-exclude=db1 --db-exclude=db2
</programlisting>
<para>
Partial restore relies on lax behavior of <productname>PostgreSQL</productname> recovery
process toward truncated files. For recovery to work properly, files of excluded databases
are restored as files of zero size. After the <productname>PostgreSQL</productname> cluster is successfully started,
you must drop the excluded databases using
<command>DROP DATABASE</command> command.
</para>
<para>
To decouple a single cluster containing multiple databases into separate clusters with minimal downtime,
you can do partial restore of the cluster as a standby using the <option>--restore-as-replica</option> option
for specific databases.
</para>
<note>
<para>
The <literal>template0</literal> and
<literal>template1</literal> databases are always restored.
</para>
</note>
<note>
<para>
Due to recovery specifics of <productname>PostgreSQL</productname> versions earlier than 12,
it is advisable that you set the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</ulink>
parameter to <literal>off</literal> when running partial
restore of a <productname>PostgreSQL</productname> cluster of version earlier than 12.
Otherwise the recovery may fail.
</para>
</note>
</refsect3>
</refsect2>
<refsect2 id="pbk-performing-point-in-time-pitr-recovery">
<title>Performing Point-in-Time (PITR) Recovery</title>
<para>
If you have enabled
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
WAL archiving</link> before taking backups, you can restore the
cluster to its state at an arbitrary point in time (recovery
target) using <link linkend="pbk-recovery-target-opts">recovery
target options</link> with the
<xref linkend="pbk-restore"/> command.
</para>
<para>
You can use both STREAM and ARCHIVE backups for point in time
recovery as long as the WAL archive is available at least starting
from the time the backup was taken.
If <option>-i</option>/<option>--backup-id</option> option is omitted,
<application>pg_probackup</application> automatically chooses the backup that is the
closest to the specified recovery target and starts the restore
process, otherwise <application>pg_probackup</application> will try to restore
the specified backup to the specified recovery target.
</para>
<itemizedlist>
<listitem>
<para>
To restore the cluster state at the exact time, specify the
<option>--recovery-target-time</option> option, in the
timestamp format. For example:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --recovery-target-time="2017-05-18 14:18:11+03"
</programlisting>
</listitem>
<listitem>
<para>
To restore the cluster state up to a specific transaction
ID, use the <option>--recovery-target-xid</option> option:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --recovery-target-xid=687
</programlisting>
</listitem>
<listitem>
<para>
To restore the cluster state up to the specific LSN, use
<option>--recovery-target-lsn</option> option:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --recovery-target-lsn=16/B374D848
</programlisting>
</listitem>
<listitem>
<para>
To restore the cluster state up to the specific named restore
point, use <option>--recovery-target-name</option> option:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --recovery-target-name="before_app_upgrade"
</programlisting>
</listitem>
<listitem>
<para>
To restore the backup to the latest state available in
the WAL archive, use <option>--recovery-target</option> option
with <literal>latest</literal> value:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --recovery-target="latest"
</programlisting>
</listitem>
<listitem>
<para>
To restore the cluster to the earliest point of consistency,
use <option>--recovery-target</option> option with the
<literal>immediate</literal> value:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --recovery-target='immediate'
</programlisting>
</listitem>
</itemizedlist>
</refsect2>
<refsect2 id="pbk-remote-backup">
<title>Using <application>pg_probackup</application> in the Remote Mode</title>
<para>
<application>pg_probackup</application> supports the remote mode that allows to perform
<literal>backup</literal> and <literal>restore</literal>
operations remotely via SSH. In this mode, the backup catalog is
stored on a local system, while <productname>PostgreSQL</productname> instance to be backed
up is located on a remote system. You must have <application>pg_probackup</application>
installed on both systems.
</para>
<note>
<para>
<application>pg_probackup</application> relies on passwordless SSH connection
for communication between the hosts.
</para>
</note>
<para>
The typical workflow is as follows:
</para>
<itemizedlist>
<listitem>
<para>
On your backup host, configure <application>pg_probackup</application> as explained in
the section
<link linkend="pbk-install-and-setup">Installation and
Setup</link>. For the
<xref linkend="pbk-add-instance"/> and
<xref linkend="pbk-set-config"/> commands, make
sure to specify <link linkend="pbk-remote-server-opts">remote
options</link> that point to the database host with the
<productname>PostgreSQL</productname> instance.
</para>
</listitem>
<listitem>
<para>
If you would like to take remote backups in
<link linkend="pbk-creating-backup">PAGE</link> mode, or rely
on <link linkend="pbk-archive-mode">ARCHIVE</link> WAL delivery
mode, or use
<link linkend="pbk-performing-point-in-time-pitr-recovery">PITR</link>,
configure continuous WAL archiving from the database host
to the backup host as explained in the section
<link linkend="pbk-setting-up-continuous-wal-archiving">Setting
up continuous WAL archiving</link>. For the
<xref linkend="pbk-archive-push"/> and
<xref linkend="pbk-archive-get"/> commands, you
must specify the <link linkend="pbk-remote-server-opts">remote
options</link> that point to the backup host with the backup
catalog.
</para>
</listitem>
<listitem>
<para>
Run <xref linkend="pbk-backup"/> or
<xref linkend="pbk-restore"/> commands with
<link linkend="pbk-remote-server-opts">remote options</link>
<emphasis role="strong">on the backup host</emphasis>.
<application>pg_probackup</application> connects to the remote system via SSH and
creates a backup locally or restores the previously taken
backup on the remote system, respectively.
</para>
</listitem>
</itemizedlist>
<para>
For example, to create an archive full backup of a
<productname>PostgreSQL</productname> cluster located on
a remote system with host address <literal>192.168.0.2</literal>
on behalf of the <literal>postgres</literal> user via SSH connection
through port <literal>2302</literal>, run:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302
</programlisting>
<para>
To restore the latest available backup on a remote system with host address
<literal>192.168.0.2</literal> on behalf of the <literal>postgres</literal>
user via SSH connection through port <literal>2302</literal>, run:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302
</programlisting>
<para>
Restoring an ARCHIVE backup or performing PITR in the remote mode
require additional information: destination address, port and
username for establishing an SSH connection
<emphasis role="strong">from</emphasis> the host with database
<emphasis role="strong">to</emphasis> the host with the backup
catalog. This information will be used by the
<command>restore_command</command> to copy WAL segments
from the archive to the <productname>PostgreSQL</productname> <filename>pg_wal</filename> directory.
</para>
<para>
To solve this problem, you can use
<link linkend="pbk-remote-wal-archive-options">Remote WAL Archive
Options</link>.
</para>
<para>
For example, to restore latest backup on remote system using
remote mode through SSH connection to user
<literal>postgres</literal> on host with address
<literal>192.168.0.2</literal> via port <literal>2302</literal>
and user <literal>backup</literal> on backup catalog host with
address <literal>192.168.0.3</literal> via port
<literal>2303</literal>, run:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --archive-host=192.168.0.3 --archive-port=2303 --archive-user=backup
</programlisting>
<para>
Provided arguments will be used to construct the <command>restore_command</command>:
</para>
<programlisting>
restore_command = '"<replaceable>install_dir</replaceable>/pg_probackup" archive-get -B "<replaceable>backup_dir</replaceable>" --instance <replaceable>instance_name</replaceable> --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'
</programlisting>
<para>
Alternatively, you can use the <option>--restore-command</option>
option to provide the entire <parameter>restore_command</parameter>:
</para>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --restore-command='"<replaceable>install_dir</replaceable>/pg_probackup" archive-get -B "<replaceable>backup_dir</replaceable>" --instance <replaceable>instance_name</replaceable> --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'
</programlisting>
<note>
<para>
The remote mode is currently unavailable for
Windows systems.
</para>
</note>
</refsect2>
<refsect2 id="pbk-running-pg-probackup-on-parallel-threads">
<title>Running <application>pg_probackup</application> on Parallel Threads</title>
<para>
<xref linkend="pbk-backup"/>,
<xref linkend="pbk-restore"/>,
<xref linkend="pbk-merge"/>,
<xref linkend="pbk-delete"/>,
<xref linkend="pbk-catchup"/>,
<xref linkend="pbk-checkdb"/>, and
<xref linkend="pbk-validate"/> processes can be
executed on several parallel threads. This can significantly
speed up <application>pg_probackup</application> operation given enough resources (CPU
cores, disk, and network bandwidth).
</para>
<para>
Parallel execution is controlled by the
<literal>-j/--threads</literal> command-line option. For
example, to create a backup using four parallel threads, run:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL -j 4
</programlisting>
<note>
<para>
Parallel restore applies only to copying data from the
backup catalog to the data directory of the cluster. When
<productname>PostgreSQL</productname> server is started, WAL records need to be replayed,
and this cannot be done in parallel.
</para>
</note>
</refsect2>
<refsect2 id="pbk-configuring-pg-probackup">
<title>Configuring <application>pg_probackup</application></title>
<para>
Once the backup catalog is initialized and a new backup instance
is added, you can use the <filename>pg_probackup.conf</filename> configuration file
located in the
<filename><replaceable>backup_dir</replaceable>/backups/<replaceable>instance_name</replaceable></filename>
directory to fine-tune <application>pg_probackup</application> configuration.
</para>
<para>
For example, <xref linkend="pbk-backup"/> and
<xref linkend="pbk-checkdb"/> commands use a regular
<productname>PostgreSQL</productname> connection. To avoid specifying
<link linkend="pbk-connection-opts">connection options</link>
each time on the command line, you can set them in the
<filename>pg_probackup.conf</filename> configuration file using the
<xref linkend="pbk-set-config"/> command.
</para>
<note>
<para>
It is <emphasis role="strong">not recommended</emphasis>
to edit <filename>pg_probackup.conf</filename> manually.
</para>
</note>
<para>
Initially, <filename>pg_probackup.conf</filename> contains the following settings:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<varname>PGDATA</varname> — the path to the data directory of the cluster to
back up.
</para>
</listitem>
<listitem>
<para>
<varname>system-identifier</varname> — the unique identifier of the <productname>PostgreSQL</productname>
instance.
</para>
</listitem>
</itemizedlist>
<para>
Additionally, you can define
<link linkend="pbk-remote-server-opts">remote</link>,
<link linkend="pbk-retention-opts">retention</link>,
<link linkend="pbk-logging-opts">logging</link>, and
<link linkend="pbk-compression-opts">compression</link> settings
using the <command>set-config</command> command:
</para>
<programlisting>
pg_probackup set-config -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable>
[--external-dirs=<replaceable>external_directory_path</replaceable>] [<replaceable>remote_options</replaceable>] [<replaceable>connection_options</replaceable>] [<replaceable>retention_options</replaceable>] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
To view the current settings, run the following command:
</para>
<programlisting>
pg_probackup show-config -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable>
</programlisting>
<para>
You can override the settings defined in <filename>pg_probackup.conf</filename> when
running <application>pg_probackup</application> <link linkend="pbk-commands">commands</link>
via the corresponding environment variables and/or command line
options.
</para>
</refsect2>
<refsect2 id="pbk-specifying-connection-settings">
<title>Specifying Connection Settings</title>
<para>
If you define connection settings in the <filename>pg_probackup.conf</filename>
configuration file, you can omit connection options in all the
subsequent <application>pg_probackup</application> commands. However, if the corresponding
environment variables are set, they get higher priority. The
options provided on the command line overwrite both environment
variables and configuration file settings.
</para>
<para>
If nothing is given, the default values are taken. By default
<application>pg_probackup</application> tries to use local connection via Unix domain
socket (<literal>localhost</literal> on Windows) and tries to get the database name
and the user name from the <envar>PGUSER</envar> environment variable or the
current OS user name.
</para>
</refsect2>
<refsect2 id="pbk-managing-the-backup-catalog">
<title>Managing the Backup Catalog</title>
<para>
With <application>pg_probackup</application>, you can manage backups from the command line:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<link linkend="pbk-viewing-backup-info">View backup
information</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="pbk-viewing-wal-archive-information">View WAL
Archive Information</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="pbk-validating-backups">Validate backups</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="pbk-merging-backups">Merge backups</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="pbk-deleting-backups">Delete backups</link>
</para>
</listitem>
</itemizedlist>
<refsect3 id="pbk-viewing-backup-info">
<title>Viewing Backup Information</title>
<para>
To view the list of existing backups for every instance, run
the command:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable>
</programlisting>
<para>
<application>pg_probackup</application> displays the list of all the available backups.
For example:
</para>
<programlisting>
BACKUP INSTANCE 'node'
======================================================================================================================================
Instance Version ID Recovery time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status
======================================================================================================================================
node 10 PYSUE8 2019-10-03 15:51:48+03 FULL ARCHIVE 1/0 16s 9047kB 16MB 4.31 0/12000028 0/12000160 OK
node 10 P7XDQV 2018-04-29 05:32:59+03 DELTA STREAM 1/1 11s 19MB 16MB 1.00 0/15000060 0/15000198 OK
node 10 P7XDJA 2018-04-29 05:28:36+03 PTRACK STREAM 1/1 21s 32MB 32MB 1.00 0/13000028 0/13000198 OK
node 10 P7XDHU 2018-04-29 05:27:59+03 PAGE STREAM 1/1 15s 33MB 16MB 1.00 0/11000028 0/110001D0 OK
node 10 P7XDHB 2018-04-29 05:27:15+03 FULL STREAM 1/0 11s 39MB 16MB 1.00 0/F000028 0/F000198 OK
</programlisting>
<para>
For each backup, the following information is provided:
</para>
<itemizedlist>
<listitem>
<para>
<literal>Instance</literal> — the instance name.
</para>
</listitem>
<listitem>
<para>
<literal>Version</literal> — <productname>PostgreSQL</productname> major version.
</para>
</listitem>
<listitem>
<para>
<literal>ID</literal> — the backup identifier.
</para>
</listitem>
<listitem>
<para>
<literal>Recovery time</literal> — the earliest moment for which you can
restore the state of the database cluster.
</para>
</listitem>
<listitem>
<para>
<literal>Mode</literal> — the method used to take this backup. Possible
values: <literal>FULL</literal>, <literal>PAGE</literal>, <literal>DELTA</literal>, <literal>PTRACK</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>WAL Mode</literal> — WAL delivery mode. Possible values: <literal>STREAM</literal>
and <literal>ARCHIVE</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>TLI</literal> — timeline identifiers of the current backup and its
parent.
</para>
</listitem>
<listitem>
<para>
<literal>Time</literal> — the time it took to perform the backup.
</para>
</listitem>
<listitem>
<para>
<literal>Data</literal> — the size of the data files in this backup. This
value does not include the size of WAL files. For
STREAM backups, the total size of the backup can be calculated
as <literal>Data</literal> + <literal>WAL</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>WAL</literal> — the uncompressed size of WAL files
that need to be applied during recovery for the backup to reach a consistent state.
</para>
</listitem>
<listitem>
<para>
<literal>Zratio</literal> — compression ratio calculated as
<quote>uncompressed-bytes</quote> / <quote>data-bytes</quote>.
</para>
</listitem>
<listitem>
<para>
<literal>Start LSN</literal> — WAL log sequence number corresponding to the
start of the backup process. REDO point for <productname>PostgreSQL</productname>
recovery process to start from.
</para>
</listitem>
<listitem>
<para>
<literal>Stop LSN</literal> — WAL log sequence number corresponding to the
end of the backup process. Consistency point for
<productname>PostgreSQL</productname> recovery process.
</para>
</listitem>
<listitem>
<para>
<literal>Status</literal> — backup status. Possible values:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>OK</literal> — the backup is complete and valid.
</para>
</listitem>
<listitem>
<para>
<literal>DONE</literal> — the backup is complete, but was not validated.
</para>
</listitem>
<listitem>
<para>
<literal>RUNNING</literal> — the backup is in progress.
</para>
</listitem>
<listitem>
<para>
<literal>MERGING</literal> — the backup is being merged.
</para>
</listitem>
<listitem>
<para>
<literal>MERGED</literal> — the backup data files were
successfully merged, but its metadata is in the process
of being updated. Only full backups can have this status.
</para>
</listitem>
<listitem>
<para>
<literal>DELETING</literal> — the backup files are being deleted.
</para>
</listitem>
<listitem>
<para>
<literal>CORRUPT</literal> — some of the backup files are corrupt.
</para>
</listitem>
<listitem>
<para>
<literal>ERROR</literal> — the backup was aborted because of an
unexpected error.
</para>
</listitem>
<listitem>
<para>
<literal>ORPHAN</literal> — the backup is invalid because one of its
parent backups is corrupt or missing.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
You can restore the cluster from the backup only if the backup
status is <literal>OK</literal> or <literal>DONE</literal>.
</para>
<para>
To get more detailed information about the backup, run the
<command>show</command> command with the backup ID:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
</programlisting>
<para>
The sample output is as follows:
</para>
<programlisting>
#Configuration
backup-mode = FULL
stream = false
compress-alg = zlib
compress-level = 1
from-replica = false
#Compatibility
block-size = 8192
wal-block-size = 8192
checksum-version = 1
program-version = 2.1.3
server-version = 10
#Result backup info
timelineid = 1
start-lsn = 0/04000028
stop-lsn = 0/040000f8
start-time = '2017-05-16 12:57:29'
end-time = '2017-05-16 12:57:31'
recovery-xid = 597
recovery-time = '2017-05-16 12:57:31'
expire-time = '2020-05-16 12:57:31'
data-bytes = 22288792
wal-bytes = 16777216
uncompressed-bytes = 39961833
pgdata-bytes = 39859393
status = OK
parent-backup-id = 'PT8XFX'
primary_conninfo = 'user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmode=disable sslcompression=1 target_session_attrs=any'
</programlisting>
<para>
Detailed output has additional attributes:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>compress-alg</literal> — compression algorithm used during backup. Possible values:
<literal>zlib</literal>, <literal>pglz</literal>, <literal>none</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>compress-level</literal> — compression level used during backup.
</para>
</listitem>
<listitem>
<para>
<literal>from-replica</literal> — was this backup taken on standby? Possible values:
<literal>1</literal>, <literal>0</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>block-size</literal> — the <ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-preset.html#GUC-BLOCK-SIZE">block_size</ulink>
setting of <productname>PostgreSQL</productname> cluster at the backup start.
</para>
</listitem>
<listitem>
<para>
<literal>checksum-version</literal> — are
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-preset.html#GUC-DATA-CHECKSUMS">data
block checksums</ulink> enabled in the backed up <productname>PostgreSQL</productname> cluster? Possible values: <literal>1</literal>, <literal>0</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>program-version</literal> — full version of <application>pg_probackup</application> binary used to create the backup.
</para>
</listitem>
<listitem>
<para>
<literal>start-time</literal> — the backup start time.
</para>
</listitem>
<listitem>
<para>
<literal>end-time</literal> — the backup end time.
</para>
</listitem>
<listitem>
<para>
<literal>expire-time</literal> — the point in time
when a pinned backup can be removed in accordance with retention
policy. This attribute is only available for pinned backups.
</para>
</listitem>
<listitem>
<para>
<literal>uncompressed-bytes</literal> — the size of data files before adding page headers and applying
compression. You can evaluate the effectiveness of compression
by comparing <literal>uncompressed-bytes</literal> to <literal>data-bytes</literal> if
compression if used.
</para>
</listitem>
<listitem>
<para>
<literal>pgdata-bytes</literal> — the size of <productname>PostgreSQL</productname>
cluster data files at the time of backup. You can evaluate the
effectiveness of an incremental backup by comparing
<literal>pgdata-bytes</literal> to <literal>uncompressed-bytes</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>recovery-xid</literal> — transaction ID at the backup end time.
</para>
</listitem>
<listitem>
<para>
<literal>parent-backup-id</literal> — ID of the parent backup. Available only
for incremental backups.
</para>
</listitem>
<listitem>
<para>
<literal>primary_conninfo</literal> — <application>libpq</application> connection parameters
used to connect to the <productname>PostgreSQL</productname> cluster to take this backup. The
password is not included.
</para>
</listitem>
<listitem>
<para>
<literal>note</literal> — text note attached to backup.
</para>
</listitem>
<listitem>
<para>
<literal>content-crc</literal> — CRC32 checksum of <literal>backup_content.control</literal> file.
It is used to detect corruption of backup metainformation.
</para>
</listitem>
</itemizedlist>
</para>
<para>
You can also get the detailed information about the backup
in the <acronym>JSON</acronym> format:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --format=json -i backup_id
</programlisting>
<para>
The sample output is as follows:
</para>
<programlisting>
[
{
"instance": "node",
"backups": [
{
"id": "PT91HZ",
"parent-backup-id": "PT8XFX",
"backup-mode": "DELTA",
"wal": "ARCHIVE",
"compress-alg": "zlib",
"compress-level": 1,
"from-replica": false,
"block-size": 8192,
"xlog-block-size": 8192,
"checksum-version": 1,
"program-version": "2.1.3",
"server-version": "10",
"current-tli": 16,
"parent-tli": 2,
"start-lsn": "0/8000028",
"stop-lsn": "0/8000160",
"start-time": "2019-06-17 18:25:11+03",
"end-time": "2019-06-17 18:25:16+03",
"recovery-xid": 0,
"recovery-time": "2019-06-17 18:25:15+03",
"data-bytes": 106733,
"wal-bytes": 16777216,
"primary_conninfo": "user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmode=disable sslcompression=1 target_session_attrs=any",
"status": "OK"
}
]
}
]
</programlisting>
</refsect3>
<refsect3 id="pbk-viewing-wal-archive-information">
<title>Viewing WAL Archive Information</title>
<para>
To view the information about WAL archive for every instance,
run the command:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> [--instance <replaceable>instance_name</replaceable>] --archive
</programlisting>
<para>
<application>pg_probackup</application> displays the list of all the available WAL files
grouped by timelines. For example:
</para>
<programlisting>
ARCHIVE INSTANCE 'node'
===================================================================================================================================
TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status
===================================================================================================================================
5 1 0/B000000 00000005000000000000000B 00000005000000000000000C 2 685kB 48.00 0 OK
4 3 0/18000000 000000040000000000000018 00000004000000000000001A 3 648kB 77.00 0 OK
3 2 0/15000000 000000030000000000000015 000000030000000000000017 3 648kB 77.00 0 OK
2 1 0/B000108 00000002000000000000000B 000000020000000000000015 5 892kB 94.00 1 DEGRADED
1 0 0/0 000000010000000000000001 00000001000000000000000A 10 8774kB 19.00 1 OK
</programlisting>
<para>
For each timeline, the following information is provided:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>TLI</literal> — timeline identifier.
</para>
</listitem>
<listitem>
<para>
<literal>Parent TLI</literal> — identifier of the timeline from which this timeline branched off.
</para>
</listitem>
<listitem>
<para>
<literal>Switchpoint</literal> — LSN of the moment when the timeline branched
off from its parent timeline.
</para>
</listitem>
<listitem>
<para>
<literal>Min Segno</literal> — the first WAL segment
belonging to the timeline.
</para>
</listitem>
<listitem>
<para>
<literal>Max Segno</literal> — the last WAL segment
belonging to the timeline.
</para>
</listitem>
<listitem>
<para>
<literal>N segments</literal> — number of WAL segments belonging to the
timeline.
</para>
</listitem>
<listitem>
<para>
<literal>Size</literal> — the size that files take on disk.
</para>
</listitem>
<listitem>
<para>
<literal>Zratio</literal> — compression ratio calculated as <literal>N segments</literal> *
<parameter>wal_segment_size</parameter> * <parameter>wal_block_size</parameter> / <literal>Size</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>N backups</literal> — number of backups belonging to the timeline.
To get the details about backups, use the <acronym>JSON</acronym> format.
</para>
</listitem>
<listitem>
<para>
<literal>Status</literal> — status of the WAL archive for this timeline. Possible
values:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>OK</literal> — all WAL segments between <literal>Min Segno</literal>
and <literal>Max Segno</literal> are present.
</para>
</listitem>
<listitem>
<para>
<literal>DEGRADED</literal> — some WAL segments between <literal>Min Segno</literal>
and <literal>Max Segno</literal> are missing. To find out which files are lost,
view this report in the <acronym>JSON</acronym> format.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
To get more detailed information about the WAL archive in the <acronym>JSON</acronym>
format, run the command:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> [--instance <replaceable>instance_name</replaceable>] --archive --format=json
</programlisting>
<para>
The sample output is as follows:
</para>
<programlisting>
[
{
"instance": "replica",
"timelines": [
{
"tli": 5,
"parent-tli": 1,
"switchpoint": "0/B000000",
"min-segno": "00000005000000000000000B",
"max-segno": "00000005000000000000000C",
"n-segments": 2,
"size": 685320,
"zratio": 48.00,
"closest-backup-id": "PXS92O",
"status": "OK",
"lost-segments": [],
"backups": []
},
{
"tli": 4,
"parent-tli": 3,
"switchpoint": "0/18000000",
"min-segno": "000000040000000000000018",
"max-segno": "00000004000000000000001A",
"n-segments": 3,
"size": 648625,
"zratio": 77.00,
"closest-backup-id": "PXS9CE",
"status": "OK",
"lost-segments": [],
"backups": []
},
{
"tli": 3,
"parent-tli": 2,
"switchpoint": "0/15000000",
"min-segno": "000000030000000000000015",
"max-segno": "000000030000000000000017",
"n-segments": 3,
"size": 648911,
"zratio": 77.00,
"closest-backup-id": "PXS9CE",
"status": "OK",
"lost-segments": [],
"backups": []
},
{
"tli": 2,
"parent-tli": 1,
"switchpoint": "0/B000108",
"min-segno": "00000002000000000000000B",
"max-segno": "000000020000000000000015",
"n-segments": 5,
"size": 892173,
"zratio": 94.00,
"closest-backup-id": "PXS92O",
"status": "DEGRADED",
"lost-segments": [
{
"begin-segno": "00000002000000000000000D",
"end-segno": "00000002000000000000000E"
},
{
"begin-segno": "000000020000000000000010",
"end-segno": "000000020000000000000012"
}
],
"backups": [
{
"id": "PXS9CE",
"backup-mode": "FULL",
"wal": "ARCHIVE",
"compress-alg": "none",
"compress-level": 1,
"from-replica": "false",
"block-size": 8192,
"xlog-block-size": 8192,
"checksum-version": 1,
"program-version": "2.1.5",
"server-version": "10",
"current-tli": 2,
"parent-tli": 0,
"start-lsn": "0/C000028",
"stop-lsn": "0/C000160",
"start-time": "2019-09-13 21:43:26+03",
"end-time": "2019-09-13 21:43:30+03",
"recovery-xid": 0,
"recovery-time": "2019-09-13 21:43:29+03",
"data-bytes": 104674852,
"wal-bytes": 16777216,
"primary_conninfo": "user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmode=disable sslcompression=1 target_session_attrs=any",
"status": "OK"
}
]
},
{
"tli": 1,
"parent-tli": 0,
"switchpoint": "0/0",
"min-segno": "000000010000000000000001",
"max-segno": "00000001000000000000000A",
"n-segments": 10,
"size": 8774805,
"zratio": 19.00,
"closest-backup-id": "",
"status": "OK",
"lost-segments": [],
"backups": [
{
"id": "PXS92O",
"backup-mode": "FULL",
"wal": "ARCHIVE",
"compress-alg": "none",
"compress-level": 1,
"from-replica": "true",
"block-size": 8192,
"xlog-block-size": 8192,
"checksum-version": 1,
"program-version": "2.1.5",
"server-version": "10",
"current-tli": 1,
"parent-tli": 0,
"start-lsn": "0/4000028",
"stop-lsn": "0/6000028",
"start-time": "2019-09-13 21:37:36+03",
"end-time": "2019-09-13 21:38:45+03",
"recovery-xid": 0,
"recovery-time": "2019-09-13 21:37:30+03",
"data-bytes": 25987319,
"wal-bytes": 50331648,
"primary_conninfo": "user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmode=disable sslcompression=1 target_session_attrs=any",
"status": "OK"
}
]
}
]
},
{
"instance": "master",
"timelines": [
{
"tli": 1,
"parent-tli": 0,
"switchpoint": "0/0",
"min-segno": "000000010000000000000001",
"max-segno": "00000001000000000000000B",
"n-segments": 11,
"size": 8860892,
"zratio": 20.00,
"status": "OK",
"lost-segments": [],
"backups": [
{
"id": "PXS92H",
"parent-backup-id": "PXS92C",
"backup-mode": "PAGE",
"wal": "ARCHIVE",
"compress-alg": "none",
"compress-level": 1,
"from-replica": "false",
"block-size": 8192,
"xlog-block-size": 8192,
"checksum-version": 1,
"program-version": "2.1.5",
"server-version": "10",
"current-tli": 1,
"parent-tli": 1,
"start-lsn": "0/4000028",
"stop-lsn": "0/50000B8",
"start-time": "2019-09-13 21:37:29+03",
"end-time": "2019-09-13 21:37:31+03",
"recovery-xid": 0,
"recovery-time": "2019-09-13 21:37:30+03",
"data-bytes": 1328461,
"wal-bytes": 33554432,
"primary_conninfo": "user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmode=disable sslcompression=1 target_session_attrs=any",
"status": "OK"
},
{
"id": "PXS92C",
"backup-mode": "FULL",
"wal": "ARCHIVE",
"compress-alg": "none",
"compress-level": 1,
"from-replica": "false",
"block-size": 8192,
"xlog-block-size": 8192,
"checksum-version": 1,
"program-version": "2.1.5",
"server-version": "10",
"current-tli": 1,
"parent-tli": 0,
"start-lsn": "0/2000028",
"stop-lsn": "0/2000160",
"start-time": "2019-09-13 21:37:24+03",
"end-time": "2019-09-13 21:37:29+03",
"recovery-xid": 0,
"recovery-time": "2019-09-13 21:37:28+03",
"data-bytes": 24871902,
"wal-bytes": 16777216,
"primary_conninfo": "user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmode=disable sslcompression=1 target_session_attrs=any",
"status": "OK"
}
]
}
]
}
]
</programlisting>
<para>
Most fields are consistent with the plain format, with some
exceptions:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
The size is in bytes.
</para>
</listitem>
<listitem>
<para>
The <structfield>closest-backup-id</structfield> attribute
contains the ID of the most recent valid backup that belongs to
one of the previous timelines. You can use this backup to perform
point-in-time recovery to this timeline. If
such a backup does not exist, this string is empty.
</para>
</listitem>
<listitem>
<para>
The <structfield>lost-segments</structfield> array provides with
information about intervals of missing segments in <literal>DEGRADED</literal> timelines. In <literal>OK</literal>
timelines, the <structfield>lost-segments</structfield> array is empty.
</para>
</listitem>
<listitem>
<para>
The <structfield>backups</structfield> array lists all backups
belonging to the timeline. If the timeline has no backups, this array is empty.
</para>
</listitem>
</itemizedlist>
</refsect3>
</refsect2>
<refsect2 id="pbk-configuring-retention-policy">
<title>Configuring Retention Policy</title>
<para>
With <application>pg_probackup</application>, you can configure
retention policy to remove redundant backups, clean up unneeded
WAL files, as well as pin specific backups to ensure they are
kept for the specified time, as explained in the sections below.
All these actions can be combined together in any way.
</para>
<refsect3 id="pbk-retention-policy">
<title>Removing Redundant Backups</title>
<para>
By default, all backup copies created with <application>pg_probackup</application> are
stored in the specified backup catalog. To save disk space,
you can configure retention policy to remove redundant backup copies.
</para>
<para>
To configure retention policy, set one or more of the
following variables in the <filename>pg_probackup.conf</filename> file via
<xref linkend="pbk-set-config"/>:
</para>
<programlisting>
--retention-redundancy=<replaceable>redundancy</replaceable>
</programlisting>
<para>
Specifies <emphasis role="strong">the number of full backup
copies</emphasis> to keep in the backup catalog.
</para>
<programlisting>
--retention-window=<replaceable>window</replaceable>
</programlisting>
<para>
Defines the earliest point in time for which <application>pg_probackup</application> can
complete the recovery. This option is set in
<emphasis role="strong">the number of days</emphasis> from the
current moment. For example, if
<literal>retention-window=7</literal>, <application>pg_probackup</application> must
keep at least one backup copy that is older than seven days, with
all the corresponding WAL files, and all the backups that follow.
</para>
<para>
If both <option>--retention-redundancy</option> and
<option>--retention-window</option> options are set, both these
conditions have to be taken into account when purging the backup
catalog. For example, if you set <literal>--retention-redundancy=2</literal>
and <literal>--retention-window=7</literal>,
<application>pg_probackup</application> has to keep two full backup
copies, as well as all the backups required to ensure recoverability
for the last seven days:
</para>
<programlisting>
pg_probackup set-config -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --retention-redundancy=2 --retention-window=7
</programlisting>
<para>
To clean up the backup catalog in accordance with retention policy,
you have to run the <xref linkend="pbk-delete"/> command with
<link linkend="pbk-retention-opts">retention flags</link>, as shown
below, or use the <xref linkend="pbk-backup"/> command with
these flags to process the outdated backup copies right when the new
backup is created.
</para>
<para>
For example, to remove all backup copies that no longer satisfy the
defined retention policy, run the following command with the
<literal>--delete-expired</literal> flag:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired
</programlisting>
<para>
If you would like to also remove the WAL files that are no
longer required for any of the backups, you should also specify the
<option>--delete-wal</option> flag:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired --delete-wal
</programlisting>
<para>
You can also set or override the current retention policy by
specifying <option>--retention-redundancy</option> and
<option>--retention-window</option> options directly when
running <command>delete</command> or <command>backup</command>
commands:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired --retention-window=7 --retention-redundancy=2
</programlisting>
<para>
Since incremental backups require that their parent full
backup and all the preceding incremental backups are
available, if any of such backups expire, they still cannot be
removed while at least one incremental backup in this chain
satisfies the retention policy. To avoid keeping expired
backups that are still required to restore an active
incremental one, you can merge them with this backup using the
<option>--merge-expired</option> flag when running
<xref linkend="pbk-backup"/> or
<xref linkend="pbk-delete"/> commands.
</para>
<para>
Suppose you have backed up the <replaceable>node</replaceable>
instance in the <replaceable>backup_dir</replaceable> directory,
with the <option>--retention-window</option> option set
to <literal>7</literal>, and you have the following backups
available on April 10, 2019:
</para>
<programlisting>
BACKUP INSTANCE 'node'
===================================================================================================================================
Instance Version ID Recovery time Mode WAL TLI Time Data WAL Zratio Start LSN Stop LSN Status
===================================================================================================================================
node 10 P7XDHR 2019-04-10 05:27:15+03 FULL STREAM 1/0 11s 200MB 16MB 1.0 0/18000059 0/18000197 OK
node 10 P7XDQV 2019-04-08 05:32:59+03 PAGE STREAM 1/0 11s 19MB 16MB 1.0 0/15000060 0/15000198 OK
node 10 P7XDJA 2019-04-03 05:28:36+03 DELTA STREAM 1/0 21s 32MB 16MB 1.0 0/13000028 0/13000198 OK
-------------------------------------------------------retention window--------------------------------------------------------
node 10 P7XDHU 2019-04-02 05:27:59+03 PAGE STREAM 1/0 31s 33MB 16MB 1.0 0/11000028 0/110001D0 OK
node 10 P7XDHB 2019-04-01 05:27:15+03 FULL STREAM 1/0 11s 200MB 16MB 1.0 0/F000028 0/F000198 OK
node 10 P7XDFT 2019-03-29 05:26:25+03 FULL STREAM 1/0 11s 200MB 16MB 1.0 0/D000028 0/D000198 OK
</programlisting>
<para>
Even though <literal>P7XDHB</literal> and <literal>P7XDHU</literal> backups are outside the
retention window, they cannot be removed as it invalidates the
succeeding incremental backups <literal>P7XDJA</literal> and <literal>P7XDQV</literal> that are
still required, so, if you run the
<xref linkend="pbk-delete"/> command with the
<option>--delete-expired</option> flag, only the <literal>P7XDFT</literal> full
backup will be removed.
</para>
<para>
With the <option>--merge-expired</option> option, the <literal>P7XDJA</literal>
backup is merged with the underlying <literal>P7XDHU</literal> and <literal>P7XDHB</literal> backups
and becomes a full one, so there is no need to keep these
expired backups anymore:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>node</replaceable> --delete-expired --merge-expired
pg_probackup show -B <replaceable>backup_dir</replaceable>
</programlisting>
<programlisting>
BACKUP INSTANCE 'node'
==================================================================================================================================
Instance Version ID Recovery time Mode WAL TLI Time Data WAL Zratio Start LSN Stop LSN Status
==================================================================================================================================
node 10 P7XDHR 2019-04-10 05:27:15+03 FULL STREAM 1/0 11s 200MB 16MB 1.0 0/18000059 0/18000197 OK
node 10 P7XDQV 2019-04-08 05:32:59+03 PAGE STREAM 1/0 11s 19MB 16MB 1.0 0/15000060 0/15000198 OK
node 10 P7XDJA 2019-04-03 05:28:36+03 FULL STREAM 1/0 21s 32MB 16MB 1.0 0/13000028 0/13000198 OK
</programlisting>
<para>
The <literal>Time</literal> field for the merged backup displays the time
required for the merge.
</para>
</refsect3>
<refsect3 id="pbk-backup-pinning">
<title>Pinning Backups</title>
<para>
If you need to keep certain backups longer than the
established retention policy allows, you can pin them
for arbitrary time. For example:
</para>
<programlisting>
pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable> --ttl=30d
</programlisting>
<para>
This command sets the expiration time of the
specified backup to 30 days starting from the time
indicated in its <literal>recovery-time</literal> attribute.
</para>
<para>
You can also explicitly set the expiration time for a backup
using the <option>--expire-time</option> option. For example:
</para>
<programlisting>
pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable> --expire-time="2020-01-01 00:00:00+03"
</programlisting>
<para>
Alternatively, you can use the <option>--ttl</option> and
<option>--expire-time</option> options with the
<xref linkend="pbk-backup"/> command to pin the newly
created backup:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL --ttl=30d
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -b FULL --expire-time="2020-01-01 00:00:00+03"
</programlisting>
<para>
To check if the backup is pinned,
run the <xref linkend="pbk-show"/> command:
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
</programlisting>
</para>
<para>
If the backup is pinned, it has the <literal>expire-time</literal>
attribute that displays its expiration time:
<programlisting>
...
recovery-time = '2017-05-16 12:57:31'
expire-time = '2020-01-01 00:00:00+03'
data-bytes = 22288792
...
</programlisting>
</para>
<para>
You can unpin the backup by setting the <option>--ttl</option> option to zero:
</para>
<programlisting>
pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable> --ttl=0
</programlisting>
<note>
<para>
A pinned incremental backup implicitly pins all
its parent backups. If you unpin such a backup later,
its implicitly pinned parents will also be automatically unpinned.
</para>
</note>
</refsect3>
<refsect3 id="pbk-wal-archive-retention-policy">
<title>Configuring WAL Archive Retention Policy</title>
<para>
When <link linkend="pbk-setting-up-continuous-wal-archiving">continuous
WAL archiving</link> is enabled, archived WAL segments can take a lot
of disk space. Even if you delete old backup copies from time to time,
the <literal>--delete-wal</literal> flag can
purge only those WAL segments that do not apply to any of the
remaining backups in the backup catalog. However, if point-in-time
recovery is critical only for the most recent backups, you can
configure WAL archive retention policy to keep WAL archive of
limited depth and win back some more disk space.
</para>
<para>
To configure WAL archive retention policy, you have to run the
<xref linkend="pbk-set-config"/> command with the
<literal>--wal-depth</literal> option that specifies the number
of backups that can be used for PITR.
This setting applies to all the timelines, so you should be able to perform
PITR for the same number of backups on each timeline, if available.
<link linkend="pbk-backup-pinning">Pinned backups</link> are
not included into this count: if one of the latest backups
is pinned, <application>pg_probackup</application> ensures that
PITR is possible for one extra backup.
</para>
<para>
To remove WAL segments that do not satisfy the defined WAL archive
retention policy, you simply have to run the <xref linkend="pbk-delete"/>
or <xref linkend="pbk-backup"/> command with the <literal>--delete-wal</literal>
flag. For archive backups, WAL segments between <literal>Start LSN</literal>
and <literal>Stop LSN</literal> are always kept intact, so such backups
remain valid regardless of the <literal>--wal-depth</literal> setting
and can still be restored, if required.
</para>
<para>
You can also use the <option>--wal-depth</option> option
with the <xref linkend="pbk-delete"/> and <xref linkend="pbk-backup"/>
commands to override the previously defined WAL archive retention
policy and purge old WAL segments on the fly.
</para>
<para>
Suppose you have backed up the <literal>node</literal>
instance in the <replaceable>backup_dir</replaceable> directory and
configured
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous WAL
archiving</link>:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> --instance <replaceable>node</replaceable>
</programlisting>
<programlisting>
BACKUP INSTANCE 'node'
====================================================================================================================================
Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status
====================================================================================================================================
node 11 PZ9442 2019-10-12 10:43:21+03 DELTA STREAM 1/0 10s 121kB 16MB 1.00 0/46000028 0/46000160 OK
node 11 PZ943L 2019-10-12 10:43:04+03 FULL STREAM 1/0 10s 180MB 32MB 1.00 0/44000028 0/44000160 OK
node 11 PZ7YR5 2019-10-11 19:49:56+03 DELTA STREAM 1/1 10s 112kB 32MB 1.00 0/41000028 0/41000160 OK
node 11 PZ7YMP 2019-10-11 19:47:16+03 DELTA STREAM 1/1 10s 376kB 32MB 1.00 0/3E000028 0/3F0000B8 OK
node 11 PZ7YK2 2019-10-11 19:45:45+03 FULL STREAM 1/0 11s 180MB 16MB 1.00 0/3C000028 0/3C000198 OK
node 11 PZ7YFO 2019-10-11 19:43:04+03 FULL STREAM 1/0 10s 30MB 16MB 1.00 0/2000028 0/200ADD8 OK
</programlisting>
<para>
You can check the state of the WAL archive by running the
<xref linkend="pbk-show"/> command with the
<option>--archive</option> flag:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> --instance node --archive
</programlisting>
<programlisting>
ARCHIVE INSTANCE 'node'
===============================================================================================================================
TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status
===============================================================================================================================
1 0 0/0 000000010000000000000001 000000010000000000000047 71 36MB 31.00 6 OK
</programlisting>
<para>
WAL purge without <option>--wal-depth</option> cannot
achieve much, only one segment is removed:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance node --delete-wal
</programlisting>
<programlisting>
ARCHIVE INSTANCE 'node'
===============================================================================================================================
TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status
===============================================================================================================================
1 0 0/0 000000010000000000000002 000000010000000000000047 70 34MB 32.00 6 OK
</programlisting>
<para>
If you would like, for example, to keep only those WAL
segments that can be applied to the latest valid backup, set the
<option>--wal-depth</option> option to 1:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance node --delete-wal --wal-depth=1
</programlisting>
<programlisting>
ARCHIVE INSTANCE 'node'
================================================================================================================================
TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status
================================================================================================================================
1 0 0/0 000000010000000000000046 000000010000000000000047 2 143kB 228.00 6 OK
</programlisting>
<para>
Alternatively, you can use the <option>--wal-depth</option>
option with the <xref linkend="pbk-backup"/> command:
</para>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> --instance node -b DELTA --wal-depth=1 --delete-wal
</programlisting>
<programlisting>
ARCHIVE INSTANCE 'node'
===============================================================================================================================
TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status
===============================================================================================================================
1 0 0/0 000000010000000000000048 000000010000000000000049 1 72kB 228.00 7 OK
</programlisting>
</refsect3>
</refsect2>
<refsect2 id="pbk-merging-backups">
<title>Merging Backups</title>
<para>
As you take more and more incremental backups, the total size of
the backup catalog can substantially grow. To save disk space,
you can merge incremental backups to their parent full backup by
running the <command>merge</command> command, specifying the backup ID of the most
recent incremental backup you would like to merge:
</para>
<programlisting>
pg_probackup merge -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
</programlisting>
<para>
This command merges backups that belong to a common incremental backup
chain. If you specify a full backup, it will be merged with its first
incremental backup. If you specify an incremental backup, it will be
merged to its parent full backup, together with all incremental backups
between them. Once the merge is complete, the full backup takes in all
the merged data, and the incremental backups are removed as redundant.
Thus, the merge operation is virtually equivalent to retaking a full
backup and removing all the outdated backups, but it allows to save much
time, especially for large data volumes, as well as I/O and network
traffic if you are using <application>pg_probackup</application> in the
<link linkend="pbk-remote-backup">remote</link> mode.
</para>
<para>
Before the merge, <application>pg_probackup</application> validates all the affected
backups to ensure that they are valid. You can check the current
backup status by running the <xref linkend="pbk-show"/>
command with the backup ID:
</para>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
</programlisting>
<para>
If the merge is still in progress, the backup status is
displayed as <literal>MERGING</literal>. For full backups,
it can also be shown as <literal>MERGED</literal> while the
metadata is being updated at the final stage of the merge.
The merge is idempotent, so you can
restart the merge if it was interrupted.
</para>
</refsect2>
<refsect2 id="pbk-deleting-backups">
<title>Deleting Backups</title>
<para>
To delete a backup that is no longer required, run the following
command:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
</programlisting>
<para>
This command will delete the backup with the specified
<replaceable>backup_id</replaceable>, together with all the
incremental backups that descend from
<replaceable>backup_id</replaceable>, if any. This way you can delete
some recent incremental backups, retaining the underlying full
backup and some of the incremental backups that follow it.
</para>
<para>
To delete obsolete WAL files that are not necessary to restore
any of the remaining backups, use the
<option>--delete-wal</option> flag:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-wal
</programlisting>
<para>
To delete backups that are expired according to the current
retention policy, use the <option>--delete-expired</option>
flag:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired
</programlisting>
<para>
Expired backups cannot be removed while at least one
incremental backup that satisfies the retention policy is based
on them. If you would like to minimize the number of backups
still required to keep incremental backups valid, specify the
<option>--merge-expired</option> flag when running this
command:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired --merge-expired
</programlisting>
<para>
In this case, <application>pg_probackup</application> searches for the oldest incremental
backup that satisfies the retention policy and merges this
backup with the underlying full and incremental backups that
have already expired, thus making it a full backup. Once the
merge is complete, the remaining expired backups are deleted.
</para>
<para>
Before merging or deleting backups, you can run the
<command>delete</command> command with the
<option>--dry-run</option> flag, which displays the status of
all the available backups according to the current retention
policy, without performing any irreversible actions.
</para>
<para>
To delete all backups with specific status, use the <option>--status</option>:
</para>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --status=ERROR
</programlisting>
<para>
Deleting backups by status ignores established retention policies.
</para>
</refsect2>
<refsect2 id="pbk-creating-backup-to-catchup">
<title>Cloning and Synchronizing <productname>PostgreSQL</productname> Instance</title>
<para>
<application>pg_probackup</application> can create a copy of a <productname>PostgreSQL</productname>
instance directly, without using the backup catalog. To do this, you can run the <xref linkend="pbk-catchup"/> command.
It can be useful in the following cases:
<itemizedlist>
<listitem>
<para>To add a new standby server.</para>
<para>Usually, <ulink url="https://postgrespro.com/docs/postgresql/current/app-pgbasebackup">pg_basebackup</ulink>
is used to create a copy of a <productname>PostgreSQL</productname> instance. If the data directory of the destination instance
is empty, the <command>catchup</command> command works similarly, but it can be faster if run in parallel mode.</para>
</listitem>
<listitem>
<para>To have a fallen-behind standby server <quote>catch up</quote> with master.</para>
<para>Under write-intensive load, replicas may fail to replay WAL fast enough to keep up with master and hence may lag behind.
A usual solution to create a new replica and switch to it requires a lot of extra space and data transfer. The <command>catchup</command>
command allows you to update an existing replica much faster by bringing differences from master.</para>
</listitem>
</itemizedlist>
</para>
<para>
<command>catchup</command> is different from other <application>pg_probackup</application>
operations:
<itemizedlist>
<listitem>
<para>
The backup catalog is not required.
</para>
</listitem>
<listitem>
<para>
STREAM WAL delivery mode is only supported.
</para>
</listitem>
<listitem>
<para>
Copying external directories
is not supported.
</para>
</listitem>
<listitem>
<para>
DDL commands
<ulink url="https://postgrespro.com/docs/postgresql/current/sql-createtablespace"
><command>CREATE TABLESPACE</command></ulink
>/<ulink url="https://postgrespro.com/docs/postgresql/current/sql-droptablespace"
><command>DROP TABLESPACE</command></ulink>
cannot be run simultaneously with <command>catchup</command>.
</para>
</listitem>
<listitem>
<para>
<command>catchup</command> takes configuration files, such as
<filename>postgresql.conf</filename>, <filename>postgresql.auto.conf</filename>,
or <filename>pg_hba.conf</filename>, from the source server and overwrites them
on the target server. The <option>--exclude-path</option> option allows you to keep
the configuration files intact.
</para>
</listitem>
</itemizedlist>
</para>
<para>
To prepare for cloning/synchronizing a <productname>PostgreSQL</productname> instance,
set up the source instance server as follows:
<itemizedlist>
<listitem>
<para>
<link linkend="pbk-configuring-the-database-cluster">Configure
the database cluster</link> for the instance to copy.
</para>
</listitem>
<listitem>
<para>
To copy from a remote server, <link linkend="pbk-configuring-the-remote-mode">configure the remote mode</link>.
</para>
</listitem>
<listitem>
<para>
To use the PTRACK catchup mode, <link linkend="pbk-setting-up-ptrack-backups">set up PTRACK backups</link>.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Before cloning/synchronizing a <productname>PostgreSQL</productname> instance, ensure that the source
instance server is running and accepting connections. To clone/sync a <productname>PostgreSQL</productname> instance,
on the server with the destination instance, you can run
the <xref linkend="pbk-catchup"/> command as follows:
</para>
<programlisting>
pg_probackup catchup -b <replaceable>catchup_mode</replaceable> --source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable> --destination-pgdata=<replaceable>path_to_local_dir</replaceable> --stream [<replaceable>connection_options</replaceable>] [<replaceable>remote_options</replaceable>]
</programlisting>
<para>
Where <replaceable>catchup_mode</replaceable> can take one of the
following values:
</para>
<itemizedlist spacing="compact">
<listitem>
<para id="pbk-catchup-modes-full">
<literal>FULL</literal> — creates a full copy of the <productname>PostgreSQL</productname> instance.
The data directory of the destination instance must be empty for this mode.
</para>
</listitem>
<listitem>
<para id="pbk-catchup-modes-delta">
<literal>DELTA</literal> — reads all data files in the data directory and
creates an incremental copy for pages that have changed
since the destination instance was shut down.
</para>
</listitem>
<listitem>
<para id="pbk-catchup-modes-ptrack">
<literal>PTRACK</literal> — tracking page changes on the fly,
only reads and copies pages that have changed since the point of divergence
of the source and destination instances.
<warning>
<para>
PTRACK catchup mode requires <application>PTRACK</application>
not earlier than 2.0 and hence, <productname>PostgreSQL</productname> not earlier than 11.
</para>
</warning>
</para>
</listitem>
</itemizedlist>
<para>
By specifying the <option>--stream</option> option, you can set
<link linkend="pbk-stream-mode">STREAM</link> WAL delivery mode
of copying, which will include all the necessary WAL files by streaming them from
the instance server via replication protocol.
</para>
<para>
You can use <link linkend="pbk-connection-opts">connection_options</link> to specify
the connection to the source database cluster. If it is located on a different server,
also specify <link linkend="pbk-remote-server-opts">remote_options</link>.
</para>
<para>
If the source database cluster contains tablespaces that must be located in
a different directory, additionally specify the <option>--tablespace-mapping</option>
option:
<programlisting>
pg_probackup catchup -b <replaceable>catchup_mode</replaceable> --source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable> --destination-pgdata=<replaceable>path_to_local_dir</replaceable> --stream --tablespace-mapping=<replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable>
</programlisting>
To run the <command>catchup</command> command on parallel threads, specify the number
of threads with the <option>--threads</option> option:
<programlisting>
pg_probackup catchup -b <replaceable>catchup_mode</replaceable> --source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable> --destination-pgdata=<replaceable>path_to_local_dir</replaceable> --stream --threads=<replaceable>num_threads</replaceable>
</programlisting>
</para>
<para>
Before cloning/synchronising a <productname>PostgreSQL</productname> instance, you can run the
<command>catchup</command> command with the <option>--dry-run</option> flag
to estimate the size of data files to be transferred, but make no changes on disk:
<programlisting>
pg_probackup catchup -b <replaceable>catchup_mode</replaceable> --source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable> --destination-pgdata=<replaceable>path_to_local_dir</replaceable> --stream --dry-run
</programlisting>
</para>
<para>
For example, assume that a remote standby server with the <productname>PostgreSQL</productname> instance having <filename>/replica-pgdata</filename> data directory has fallen behind. To sync this instance with the one in <filename>/master-pgdata</filename> data directory, you can run
the <command>catchup</command> command in the <literal>PTRACK</literal> mode on four parallel threads as follows:
<programlisting>
pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=PTRACK --remote-host=remote-hostname --remote-user=remote-unix-username -j 4 --exclude-path=postgresql.conf --exclude-path=postgresql.auto.conf --exclude-path=pg_hba.conf --exclude-path=pg_ident.conf
</programlisting>
Note that in this example, the configuration files will not be overwritten during synchronization.
</para>
<para>
Another example shows how you can add a new remote standby server with the <productname>PostgreSQL</productname> data directory <filename>/replica-pgdata</filename> by running the <command>catchup</command> command in the <literal>FULL</literal> mode
on four parallel threads:
<programlisting>
pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=FULL --remote-host=remote-hostname --remote-user=remote-unix-username -j 4
</programlisting>
</para>
</refsect2>
</refsect1>
<refsect1 id="pbk-reference">
<title>Command-Line Reference</title>
<refsect2 id="pbk-commands">
<title>Commands</title>
<para>
This section describes <application>pg_probackup</application> commands.
Optional parameters are enclosed in square brackets. For detailed
parameter descriptions, see the section <link linkend="pbk-options">Options</link>.
</para>
<refsect3 id="pbk-version" xreflabel="version">
<title>version</title>
<programlisting>
pg_probackup version
</programlisting>
<para>
Prints <application>pg_probackup</application> version.
</para>
</refsect3>
<refsect3 id="pbk-help" xreflabel="help">
<title>help</title>
<programlisting>
pg_probackup help [<replaceable>command</replaceable>]
</programlisting>
<para>
Displays the synopsis of <application>pg_probackup</application> commands. If one of the
<application>pg_probackup</application> commands is specified, shows detailed information
about the options that can be used with this command.
</para>
</refsect3>
<refsect3 id="pbk-init" xreflabel="init">
<title>init</title>
<programlisting>
pg_probackup init -B <replaceable>backup_dir</replaceable> [--help]
</programlisting>
<para>
Initializes the backup catalog in
<replaceable>backup_dir</replaceable> that will store backup copies,
WAL archive, and meta information for the backed up database
clusters. If the specified <replaceable>backup_dir</replaceable>
already exists, it must be empty. Otherwise, <application>pg_probackup</application>
displays a corresponding error message.
</para>
<para>
For details, see the section
<link linkend="pbk-initializing-the-backup-catalog">Initializing
the Backup Catalog</link>.
</para>
</refsect3>
<refsect3 id="pbk-add-instance" xreflabel="add-instance">
<title>add-instance</title>
<programlisting>
pg_probackup add-instance -B <replaceable>backup_dir</replaceable> -D <replaceable>data_dir</replaceable> --instance <replaceable>instance_name</replaceable> [--help]
</programlisting>
<para>
Initializes a new backup instance inside the backup catalog
<replaceable>backup_dir</replaceable> and generates the
<filename>pg_probackup.conf</filename> configuration file that controls
<application>pg_probackup</application> settings for the cluster with the specified
<replaceable>data_dir</replaceable> data directory.
</para>
<para>
For details, see the section
<link linkend="pbk-adding-new-backup-instance">Adding a New
Backup Instance</link>.
</para>
</refsect3>
<refsect3 id="pbk-del-instance" xreflabel="del-instance">
<title>del-instance</title>
<programlisting>
pg_probackup del-instance -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> [--help]
</programlisting>
<para>
Deletes all backups and WAL files associated with the
specified instance.
</para>
</refsect3>
<refsect3 id="pbk-set-config" xreflabel="set-config">
<title>set-config</title>
<programlisting>
pg_probackup set-config -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable>
[--help] [--pgdata=<replaceable>pgdata-path</replaceable>]
[--retention-redundancy=<replaceable>redundancy</replaceable>][--retention-window=<replaceable>window</replaceable>][--wal-depth=<replaceable>wal_depth</replaceable>]
[--compress-algorithm=<replaceable>compression_algorithm</replaceable>] [--compress-level=<replaceable>compression_level</replaceable>]
[-d <replaceable>dbname</replaceable>] [-h <replaceable>host</replaceable>] [-p <replaceable>port</replaceable>] [-U <replaceable>username</replaceable>]
[--archive-timeout=<replaceable>timeout</replaceable>] [--external-dirs=<replaceable>external_directory_path</replaceable>]
[--restore-command=<replaceable>cmdline</replaceable>]
[<replaceable>remote_options</replaceable>] [<replaceable>remote_wal_archive_options</replaceable>] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Adds the specified connection, compression, retention, logging,
and external directory settings into the <filename>pg_probackup.conf</filename>
configuration file, or modifies the previously defined values.
</para>
<para>
For all available settings, see the
<link linkend="pbk-options">Options</link> section.
</para>
<para>
It is <emphasis role="strong">not recommended</emphasis> to
edit <filename>pg_probackup.conf</filename> manually.
</para>
</refsect3>
<refsect3 id="pbk-set-backup" xreflabel="set-backup">
<title>set-backup</title>
<programlisting>
pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
{--ttl=<replaceable>ttl</replaceable> | --expire-time=<replaceable>time</replaceable>}
[--note=<replaceable>backup_note</replaceable>] [--help]
</programlisting>
<para>
Sets the provided backup-specific settings into the
<filename>backup.control</filename> configuration file, or modifies the previously
defined values.
</para>
<variablelist>
<varlistentry>
<term><option>--note=<replaceable>backup_note</replaceable></option></term>
<listitem>
<para>
Sets the text note for backup copy.
If <replaceable>backup_note</replaceable> contain newline characters,
then only substring before first newline character will be saved.
Max size of text note is 1 KB.
The <replaceable>'none'</replaceable> value removes current note.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
For all available pinning settings, see the section
<link linkend="pbk-pinning-options">Pinning Options</link>.
</para>
</refsect3>
<refsect3 id="pbk-show-config" xreflabel="show-config">
<title>show-config</title>
<programlisting>
pg_probackup show-config -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> [--format=plain|json]
</programlisting>
<para>
Displays the contents of the <filename>pg_probackup.conf</filename> configuration
file located in the
<filename><replaceable>backup_dir</replaceable>/backups/<replaceable>instance_name</replaceable></filename>
directory. You can specify the
<literal>--format=json</literal> option to get the result
in the <acronym>JSON</acronym> format. By default, configuration settings are
shown as plain text.
</para>
<para>
To edit <filename>pg_probackup.conf</filename>, use the
<xref linkend="pbk-set-config"/> command.
</para>
</refsect3>
<refsect3 id="pbk-show" xreflabel="show">
<title>show</title>
<programlisting>
pg_probackup show -B <replaceable>backup_dir</replaceable>
[--help] [--instance <replaceable>instance_name</replaceable> [-i <replaceable>backup_id</replaceable> | --archive]] [--format=plain|json] [--no-color]
</programlisting>
<para>
Shows the contents of the backup catalog. If
<replaceable>instance_name</replaceable> and
<replaceable>backup_id</replaceable> are specified, shows detailed
information about this backup. If the <option>--archive</option> option is
specified, shows the contents of WAL archive of the backup
catalog.
</para>
<para>
By default, the contents of the backup catalog is shown as
plain text. You can specify the
<literal>--format=json</literal> option to get the result
in the <acronym>JSON</acronym> format.
If <literal>--no-color</literal> flag is used,
then the output is not colored.
</para>
<para>
For details on usage, see the sections
<link linkend="pbk-managing-the-backup-catalog">Managing the
Backup Catalog</link> and
<link linkend="pbk-viewing-wal-archive-information">Viewing WAL
Archive Information</link>.
</para>
</refsect3>
<refsect3 id="pbk-backup" xreflabel="backup">
<title>backup</title>
<programlisting>
pg_probackup backup -B <replaceable>backup_dir</replaceable> -b <replaceable>backup_mode</replaceable> --instance <replaceable>instance_name</replaceable>
[--help] [-j <replaceable>num_threads</replaceable>] [--progress]
[-C] [--stream [-S slot_name] [--temp-slot]] [--backup-pg-log]
[--no-validate] [--skip-block-validation]
[-w --no-password] [-W --password]
[--archive-timeout=<replaceable>timeout</replaceable>] [--external-dirs=<replaceable>external_directory_path</replaceable>]
[--no-sync] [--note=<replaceable>backup_note</replaceable>]
[<replaceable>connection_options</replaceable>] [<replaceable>compression_options</replaceable>] [<replaceable>remote_options</replaceable>]
[<replaceable>retention_options</replaceable>] [<replaceable>pinning_options</replaceable>] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Creates a backup copy of the <productname>PostgreSQL</productname> instance.
<variablelist>
<varlistentry>
<term><option>-b <replaceable>mode</replaceable></option></term>
<term><option>--backup-mode=<replaceable>mode</replaceable></option></term>
<listitem>
<para>
Specifies the backup mode to use. Possible values are:
<literal><link linkend="pbk-modes-full">FULL</link></literal>,
<literal><link linkend="pbk-modes-delta">DELTA</link></literal>,
<literal><link linkend="pbk-modes-page">PAGE</link></literal>, and
<literal><link linkend="pbk-modes-ptrack">PTRACK</link></literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-C</option></term>
<term><option>--smooth-checkpoint</option></term>
<listitem>
<para>
Spreads out the checkpoint over a period of time. By default,
<application>pg_probackup</application> tries to complete the checkpoint as soon as
possible.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--stream</option></term>
<listitem>
<para>
Makes a <link linkend="pbk-stream-mode">STREAM</link> backup, which
includes all the necessary WAL files by streaming them from
the database server via replication protocol.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--temp-slot</option></term>
<listitem>
<para>
Creates a temporary physical replication slot for streaming
WAL from the backed up <productname>PostgreSQL</productname> instance. It ensures that
all the required WAL segments remain available if WAL is
rotated while the backup is in progress. This flag can only be
used together with the <option>--stream</option> flag.
The default slot name is <literal>pg_probackup_slot</literal>,
which can be changed using the <option>--slot</option>/<option>-S</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S <replaceable>slot_name</replaceable></option></term>
<term><option>--slot=<replaceable>slot_name</replaceable></option></term>
<listitem>
<para>
Specifies the replication slot for WAL streaming. This option
can only be used together with the <option>--stream</option>
flag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--backup-pg-log</option></term>
<listitem>
<para>
Includes the log directory into the backup. This directory
usually contains log messages. By default, log directory is
excluded.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-E <replaceable>external_directory_path</replaceable></option></term>
<term><option>--external-dirs=<replaceable>external_directory_path</replaceable></option></term>
<listitem>
<para>
Includes the specified directory into the backup by recursively
copying its contents into a separate subdirectory in the backup catalog. This option
is useful to back up scripts, SQL dump files, and configuration
files located outside of the data directory. If you would like
to back up several external directories, separate their paths
by a colon on Unix and a semicolon on Windows.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--archive-timeout=<replaceable>wait_time</replaceable></option></term>
<listitem>
<para>
Sets the timeout for WAL segment archiving and
streaming, in seconds. By default, <application>pg_probackup</application> waits 300 seconds.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-block-validation</option></term>
<listitem>
<para>
Disables block-level checksum verification to speed up
the backup process.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-validate</option></term>
<listitem>
<para>
Skips automatic validation after the backup is taken. You can
use this flag if you validate backups regularly and would like
to save time when running backup operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-sync</option></term>
<listitem>
<para>
Do not sync backed up files to disk. You can use this flag to speed
up the backup process. Using this flag can result in data
corruption in case of operating system or hardware crash.
If you use this option, it is recommended to run the
<xref linkend="pbk-validate"/> command once the backup is complete
to detect possible issues.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--note=<replaceable>backup_note</replaceable></option></term>
<listitem>
<para>
Sets the text note for backup copy.
If <replaceable>backup_note</replaceable> contain newline characters,
then only substring before first newline character will be saved.
Max size of text note is 1 KB.
The <replaceable>'none'</replaceable> value removes current note.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Additionally, <link linkend="pbk-connection-opts">connection
options</link>, <link linkend="pbk-retention-opts">retention
options</link>, <link linkend="pbk-pinning-options">pinning
options</link>, <link linkend="pbk-remote-server-opts">remote
mode options</link>,
<link linkend="pbk-compression-opts">compression
options</link>, <link linkend="pbk-logging-opts">logging
options</link>, and <link linkend="pbk-common-options">common
options</link> can be used.
</para>
<para>
For details on usage, see the section
<link linkend="pbk-creating-backup">Creating a Backup</link>.
</para>
</refsect3>
<refsect3 id="pbk-restore" xreflabel="restore">
<title>restore</title>
<programlisting>
pg_probackup restore -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable>
[--help] [-D <replaceable>data_dir</replaceable>] [-i <replaceable>backup_id</replaceable>]
[-j <replaceable>num_threads</replaceable>] [--progress]
[-T <replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable>] [--external-mapping=<replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable>] [--skip-external-dirs]
[-R | --restore-as-replica] [--no-validate] [--skip-block-validation]
[--force] [--no-sync]
[--restore-command=<replaceable>cmdline</replaceable>]
[--primary-conninfo=<replaceable>primary_conninfo</replaceable>]
[-S | --primary-slot-name=<replaceable>slot_name</replaceable>]
[-X <replaceable>wal_dir</replaceable> | --waldir=<replaceable>wal_dir</replaceable>]
[<replaceable>recovery_target_options</replaceable>] [<replaceable>logging_options</replaceable>] [<replaceable>remote_options</replaceable>]
[<replaceable>partial_restore_options</replaceable>] [<replaceable>remote_wal_archive_options</replaceable>]
</programlisting>
<para>
Restores the <productname>PostgreSQL</productname> instance from a backup copy located in
the <replaceable>backup_dir</replaceable> backup catalog. If you
specify a <link linkend="pbk-recovery-target-opts">recovery
target option</link>, <application>pg_probackup</application> finds the closest
backup and restores it to the specified recovery target.
If neither the backup ID nor recovery target options are provided,
<application>pg_probackup</application> uses the most recent backup
to perform the recovery.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>-R</option></term>
<term><option>--restore-as-replica</option></term>
<listitem>
<para>
Creates a minimal recovery configuration file to facilitate setting up a
standby server. If the replication connection requires a password,
you must specify the password manually in the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-replication.html#GUC-PRIMARY-CONNINFO">primary_conninfo</ulink>
parameter as it is not included.
For <productname>PostgreSQL</productname> 11 or lower,
recovery settings are written into the <filename>recovery.conf</filename>
file. Starting from <productname>PostgreSQL</productname> 12,
<application>pg_probackup</application> writes these settings into
the <filename>probackup_recovery.conf</filename> file in the data
directory, and then includes them into the
<filename>postgresql.auto.conf</filename> when the cluster is
is started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--primary-conninfo=<replaceable>primary_conninfo</replaceable></option></term>
<listitem>
<para>
Sets the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-replication.html#GUC-PRIMARY-CONNINFO">primary_conninfo</ulink>
parameter to the specified value.
This option will be ignored unless the <option>-R</option> flag is specified.
</para>
<para>
Example: <literal>--primary-conninfo="host=192.168.1.50 port=5432 user=foo password=foopass"</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S</option></term>
<term><option>--primary-slot-name=<replaceable>slot_name</replaceable></option></term>
<listitem>
<para>
Sets the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME">primary_slot_name</ulink>
parameter to the specified value.
This option will be ignored unless the <option>-R</option> flag is specified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-T <replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable></option></term>
<term><option>--tablespace-mapping=<replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable></option></term>
<listitem>
<para>
Relocates the tablespace from the <replaceable>OLDDIR</replaceable> to the <replaceable>NEWDIR</replaceable>
directory at the time of recovery. Both <replaceable>OLDDIR</replaceable> and <replaceable>NEWDIR</replaceable> must
be absolute paths. If the path contains the equals sign (<literal>=</literal>),
escape it with a backslash. This option can be specified
multiple times for multiple tablespaces.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--external-mapping=<replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable></option></term>
<listitem>
<para>
Relocates an external directory included into the backup from
the <replaceable>OLDDIR</replaceable> to the <replaceable>NEWDIR</replaceable> directory at the time of recovery.
Both <replaceable>OLDDIR</replaceable> and <replaceable>NEWDIR</replaceable> must be absolute paths. If the path
contains the equals sign (<literal>=</literal>), escape it with a backslash. This
option can be specified multiple times for multiple
directories.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-external-dirs</option></term>
<listitem>
<para>
Skip external directories included into the backup with the
<option>--external-dirs</option> option. The contents of
these directories will not be restored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-block-validation</option></term>
<listitem>
<para>
Disables block-level checksum verification to speed up
validation. During automatic validation before the restore only
file-level checksums will be verified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-validate</option></term>
<listitem>
<para>
Skips backup validation. You can use this flag if you validate
backups regularly and would like to save time when running
restore operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--restore-command=<replaceable>cmdline</replaceable></option></term>
<listitem>
<para>
Sets the
<ulink url="https://postgrespro.com/docs/postgresql/current/archive-recovery-settings.html#RESTORE-COMMAND">restore_command</ulink>
parameter to the specified command. For example:
<literal>--restore-command='cp /mnt/server/archivedir/%f "%p"'</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--force</option></term>
<listitem>
<para>
Allows to ignore an invalid status of the backup. You can use
this flag if you need to restore the
<productname>PostgreSQL</productname> cluster from a corrupt or an invalid backup.
Use with caution.
If <envar>PGDATA</envar> contains a non-empty directory with system ID different from that
of the backup being restored, <link linkend="pbk-incremental-restore">incremental restore</link>
with this flag overwrites the directory contents (while an error occurs without the flag). If tablespaces
are remapped through the <literal>--tablespace-mapping</literal> option into non-empty directories,
the contents of such directories will be deleted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-sync</option></term>
<listitem>
<para>
Do not sync restored files to disk. You can use this flag to speed
up restore process. Using this flag can result in data
corruption in case of operating system or hardware crash.
If it happens, you have to run the <xref linkend="pbk-restore"/>
command again.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-X <replaceable>wal_dir</replaceable></option></term>
<term><option>--waldir=<replaceable>wal_dir</replaceable></option></term>
<listitem>
<para>
Specifies the directory where WAL should be stored.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Additionally, <link linkend="pbk-recovery-target-opts">recovery
target options</link>,
<link linkend="pbk-remote-server-opts">remote mode
options</link>,
<link linkend="pbk-remote-wal-archive-options">remote WAL archive
options</link>, <link linkend="pbk-logging-opts">logging
options</link>, <link linkend="pbk-partial-restore-options">partial
restore options</link>, and <link linkend="pbk-common-options">common
options</link> can be used.
</para>
<para>
For details on usage, see the section
<link linkend="pbk-restoring-a-cluster">Restoring a
Cluster</link>.
</para>
</refsect3>
<refsect3 id="pbk-checkdb" xreflabel="checkdb">
<title>checkdb</title>
<programlisting>
pg_probackup checkdb
[-B <replaceable>backup_dir</replaceable>] [--instance <replaceable>instance_name</replaceable>] [-D <replaceable>data_dir</replaceable>]
[--help] [-j <replaceable>num_threads</replaceable>] [--progress]
[--amcheck [--skip-block-validation] [--checkunique] [--heapallindexed]]
[<replaceable>connection_options</replaceable>] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Verifies the <productname>PostgreSQL</productname> database cluster correctness by
detecting physical and logical corruption.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--amcheck</option></term>
<listitem>
<para>
Performs logical verification of indexes for the specified
<productname>PostgreSQL</productname> instance if no corruption was found while checking
data files. You must have the <ulink url="https://postgrespro.com/docs/enterprise/current/amcheck.html"><application>amcheck</application></ulink>
extension or the <application>amcheck_next</application> extension
installed in the database to check its indexes. For databases
without <application>amcheck</application>, index verification will be skipped.
Additional options <option>--checkunique</option> and <option>--heapallindexed</option>
are effective depending on the version of <application>amcheck</application> installed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--checkunique</option></term>
<listitem>
<para>
Verifies unique constraints during logical verification of indexes.
You can use this flag only together with the <option>--amcheck</option> flag when
the <application>amcheck</application> extension is
installed in the database.
</para>
<para>
The verification of unique constraints is only possible if in the version of the
<application>amcheck</application> extension you are using, the
<function>bt_index_check</function> function takes the
<parameter>checkunique</parameter> parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--heapallindexed</option></term>
<listitem>
<para>
Checks that all heap tuples that should be indexed are
actually indexed. You can use this flag only together with the
<option>--amcheck</option> flag.
</para>
<para>
This check is only possible if in the version of the
<application>amcheck</application>/<application>amcheck_next</application> extension
you are using, the <function>bt_index_check</function>
function takes the <parameter>heapallindexed</parameter> parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-block-validation</option></term>
<listitem>
<para>
Skip validation of data files. You can use this flag only
together with the <option>--amcheck</option> flag, so that only logical
verification of indexes is performed.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Additionally, <link linkend="pbk-connection-opts">connection
options</link> and <link linkend="pbk-logging-opts">logging
options</link> can be used.
</para>
<para>
For details on usage, see the section
<link linkend="pbk-verifying-a-cluster">Verifying a
Cluster</link>.
</para>
</refsect3>
<refsect3 id="pbk-validate" xreflabel="validate">
<title>validate</title>
<programlisting>
pg_probackup validate -B <replaceable>backup_dir</replaceable>
[--help] [--instance <replaceable>instance_name</replaceable>] [-i <replaceable>backup_id</replaceable>]
[-j <replaceable>num_threads</replaceable>] [--progress]
[--skip-block-validation]
[<replaceable>recovery_target_options</replaceable>] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Verifies that all the files required to restore the cluster
are present and are not corrupt. If
<replaceable>instance_name</replaceable> is not specified,
<application>pg_probackup</application> validates all backups available in the backup
catalog. If you specify the <replaceable>instance_name</replaceable>
without any additional options, <application>pg_probackup</application> validates all the
backups available for this backup instance. If you specify the
<replaceable>instance_name</replaceable> with a
<link linkend="pbk-recovery-target-opts">recovery target
option</link> and/or a <replaceable>backup_id</replaceable>,
<application>pg_probackup</application> checks whether it is possible to restore the
cluster using these options.
</para>
<para>
For details, see the section
<link linkend="pbk-validating-backups">Validating a
Backup</link>.
</para>
</refsect3>
<refsect3 id="pbk-merge" xreflabel="merge">
<title>merge</title>
<programlisting>
pg_probackup merge -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable>
[--help] [-j <replaceable>num_threads</replaceable>] [--progress] [--no-validate] [--no-sync]
[<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Merges backups that belong to a common incremental backup
chain. If you specify a full backup, it will be merged with its first
incremental backup. If you specify an incremental backup, it will be
merged to its parent full backup, together with all incremental backups
between them. Once the merge is complete, the full backup takes in all
the merged data, and the incremental backups are removed as redundant.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--no-validate</option></term>
<listitem>
<para>
Skips automatic validation before and after merge.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-sync</option></term>
<listitem>
<para>
Do not sync merged files to disk. You can use this flag to speed
up the merge process. Using this flag can result in data
corruption in case of operating system or hardware crash.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
For details, see the section
<link linkend="pbk-merging-backups">Merging Backups</link>.
</para>
</refsect3>
<refsect3 id="pbk-delete" xreflabel="delete">
<title>delete</title>
<programlisting>
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable>
[--help] [-j <replaceable>num_threads</replaceable>] [--progress]
[--retention-redundancy=<replaceable>redundancy</replaceable>][--retention-window=<replaceable>window</replaceable>][--wal-depth=<replaceable>wal_depth</replaceable>] [--delete-wal]
{-i <replaceable>backup_id</replaceable> | --delete-expired [--merge-expired] | --merge-expired | --status=backup_status}
[--dry-run] [--no-validate] [--no-sync] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Deletes backup with specified <replaceable>backup_id</replaceable>
or launches the retention purge of backups and archived WAL
that do not satisfy the current retention policies.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--no-validate</option></term>
<listitem>
<para>
Skips automatic validation before and after retention merge.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-sync</option></term>
<listitem>
<para>
Do not sync merged files to disk. You can use this flag to speed
up the retention merge process. Using this flag can result in data
corruption in case of operating system or hardware crash.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
For details, see the sections
<link linkend="pbk-deleting-backups">Deleting Backups</link>,
<link linkend="pbk-retention-opts">Retention Options</link>, and
<link linkend="pbk-configuring-retention-policy">Configuring
Retention Policy</link>.
</para>
</refsect3>
<refsect3 id="pbk-archive-push" xreflabel="archive-push">
<title>archive-push</title>
<programlisting>
pg_probackup archive-push -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable>
--wal-file-name=<replaceable>wal_file_name</replaceable> [--wal-file-path=<replaceable>wal_file_path</replaceable>]
[--help] [--no-sync] [--compress] [--no-ready-rename] [--overwrite]
[-j <replaceable>num_threads</replaceable>] [--batch-size=<replaceable>batch_size</replaceable>]
[--archive-timeout=<replaceable>timeout</replaceable>]
[--compress-algorithm=<replaceable>compression_algorithm</replaceable>]
[--compress-level=<replaceable>compression_level</replaceable>]
[<replaceable>remote_options</replaceable>] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Copies WAL files into the corresponding subdirectory of the
backup catalog and validates the backup instance by
<replaceable>instance_name</replaceable> and
<varname>system-identifier</varname>. If parameters of the
backup instance and the cluster do not match, this command
fails with the following error message: <literal>Refuse to push WAL
segment segment_name into archive. Instance parameters
mismatch.</literal>
</para>
<para>
If the files to be copied already exists in the backup catalog,
<application>pg_probackup</application> computes and compares their checksums. If the
checksums match, <command>archive-push</command> skips the corresponding file and
returns a successful execution code. Otherwise, <command>archive-push</command>
fails with an error. If you would like to replace WAL files in
the case of checksum mismatch, run the <command>archive-push</command> command
with the <option>--overwrite</option> flag.
</para>
<para>
Each file is copied to a temporary file with the
<literal>.part</literal> suffix. If the temporary file already
exists, <application>pg_probackup</application> will wait
<option>archive_timeout</option> seconds before discarding it.
After the copy is done, atomic rename is performed.
This algorithm ensures that a failed <command>archive-push</command>
will not stall continuous archiving and that concurrent archiving from
multiple sources into a single WAL archive has no risk of archive
corruption.
</para>
<para>
To speed up archiving, you can specify the <option>--batch-size</option> option
to copy WAL segments in batches of the specified size.
If <option>--batch-size</option> option is used, then you can also specify
the <option>-j</option> option to copy the batch of WAL segments on multiple threads.
</para>
<para>
WAL segments copied to the archive are synced to disk unless
the <option>--no-sync</option> flag is used.
</para>
<para>
You can use <command>archive-push</command> in the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</ulink>
<productname>PostgreSQL</productname> parameter to set up
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
WAL archiving</link>.
</para>
<para>
For details, see sections
<link linkend="pbk-archiving-options">Archiving Options</link> and
<link linkend="pbk-compression-opts">Compression
Options</link>.
</para>
</refsect3>
<refsect3 id="pbk-archive-get" xreflabel="archive-get">
<title>archive-get</title>
<programlisting>
pg_probackup archive-get -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --wal-file-path=<replaceable>wal_file_path</replaceable> --wal-file-name=<replaceable>wal_file_name</replaceable>
[-j <replaceable>num_threads</replaceable>] [--batch-size=<replaceable>batch_size</replaceable>]
[--prefetch-dir=<replaceable>prefetch_dir_path</replaceable>] [--no-validate-wal]
[--help] [<replaceable>remote_options</replaceable>] [<replaceable>logging_options</replaceable>]
</programlisting>
<para>
Copies WAL files from the corresponding subdirectory of the
backup catalog to the cluster's write-ahead log location. This
command is automatically set by <application>pg_probackup</application> as part of the
<command>restore_command</command> when
restoring backups using a WAL archive. You do not need to set
it manually.
</para>
<para>
To speed up recovery, you can specify the <option>--batch-size</option> option
to copy WAL segments in batches of the specified size.
If <option>--batch-size</option> option is used, then you can also specify
the <option>-j</option> option to copy the batch of WAL segments on multiple threads.
</para>
<para>
For details, see section <link linkend="pbk-archiving-options">Archiving Options</link>.
</para>
</refsect3>
<refsect3 id="pbk-catchup" xreflabel="catchup">
<title>catchup</title>
<programlisting>
pg_probackup catchup -b <replaceable>catchup_mode</replaceable>
--source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable>
--destination-pgdata=<replaceable>path_to_local_dir</replaceable>
[--help] [-j | --threads=<replaceable>num_threads</replaceable>] [--stream] [--dry-run]
[--temp-slot] [-P | --perm-slot] [-S | --slot=<replaceable>slot_name</replaceable>]
[--exclude-path=<replaceable>PATHNAME</replaceable>]
[-T <replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable>]
[<replaceable>connection_options</replaceable>] [<replaceable>remote_options</replaceable>]
</programlisting>
<para>
Creates a copy of a <productname>PostgreSQL</productname>
instance without using the backup catalog.
<variablelist>
<varlistentry>
<term><option>-b <replaceable>catchup_mode</replaceable></option></term>
<term><option>--backup-mode=<replaceable>catchup_mode</replaceable></option></term>
<listitem>
<para>
Specifies the catchup mode to use. Possible values are:
<literal><link linkend="pbk-catchup-modes-full">FULL</link></literal>,
<literal><link linkend="pbk-catchup-modes-delta">DELTA</link></literal>, and
<literal><link linkend="pbk-catchup-modes-ptrack">PTRACK</link></literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable></option></term>
<listitem>
<para>
Specifies the path to the data directory of the instance to be copied. The path can be local or remote.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--destination-pgdata=<replaceable>path_to_local_dir</replaceable></option></term>
<listitem>
<para>
Specifies the path to the local data directory to copy to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-j <replaceable>num_threads</replaceable></option></term>
<term><option>--threads=<replaceable>num_threads</replaceable></option></term>
<listitem>
<para>
Sets the number of parallel threads for
<command>catchup</command> process.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--stream</option></term>
<listitem>
<para>
Copies the instance in <link linkend="pbk-stream-mode">STREAM</link> WAL delivery mode,
including all the necessary WAL files by streaming them from
the instance server via replication protocol.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--dry-run</option></term>
<listitem>
<para>
Displays the total size of the files to be transferred by <command>catchup</command>.
This flag initiates a trial run of <command>catchup</command>, which does
not actually create, delete or move files on disk. WAL streaming is skipped with <option>--dry-run</option>.
This flag also allows you to check that
all the options are correct and cloning/synchronising is ready to run.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-x</option>=<replaceable>path_prefix</replaceable></term>
<term><option>--exclude-path</option>=<replaceable>path_prefix</replaceable></term>
<listitem>
<para>
Specifies a prefix for files to exclude from the synchronization of <productname>PostgreSQL</productname>
instances during copying. The prefix must contain a path relative to the data directory of an instance<!--or
an absolute path. The path can be on the source or destination server-->.
If the prefix specifies a directory,
all files in this directory will not be synchronized.
<warning>
<para>
This option is dangerous since excluding files from synchronization can result in
incomplete synchronization; use with care.
</para>
</warning>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--temp-slot</option></term>
<listitem>
<para>
Creates a <emphasis>temporary</emphasis> physical replication slot for streaming
WAL from the <productname>PostgreSQL</productname> instance being copied. It ensures that
all the required WAL segments remain available if WAL is
rotated while the backup is in progress. This flag can only be
used together with the <option>--stream</option> flag and
cannot be used together with the <option>--perm-slot</option> flag.
The default slot name is <literal>pg_probackup_slot</literal>,
which can be changed using the <option>--slot</option>/<option>-S</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option></term>
<term><option>--perm-slot</option></term>
<listitem>
<para>
Creates a <emphasis>permanent</emphasis> physical replication slot for streaming
WAL from the <productname>PostgreSQL</productname> instance being copied. This flag can only be
used together with the <option>--stream</option> flag and
cannot be used together with the <option>--temp-slot</option> flag.
The default slot name is <literal>pg_probackup_perm_slot</literal>,
which can be changed using the <option>--slot</option>/<option>-S</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S <replaceable>slot_name</replaceable></option></term>
<term><option>--slot=<replaceable>slot_name</replaceable></option></term>
<listitem>
<para>
Specifies the replication slot for WAL streaming. This option
can only be used together with the <option>--stream</option>
flag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-T <replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable></option></term>
<term><option>--tablespace-mapping=<replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable></option></term>
<listitem>
<para>
Relocates the tablespace from the <replaceable>OLDDIR</replaceable> to the <replaceable>NEWDIR</replaceable>
directory at the time of recovery. Both <replaceable>OLDDIR</replaceable> and <replaceable>NEWDIR</replaceable> must
be absolute paths. If the path contains the equals sign (<literal>=</literal>),
escape it with a backslash. This option can be specified
multiple times for multiple tablespaces.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Additionally, <link linkend="pbk-connection-opts">connection
options</link>, <link linkend="pbk-remote-server-opts">remote
mode options</link> can be used.
</para>
<para>
For details on usage, see the section
<link linkend="pbk-creating-backup-to-catchup">Cloning and Synchronizing <productname>PostgreSQL</productname> Instance</link>.
</para>
</refsect3>
</refsect2>
<refsect2 id="pbk-options">
<title>Options</title>
<para>
This section describes command-line options for <application>pg_probackup</application>
commands. If the option value can be derived from an environment
variable, this variable is specified below the command-line
option, in the uppercase. Some values can be taken from the
<filename>pg_probackup.conf</filename> configuration file located in the backup
catalog.
</para>
<para>
For details, see <xref linkend="pbk-configuring-pg-probackup"/>.
</para>
<para>
If an option is specified using more than one method,
command-line input has the highest priority, while the
<filename>pg_probackup.conf</filename> settings have the lowest priority.
</para>
<refsect3 id="pbk-common-options">
<title>Common Options</title>
<para>
The list of general options.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>-B <replaceable>directory</replaceable></option></term>
<term><option>--backup-path=<replaceable>directory</replaceable></option></term>
<term><envar>BACKUP_PATH</envar></term>
<listitem>
<para>
Specifies the absolute path to the backup catalog. Backup
catalog is a directory where all backup files and meta
information are stored. Since this option is required for most
of the <application>pg_probackup</application> commands, you are recommended to specify
it once in the <envar>BACKUP_PATH</envar> environment variable. In this case,
you do not need to use this option each time on the command
line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-D <replaceable>directory</replaceable></option></term>
<term><option>--pgdata=<replaceable>directory</replaceable></option></term>
<term><envar>PGDATA</envar></term>
<listitem>
<para>
Specifies the absolute path to the data directory of the
database cluster. This option is mandatory only for the
<xref linkend="pbk-add-instance"/> command.
Other commands can take its value from the <envar>PGDATA</envar> environment
variable, or from the <filename>pg_probackup.conf</filename> configuration file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i <replaceable>backup_id</replaceable></option></term>
<term><option>--backup-id=<replaceable>backup_id</replaceable></option></term>
<listitem>
<para>
Specifies the unique identifier of the backup.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-j <replaceable>num_threads</replaceable></option></term>
<term><option>--threads=<replaceable>num_threads</replaceable></option></term>
<listitem>
<para>
Sets the number of parallel threads for <command>backup</command>,
<command>restore</command>, <command>merge</command>,
<command>validate</command>, <command>checkdb</command>, and
<command>archive-push</command> processes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--progress</option></term>
<listitem>
<para>
Shows the progress of operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--help</option></term>
<listitem>
<para>
Shows detailed information about the options that can be used
with this command.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-recovery-target-opts">
<title>Recovery Target Options</title>
<para>
If
<link linkend="pbk-setting-up-continuous-wal-archiving">continuous
WAL archiving</link> is configured, you can use one of these
options together with <xref linkend="pbk-restore"/>
or <xref linkend="pbk-validate"/> commands to
specify the moment up to which the database cluster must be
restored or validated.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--recovery-target=immediate|latest</option></term>
<listitem>
<para>
Defines when to stop the recovery:
<itemizedlist spacing="compact">
<listitem>
<para>
The <literal>immediate</literal> value stops the recovery
after reaching the consistent state of the specified
backup, or the latest available backup if the
<option>-i</option>/<option>--backup-id</option> option is omitted.
This is the default behavior for STREAM backups.
</para>
</listitem>
<listitem>
<para>
The <literal>latest</literal> value continues the recovery
until all WAL segments available in the archive are
applied. This is the default behavior for ARCHIVE backups.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--recovery-target-timeline=<replaceable>timeline</replaceable></option></term>
<listitem>
<para>
Specifies a particular timeline to be used for recovery.
By default, the timeline of the specified backup is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--recovery-target-lsn=<replaceable>lsn</replaceable></option></term>
<listitem>
<para>
Specifies the LSN of the write-ahead log location up to which
recovery will proceed. Can be used only when restoring
a database cluster of major version 10 or higher.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--recovery-target-name=<replaceable>recovery_target_name</replaceable></option></term>
<listitem>
<para>
Specifies a named savepoint up to which to restore the cluster.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--recovery-target-time=<replaceable>time</replaceable></option></term>
<listitem>
<para>
Specifies the timestamp up to which recovery will proceed.
If the time zone offset is not specified, the local time zone is used.
</para>
<para>
Example: <literal>--recovery-target-time="2020-01-01 00:00:00+03"</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--recovery-target-xid=<replaceable>xid</replaceable></option></term>
<listitem>
<para>
Specifies the transaction ID up to which recovery will
proceed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--recovery-target-inclusive=<replaceable>boolean</replaceable></option></term>
<term><option></option></term>
<listitem>
<para>
Specifies whether to stop just after the specified recovery
target (<literal>true</literal>), or just before the recovery target (<literal>false</literal>).
This option can only be used together with
<option>--recovery-target-name</option>,
<option>--recovery-target-time</option>,
<option>--recovery-target-lsn</option> or
<option>--recovery-target-xid</option> options. The default
depends on the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal#GUC-RECOVERY-TARGET-INCLUSIVE">recovery_target_inclusive</ulink>
parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--recovery-target-action=pause|promote|shutdown</option></term>
<listitem>
<para>
Specifies
<ulink url="https://postgrespro.com/docs/postgresql/current/recovery-target-settings.html#RECOVERY-TARGET-ACTION">the
action</ulink> the server should take when the recovery target
is reached.
</para>
<para>
Default: <literal>pause</literal>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-retention-opts">
<title>Retention Options</title>
<para>
You can use these options together with
<xref linkend="pbk-backup"/> and
<xref linkend="pbk-delete"/> commands.
</para>
<para>
For details on configuring retention policy, see the section
<link linkend="pbk-configuring-retention-policy">Configuring
Retention Policy</link>.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--retention-redundancy=<replaceable>redundancy</replaceable></option></term>
<term><option></option></term>
<listitem>
<para>
Specifies the number of full backup copies to keep in the data
directory. Must be a non-negative integer. The zero value disables
this setting.
</para>
<para>
Default: <literal>0</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--retention-window=<replaceable>window</replaceable></option></term>
<term><option></option></term>
<listitem>
<para>
Number of days of recoverability. Must be a non-negative integer.
The zero value disables this setting.
</para>
<para>
Default: <literal>0</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--wal-depth=<replaceable>wal_depth</replaceable></option></term>
<listitem>
<para>
Number of latest valid backups on every timeline that must
retain the ability to perform PITR. Must be a non-negative
integer. The zero value disables this setting.
</para>
<para>
Default: <literal>0</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--delete-wal</option></term>
<listitem>
<para>
Deletes WAL files that are no longer required to restore the
cluster from any of the existing backups.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--delete-expired</option></term>
<listitem>
<para>
Deletes backups that do not conform to the retention policy
defined in the <filename>pg_probackup.conf</filename> configuration file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--merge-expired</option></term>
<term><option></option></term>
<listitem>
<para>
Merges the oldest incremental backup that satisfies the
requirements of retention policy with its parent backups that
have already expired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--dry-run</option></term>
<listitem>
<para>
Displays the current status of all the available backups,
without deleting or merging expired backups, if any.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-pinning-options">
<title>Pinning Options</title>
<para>
You can use these options together with
<xref linkend="pbk-backup"/> and
<xref linkend="pbk-set-backup"/> commands.
</para>
<para>
For details on backup pinning, see the section
<link linkend="pbk-backup-pinning">Backup Pinning</link>.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--ttl=<replaceable>ttl</replaceable></option></term>
<listitem>
<para>
Specifies the amount of time the backup should be pinned.
Must be a non-negative integer. The zero value unpins the already
pinned backup. Supported units: ms, s, min, h, d (s by
default).
</para>
<para>
Example: <literal>--ttl=30d</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--expire-time=<replaceable>time</replaceable></option></term>
<listitem>
<para>
Specifies the timestamp up to which the backup will stay
pinned. Must be an ISO-8601 complaint timestamp.
If the time zone offset is not specified, the local time zone is used.
</para>
<para>
Example: <literal>--expire-time="2020-01-01 00:00:00+03"</literal>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-logging-opts">
<title>Logging Options</title>
<para>
You can use these options with any command.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--no-color</option></term>
<listitem>
<para>
Disable coloring for console log messages of <literal>warning</literal> and <literal>error</literal> levels.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-level-console=<replaceable>log_level</replaceable></option></term>
<listitem>
<para>
Controls which message levels are sent to the console log.
Valid values are <literal>verbose</literal>,
<literal>log</literal>, <literal>info</literal>,
<literal>warning</literal>, <literal>error</literal> and
<literal>off</literal>. Each level includes all the levels
that follow it. The later the level, the fewer messages are
sent. The <literal>off</literal> level disables console
logging.
</para>
<para>
Default: <literal>info</literal>
</para>
<note>
<para>
All console log messages are going to <systemitem>stderr</systemitem>, so
the output of <xref linkend="pbk-show"/> and
<xref linkend="pbk-show-config"/> commands does
not mingle with log messages.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-level-file=<replaceable>log_level</replaceable></option></term>
<listitem>
<para>
Controls which message levels are sent to a log file. Valid
values are <literal>verbose</literal>, <literal>log</literal>,
<literal>info</literal>, <literal>warning</literal>,
<literal>error</literal>, and <literal>off</literal>. Each
level includes all the levels that follow it. The later the
level, the fewer messages are sent. The <literal>off</literal>
level disables file logging.
</para>
<para>
Default: <literal>off</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-filename=<replaceable>log_filename</replaceable></option></term>
<listitem>
<para>
Defines the filenames of the created log files. The filenames
are treated as a <function>strftime</function> pattern, so you can use %-escapes to
specify time-varying filenames.
</para>
<para>
Default: <filename>pg_probackup.log</filename>
</para>
<para>
For example, if you specify the <literal>pg_probackup-%u.log</literal> pattern,
<application>pg_probackup</application> generates a separate log file for each day of the
week, with <literal>%u</literal> replaced by the corresponding decimal number:
<filename>pg_probackup-1.log</filename> for Monday, <filename>pg_probackup-2.log</filename> for Tuesday,
and so on.
</para>
<para>
This option takes effect if file logging is enabled by the
<option>--log-level-file</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--error-log-filename=<replaceable>error_log_filename</replaceable></option></term>
<listitem>
<para>
Defines the filenames of log files for error messages only.
The filenames are treated as a <function>strftime</function> pattern, so you can
use %-escapes to specify time-varying filenames.
</para>
<para>
Default: none
</para>
<para>
For example, if you specify the <filename>error-pg_probackup-%u.log</filename>
pattern, <application>pg_probackup</application> generates a separate log file for each
day of the week, with <literal>%u</literal> replaced by the corresponding decimal
number: <filename>error-pg_probackup-1.log</filename> for Monday,
<filename>error-pg_probackup-2.log</filename> for Tuesday, and so on.
</para>
<para>
This option is useful for troubleshooting and monitoring.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-directory=<replaceable>log_directory</replaceable></option></term>
<listitem>
<para>
Defines the directory in which log files will be created. You
must specify the absolute path. This directory is created
lazily, when the first log message is written.
</para>
<para>
Default: <filename>$BACKUP_PATH/log/</filename>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-format-console=<replaceable>log_format</replaceable></option></term>
<listitem>
<para>
Defines the format of the console log. Only set from the command line. Note that you cannot
specify this option in the <filename>pg_probackup.conf</filename> configuration file through
the <xref linkend="pbk-set-config"/> command and that the <xref linkend="pbk-backup"/>
command also treats this option specified in the configuration file as an error.
Possible values are:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>plain</literal> — sets the plain-text format of the console log.
</para>
</listitem>
<listitem>
<para>
<literal>json</literal> — sets the <acronym>JSON</acronym> format of the console log.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Default: <literal>plain</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-format-file=<replaceable>log_format</replaceable></option></term>
<listitem>
<para>
Defines the format of log files used. Possible values are:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>plain</literal> — sets the plain-text format of log files.
</para>
</listitem>
<listitem>
<para>
<literal>json</literal> — sets the <acronym>JSON</acronym> format of log files.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Default: <literal>plain</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-rotation-size=<replaceable>log_rotation_size</replaceable></option></term>
<listitem>
<para>
Maximum size of an individual log file. If this value is
reached, the log file is rotated once a <application>pg_probackup</application> command
is launched, except <command>help</command> and <command>version</command> commands. The zero value
disables size-based rotation. Supported units: kB, MB, GB, TB
(kB by default).
</para>
<para>
Default: <literal>0</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--log-rotation-age=<replaceable>log_rotation_age</replaceable></option></term>
<listitem>
<para>
Maximum lifetime of an individual log file. If this value is
reached, the log file is rotated once a <application>pg_probackup</application> command
is launched, except <command>help</command> and <command>version</command> commands. The time of the
last log file creation is stored in
<filename>$BACKUP_PATH/log/log_rotation</filename>. The zero value disables
time-based rotation. Supported units: ms, s, min, h, d (min by
default).
</para>
<para>
Default: <literal>0</literal>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-connection-opts">
<title>Connection Options</title>
<para>
You can use these options together with
<xref linkend="pbk-backup"/>,
<xref linkend="pbk-catchup"/>, and
<xref linkend="pbk-checkdb"/> commands.
</para>
<para>
All
<ulink url="https://postgrespro.com/docs/postgresql/current/libpq-envars.html">libpq
environment variables</ulink> are supported.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>-d <replaceable>dbname</replaceable></option></term>
<term><option>--pgdatabase=<replaceable>dbname</replaceable></option></term>
<term><envar>PGDATABASE</envar></term>
<listitem>
<para>
Specifies the name of the database to connect to. The
connection is used only for managing backup process, so you
can connect to any existing database. If this option is not
provided on the command line, <envar>PGDATABASE</envar> environment variable,
or the <filename>pg_probackup.conf</filename> configuration file, <application>pg_probackup</application>
tries to take this value from the <envar>PGUSER</envar> environment variable,
or from the current user name if <envar>PGUSER</envar> variable is not set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h <replaceable>host</replaceable></option></term>
<term><option>--pghost=<replaceable>host</replaceable></option></term>
<term><envar>PGHOST</envar></term>
<listitem>
<para>
Specifies the host name of the system on which the server is
running. If the value begins with a slash, it is used as a
directory for the Unix domain socket.
</para>
<para>
Default: <literal>localhost</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p <replaceable>port</replaceable></option></term>
<term><option>--pgport=<replaceable>port</replaceable></option></term>
<term><envar>PGPORT</envar></term>
<listitem>
<para>
Specifies the TCP port or the local Unix domain socket file
extension on which the server is listening for connections.
</para>
<para>
Default: <literal>5432</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-U <replaceable>username</replaceable></option></term>
<term><option>--pguser=<replaceable>username</replaceable></option></term>
<term><envar>PGUSER</envar></term>
<listitem>
<para>
User name to connect as.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w</option></term>
<term><option>--no-password</option></term>
<listitem>
<para>
Disables a password prompt. If the server requires password
authentication and a password is not available by other means
such as a
<ulink url="https://postgrespro.com/docs/postgresql/current/libpq-pgpass.html">.pgpass</ulink>
file or <envar>PGPASSWORD</envar> environment variable, the connection
attempt will fail. This flag can be useful in batch jobs and
scripts where no user is present to enter a password.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-W</option></term>
<term><option>--password</option></term>
<listitem>
<para>
Forces a password prompt. (Deprecated)
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-compression-opts">
<title>Compression Options</title>
<para>
You can use these options together with
<xref linkend="pbk-backup"/> and
<xref linkend="pbk-archive-push"/> commands.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--compress-algorithm=<replaceable>compression_algorithm</replaceable></option></term>
<listitem>
<para>
Defines the algorithm to use for compressing data files.
Possible values are <literal>zlib</literal>,
<literal>pglz</literal>, and <literal>none</literal>. If set
to <literal>zlib</literal> or <literal>pglz</literal>, this option enables compression. By default,
compression is disabled. For the
<xref linkend="pbk-archive-push"/> command, the
<literal>pglz</literal> compression algorithm is not supported.
</para>
<para>
Default: <literal>none</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--compress-level=<replaceable>compression_level</replaceable></option></term>
<listitem>
<para>
Defines compression level (0 through 9, 0 being no compression
and 9 being best compression). This option can be used
together with the <option>--compress-algorithm</option> option.
</para>
<para>
Default: <literal>1</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--compress</option></term>
<listitem>
<para>
Alias for <literal>--compress-algorithm=zlib</literal> and
<literal>--compress-level=1</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-archiving-options">
<title>Archiving Options</title>
<para>
These options can be used with the
<xref linkend="pbk-archive-push"/> command in the
<ulink url="https://postgrespro.com/docs/postgresql/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</ulink>
setting and the <xref linkend="pbk-archive-get"/>
command in the
<ulink url="https://postgrespro.com/docs/postgresql/current/archive-recovery-settings.html#RESTORE-COMMAND">restore_command</ulink>
setting.
</para>
<para>
Additionally, <link linkend="pbk-remote-server-opts">remote mode
options</link> and <link linkend="pbk-logging-opts">logging
options</link> can be used.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--wal-file-path=<replaceable>wal_file_path</replaceable></option></term>
<listitem>
<para>
Provides the path to the WAL file in
<parameter>archive_command</parameter> and
<parameter>restore_command</parameter>. Use the <literal>%p</literal>
variable as the value for this option or explicitly specify the path to a file
outside of the data directory. If you skip this option, the path
specified in <filename>pg_probackup.conf</filename> will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--wal-file-name=<replaceable>wal_file_name</replaceable></option></term>
<listitem>
<para>
Provides the name of the WAL file in
<parameter>archive_command</parameter> and
<parameter>restore_command</parameter>. Use the <literal>%f</literal>
variable as the value for this option for correct processing.
If the value of <option>--wal-file-path</option> is a path
outside of the data directory, explicitly specify the filename.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--overwrite</option></term>
<listitem>
<para>
Overwrites archived WAL file. Use this flag together with the
<xref linkend="pbk-archive-push"/> command if
the specified subdirectory of the backup catalog already
contains this WAL file and it needs to be replaced with its
newer copy. Otherwise, <command>archive-push</command> reports that a WAL segment
already exists, and aborts the operation. If the file to
replace has not changed, <command>archive-push</command> skips this file
regardless of the <option>--overwrite</option> flag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--batch-size=<replaceable>batch_size</replaceable></option></term>
<listitem>
<para>
Sets the maximum number of files that can be copied into the archive
by a single <command>archive-push</command> process, or from
the archive by a single <command>archive-get</command> process.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--archive-timeout=<replaceable>wait_time</replaceable></option></term>
<listitem>
<para>
Sets the timeout for considering existing <literal>.part</literal>
files to be stale. By default, <application>pg_probackup</application>
waits 300 seconds.
This option can be used only with <xref linkend="pbk-archive-push"/> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-ready-rename</option></term>
<listitem>
<para>
Do not rename status files in the <literal>archive_status</literal> directory.
This option should be used only if <parameter>archive_command</parameter>
contains multiple commands.
This option can be used only with <xref linkend="pbk-archive-push"/> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-sync</option></term>
<listitem>
<para>
Do not sync copied WAL files to disk. You can use this flag to speed
up archiving process. Using this flag can result in WAL archive
corruption in case of operating system or hardware crash.
This option can be used only with <xref linkend="pbk-archive-push"/> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--prefetch-dir=<replaceable>path</replaceable></option></term>
<listitem>
<para>
Directory used to store prefetched WAL segments if <option>--batch-size</option> option is used.
Directory must be located on the same filesystem and on the same mountpoint the
<literal>PGDATA/pg_wal</literal> is located.
By default files are stored in <literal>PGDATA/pg_wal/pbk_prefetch</literal> directory.
This option can be used only with <xref linkend="pbk-archive-get"/> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-validate-wal</option></term>
<listitem>
<para>
Do not validate prefetched WAL file before using it.
Use this option if you want to increase the speed of recovery.
This option can be used only with <xref linkend="pbk-archive-get"/> command.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-remote-server-opts">
<title>Remote Mode Options</title>
<para>
This section describes the options related to running
<application>pg_probackup</application> operations remotely via SSH. These options can be
used with <xref linkend="pbk-add-instance"/>,
<xref linkend="pbk-set-config"/>,
<xref linkend="pbk-backup"/>,
<xref linkend="pbk-catchup"/>,
<xref linkend="pbk-restore"/>,
<xref linkend="pbk-archive-push"/>, and
<xref linkend="pbk-archive-get"/> commands.
</para>
<para>
For details on configuring and using the remote mode,
see <xref linkend="pbk-configuring-the-remote-mode"/> and
<xref linkend="pbk-remote-backup"/>.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--remote-proto=<replaceable>proto</replaceable></option></term>
<listitem>
<para>
Specifies the protocol to use for remote operations. Currently
only the SSH protocol is supported. Possible values are:
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>ssh</literal> enables the remote mode via
SSH. This is the default value.
</para>
</listitem>
<listitem>
<para>
<literal>none</literal> explicitly disables the remote
mode.
</para>
</listitem>
</itemizedlist>
<para>
You can omit this option if the
<option>--remote-host</option> option is specified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remote-host=<replaceable>destination</replaceable></option></term>
<term><option></option></term>
<listitem>
<para>
Specifies the remote host IP address or hostname to connect
to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remote-port=<replaceable>port</replaceable></option></term>
<listitem>
<para>
Specifies the remote host port to connect to.
</para>
<para>
Default: <literal>22</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remote-user=<replaceable>username</replaceable></option></term>
<listitem>
<para>
Specifies remote host user for SSH connection. If you omit
this option, the current user initiating the SSH connection is
used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remote-path=<replaceable>path</replaceable></option></term>
<listitem>
<para>
Specifies <application>pg_probackup</application> installation directory on the remote
system.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--ssh-options=<replaceable>ssh_options</replaceable></option></term>
<listitem>
<para>
Provides a string of SSH command-line options. For example,
the following options can be used to set <parameter>keep-alive</parameter> for SSH
connections opened by <application>pg_probackup</application>:
<literal>--ssh-options="-o ServerAliveCountMax=5 -o ServerAliveInterval=60"</literal>.
For the full list of possible options, see
<ulink url="https://man.openbsd.org/ssh_config.5">ssh_config
manual page</ulink>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-remote-wal-archive-options">
<title>Remote WAL Archive Options</title>
<para>
This section describes the options used to provide the
arguments for <link linkend="pbk-remote-server-opts">remote mode
options</link> in
<xref linkend="pbk-archive-get"/> used in the
<ulink url="https://postgrespro.com/docs/postgresql/current/archive-recovery-settings.html#RESTORE-COMMAND">restore_command</ulink>
command when restoring ARCHIVE backups or performing PITR.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--archive-host=<replaceable>destination</replaceable></option></term>
<listitem>
<para>
Provides the argument for the <option>--remote-host</option>
option in the <command>archive-get</command> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--archive-port=<replaceable>port</replaceable></option></term>
<listitem>
<para>
Provides the argument for the <option>--remote-port</option>
option in the <command>archive-get</command> command.
</para>
<para>
Default: <literal>22</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--archive-user=<replaceable>username</replaceable></option></term>
<listitem>
<para>
Provides the argument for the <option>--remote-user</option>
option in the <command>archive-get</command> command. If you omit
this option, the user that has started the <productname>PostgreSQL</productname> cluster is used.
</para>
<para>
Default: <productname>PostgreSQL</productname> user
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-incremental-restore-options">
<title>Incremental Restore Options</title>
<para>
This section describes the options for incremental cluster restore.
These options can be used with the
<xref linkend="pbk-restore"/> command.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>-I <replaceable>incremental_mode</replaceable></option></term>
<term><option>--incremental-mode=<replaceable>incremental_mode</replaceable></option></term>
<listitem>
<para>
Specifies the incremental mode to be used. Possible values are:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>CHECKSUM</literal> — replace only pages with mismatched checksum and LSN.
</para>
</listitem>
<listitem>
<para>
<literal>LSN</literal> — replace only pages with LSN greater than point of divergence.
</para>
</listitem>
<listitem>
<para>
<literal>NONE</literal> — regular restore.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-partial-restore-options">
<title>Partial Restore Options</title>
<para>
This section describes the options for partial cluster restore.
These options can be used with the
<xref linkend="pbk-restore"/> command.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--db-exclude=<replaceable>dbname</replaceable></option></term>
<listitem>
<para>
Specifies the name of the database to exclude from restore. All other
databases in the cluster will be restored as usual, including
<literal>template0</literal> and <literal>template1</literal>.
This option can be specified multiple times for multiple
databases.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--db-include=<replaceable>dbname</replaceable></option></term>
<listitem>
<para>
Specifies the name of the database to restore from a backup. All other
databases in the cluster will not be restored, with the exception
of <literal>template0</literal> and
<literal>template1</literal>. This option can be specified
multiple times for multiple databases.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-replica-options">
<title>Replica Options</title>
<para>
This section describes the options related to taking a backup
from standby.
</para>
<note>
<para>
Starting from <application>pg_probackup</application> 2.0.24, backups can be
taken from standby without connecting to the master server,
so these options are no longer required. In lower versions,
<application>pg_probackup</application> had to connect to the master to determine
recovery time — the earliest moment for which you can
restore a consistent state of the database cluster.
</para>
</note>
<para>
<variablelist>
<varlistentry>
<term><option>--master-db=<replaceable>dbname</replaceable></option></term>
<listitem>
<para>
Deprecated. Specifies the name of the database on the master
server to connect to. The connection is used only for managing
the backup process, so you can connect to any existing
database. Can be set in the <filename>pg_probackup.conf</filename> using the
<xref linkend="pbk-set-config"/> command.
</para>
<para>
Default: <literal>postgres</literal>, the default <productname>PostgreSQL</productname> database
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--master-host=<replaceable>host</replaceable></option></term>
<listitem>
<para>
Deprecated. Specifies the host name of the system on which the
master server is running.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--master-port=<replaceable>port</replaceable></option></term>
<listitem>
<para>
Deprecated. Specifies the TCP port or the local Unix domain
socket file extension on which the master server is listening
for connections.
</para>
<para>
Default: <literal>5432</literal>, the <productname>PostgreSQL</productname> default port
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--master-user=<replaceable>username</replaceable></option></term>
<listitem>
<para>
Deprecated. User name to connect as.
</para>
<para>
Default: <literal>postgres</literal>,
the <productname>PostgreSQL</productname> default user name
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--replica-timeout=<replaceable>timeout</replaceable></option></term>
<term><option></option></term>
<listitem>
<para>
Deprecated. Wait time for WAL segment streaming via
replication, in seconds. By default, <application>pg_probackup</application> waits 300
seconds. You can also define this parameter in the
<filename>pg_probackup.conf</filename> configuration file using the
<xref linkend="pbk-set-config"/> command.
</para>
<para>
Default: <literal>300 sec</literal>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
<refsect3 id="pbk-test-options">
<title>Testing and Debugging Options</title>
<para>
This section describes options useful only in a test or development environment.
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--destroy-all-other-dbs</option></term>
<listitem>
<para>
By default, <application>pg_probackup</application> exits with an
error if an attempt is made to perform a partial incremental restore
since this destroys databases not included in the restore set. This
flag allows you to suppress the error and proceed with the partial
incremental restore (e.g., to keep a development database snapshot
up-to-date with a production one). This option can be used with the
<xref linkend="pbk-restore"/> command.
</para>
<important>
<para>Never use this flag in a production cluster.</para>
</important>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect3>
</refsect2>
</refsect1>
<refsect1 id="pbk-howto">
<title>How-To</title>
<para>
All examples below assume the remote mode of operations via
SSH. If you are planning to run backup and
restore operation locally, skip the
<quote>Setup passwordless SSH connection</quote> step
and omit all <option>--remote-*</option> options.
</para>
<para>
Examples are based on <productname>Ubuntu</productname> 18.04,
<productname>PostgreSQL</productname> 11, and <application>pg_probackup</application>
2.2.0.
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>backup</literal> — <productname>PostgreSQL</productname>
role used for connection to <productname>PostgreSQL</productname>
cluster.
</para>
</listitem>
<listitem>
<para>
<literal>backupdb</literal> — database used for connection
to <productname>PostgreSQL</productname> cluster.
</para>
</listitem>
<listitem>
<para>
<literal>backup_host</literal> — host with backup catalog.
</para>
</listitem>
<listitem>
<para>
<literal>backupman</literal> — user on
<literal>backup_host</literal> running all <application>pg_probackup</application>
operations.
</para>
</listitem>
<listitem>
<para>
<filename>/mnt/backups</filename> — directory on
<literal>backup_host</literal> where backup catalog is stored.
</para>
</listitem>
<listitem>
<para>
<literal>postgres_host</literal> — host with <productname>PostgreSQL</productname>
cluster.
</para>
</listitem>
<listitem>
<para>
<literal>postgres</literal> — user on
<literal>postgres_host</literal> that has started the <productname>PostgreSQL</productname> cluster.
</para>
</listitem>
<listitem>
<para>
<filename>/var/lib/postgresql/11/main</filename> — <productname>PostgreSQL</productname>
data directory on <literal>postgres_host</literal>.
</para>
</listitem>
</itemizedlist>
<refsect2 id="pbk-minimal-setup">
<title>Minimal Setup</title>
<para>
This scenario illustrates setting up standalone FULL and DELTA backups.
</para>
<procedure>
<step id="pbk-setup-passwordless-ssh-connection-from-backup-host-to-postgres-host">
<title>Set up passwordless SSH connection from
<literal>backup_host</literal> to
<literal>postgres_host</literal>:</title>
<programlisting>
[backupman@backup_host] ssh-copy-id postgres@postgres_host
</programlisting>
</step>
<step id="pbk-setup-postgresql-cluster">
<title>Configure your <productname>PostgreSQL</productname> cluster.</title>
<para>
For security purposes, it is recommended to use a separate
database for backup operations.
</para>
<programlisting>
postgres=#
CREATE DATABASE backupdb;
</programlisting>
<para>
Connect to the <literal>backupdb</literal> database, create the
<literal>probackup</literal> role, and grant the following
permissions to this role:
</para>
<programlisting>
backupdb=#
BEGIN;
CREATE ROLE backup WITH LOGIN REPLICATION;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_start_backup(text, boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup(boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;
</programlisting>
</step>
<step id="pbk-init-the-backup-catalog">
<title>Initialize the backup catalog:</title>
<programlisting>
[backupman@backup_host]$ pg_probackup-11 init -B /mnt/backups
INFO: Backup catalog '/mnt/backups' successfully inited
</programlisting>
</step>
<step id="pbk-add-instance-pg-11-to-backup-catalog">
<title>Add instance <literal>pg-11</literal> to the backup catalog:</title>
<programlisting>
[backupman@backup_host]$ pg_probackup-11 add-instance -B /mnt/backups --instance pg-11 --remote-host=postgres_host --remote-user=postgres -D /var/lib/postgresql/11/main
INFO: Instance 'node' successfully inited
</programlisting>
</step>
<step id="pbk-take-full-backup">
<title>Take a FULL backup:</title>
<programlisting>
[backupman@backup_host] pg_probackup-11 backup -B /mnt/backups --instance pg-11 -b FULL --stream --remote-host=postgres_host --remote-user=postgres -U backup -d backupdb
INFO: Backup start, pg_probackup version: 2.2.0, instance: node, backup ID: PZ7YK2, backup mode: FULL, wal mode: STREAM, remote: true, compress-algorithm: none, compress-level: 1
INFO: Start transferring data files
INFO: Data files are transferred
INFO: wait for pg_stop_backup()
INFO: pg_stop backup() successfully executed
INFO: Validating backup PZ7YK2
INFO: Backup PZ7YK2 data files are valid
INFO: Backup PZ7YK2 resident size: 196MB
INFO: Backup PZ7YK2 completed
</programlisting>
</step>
<step id="pbk-lets-take-a-look-at-the-backup-catalog">
<title>Let's take a look at the backup catalog:</title>
<programlisting>
[backupman@backup_host] pg_probackup-11 show -B /mnt/backups --instance pg-11
BACKUP INSTANCE 'pg-11'
==================================================================================================================================
Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status
==================================================================================================================================
node 11 PZ7YK2 2019-10-11 19:45:45+03 FULL STREAM 1/0 11s 180MB 16MB 1.00 0/3C000028 0/3C000198 OK
</programlisting>
</step>
<step id="pbk-take-incremental-backup-in-delta-mode">
<title>Take an incremental backup in the DELTA mode:</title>
<programlisting>
[backupman@backup_host] pg_probackup-11 backup -B /mnt/backups --instance pg-11 -b delta --stream --remote-host=postgres_host --remote-user=postgres -U backup -d backupdb
INFO: Backup start, pg_probackup version: 2.2.0, instance: node, backup ID: PZ7YMP, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: none, compress-level: 1
INFO: Parent backup: PZ7YK2
INFO: Start transferring data files
INFO: Data files are transferred
INFO: wait for pg_stop_backup()
INFO: pg_stop backup() successfully executed
INFO: Validating backup PZ7YMP
INFO: Backup PZ7YMP data files are valid
INFO: Backup PZ7YMP resident size: 32MB
INFO: Backup PZ7YMP completed
</programlisting>
</step>
<step id="pbk-lets-hide-some-parameters-into-config-so-cmdline-can-be-less-crowdy">
<title>Let's add some parameters to <application>pg_probackup</application>
configuration file, so that you can omit them from the command line:</title>
<programlisting>
[backupman@backup_host] pg_probackup-11 set-config -B /mnt/backups --instance pg-11 --remote-host=postgres_host --remote-user=postgres -U backup -d backupdb
</programlisting>
</step>
<step id="pbk-take-another-incremental-backup-in-delta-mode-omitting-some-of-the-previous-parameters">
<title>Take another incremental backup in the DELTA mode, omitting
some of the previous parameters:</title>
<programlisting>
[backupman@backup_host] pg_probackup-11 backup -B /mnt/backups --instance pg-11 -b delta --stream
INFO: Backup start, pg_probackup version: 2.2.0, instance: node, backup ID: PZ7YR5, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: none, compress-level: 1
INFO: Parent backup: PZ7YMP
INFO: Start transferring data files
INFO: Data files are transferred
INFO: wait for pg_stop_backup()
INFO: pg_stop backup() successfully executed
INFO: Validating backup PZ7YR5
INFO: Backup PZ7YR5 data files are valid
INFO: Backup PZ7YR5 resident size: 32MB
INFO: Backup PZ7YR5 completed
</programlisting>
</step>
<step id="pbk-lets-take-a-look-at-instance-config">
<title>Let's take a look at the instance configuration:</title>
<programlisting>
[backupman@backup_host] pg_probackup-11 show-config -B /mnt/backups --instance pg-11
# Backup instance information
pgdata = /var/lib/postgresql/11/main
system-identifier = 6746586934060931492
xlog-seg-size = 16777216
# Connection parameters
pgdatabase = backupdb
pghost = postgres_host
pguser = backup
# Replica parameters
replica-timeout = 5min
# Archive parameters
archive-timeout = 5min
# Logging parameters
log-level-console = INFO
log-level-file = OFF
log-format-console = PLAIN
log-format-file = PLAIN
log-filename = pg_probackup.log
log-rotation-size = 0
log-rotation-age = 0
# Retention parameters
retention-redundancy = 0
retention-window = 0
wal-depth = 0
# Compression parameters
compress-algorithm = none
compress-level = 1
# Remote access parameters
remote-proto = ssh
remote-host = postgres_host
</programlisting>
<para>
Note that we are getting the default values for other options
that were not overwritten by the <command>set-config</command> command.
</para>
</step>
<step id="pbk-lets-take-a-look-at-the-backup-catalog-1">
<title>Let's take a look at the backup catalog:</title>
<programlisting>
[backupman@backup_host] pg_probackup-11 show -B /mnt/backups --instance pg-11
====================================================================================================================================
Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status
====================================================================================================================================
node 11 PZ7YR5 2019-10-11 19:49:56+03 DELTA STREAM 1/1 10s 112kB 32MB 1.00 0/41000028 0/41000160 OK
node 11 PZ7YMP 2019-10-11 19:47:16+03 DELTA STREAM 1/1 10s 376kB 32MB 1.00 0/3E000028 0/3F0000B8 OK
node 11 PZ7YK2 2019-10-11 19:45:45+03 FULL STREAM 1/0 11s 180MB 16MB 1.00 0/3C000028 0/3C000198 OK
</programlisting>
</step>
</procedure>
</refsect2>
</refsect1>
<refsect1 id="pbk-versioning">
<title>Versioning</title>
<para>
<application>pg_probackup</application> follows
<ulink url="https://semver.org/">semantic</ulink> versioning.
</para>
</refsect1>
<refsect1>
<title>Authors</title>
<para>
Postgres Professional, Moscow, Russia.
</para>
<refsect2>
<title>Credits</title>
<para>
<application>pg_probackup</application> utility is based on <application>pg_arman</application>,
which was originally written by NTT and then developed and maintained by Michael Paquier.
</para>
</refsect2>
</refsect1>
</refentry>
Reference in New Issue View Git Blame Copy Permalink