mirror of
https://github.com/postgrespro/pg_probackup.git
synced 2024-12-11 11:41:33 +02:00
5253 lines
218 KiB
XML
5253 lines
218 KiB
XML
<!--
|
|
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>
|
|
|
|
</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 <productname>PostgreSQL</productname> 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>
|
|
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>
|
|
</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>
|
|
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>
|
|
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>
|
|
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>
|
|
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 <productname>PostgreSQL</productname> 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 higher,
|
|
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 PostgreSQL 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>libicu</application> versions.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
All backups in the incremental chain must belong to the same
|
|
timeline. For example, if you have taken incremental backups on a
|
|
standby server that gets promoted, you have to take another FULL
|
|
backup.
|
|
</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 PostgreSQL 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.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.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> 10 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.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>
|
|
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>
|
|
</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-path=%p --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;
|
|
</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-archive-push"/>,
|
|
<xref linkend="pbk-archive-get"/>.
|
|
</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>
|
|
<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> 12 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. The maximum allowed value is 1024.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Grant the right to execute <application>PTRACK</application>
|
|
functions to the <literal>backup</literal> role
|
|
in the database used to connect to the cluster:
|
|
</para>
|
|
<programlisting>
|
|
GRANT EXECUTE ON FUNCTION pg_ptrack_get_pagemapset(pg_lsn) TO backup;
|
|
GRANT EXECUTE ON FUNCTION pg_ptrack_control_lsn() TO backup;
|
|
GRANT EXECUTE ON FUNCTION pg_ptrack_get_block(oid, oid, oid, bigint) TO backup;
|
|
</programlisting>
|
|
</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>
|
|
|
|
<para>
|
|
For older <productname>PostgreSQL</productname> versions,
|
|
PTRACK required taking backups in the exclusive mode
|
|
to provide exclusive access to bitmaps with changed blocks.
|
|
To set up PTRACK backups for <productname>PostgreSQL</productname> 11
|
|
or lower, do the following:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Set the <parameter>ptrack_enable</parameter> parameter to
|
|
<literal>on</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Grant the right to execute <application>PTRACK</application>
|
|
functions to the <literal>backup</literal> role
|
|
<emphasis role="strong">in every database</emphasis> of the
|
|
cluster:
|
|
</para>
|
|
<programlisting>
|
|
GRANT EXECUTE ON FUNCTION pg_catalog.pg_ptrack_clear() TO backup;
|
|
GRANT EXECUTE ON FUNCTION pg_catalog.pg_ptrack_get_and_clear(oid, oid) TO backup;
|
|
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup() TO backup;
|
|
</programlisting>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</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:
|
|
</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
FULL — creates a full backup that contains all the data
|
|
files of the cluster to be restored.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
DELTA — reads all data files in the data directory and
|
|
creates an incremental backup for pages that have changed
|
|
since the previous backup.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
PAGE — creates an incremental backup based on the WAL
|
|
files that have been generated since the previous full or
|
|
incremental backup was taken. Only changed blocks are read
|
|
from data files.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
PTRACK — creates an incremental backup tracking page
|
|
changes on the fly.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<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 ommitted, 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-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>
|
|
<note>
|
|
<para>
|
|
The <literal>template0</literal> and
|
|
<literal>template1</literal> databases are always restored.
|
|
</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-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>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 by retention purge.
|
|
</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>
|
|
</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 set retention policies for backups
|
|
and WAL archive. All policies can be combined together in any
|
|
way.
|
|
</para>
|
|
<refsect3 id="pbk-retention-policy">
|
|
<title>Backup Retention Policy</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 and periodically clean up
|
|
redundant backup copies accordingly.
|
|
</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
|
|
delete all backup copies that are older than seven days, with
|
|
all the corresponding WAL files.
|
|
</para>
|
|
<para>
|
|
If both <option>--retention-redundancy</option> and
|
|
<option>--retention-window</option> options are set,
|
|
<application>pg_probackup</application> keeps backup copies that satisfy at least one
|
|
condition. For example, if you set
|
|
<literal>--retention-redundancy=2</literal> and
|
|
<literal>--retention-window=7</literal>, <application>pg_probackup</application> purges
|
|
the backup catalog to keep only two full backup copies and all
|
|
backups that are newer than 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, run:
|
|
</para>
|
|
<programlisting>
|
|
pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired
|
|
</programlisting>
|
|
<para>
|
|
<application>pg_probackup</application> deletes all backup copies that do not conform to
|
|
the defined retention policy.
|
|
</para>
|
|
<para>
|
|
If you would like to also remove the WAL files that are no
|
|
longer required for any of the backups, add 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>
|
|
<note>
|
|
<para>
|
|
Alternatively, you can use the
|
|
<option>--delete-expired</option>,
|
|
<option>--merge-expired</option>,
|
|
<option>--delete-wal</option> flags and the
|
|
<option>--retention-window</option> and
|
|
<option>--retention-redundancy</option> options together
|
|
with the <xref linkend="pbk-backup"/> command to
|
|
remove and merge the outdated backup copies once the new
|
|
backup is created.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
You can 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>Backup Pinning</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, the <literal>expire-time</literal>
|
|
attribute 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>
|
|
Only pinned backups have the <literal>expire-time</literal>
|
|
attribute in the backup metadata.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
A pinned incremental backup implicitly pins all
|
|
its parent backups.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
You can unpin the backup by setting the
|
|
<option>--ttl</option> option to zero using the
|
|
<xref linkend="pbk-set-backup"/> command. For example:
|
|
</para>
|
|
<programlisting>
|
|
pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable> --ttl=0
|
|
</programlisting>
|
|
|
|
</refsect3>
|
|
<refsect3 id="pbk-wal-archive-retention-policy">
|
|
<title>WAL Archive Retention Policy</title>
|
|
<para>
|
|
By default, <application>pg_probackup</application> purges
|
|
only redundant WAL segments that cannot be applied to any of the
|
|
backups in the backup catalog. To save disk space,
|
|
you can configure WAL archive retention policy, which allows to
|
|
keep WAL of limited depth measured in backups per timeline.
|
|
</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 last valid backup, use the
|
|
<option>--wal-depth</option> option:
|
|
</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>
|
|
<note>
|
|
<para>
|
|
<link linkend="pbk-backup-pinning">Pinned backups</link> are
|
|
ignored for the purpose of WAL Archive Retention Policy fulfilment.
|
|
</para>
|
|
</note>
|
|
</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 the specified incremental backup to its
|
|
parent full backup, together with all incremental backups
|
|
between them. Once the merge is complete, 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>. 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>
|
|
</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>} [--help]
|
|
</programlisting>
|
|
<para>
|
|
Sets the provided backup-specific settings into the
|
|
<filename>backup.control</filename> configuration file, or modifies the previously
|
|
defined values.
|
|
</para>
|
|
<para>
|
|
For all available 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]
|
|
</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.
|
|
</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>]
|
|
[<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:
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<literal>FULL</literal> — creates a full backup that contains all the data
|
|
files of the cluster to be restored.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>DELTA</literal> — reads all data files in the data directory and
|
|
creates an incremental backup for pages that have changed
|
|
since the previous backup.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>PAGE</literal> — creates an incremental PAGE backup based on the WAL
|
|
files that have changed since the previous full or
|
|
incremental backup was taken.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>PTRACK</literal> — creates an incremental PTRACK backup tracking
|
|
page changes on the fly.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</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>
|
|
</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]
|
|
[--restore-command=<replaceable>cmdline</replaceable>]
|
|
[--primary-conninfo=<replaceable>primary_conninfo</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 if used without the <option>-R</option> flag.
|
|
</para>
|
|
<para>
|
|
Example: <literal>--primary-conninfo='host=192.168.1.50 port=5432 user=foo password=foopass'</literal>
|
|
</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.
|
|
</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">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]
|
|
[--skip-block-validation] [--amcheck] [--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 <application>amcheck</application>
|
|
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.
|
|
</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>
|
|
|
|
<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 you are using the
|
|
<application>amcheck</application> extension of version 2.0 or higher, or
|
|
the <application>amcheck_next</application> extension of any version.
|
|
</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]
|
|
[<replaceable>logging_options</replaceable>]
|
|
</programlisting>
|
|
<para>
|
|
Merges the specified incremental backup to its parent full
|
|
backup, together with all incremental backups between them, if
|
|
any. As a result, the full backup takes in all the merged
|
|
data, and the incremental backups are removed as redundant.
|
|
</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}
|
|
[--dry-run]
|
|
[<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>
|
|
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-path=<replaceable>wal_file_path</replaceable> --wal-file-name=<replaceable>wal_file_name</replaceable>
|
|
[--help] [--compress] [--compress-algorithm=<replaceable>compression_algorithm</replaceable>]
|
|
[--compress-level=<replaceable>compression_level</replaceable>] [--overwrite]
|
|
[<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> For each WAL file moved to the backup catalog, you
|
|
will see the following message in the <productname>PostgreSQL</productname> log file:
|
|
<literal>pg_probackup archive-push completed successfully</literal>.
|
|
</para>
|
|
<para>
|
|
If the files to be copied already exist 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>
|
|
The files are copied to a temporary file with the
|
|
<literal>.part</literal> suffix. 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 have no risk of archive corruption. WAL segments copied to
|
|
the archive are synced to disk.
|
|
</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>
|
|
[--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>
|
|
</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>, and <command>checkdb</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.
|
|
</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/recovery-target-settings.html#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.
|
|
</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>--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-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"/> 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.
|
|
</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 for correct processing.
|
|
</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.
|
|
</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>
|
|
</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-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-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>
|
|
</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.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 backup -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-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 backup -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>
|