(original) (raw)

Description

pg_probackup is a utility to manage backup and recovery of PostgreSQL database clusters. It is designed to perform periodic backups of the PostgreSQL instance that enable you to restore the server in case of a failure.pg_probackup supports PostgreSQL 11 or higher.

Overview

As compared to other backup solutions, pg_probackup offers the following benefits that can help you implement different backup strategies and deal with large amounts of data:

To manage backup data, pg_probackup creates a_backup catalog_. 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.

Using pg_probackup, you can take full or incrementalbackups:

pg_probackup 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 withpg_probackup must use one of the following_WAL delivery modes_:

Limitations

pg_probackup currently has the following limitations:

Quick Start

To quickly get started with pg_probackup, complete the steps below. This will set up FULL and DELTA backups in the remote mode and demonstrate some basic pg_probackup operations. In the following, these terms are used:

Steps to perform:

  1. Install pg_probackup on both backup_host and postgres_host.
  2. Set up an SSH connection from backup_host to postgres_host.
  3. Configure your database cluster for STREAM backups.
  4. Initialize the backup catalog:
    backup_user@backup_host:~$ pg_probackup-16 init -B /mnt/backups
    INFO: Backup catalog '/mnt/backups' successfully initialized
  5. Add a backup instance called mydb to the backup catalog:
    backup_user@backup_host:~$ pg_probackup-16 add-instance \
    -B /mnt/backups \
    -D /var/lib/pgpro/std-16/data \
    --instance=node \
    --remote-host=postgres_host \
    --remote-user=postgres
    INFO: Instance 'node' successfully initialized
  6. Make a FULL backup:
    backup_user@backup_host:~$ pg_probackup-16 backup \
    -B /mnt/backups \
    -b FULL \
    --instance=node \
    --stream \
    --compress-algorithm=zlib \
    --remote-host=postgres_host \
    --remote-user=postgres \
    -U backup \
    -d backupdb
    INFO: Backup start, pg_probackup version: 2.5.15, instance: node, backup ID: SCUN1Q, backup mode: FULL, wal mode: STREAM, remote: true, compress-algorithm: zlib, compress-level: 1
    INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
    INFO: Database backup start
    INFO: wait for pg_backup_start()
    INFO: Wait for WAL segment /mnt/backups/backups/node/SCUN1Q/database/pg_wal/000000010000000000000008 to be streamed
    INFO: PGDATA size: 96MB
    INFO: Current Start LSN: 0/8000028, TLI: 1
    INFO: Start transferring data files
    INFO: Data files are transferred, time elapsed: 1s
    INFO: wait for pg_stop_backup()
    INFO: pg_stop backup() successfully executed
    INFO: stop_lsn: 0/800BBD0
    INFO: Getting the Recovery Time from WAL
    INFO: Syncing backup files to disk
    INFO: Backup files are synced, time elapsed: 1s
    INFO: Validating backup SCUN1Q
    INFO: Backup SCUN1Q data files are valid
    INFO: Backup SCUN1Q resident size: 56MB
    INFO: Backup SCUN1Q completed
  7. List the backups of the instance:
    backup_user@backup_host:~$ pg_probackup-16 show \
    -B /mnt/backups \
    --instance=node

================================================================================================================================
Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status

node 16 SCUN1Q 2024-05-02 11:17:53+03 FULL STREAM 1/0 12s 40MB 16MB 2.42 0/8000028 0/800BBD0 OK 8. Make an incremental backup in the DELTA mode:
backup_user@backup_host:$ pg_probackup-16 backup \
-B /mnt/backups \
-b DELTA \
--instance=node \
--stream \
--compress-algorithm=zlib \
--remote-host=postgres_host \
--remote-user=postgres \
-U backup \
-d backupdb
INFO: Backup start, pg_probackup version: 2.5.15, instance: node, backup ID: SCUN22, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: zlib, compress-level: 1
INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
INFO: Database backup start
INFO: wait for pg_backup_start()
INFO: Parent backup: SCUN1Q
INFO: Wait for WAL segment /mnt/backups/backups/node/SCUN22/database/pg_wal/000000010000000000000009 to be streamed
INFO: PGDATA size: 96MB
INFO: Current Start LSN: 0/9000028, TLI: 1
INFO: Parent Start LSN: 0/8000028, TLI: 1
INFO: Start transferring data files
INFO: Data files are transferred, time elapsed: 1s
INFO: wait for pg_stop_backup()
INFO: pg_stop backup() successfully executed
INFO: stop_lsn: 0/9000168
INFO: Getting the Recovery Time from WAL
INFO: Syncing backup files to disk
INFO: Backup files are synced, time elapsed: 1s
INFO: Validating backup SCUN22
INFO: Backup SCUN22 data files are valid
INFO: Backup SCUN22 resident size: 34MB
INFO: Backup SCUN22 completed 9. Add or modify some parameters in the pg_probackup configuration file, so that you do not have to specify them each time on the command line:
backup_user@backup_host:$ pg_probackup-16 set-config \
-B /mnt/backups \
--instance=node \
--remote-host=postgres_host \
--remote-user=postgres \
-U backup \
-d backupdb 10. Check the configuration of the instance:
backup_user@backup_host:$ pg_probackup-16 show-config \
-B /mnt/backups \
--instance=node
# Backup instance information
pgdata = /var/lib/pgpro/std-16/data
system-identifier = 7364313570668255886
xlog-seg-size = 16777216
# Connection parameters
pgdatabase = backupdb
pghost = postgres_host
pguser = backup
# Replica parameters
replica-timeout = 5min
# Archive parameters
archive-timeout = 5min
# Logging parameters
log-level-console = INFO
log-level-file = OFF
log-format-console = PLAIN
log-format-file = PLAIN
log-filename = pg_probackup.log
log-rotation-size = 0TB
log-rotation-age = 0d
# 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
remote-user = postgres
Note that the parameters not modified via set-config retain their default values. 11. Make another incremental backup in the DELTA mode, omitting the parameters stored in the configuration file earlier:
backup_user@backup_host:$ pg_probackup-16 backup \
-B /mnt/backups \
-b DELTA \
--instance=node \
--stream \
--compress-algorithm=zlib
INFO: Backup start, pg_probackup version: 2.5.15, instance: node, backup ID: SCUN2C, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: zlib, compress-level: 1
INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
INFO: Database backup start
INFO: wait for pg_backup_start()
INFO: Parent backup: SCUN22
INFO: Wait for WAL segment /mnt/backups/backups/node/SCUN2C/database/pg_wal/00000001000000000000000B to be streamed
INFO: PGDATA size: 96MB
INFO: Current Start LSN: 0/B000028, TLI: 1
INFO: Parent Start LSN: 0/9000028, TLI: 1
INFO: Start transferring data files
INFO: Data files are transferred, time elapsed: 0
INFO: wait for pg_stop_backup()
INFO: pg_stop backup() successfully executed
INFO: stop_lsn: 0/B000168
INFO: Getting the Recovery Time from WAL
INFO: Syncing backup files to disk
INFO: Backup files are synced, time elapsed: 0
INFO: Validating backup SCUN2C
INFO: Backup SCUN2C data files are valid
INFO: Backup SCUN2C resident size: 17MB
INFO: Backup SCUN2C completed 12. List the backups of the instance again:
backup_user@backup_host:~$ pg_probackup-16 show \
-B /mnt/backups \
--instance=node

Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status

node 16 SCUN2C 2024-05-02 11🔞13+03 DELTA STREAM 1/1 10s 1139kB 16MB 1.00 0/B000028 0/B000168 OK
node 16 SCUN22 2024-05-02 11🔞04+03 DELTA STREAM 1/1 10s 2357kB 32MB 1.02 0/9000028 0/9000168 OK
node 16 SCUN1Q 2024-05-02 11:17:53+03 FULL STREAM 1/0 12s 40MB 16MB 2.42 0/8000028 0/800BBD0 OK 13. Restore the data from the latest available backup to an arbitrary location:
backup_user@backup_host:~$ pg_probackup-16 restore \
-B /mnt/backups \
-D /var/lib/pgpro/std-16/staging-data \
--instance=node
INFO: Validating parents for backup SCUN2C
INFO: Validating backup SCUN1Q
INFO: Backup SCUN1Q data files are valid
INFO: Validating backup SCUN22
INFO: Backup SCUN22 data files are valid
INFO: Validating backup SCUN2C
INFO: Backup SCUN2C data files are valid
INFO: Backup SCUN2C WAL segments are valid
INFO: Backup SCUN2C is valid.
INFO: Restoring the database from backup SCUN2C on localhost
INFO: Start restoring backup files. PGDATA size: 112MB
INFO: Backup files are restored. Transfered bytes: 112MB, time elapsed: 0
INFO: Restore incremental ratio (less is better): 100% (112MB/112MB)
INFO: Syncing restored files to disk
INFO: Restored backup files are synced, time elapsed: 2s
INFO: Restore of backup SCUN2C completed.

Installation

Installation on Debian family systems (Debian, Ubuntu etc.)

You may need to use apt-get instead of apt on older systems in the commands below.

  1. Add the pg_probackup repository GPG key
    sudo apt install gpg wget
    wget -qO - https://repo.postgrespro.ru/pg_probackup/keys/GPG-KEY-PG-PROBACKUP | \
    sudo tee /etc/apt/trusted.gpg.d/pg_probackup.asc
  2. Setup the binary package repository
    . /etc/os-release
    echo "deb [arch=amd64] https://repo.postgrespro.ru/pg_probackup/deb VERSIONCODENAMEmain−VERSION_CODENAME main-VERSIONC​ODENAMEmain−VERSION_CODENAME" | \
    sudo tee /etc/apt/sources.list.d/pg_probackup.list
  3. Optionally setup the source package repository for rebuilding the binaries
    echo "deb-src [arch=amd64] https://repo.postgrespro.ru/pg_probackup/deb VERSIONCODENAMEmain−VERSION_CODENAME main-VERSIONC​ODENAMEmain−VERSION_CODENAME" | \
    sudo tee -a /etc/apt/sources.list.d/pg_probackup.list
  4. List the available pg_probackup packages
    • Using apt:
      sudo apt update
      apt search pg_probackup
    • Using apt-get:
      sudo apt-get update
      apt-cache search pg_probackup
  5. Install or upgrade a pg_probackup version of your choice
    sudo apt install pg-probackup-16
  6. Optionally install the debug package
    sudo apt install pg-probackup-16-dbg
  7. Optionally install the source package (provided you have set up the source package repository as described above)
    sudo apt install dpkg-dev
    sudo apt source pg-probackup-16

Installation on Red Hat family systems (CentOS, Oracle Linux etc.)

You may need to use yum instead of dnf on older systems in the commands below.

  1. Install the pg_probackup repository
    dnf install https://repo.postgrespro.ru/pg_probackup/keys/pg_probackup-repo-centos.noarch.rpm
  2. List the available pg_probackup packages
    dnf search pg_probackup
  3. Install or upgrade a pg_probackup version of your choice
    dnf install pg_probackup-16
  4. Optionally install the debug package
    dnf install pg_probackup-16-debuginfo
  5. Optionally install the source package for rebuilding the binaries
    • Using dnf:
      dnf install 'dnf-command(download)'
      dnf download --source pg_probackup-16
    • Using yum:
      yumdownloader --source pg_probackup-16

Installation on ALT Linux

  1. Setup the repository
  2. List the available pg_probackup packages
    sudo apt-get update
    apt-cache search pg_probackup
  3. Install or upgrade a pg_probackup version of your choice
    sudo apt-get install pg_probackup-16
  4. Optionally install the debug package
    sudo apt-get install pg_probackup-16-debuginfo

Installation on SUSE Linux

  1. Add the pg_probackup repository GPG key
    zypper in -y gpg wget
    wget -O GPG-KEY-PG_PROBACKUP https://repo.postgrespro.ru/pg_probackup/keys/GPG-KEY-PG_PROBACKUP
    rpm --import GPG-KEY-PG_PROBACKUP
  2. Setup the repository
    zypper in https://repo.postgrespro.ru/pg_probackup/keys/pg_probackup-repo-suse.noarch.rpm
  3. List the available pg_probackup packages
    zypper se pg_probackup
  4. Install or upgrade a pg_probackup version of your choice
    zypper in pg_probackup-16
  5. Optionally install the source package for rebuilding the binaries
    zypper si pg_probackup-16

Setup

Once you have pg_probackup installed, complete the following setup:

Initializing the Backup Catalog

pg_probackup stores all WAL and backup files in the corresponding subdirectories of the backup catalog.

To initialize the backup catalog, run the following command:

pg_probackup init -B backupdir

where backupdir is the path to the backup catalog. If the backupdir already exists, it must be empty. Otherwise, pg_probackup returns an error.

The user launching pg_probackup must have full access to the backupdir directory.

pg_probackup creates the backupdir backup catalog, with the following subdirectories:

Once the backup catalog is initialized, you can add a new backup instance.

Adding a New Backup Instance

pg_probackup 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.

To add a new backup instance, run the following command:

pg_probackup add-instance -B backupdir -D datadir --instance=instancename [remoteoptions]

Where:

pg_probackup creates the instancename subdirectories under the backups/ and wal/ directories of the backup catalog. Thebackups/_`instancename`_ directory contains the pg_probackup.conf configuration file that controlspg_probackup settings for this backup instance. To addremote_options to the configuration file, use theset-config command.

For details on how to fine-tune pg_probackup configuration, seethe section called “Configuring pg_probackup”.

The user launching pg_probackup must have full access to_backupdir_ directory and at least read-only access to datadir directory. If you specify the path to the backup catalog in theBACKUP_PATH environment variable, you can omit the corresponding option when running pg_probackup commands.

Note

For PostgreSQL 11 or higher, it is recommended to use theallow-group-access 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.

Configuring the Database Cluster

Although pg_probackup 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 backup role is used as an example.

For security reasons, it is recommended to run the configuration SQL queries below in a separate database.

postgres=# CREATE DATABASE backupdb; postgres=# \c backupdb

To perform a backup, the following permissions for role backup are required only in the database used for connection to the PostgreSQL server.

For PostgreSQL versions 11 — 14:

BEGIN; CREATE ROLE backup WITH LOGIN; GRANT USAGE ON SCHEMA pg_catalog TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_start_backup(text, boolean, boolean) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup(boolean, boolean) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup; COMMIT;

For PostgreSQL 15 or higher:

BEGIN; CREATE ROLE backup WITH LOGIN; GRANT USAGE ON SCHEMA pg_catalog TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_start(text, boolean) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_stop(boolean) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup; GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup; COMMIT;

In thepg_hba.conf file, allow connection to the database cluster on behalf of thebackup role.

Since pg_probackup needs to read cluster files directly,pg_probackup 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 (PGDATA) you are going to back up.

Depending on whether you plan to takestandalone orarchive backups, PostgreSQL cluster configuration will differ, as specified in the sections below. To back up the database cluster from a standby server, run pg_probackup in the remote mode, or create PTRACK backups, additional setup is required.

For details, see the sectionsSetting up STREAM Backups,Setting up continuous WAL archiving,Setting up Backup from Standby,Configuring the Remote Mode,Setting up Partial Restore, andSetting up PTRACK Backups.

Setting up STREAM Backups

To set up the cluster forSTREAM backups, complete the following steps:

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 sectionSetting up continuous WAL archiving.

Once these steps are complete, you can start taking FULL, PAGE, DELTA, and PTRACK backups in theSTREAM WAL mode.

Note

If you are planning to rely on.pgpass for authentication when running backup in STREAM mode, then .pgpass must contain credentials for replication database, used to establish connection via replication protocol. Example: pghost:5432:replication:backup_user:my_strong_password

Setting up Continuous WAL Archiving

Making backups in PAGE backup mode, performingPITR and making backups withARCHIVE WAL delivery mode requirecontinuous WAL archiving to be enabled. To set up continuous archiving in the cluster, complete the following steps:

where installdir is the installation directory of the pg_probackup version you are going to use, backupdir and_instancename_ refer to the already initialized backup catalog instance for this database cluster, and remote_options only need to be specified to archive WAL on a remote host. For details about all possible archive-push parameters, see the section archive-push.

Once these steps are complete, you can start making backups in theARCHIVE WAL mode, backups in the PAGE backup mode, as well as performPITR.

You can view the current state of the WAL archive using theshow command. For details, seethe section called “Viewing WAL Archive Information”.

If you are planning to make PAGE backups and/or backups withARCHIVE 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 thearchive_timeout PostgreSQL parameter on master. The value of this parameter should be slightly lower than the --archive-timeout 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 --archive-timeout.

Note

Instead of using the archive-push command provided by pg_probackup, you can use any other tool to set up continuous archiving as long as it delivers WAL segments into_`backupdir`_/wal/_`instancename`_ directory. If compression is used, it should begzip, and .gz suffix in filename is mandatory.

Note

Instead of configuring continuous archiving by setting thearchive_mode and archive_command parameters, you can opt for using thepg_receivewal utility. In this case, pg_receivewal -D _`directory`_ option should point to_`backupdir`_/wal/_`instancename`_ directory. pg_probackup supports WAL compression that can be done by pg_receivewal.“Zero Data Loss” archive strategy can be achieved only by using pg_receivewal.

Setting up Backup from Standby

pg_probackup can take backups from a standby server. This requires the following additional setup:

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.

Backup from the standby server has the following limitations:

Setting up Cluster Verification

Logical verification of a database cluster requires the following additional setup. Role backup is used as an example:

GRANT SELECT ON TABLE pg_catalog.pg_am TO backup; GRANT SELECT ON TABLE pg_catalog.pg_class TO backup; GRANT SELECT ON TABLE pg_catalog.pg_database TO backup; GRANT SELECT ON TABLE pg_catalog.pg_namespace TO backup; GRANT SELECT ON TABLE pg_catalog.pg_extension TO backup; GRANT EXECUTE ON FUNCTION bt_index_check(regclass) TO backup; GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool) TO backup; GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool, bool) TO backup;

Setting up Partial Restore

If you are planning to use partial restore, complete the following additional step:

Configuring the Remote Mode

pg_probackup supports the remote mode that allows you to perform backup, restore and WAL archiving operations remotely. In this mode, the backup catalog is stored on a local system, whilePostgreSQL instance to backup and/or to restore is located on a remote system. Currently the only supported remote protocol is SSH.

Set up SSH

If you are going to use pg_probackup in remote mode via SSH, complete the following steps:

  1. Install pg_probackup on both systems:backup_host andpostgres_host.
  2. For communication between the hosts set up a passwordless SSH connection between the backup_user user onbackup_host and thepostgres user onpostgres_host:
    [backup_user@backup_host] ssh-copy-id postgres@postgres_host
    Where:
    • backup_host is the system with_backup catalog_.
    • postgres_host is the system with the PostgreSQL cluster.
    • backup_user is the OS user onbackup_host used to run pg_probackup.
    • postgres is the user onpostgres_host under whichPostgreSQL cluster processes are running. For PostgreSQL 11 or higher a more secure approach can be used thanks toallow-group-access feature.
  3. If you are going to rely oncontinuous WAL archiving, set up a passwordless SSH connection between the postgres user onpostgres_host and the backup user on backup_host:
    [postgres@postgres_host] ssh-copy-id backup_user@backup_host
  4. Make sure pg_probackup on postgres_host can be located when a connection via SSH is made. For example, for Bash, you can modify PATH in ~/.bashrc of the postgres user (above the line in bashrc that exits the script for non-interactive shells). Alternatively, for pg_probackup commands, specify the path to the directory containing the pg_probackup binary on postgres_host via the --remote-path option.

pg_probackup in the remote mode via SSH works as follows:

Note

You can imposeadditional restrictions on SSH settings to protect the system in the event of account compromise.

Setting up PTRACK Backups

The PTRACK backup mode can be used only for Postgres Pro Standard andPostgres Pro Enterprise installations, or patched vanilla PostgreSQL. Links to PTRACK patches can be foundhere.

Note

PTRACK versions lower than 2.0 are deprecated and not supported. Postgres Pro Standard and Postgres Pro Enterprise versions starting with 11.9.1 contain PTRACK 2.0. Upgrade your server to avoid issues in backups that you will take in future and be sure to take fresh backups of your clusters with the upgraded PTRACK since the backups taken with PTRACK 1.x might be corrupt.

If you are going to use PTRACK backups, complete the following additional steps. The role that will perform PTRACK backups (the backup role in the examples below) must have access to all the databases of the cluster.

For PostgreSQL 11 or higher:

  1. Create PTRACK extension:
    CREATE EXTENSION ptrack;
  2. To enable tracking page updates, set ptrack.map_size parameter to a positive integer and restart the server.
    For optimal performance, it is recommended to setptrack.map_size to_`N`_ / 1024, where_N_ is the size of thePostgreSQL 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 ptrack.map_size to a higher value does not affect PTRACK operation, but it is not recommended to set this parameter to a value higher than 1024.

Note

If you change the ptrack.map_size 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 ptrack.map_size.

Usage

Creating a Backup

To create a backup, run the following command:

pg_probackup backup -B backupdir --instance=instancename -b backupmode

Where backupmode can take one of the following values:[FULL](#pbk-modes-full),[DELTA](#pbk-modes-delta),[PAGE](#pbk-modes-page), and[PTRACK](#pbk-modes-ptrack).

When restoring a cluster from an incremental backup,pg_probackup relies on the parent full backup and all the incremental backups between them, which is called“the backup chain”. You must create at least one full backup before taking incremental ones.

ARCHIVE Mode

ARCHIVE is the default WAL delivery mode.

For example, to make a FULL backup in ARCHIVE mode, run:

pg_probackup backup -B backupdir --instance=instancename -b FULL

ARCHIVE backups rely oncontinuous archiving to get WAL segments required to restore the cluster to a consistent state at the time the backup was taken.

When a backup is taken, pg_probackup ensures that WAL files containing WAL records between Start LSN and Stop LSN actually exist in_`backupdir`_/wal/_`instancename`_ directory. pg_probackup also ensures that WAL records betweenStart LSN and Stop LSN can be parsed. This precaution eliminates the risk of silent WAL corruption.

STREAM Mode

STREAM is the optional WAL delivery mode.

For example, to make a FULL backup in the STREAM mode, add the--stream flag to the command from the previous example:

pg_probackup backup -B backupdir --instance=instancename -b FULL --stream --temp-slot

The optional --temp-slot flag ensures that the required segments remain available if the WAL is rotated before the backup is complete.

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.

During backup pg_probackup streams WAL files containing WAL records between Start LSN andStop LSN to_`backupdir`_/backups/_`instancename`_/_`backupid`_/database/pg_wal directory. To eliminate the risk of silent WAL corruption, pg_probackup also checks that WAL records between Start LSN andStop LSN can be parsed.

Even if you are usingcontinuous archiving, STREAM backups can still be useful in the following cases:

Page Validation

Ifdata checksums are enabled in the database cluster,pg_probackup uses this information to check correctness of data files during backup. While reading each page,pg_probackup checks whether the calculated checksum coincides with the checksum stored in the page header. This guarantees that the PostgreSQL instance and the backup itself have no corrupt pages. Note that pg_probackup 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.

A page is considered corrupt if checksum comparison has failed more than 100 times. In this case, the backup is aborted.

Even if data checksums are not enabled, pg_probackup always performs sanity checks for page headers.

External Directories

To back up a directory located outside of the data directory, use the optional --external-dirs 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.

For example, to include /etc/dir1 and/etc/dir2 directories into the full backup of your instancename instance that will be stored under the backupdir directory on Linux, run:

pg_probackup backup -B backupdir --instance=instancename -b FULL --external-dirs=/etc/dir1:/etc/dir2

Similarly, to include C:\dir1 andC:\dir2 directories into the full backup on Windows, run:

pg_probackup backup -B backupdir --instance=instancename -b FULL --external-dirs=C:\dir1;C:\dir2

pg_probackup 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.

To include the same directories into each backup of your instance, you can specify them in the pg_probackup.conf configuration file using theset-config command with the--external-dirs option.

Performing Cluster Verification

To verify that PostgreSQL database cluster is not corrupt, run the following command:

pg_probackup checkdb [-B backupdir [--instance=instancename]] [-D datadir] [connectionoptions]

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, checkdb continues cluster verification until all pages in the cluster are validated.

By default, similar page validation is performed automatically while a backup is taken bypg_probackup. The checkdb command enables you to perform such page validation on demand, without taking any backup copies, even if the cluster is not backed up using pg_probackup at all.

To perform cluster verification, pg_probackup needs to connect to the cluster to be verified. In general, it is enough to specify the backup instance of this cluster forpg_probackup to determine the required connection options. However, if -B and--instance options are omitted, you have to provideconnection options and_datadir_ via environment variables or command-line options.

Physical verification cannot detect logical inconsistencies, missing or nullified blocks and entire files, or similar anomalies. Extensionsamcheck andamcheck_next provide a partial solution to these problems.

If you would like, in addition to physical verification, to verify all indexes in all databases using these extensions, you can specify the --amcheck flag when running the checkdb command:

pg_probackup checkdb -D datadir --amcheck [connectionoptions]

You can skip physical verification by specifying the--skip-block-validation flag. In this case, you can omit backup_dir and_data_dir_ options, onlyconnection options are mandatory:

pg_probackup checkdb --amcheck --skip-block-validation [connectionoptions]

Logical verification can be done more thoroughly with the--heapallindexed 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.

Validating a Backup

pg_probackup calculates checksums for each file in a backup during the backup process. The process of checking checksums of backup data files is called_the backup validation_. By default, validation is run immediately after the backup is taken and right before the restore, to detect possible backup corruption.

If you would like to skip backup validation, you can specify the--no-validate flag when runningbackup andrestore commands.

To ensure that all the required backup files are present and can be used to restore the database cluster, you can run thevalidate command with the exactrecovery target options you are going to use for recovery.

For example, to check that you can restore the database cluster from a backup copy up to transaction ID 4242, run this command:

pg_probackup validate -B backupdir --instance=instancename --recovery-target-xid=4242

If validation completes successfully, pg_probackup 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.

If you specify backup_id via-i/--backup-id option, then only the backup copy with specified backup ID will be validated. If_backup_id_ is specified withrecovery target options, the validate command will check whether it is possible to restore the specified backup to the specified recovery target.

For example, to check that you can restore the database cluster from a backup copy with the SCUN2C backup ID up to the specified timestamp, run this command:

pg_probackup validate -B backupdir --instance=instancename -i SCUN2C --recovery-target-time="2024-05-03 11🔞13+03"

If you specify the backupid of an incremental backup, all its parents starting from FULL backup will be validated.

If you omit all the parameters, all backups are validated.

Restoring a Cluster

To restore the database cluster from a backup, run the restore command with at least the following options:

pg_probackup restore -B backupdir --instance=instancename -i backupid

Where:

Once the restore command is complete, start the database service.

If you restore ARCHIVE backups, perform PITR, or specify the --restore-as-replica flag with therestore command to set up a standby server,pg_probackup 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 theprimary_conninfo parameter; you have to add the password manually or use the --primary-conninfo option, if required. For PostgreSQL 11, recovery settings are written into the recovery.conf file. Starting from PostgreSQL 12,pg_probackup writes these settings into the probackup_recovery.conf file and then includes it into postgresql.auto.conf.

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,PostgreSQL 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 therecovery target options with the restore command, as explained in the section called “Performing Point-in-Time (PITR) Recovery”.

If the cluster to restore contains tablespaces, pg_probackup restores them to their original location by default. To restore tablespaces to a different location, use the--tablespace-mapping/-T 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.

When using the --tablespace-mapping/-T option, you must provide absolute paths to the old and new tablespace directories. If a path happens to contain an equals sign (=), escape it with a backslash. This option can be specified multiple times for multiple tablespaces. For example:

pg_probackup restore -B backupdir --instance=instancename -D datadir -j 4 -i backupid -T tablespace1_dir=tablespace1newdir -T tablespace2_dir=tablespace2newdir

To restore the cluster on a remote host, follow the instructions inthe section called “Using pg_probackup in the Remote Mode”.

Note

By default, the 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--no-validate flag to skip validation and speed up the recovery.

Incremental Restore

The speed of restore from backup can be significantly improved by replacing only invalid and changed pages in already existing PostgreSQL data directory usingincremental restore options with the restore command.

To restore the database cluster from a backup in incremental mode, run the restore command with the following options:

pg_probackup restore -B backupdir --instance=instancename -D datadir -I incrementalmode

Where incrementalmode can take one of the following values:

Regardless of chosen incremental mode, pg_probackup will check, that postmaster in given destination directory is not running and system-identifier is the same as in the backup.

Suppose you want to return an old master as replica after switchover using incremental restore in LSN mode:

====================================================================================================================================== Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status

node 16 SCUN3Y 2024-05-02 11:19:16+03 DELTA STREAM 16/15 7s 92MB 208MB 2.27 0/3C0043A8 0/46159C70 OK
node 16 SCUN3M 2024-05-02 11:19:01+03 PTRACK STREAM 15/15 10s 30MB 16MB 2.23 0/32000028 0/32005ED0 OK
node 16 SCUN39 2024-05-02 11🔞50+03 PAGE STREAM 15/15 12s 46MB 32MB 1.44 0/2A000028 0/2B0000B8 OK
node 16 SCUN2V 2024-05-02 11🔞38+03 FULL STREAM 15/0 11s 154MB 16MB 2.32 0/23000028 0/23000168 OK

backup_user@backup_host:~$ pg_probackup-16 restore -B /mnt/backups --instance=node -R -I lsn INFO: Destination directory and tablespace directories are empty, disable incremental restore INFO: Validating parents for backup SCUN3Y INFO: Validating backup SCUN2V INFO: Backup SCUN2V data files are valid INFO: Validating backup SCUN39 INFO: Backup SCUN39 data files are valid INFO: Validating backup SCUN3M INFO: Backup SCUN3M data files are valid INFO: Validating backup SCUN3Y INFO: Backup SCUN3Y data files are valid INFO: Backup SCUN3Y WAL segments are valid INFO: Backup SCUN3Y is valid. INFO: Restoring the database from backup SCUN3Y INFO: Start restoring backup files. PGDATA size: 759MB INFO: Backup files are restored. Transfered bytes: 759MB, time elapsed: 3s INFO: Restore incremental ratio (less is better): 100% (759MB/759MB) INFO: Syncing restored files to disk INFO: Restored backup files are synced, time elapsed: 1s INFO: Restore of backup SCUN3Y completed.

Note

Incremental restore is possible only for backups withprogram_version equal or greater than 2.4.0.

Partial Restore

If you have enabledpartial restore before taking backups, you can restore only some of the databases usingpartial restore options with the restore commands.

To restore the specified databases only, run the restore command with the following options:

pg_probackup restore -B backupdir --instance=instancename --db-include=databasename

The --db-include option can be specified multiple times. For example, to restore only databasesdb1 and db2, run the following command:

pg_probackup restore -B backupdir --instance=instancename --db-include=db1 --db-include=db2

To exclude one or more databases from restore, use the --db-exclude option:

pg_probackup restore -B backupdir --instance=instancename --db-exclude=databasename

The --db-exclude option can be specified multiple times. For example, to exclude the databasesdb1 and db2 from restore, run the following command:

pg_probackup restore -B backupdir --instance=instancename --db-exclude=db1 --db-exclude=db2

Partial restore relies on lax behavior of PostgreSQL recovery process toward truncated files. For recovery to work properly, files of excluded databases are restored as files of zero size. After the PostgreSQL cluster is successfully started, you must drop the excluded databases usingDROP DATABASE command.

To decouple a single cluster containing multiple databases into separate clusters with minimal downtime, you can do partial restore of the cluster as a standby using the --restore-as-replica option for specific databases.

Note

The template0 andtemplate1 databases are always restored.

Note

Due to recovery specifics of PostgreSQL versions earlier than 12, it is advisable that you set thehot_standby parameter to off when running partial restore of a PostgreSQL cluster of version earlier than 12. Otherwise the recovery may fail.

Performing Point-in-Time (PITR) Recovery

If you have enabledcontinuous WAL archiving before taking backups, you can restore the cluster to its state at an arbitrary point in time (recovery target) using recovery target options with therestore command.

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 -i/--backup-id option is omitted,pg_probackup automatically chooses the backup that is the closest to the specified recovery target and starts the restore process, otherwise pg_probackup will try to restore the specified backup to the specified recovery target.

Using pg_probackup in the Remote Mode

pg_probackup supports the remote mode that allows you to performbackup and restore operations remotely via SSH. In this mode, the backup catalog is stored on a local system, while PostgreSQL instance to be backed up is located on a remote system. You must have pg_probackup installed on both systems.

Note

pg_probackup relies on passwordless SSH connection for communication between the hosts.

Note

In addition to SSH connection, pg_probackup uses a regular connection to the database to manage the remote operation. See the section Configuring the Database Cluster for details of how to set up a database connection.

The typical workflow is as follows:

For example, to create an archive full backup of aPostgreSQL cluster located on a remote system with host address 192.168.0.2 on behalf of the postgres user via SSH connection through port 2302, run:

pg_probackup backup -B backupdir --instance=instancename -b FULL --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302

To restore the latest available backup on a remote system with host address192.168.0.2 on behalf of the postgres user via SSH connection through port 2302, run:

pg_probackup restore -B backupdir --instance=instancename --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302

Restoring an ARCHIVE backup or performing PITR in the remote mode require additional information: destination address, port and username for establishing an SSH connectionfrom the host with databaseto the host with the backup catalog. This information will be used by therestore_command to copy WAL segments from the archive to the PostgreSQL pg_wal directory.

To solve this problem, you can useRemote WAL Archive Options.

For example, to restore latest backup on remote system using remote mode through SSH connection to userpostgres on host with address192.168.0.2 via port 2302 and user backup on backup catalog host with address 192.168.0.3 via port2303, run:

pg_probackup restore -B backupdir --instance=instancename --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --archive-host=192.168.0.3 --archive-port=2303 --archive-user=backup

Provided arguments will be used to construct the restore_command:

restore_command = '"installdir/pg_probackup" archive-get -B "backupdir" --instance=instancename --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'

Alternatively, you can use the --restore-command option to provide the entire restorecommand:

pg_probackup restore -B backupdir --instance=instancename --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --restore-command='"installdir/pg_probackup" archive-get -B "backupdir" --instance=instancename --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'

Note

The remote mode is currently unavailable for Windows systems.

Running pg_probackup on Parallel Threads

backup,restore,merge,delete,catchup,checkdb, andvalidate processes can be executed on several parallel threads. This can significantly speed up pg_probackup operation given enough resources (CPU cores, disk, and network bandwidth).

Parallel execution is controlled by the-j/--threads command-line option. For example, to create a backup using four parallel threads, run:

pg_probackup backup -B backupdir --instance=instancename -b FULL -j 4

Note

Parallel restore applies only to copying data from the backup catalog to the data directory of the cluster. WhenPostgreSQL server is started, WAL records need to be replayed, and this cannot be done in parallel.

Configuring pg_probackup

Once the backup catalog is initialized and a new backup instance is added, you can use the pg_probackup.conf configuration file located in the_`backupdir`_/backups/_`instancename`_ directory to fine-tune pg_probackup configuration.

For example, backup andcheckdb commands use a regularPostgreSQL connection. To avoid specifyingconnection options each time on the command line, you can set them in thepg_probackup.conf configuration file using theset-config command.

Note

It is not recommended to edit pg_probackup.conf manually.

Initially, pg_probackup.conf contains the following settings:

Additionally, you can defineremote,retention,logging, andcompression settings using the set-config command:

pg_probackup set-config -B backupdir --instance=instancename [--external-dirs=externaldirectorypath] [remoteoptions] [connectionoptions] [retentionoptions] [loggingoptions]

To view the current settings, run the following command:

pg_probackup show-config -B backupdir --instance=instancename

You can override the settings defined in pg_probackup.conf when running pg_probackup commands via the corresponding environment variables and/or command line options.

Specifying Connection Settings

If you define connection settings in the pg_probackup.conf configuration file, you can omit connection options in all the subsequent pg_probackup 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.

If nothing is given, the default values are taken. By defaultpg_probackup tries to use local connection via Unix domain socket (localhost on Windows) and tries to get the database name and the user name from the PGUSER environment variable or the current OS user name.

Managing the Backup Catalog

With pg_probackup, you can manage backups from the command line:

Viewing Backup Information

To view the list of existing backups for every instance, run the command:

pg_probackup show -B backupdir

pg_probackup displays the list of all the available backups. For example:

BACKUP INSTANCE 'node'

Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status

node 16 SCUN4E 2024-05-02 11:19:37+03 FULL ARCHIVE 1/0 13s 239MB 16MB 2.31 0/4C000028 0/4D0000B8 OK
node 16 SCUN3Y 2024-05-02 11:19:16+03 DELTA STREAM 1/1 7s 92MB 208MB 2.27 0/3C0043A8 0/46159C70 OK
node 16 SCUN3M 2024-05-02 11:19:01+03 PTRACK STREAM 1/1 10s 30MB 16MB 2.23 0/32000028 0/32005ED0 OK
node 16 SCUN39 2024-05-02 11🔞50+03 PAGE STREAM 1/1 12s 46MB 32MB 1.44 0/2A000028 0/2B0000B8 OK
node 16 SCUN2V 2024-05-02 11🔞38+03 FULL STREAM 1/0 11s 154MB 16MB 2.32 0/23000028 0/23000168 OK

For each backup, the following information is provided:

You can restore the cluster from the backup only if the backup status is OK or DONE.

To get more detailed information about the backup, run theshow command with the backup ID:

pg_probackup show -B backupdir --instance=instancename -i backupid

The sample output is as follows:

#Configuration backup-mode = FULL stream = false compress-alg = zlib compress-level = 1 from-replica = false

#Compatibility block-size = 8192 xlog-block-size = 8192 checksum-version = 1 program-version = 2.5.15 server-version = 16

#Result backup info timelineid = 1 start-lsn = 0/4C000028 stop-lsn = 0/4D0000B8 start-time = '2024-05-02 11:19:26+03' end-time = '2024-05-02 11:19:39+03' recovery-xid = 743 recovery-time = '2024-05-02 11:19:37+03' data-bytes = 250827955 wal-bytes = 16777216 uncompressed-bytes = 578216425 pgdata-bytes = 578216107 status = OK primary_conninfo = 'user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable' content-crc = 802820606

Detailed output has additional attributes:

You can also get the detailed information about the backup in the JSON format:

pg_probackup show -B backupdir --instance=instancename --format=json -i backup_id

The sample output is as follows:

[ { "instance": "node", "backups": [ { "id": "SCUN4E", "backup-mode": "FULL", "wal": "ARCHIVE", "compress-alg": "zlib", "compress-level": 1, "from-replica": "false", "block-size": 8192, "xlog-block-size": 8192, "checksum-version": 1, "program-version": "2.5.15", "server-version": "16", "current-tli": 16, "parent-tli": 2, "start-lsn": "0/4C000028", "stop-lsn": "0/4D0000B8", "start-time": "2024-05-02 11:19:26+03", "end-time": "2024-05-02 11:19:39+03", "recovery-xid": 743, "recovery-time": "2024-05-02 11:19:37+03", "data-bytes": 250827955, "wal-bytes": 16777216, "uncompressed-bytes": 578216425, "pgdata-bytes": 578216107, "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable", "status": "OK", "content-crc": 802820606 } ] } ]

Viewing WAL Archive Information

To view the information about WAL archive for every instance, run the command:

pg_probackup show -B backupdir [--instance=instancename] --archive

pg_probackup displays the list of all the available WAL files grouped by timelines. For example:

ARCHIVE INSTANCE 'node'

TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status

1 0 0/0 000000010000000000000019 00000001000000000000004D 53 848MB 1.00 5 OK

For each timeline, the following information is provided:

To get more detailed information about the WAL archive in the JSON format, run the command:

pg_probackup show -B backupdir [--instance=instancename] --archive --format=json

The sample output is as follows:

[ { "instance": "node", "timelines": [ { "tli": 1, "parent-tli": 0, "switchpoint": "0/0", "min-segno": "000000010000000000000019", "max-segno": "00000001000000000000004D", "n-segments": 53, "size": 889192448, "zratio": 1.00, "closest-backup-id": "", "status": "OK", "lost-segments": [], "backups": [ { "id": "SCUN4E", "backup-mode": "FULL", "wal": "ARCHIVE", "compress-alg": "zlib", "compress-level": 1, "from-replica": "false", "block-size": 8192, "xlog-block-size": 8192, "checksum-version": 1, "program-version": "2.5.15", "server-version": "16", "current-tli": 1, "parent-tli": 0, "start-lsn": "0/4C000028", "stop-lsn": "0/4D0000B8", "start-time": "2024-05-02 11:19:26+03", "end-time": "2024-05-02 11:19:39+03", "recovery-xid": 743, "recovery-time": "2024-05-02 11:19:37+03", "data-bytes": 250827955, "wal-bytes": 16777216, "uncompressed-bytes": 578216425, "pgdata-bytes": 578216107, "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable", "status": "OK", "content-crc": 802820606 }, { "id": "SCUN3Y", "parent-backup-id": "SCUN3M", "backup-mode": "DELTA", "wal": "STREAM", "compress-alg": "zlib", "compress-level": 1, "from-replica": "false", "block-size": 8192, "xlog-block-size": 8192, "checksum-version": 1, "program-version": "2.5.15", "server-version": "16", "current-tli": 1, "parent-tli": 1, "start-lsn": "0/3C0043A8", "stop-lsn": "0/46159C70", "start-time": "2024-05-02 11:19:10+03", "end-time": "2024-05-02 11:19:17+03", "recovery-xid": 743, "recovery-time": "2024-05-02 11:19:16+03", "data-bytes": 96029293, "wal-bytes": 218103808, "uncompressed-bytes": 217639806, "pgdata-bytes": 578216107, "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable", "status": "OK", "content-crc": 3074300814 }, { "id": "SCUN3M", "parent-backup-id": "SCUN39", "backup-mode": "PTRACK", "wal": "STREAM", "compress-alg": "zlib", "compress-level": 1, "from-replica": "false", "block-size": 8192, "xlog-block-size": 8192, "checksum-version": 1, "program-version": "2.5.15", "server-version": "16", "current-tli": 1, "parent-tli": 1, "start-lsn": "0/32000028", "stop-lsn": "0/32005ED0", "start-time": "2024-05-02 11🔞58+03", "end-time": "2024-05-02 11:19:08+03", "recovery-xid": 742, "recovery-time": "2024-05-02 11:19:01+03", "data-bytes": 31205704, "wal-bytes": 16777216, "uncompressed-bytes": 69585790, "pgdata-bytes": 509927595, "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable", "status": "OK", "content-crc": 3446949708 }, { "id": "SCUN39", "parent-backup-id": "SCUN2V", "backup-mode": "PAGE", "wal": "STREAM", "compress-alg": "pglz", "compress-level": 1, "from-replica": "false", "block-size": 8192, "xlog-block-size": 8192, "checksum-version": 1, "program-version": "2.5.15", "server-version": "16", "current-tli": 1, "parent-tli": 1, "start-lsn": "0/2A000028", "stop-lsn": "0/2B0000B8", "start-time": "2024-05-02 11🔞45+03", "end-time": "2024-05-02 11🔞57+03", "recovery-xid": 741, "recovery-time": "2024-05-02 11🔞50+03", "data-bytes": 48381612, "wal-bytes": 33554432, "uncompressed-bytes": 69569406, "pgdata-bytes": 441639083, "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable", "status": "OK", "content-crc": 3492989773 }, { "id": "SCUN2V", "backup-mode": "FULL", "wal": "STREAM", "compress-alg": "zlib", "compress-level": 1, "from-replica": "false", "block-size": 8192, "xlog-block-size": 8192, "checksum-version": 1, "program-version": "2.5.15", "server-version": "16", "current-tli": 1, "parent-tli": 0, "start-lsn": "0/23000028", "stop-lsn": "0/23000168", "start-time": "2024-05-02 11🔞31+03", "end-time": "2024-05-02 11🔞42+03", "recovery-xid": 740, "recovery-time": "2024-05-02 11🔞38+03", "data-bytes": 161084290, "wal-bytes": 16777216, "uncompressed-bytes": 373359081, "pgdata-bytes": 373358763, "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable", "status": "OK", "content-crc": 1621343133 } ] } ] } ]

Most fields are consistent with the plain format, with some exceptions:

Configuring Retention Policy

With pg_probackup, you can configure retention policy to remove redundant backups, clean up unneeded WAL files, as well as pin specific backups to ensure they are kept for the specified time, as explained in the sections below. All these actions can be combined together in any way.

Removing Redundant Backups

By default, all backup copies created with pg_probackup are stored in the specified backup catalog. To save disk space, you can configure retention policy to remove redundant backup copies.

To configure retention policy, set one or more of the following variables in the pg_probackup.conf file viaset-config:

--retention-redundancy=redundancy

Specifies the number of full backup copies to keep in the backup catalog.

--retention-window=window

Defines the earliest point in time for which pg_probackup can complete the recovery. This option is set inthe number of days from the current moment. For example, ifretention-window=7, pg_probackup must keep at least one backup copy that is older than seven days, with all the corresponding WAL files, and all the backups that follow.

If both --retention-redundancy and--retention-window options are set, both these conditions have to be taken into account when purging the backup catalog. For example, if you set --retention-redundancy=2 and --retention-window=7,pg_probackup has to keep two full backup copies, as well as all the backups required to ensure recoverability for the last seven days:

pg_probackup set-config -B backupdir --instance=instancename --retention-redundancy=2 --retention-window=7

To clean up the backup catalog in accordance with retention policy, you have to run the delete command withretention flags, as shown below, or use the backup command with these flags to process the outdated backup copies right when the new backup is created.

For example, to remove all backup copies that no longer satisfy the defined retention policy, run the following command with the--delete-expired flag:

pg_probackup delete -B backupdir --instance=instancename --delete-expired

If you would like to also remove the WAL files that are no longer required for any of the backups, you should also specify the--delete-wal flag:

pg_probackup delete -B backupdir --instance=instancename --delete-expired --delete-wal

You can also set or override the current retention policy by specifying --retention-redundancy and--retention-window options directly when running delete or backup commands:

pg_probackup delete -B backupdir --instance=instancename --delete-expired --retention-window=7 --retention-redundancy=2

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--merge-expired flag when runningbackup ordelete commands.

Suppose you have backed up the node instance in the backupdir directory, with the --retention-window option set to 7, and you have the following backups available on May 02, 2024:

BACKUP INSTANCE 'node'

Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status

node 16 SCUN6L 2024-05-02 11:20:48+03 FULL ARCHIVE 1/0 5s 296MB 16MB 2.30 0/46000028 0/470000B8 OK
node 16 SCQXUI 2024-04-30 11:20:45+03 PAGE ARCHIVE 1/1 5s 6280kB 16MB 1.00 0/44000028 0/450000F0 OK
node 16 SCFTUG 2024-04-24 11:20:43+03 DELTA ARCHIVE 1/1 5s 6280kB 16MB 1.00 0/42000028 0/430000B8 OK
----------------------------------------------------------retention window----------------------------------------------------------- node 16 SCDZ6D 2024-04-23 11:20:40+03 PAGE ARCHIVE 1/1 5s 6280kB 16MB 1.00 0/40000028 0/410000B8 OK
node 16 SCC4HX 2024-04-22 11:20:24+03 FULL ARCHIVE 1/0 5s 296MB 16MB 2.30 0/3E000028 0/3F0000F0 OK
node 16 SC8F5G 2024-04-20 11:20:07+03 FULL ARCHIVE 1/0 5s 296MB 16MB 2.30 0/3C0000D8 0/3D00BB58 OK

Even though SCC4HX and SCDZ6D backups are outside the retention window, they cannot be removed as it invalidates the succeeding incremental backups SCFTUG and SCQXUI that are still required, so, if you run thedelete command with the--delete-expired flag, only the SC8F5G full backup will be removed.

With the --merge-expired option, the SCFTUG backup is merged with the underlying SCDZ6D and SCC4HX backups and becomes a full one, so there is no need to keep these expired backups anymore:

pg_probackup delete -B backupdir --instance=node --delete-expired --merge-expired pg_probackup show -B backupdir

BACKUP INSTANCE 'node'

Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status

node 16 SCUN6L 2024-05-02 11:20:48+03 FULL ARCHIVE 1/0 5s 296MB 16MB 2.30 0/46000028 0/470000B8 OK
node 16 SCQXUI 2024-04-30 11:20:45+03 PAGE ARCHIVE 1/1 5s 6280kB 16MB 1.00 0/44000028 0/450000F0 OK
node 16 SCFTUG 2024-04-24 11:20:43+03 FULL ARCHIVE 1/1 5s 296MB 16MB 1.00 0/42000028 0/430000B8 OK

The Time field for the merged backup displays the time required for the merge.

Pinning Backups

If you need to keep certain backups longer than the established retention policy allows, you can pin them for arbitrary time. For example:

pg_probackup set-backup -B backupdir --instance=instancename -i backupid --ttl=30d

This command sets the expiration time of the specified backup to 30 days starting from the time indicated in its recovery-time attribute.

You can also explicitly set the expiration time for a backup using the --expire-time option. For example:

pg_probackup set-backup -B backupdir --instance=instancename -i backupid --expire-time="2027-05-02 11:21:00+00"

Alternatively, you can use the --ttl and--expire-time options with thebackup command to pin the newly created backup:

pg_probackup backup -B backupdir --instance=instancename -b FULL --ttl=30d pg_probackup backup -B backupdir --instance=instancename -b FULL --expire-time="2027-05-02 11:21:00+00"

To check if the backup is pinned, run the show command:

pg_probackup show -B backupdir --instance=instancename -i backupid

If the backup is pinned, it has the expire-time attribute that displays its expiration time:

... recovery-time = '2024-05-02 11:21:00+00' expire-time = '2027-05-02 11:21:00+00' data-bytes = 22288792 ...

You can unpin the backup by setting the --ttl option to zero:

pg_probackup set-backup -B backupdir --instance=instancename -i backupid --ttl=0

Note

A pinned incremental backup implicitly pins all its parent backups. If you unpin such a backup later, its implicitly pinned parents will also be automatically unpinned.

Configuring WAL Archive Retention Policy

When continuous WAL archiving is enabled, archived WAL segments can take a lot of disk space. Even if you delete old backup copies from time to time, the --delete-wal flag can purge only those WAL segments that do not apply to any of the remaining backups in the backup catalog. However, if point-in-time recovery is critical only for the most recent backups, you can configure WAL archive retention policy to keep WAL archive of limited depth and win back some more disk space.

To configure WAL archive retention policy, you have to run theset-config command with the--wal-depth option that specifies the number of backups that can be used for PITR. This setting applies to all the timelines, so you should be able to perform PITR for the same number of backups on each timeline, if available.Pinned backups are not included into this count: if one of the latest backups is pinned, pg_probackup ensures that PITR is possible for one extra backup.

To remove WAL segments that do not satisfy the defined WAL archive retention policy, you simply have to run the delete or backup command with the --delete-wal flag. For archive backups, WAL segments between Start LSN and Stop LSN are always kept intact, so such backups remain valid regardless of the --wal-depth setting and can still be restored, if required.

You can also use the --wal-depth option with the delete and backup commands to override the previously defined WAL archive retention policy and purge old WAL segments on the fly.

Suppose you have backed up the node instance in the backupdir directory and configuredcontinuous WAL archiving:

pg_probackup show -B backupdir --instance=node

====================================================================================================================================== Instance Version ID Recovery Time Mode WAL Mode TLI Time Data WAL Zratio Start LSN Stop LSN Status

node 16 SCUN92 2024-05-02 11:22:16+03 DELTA STREAM 1/1 9s 1162kB 32MB 1.08 0/7C000028 0/7C000168 OK
node 16 SCUN8N 2024-05-02 11:22:09+03 FULL STREAM 1/0 12s 296MB 16MB 2.30 0/7A000028 0/7A009A08 OK
node 16 SCUN8I 2024-05-02 11:21:55+03 DELTA STREAM 1/1 5s 1148kB 32MB 1.01 0/78000028 0/78000168 OK
node 16 SCUN86 2024-05-02 11:21:47+03 DELTA STREAM 1/1 11s 120MB 16MB 2.27 0/76000028 0/760001A0 OK
node 16 SCUN7I 2024-05-02 11:21:29+03 FULL STREAM 1/0 22s 296MB 288MB 2.30 0/63012FE8 0/74E7ADA0 OK
node 16 SCUN71 2024-05-02 11:21:12+03 FULL STREAM 1/0 13s 296MB 272MB 2.30 0/49000028 0/573683B8 OK

You can check the state of the WAL archive by running theshow command with the--archive flag:

pg_probackup show -B backupdir --instance=node --archive

ARCHIVE INSTANCE 'node'

TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status

1 0 0/0 000000010000000000000048 00000001000000000000007C 53 848MB 1.00 6 OK

WAL purge without --wal-depth cannot achieve much, only one segment is removed:

pg_probackup delete -B backupdir --instance=node --delete-wal

ARCHIVE INSTANCE 'node'

TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status

1 0 0/0 000000010000000000000049 00000001000000000000007C 52 832MB 1.00 6 OK

If you would like, for example, to keep only those WAL segments that can be applied to the latest valid backup, set the--wal-depth option to 1:

pg_probackup delete -B backupdir --instance=node --delete-wal --wal-depth=1

ARCHIVE INSTANCE 'node'

TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status

1 0 0/0 00000001000000000000007C 00000001000000000000007C 1 16MB 1.00 6 OK

Alternatively, you can use the --wal-depth option with the backup command:

pg_probackup backup -B backupdir --instance=node -b DELTA --wal-depth=1 --delete-wal

ARCHIVE INSTANCE 'node'

TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status

1 0 0/0 00000001000000000000007E 00000001000000000000007E 1 16MB 1.00 7 OK

Merging Backups

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 merge command, specifying the backup ID of the most recent incremental backup you would like to merge:

pg_probackup merge -B backupdir --instance=instancename -i backupid

This command merges backups that belong to a common incremental backup chain. If you specify a full backup, it will be merged with its first incremental backup. If you specify an incremental backup, it will be merged to its parent full backup, together with all incremental backups between them. Once the merge is complete, the full backup takes in all the merged data, and the incremental backups are removed as redundant. Thus, the merge operation is virtually equivalent to retaking a full backup and removing all the outdated backups, but it allows you to save much time, especially for large data volumes, as well as I/O and network traffic if you are using pg_probackup in theremote mode.

Before the merge, pg_probackup validates all the affected backups to ensure that they are valid. You can check the current backup status by running the show command with the backup ID:

pg_probackup show -B backupdir --instance=instancename -i backupid

If the merge is still in progress, the backup status is displayed as MERGING. For full backups, it can also be shown as MERGED while the metadata is being updated at the final stage of the merge. The merge is idempotent, so you can restart the merge if it was interrupted.

Deleting Backups

To delete a backup that is no longer required, run the following command:

pg_probackup delete -B backupdir --instance=instancename -i backupid

This command will delete the backup with the specified_backupid, together with all the incremental backups that descend frombackupid_, 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.

To delete obsolete WAL files that are not necessary to restore any of the remaining backups, use the--delete-wal flag:

pg_probackup delete -B backupdir --instance=instancename --delete-wal

To delete backups that are expired according to the current retention policy, use the --delete-expired flag:

pg_probackup delete -B backupdir --instance=instancename --delete-expired

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--merge-expired flag when running this command:

pg_probackup delete -B backupdir --instance=instancename --delete-expired --merge-expired

In this case, pg_probackup 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.

Before merging or deleting backups, you can run thedelete command with the--dry-run flag, which displays the status of all the available backups according to the current retention policy, without performing any irreversible actions.

To delete all backups with specific status, use the --status:

pg_probackup delete -B backupdir --instance=instancename --status=ERROR

Deleting backups by status ignores established retention policies.

Cloning and Synchronizing PostgreSQL Instance

pg_probackup can create a copy of a PostgreSQL instance directly, without using the backup catalog. To do this, you can run the catchup command. It can be useful in the following cases:

catchup is different from other pg_probackup operations:

To prepare for cloning/synchronizing a PostgreSQL instance, set up the source server as follows:

Before cloning/synchronizing a PostgreSQL instance, ensure that the source server is running and accepting connections. To clone/sync a PostgreSQL instance, on the server with the destination instance, you can run the catchup command as follows:

pg_probackup catchup -b catchupmode --source-pgdata=pathtopgdataonremoteserver --destination-pgdata=pathtolocaldir --stream [connectionoptions] [remoteoptions]

Where catchupmode can take one of the following values:

Warning

PTRACK catchup mode requires PTRACK not earlier than 2.0 and hence, PostgreSQL not earlier than 11.

By specifying the --stream option, you can setSTREAM WAL delivery mode of copying, which will include all the necessary WAL files by streaming them from the server via replication protocol.

You can use connection_options to specify the connection to the source database cluster. If it is located on a different server, also specify remote_options.

If the source database cluster contains tablespaces that must be located in a different directory, additionally specify the --tablespace-mapping option:

pg_probackup catchup -b catchupmode --source-pgdata=pathtopgdataonremoteserver --destination-pgdata=pathtolocaldir --stream --tablespace-mapping=OLDDIR=NEWDIR

To run the catchup command on parallel threads, specify the number of threads with the --threads option:

pg_probackup catchup -b catchupmode --source-pgdata=pathtopgdataonremoteserver --destination-pgdata=pathtolocaldir --stream --threads=numthreads

Before cloning/synchronising a PostgreSQL instance, you can run thecatchup command with the --dry-run flag to estimate the size of data files to be transferred, but make no changes on disk:

pg_probackup catchup -b catchupmode --source-pgdata=pathtopgdataonremoteserver --destination-pgdata=pathtolocaldir --stream --dry-run

For example, assume that a remote standby server with the PostgreSQL instance having /replica-pgdata data directory has fallen behind. To sync this instance with the one in /master-pgdata data directory, you can run the catchup command in the PTRACK mode on four parallel threads as follows:

pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=PTRACK --remote-host=remote-hostname --remote-user=remote-unix-username -j 4 --exclude-path=postgresql.conf --exclude-path=postgresql.auto.conf --exclude-path=pg_hba.conf --exclude-path=pg_ident.conf

Note that in this example, the configuration files will not be overwritten during synchronization.

Another example shows how you can add a new remote standby server with the PostgreSQL data directory /replica-pgdata by running the catchup command in the FULL mode on four parallel threads:

pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=FULL --remote-host=remote-hostname --remote-user=remote-unix-username -j 4

Command-Line Reference

Commands

This section describes pg_probackup commands. Optional parameters are enclosed in square brackets. For detailed parameter descriptions, see the section Options.

version

pg_probackup version

Prints pg_probackup version.

help

pg_probackup help [command]

Displays the synopsis of pg_probackup commands. If one of thepg_probackup commands is specified, shows detailed information about the options that can be used with this command.

init

pg_probackup init -B backupdir [--help]

Initializes the backup catalog in_backupdir_ that will store backup copies, WAL archive, and meta information for the backed up database clusters. If the specified backupdir already exists, it must be empty. Otherwise, pg_probackup displays a corresponding error message.

For details, see the sectionInitializing the Backup Catalog.

add-instance

pg_probackup add-instance -B backupdir -D datadir --instance=instancename [--help]

Initializes a new backup instance inside the backup catalog_backupdir_ and generates thepg_probackup.conf configuration file that controlspg_probackup settings for the cluster with the specified_datadir_ data directory.

For details, see the sectionAdding a New Backup Instance.

del-instance

pg_probackup del-instance -B backupdir --instance=instancename [--help]

Deletes all backups and WAL files associated with the specified instance.

set-config

pg_probackup set-config -B backupdir --instance=instancename [--help] [--pgdata=pgdata-path] [--retention-redundancy=redundancy][--retention-window=window][--wal-depth=waldepth] [--compress-algorithm=compressionalgorithm] [--compress-level=compressionlevel] [-d dbname] [-h host] [-p port] [-U username] [--archive-timeout=timeout] [--external-dirs=externaldirectorypath] [--restore-command=cmdline] [remoteoptions] [remotewalarchiveoptions] [loggingoptions]

Adds the specified connection, compression, retention, logging, and external directory settings into the pg_probackup.conf configuration file, or modifies the previously defined values.

For all available settings, see theOptions section.

It is not recommended to edit pg_probackup.conf manually.

set-backup

pg_probackup set-backup -B backupdir --instance=instancename -i backupid {--ttl=ttl | --expire-time=time} [--note=backupnote] [--help]

Sets the provided backup-specific settings into thebackup.control configuration file, or modifies the previously defined values.

--note=_`backupnote`_

Sets the text note for backup copy. If backupnote contain newline characters, then only substring before first newline character will be saved. Max size of text note is 1 KB. The 'none' value removes current note.

For all available pinning settings, see the sectionPinning Options.

show-config

pg_probackup show-config -B backupdir --instance=instancename [--format=plain|json] [--no-scale-units] [loggingoptions]

Displays the contents of the pg_probackup.conf configuration file located in the_`backupdir`_/backups/_`instancename`_ directory. You can specify the--format=json option to get the result in the JSON format. By default, configuration settings are shown as plain text.

You can also specify the --no-scale-units option to display time and memory configuration settings in their base (unscaled) units. Otherwise, the values are scaled to larger units for optimal display. For example, if archive-timeout is 300, then5min is displayed, but if archive-timeout is 301, then 301s is displayed. Also, if the --no-scale-units option is specified, configuration settings are displayed without units and for the JSON format, numeric and boolean values are not enclosed in quotes. This facilitates parsing the output.

To edit pg_probackup.conf, use theset-config command.

show

pg_probackup show -B backupdir [--help] [--instance=instancename [-i backupid | --archive]] [--format=plain|json] [--no-color]

Shows the contents of the backup catalog. If_instancename_ and_backupid_ are specified, shows detailed information about this backup. If the --archive option is specified, shows the contents of WAL archive of the backup catalog.

By default, the contents of the backup catalog is shown as plain text. You can specify the--format=json option to get the result in the JSON format. If --no-color flag is used, then the output is not colored.

For details on usage, see the sectionsManaging the Backup Catalog andViewing WAL Archive Information.

backup

pg_probackup backup -B backupdir -b backupmode --instance=instancename [--help] [-j numthreads] [--progress] [-C] [--stream [-S slot_name] [--temp-slot]] [--backup-pg-log] [--no-validate] [--skip-block-validation] [-w --no-password] [-W --password] [--archive-timeout=timeout] [--external-dirs=externaldirectorypath] [--no-sync] [--note=backupnote] [connectionoptions] [compressionoptions] [remoteoptions] [retentionoptions] [pinningoptions] [loggingoptions]

Creates a backup copy of the PostgreSQL instance.

-b _`mode`_, --backup-mode=_`mode`_

Specifies the backup mode to use. Possible values are:[FULL](#pbk-modes-full),[DELTA](#pbk-modes-delta),[PAGE](#pbk-modes-page), and[PTRACK](#pbk-modes-ptrack).

-C, --smooth-checkpoint

Spreads out the checkpoint over a period of time. By default,pg_probackup tries to complete the checkpoint as soon as possible.

--stream

Makes a STREAM backup, which includes all the necessary WAL files by streaming them from the database server via replication protocol.

--temp-slot

Creates a temporary physical replication slot for streaming WAL from the backed up PostgreSQL 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 --stream flag. The default slot name is pg_probackup_slot, which can be changed using the --slot/-S option.

-S _`slotname`_, --slot=_`slotname`_

Specifies the replication slot for WAL streaming. This option can only be used together with the --stream flag.

--backup-pg-log

Includes the log directory into the backup. This directory usually contains log messages. By default, log directory is excluded.

-E _`externaldirectorypath`_, --external-dirs=_`externaldirectorypath`_

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.

--archive-timeout=_`waittime`_

Sets the timeout for WAL segment archiving and streaming, in seconds. By default, pg_probackup waits 300 seconds.

--skip-block-validation

Disables block-level checksum verification to speed up the backup process.

--no-validate

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.

--no-sync

Do not sync backed up files to disk. You can use this flag to speed up the backup process. Using this flag can result in data corruption in case of operating system or hardware crash. If you use this option, it is recommended to run thevalidate command once the backup is complete to detect possible issues.

--note=_`backupnote`_

Sets the text note for backup copy. If backupnote contain newline characters, then only substring before first newline character will be saved. Max size of text note is 1 KB. The 'none' value removes current note.

Additionally, connection options, retention options, pinning options, remote mode options,compression options, logging options, and common options can be used.

For details on usage, see the sectionCreating a Backup.

restore

pg_probackup restore -B backupdir --instance=instancename [--help] [-D datadir] [-i backupid] [-j numthreads] [--progress] [-T OLDDIR=NEWDIR] [--external-mapping=OLDDIR=NEWDIR] [--skip-external-dirs] [-R | --restore-as-replica] [--no-validate] [--skip-block-validation] [--force] [--no-sync] [--restore-command=cmdline] [--primary-conninfo=primaryconninfo] [-S | --primary-slot-name=slotname] [-X waldir | --waldir=waldir] [recoverytargetoptions] [loggingoptions] [remoteoptions] [partialrestoreoptions] [remotewalarchiveoptions]

Restores the PostgreSQL instance from a backup copy located in the backupdir backup catalog. If you specify a recovery target option, pg_probackup finds the closest backup and restores it to the specified recovery target. If neither the backup ID nor recovery target options are provided,pg_probackup uses the most recent backup to perform the recovery.

-R, --restore-as-replica

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 theprimary_conninfo parameter as it is not included. For PostgreSQL 11 or lower, recovery settings are written into the recovery.conf file. Starting from PostgreSQL 12,pg_probackup writes these settings into the probackup_recovery.conf file in the data directory, and then includes them into thepostgresql.auto.conf when the cluster is is started.

--primary-conninfo=_`primaryconninfo`_

Sets theprimary_conninfo parameter to the specified value. This option will be ignored unless the -R flag is specified.

Example: --primary-conninfo="host=192.168.1.50 port=5432 user=foo password=foopass"

-S, --primary-slot-name=_`slotname`_

Sets theprimary_slot_name parameter to the specified value. This option will be ignored unless the -R flag is specified.

-T _`OLDDIR`_=_`NEWDIR`_, --tablespace-mapping=_`OLDDIR`_=_`NEWDIR`_

Relocates the tablespace from the OLDDIR to the NEWDIR directory at the time of recovery. Both OLDDIR and NEWDIR must be absolute paths. If the path contains the equals sign (=), escape it with a backslash. This option can be specified multiple times for multiple tablespaces.

--external-mapping=_`OLDDIR`_=_`NEWDIR`_

Relocates an external directory included into the backup from the OLDDIR to the NEWDIR directory at the time of recovery. Both OLDDIR and NEWDIR must be absolute paths. If the path contains the equals sign (=), escape it with a backslash. This option can be specified multiple times for multiple directories.

--skip-external-dirs

Skip external directories included into the backup with the--external-dirs option. The contents of these directories will not be restored.

--skip-block-validation

Disables block-level checksum verification to speed up validation. During automatic validation before the restore only file-level checksums will be verified.

--no-validate

Skips backup validation. You can use this flag if you validate backups regularly and would like to save time when running restore operations.

--restore-command=_`cmdline`_

Sets therestore_command parameter to the specified command. For example:--restore-command='cp /mnt/server/archivedir/%f "%p"'

--force

Allows to ignore an invalid status of the backup. You can use this flag if you need to restore thePostgreSQL cluster from a corrupt or an invalid backup. Use with caution. If PGDATA contains a non-empty directory with system ID different from that of the backup being restored, incremental restore with this flag overwrites the directory contents (while an error occurs without the flag). If tablespaces are remapped through the --tablespace-mapping option into non-empty directories, the contents of such directories will be deleted.

--no-sync

Do not sync restored files to disk. You can use this flag to speed up restore process. Using this flag can result in data corruption in case of operating system or hardware crash. If it happens, you have to run the restore command again.

-X _`waldir`_, --waldir=_`waldir`_

Specifies the directory where WAL should be stored.

Additionally, recovery target options,remote mode options,remote WAL archive options, logging options, partial restore options, and common options can be used.

For details on usage, see the sectionRestoring a Cluster.

checkdb

pg_probackup checkdb [-B backupdir] [--instance=instancename] [-D datadir] [--help] [-j numthreads] [--progress] [--amcheck [--skip-block-validation] [--checkunique] [--heapallindexed]] [connectionoptions] [loggingoptions]

Verifies the PostgreSQL database cluster correctness by detecting physical and logical corruption.

--amcheck

Performs logical verification of indexes for the specifiedPostgreSQL instance if no corruption was found while checking data files. You must have the amcheck extension or the amcheck_next extension installed in the database to check its indexes. For databases without amcheck, index verification will be skipped. Additional options --checkunique and --heapallindexed are effective depending on the version of amcheck installed.

--checkunique

Verifies unique constraints during logical verification of indexes. You can use this flag only together with the --amcheck flag when the amcheck extension is installed in the database.

The verification of unique constraints is only possible if in the version of theamcheck extension you are using, thebt_index_check function takes the_checkunique_ parameter.

--heapallindexed

Checks that all heap tuples that should be indexed are actually indexed. You can use this flag only together with the--amcheck flag.

This check is only possible if in the version of theamcheck/amcheck_next extension you are using, the bt_index_check function takes the heapallindexed parameter.

--skip-block-validation

Skip validation of data files. You can use this flag only together with the --amcheck flag, so that only logical verification of indexes is performed.

Additionally, connection options and logging options can be used.

For details on usage, see the sectionVerifying a Cluster.

validate

pg_probackup validate -B backupdir [--help] [--instance=instancename] [-i backupid] [-j numthreads] [--progress] [--skip-block-validation] [recoverytargetoptions] [loggingoptions]

Verifies that all the files required to restore the cluster are present and are not corrupt. If_instancename_ is not specified,pg_probackup validates all backups available in the backup catalog. If you specify the instancename without any additional options, pg_probackup validates all the backups available for this backup instance. If you specify the_instancename_ with arecovery target option and/or a backupid,pg_probackup checks whether it is possible to restore the cluster using these options.

For details, see the sectionValidating a Backup.

merge

pg_probackup merge -B backupdir --instance=instancename -i backupid [--help] [-j numthreads] [--progress] [--no-validate] [--no-sync] [loggingoptions]

Merges backups that belong to a common incremental backup chain. If you specify a full backup, it will be merged with its first incremental backup. If you specify an incremental backup, it will be merged to its parent full backup, together with all incremental backups between them. Once the merge is complete, the full backup takes in all the merged data, and the incremental backups are removed as redundant.

--no-validate

Skips automatic validation before and after merge.

--no-sync

Do not sync merged files to disk. You can use this flag to speed up the merge process. Using this flag can result in data corruption in case of operating system or hardware crash.

For details, see the sectionMerging Backups.

delete

pg_probackup delete -B backupdir --instance=instancename [--help] [-j numthreads] [--progress] [--retention-redundancy=redundancy][--retention-window=window][--wal-depth=waldepth] [--delete-wal] {-i backupid | --delete-expired [--merge-expired] | --merge-expired | --status=backup_status} [--dry-run] [--no-validate] [--no-sync] [loggingoptions]

Deletes backup with specified backupid or launches the retention purge of backups and archived WAL that do not satisfy the current retention policies.

--no-validate

Skips automatic validation before and after retention merge.

--no-sync

Do not sync merged files to disk. You can use this flag to speed up the retention merge process. Using this flag can result in data corruption in case of operating system or hardware crash.

For details, see the sectionsDeleting Backups,Retention Options, andConfiguring Retention Policy.

archive-push

pg_probackup archive-push -B backupdir --instance=instancename --wal-file-name=walfilename [--wal-file-path=walfilepath] [--help] [--no-sync] [--compress] [--no-ready-rename] [--overwrite] [-j numthreads] [--batch-size=batchsize] [--archive-timeout=timeout] [--compress-algorithm=compressionalgorithm] [--compress-level=compressionlevel] [remoteoptions] [loggingoptions]

Copies WAL files into the corresponding subdirectory of the backup catalog and validates the backup instance by_instancename_ andsystem-identifier. If parameters of the backup instance and the cluster do not match, this command fails with the following error message: Refuse to push WAL segment segment_name into archive. Instance parameters mismatch.

If the files to be copied already exists in the backup catalog,pg_probackup computes and compares their checksums. If the checksums match, archive-push skips the corresponding file and returns a successful execution code. Otherwise, archive-push fails with an error. If you would like to replace WAL files in the case of checksum mismatch, run the archive-push command with the --overwrite flag.

Each file is copied to a temporary file with the.part suffix. If the temporary file already exists, pg_probackup will waitarchive_timeout seconds before discarding it. After the copy is done, atomic rename is performed. This algorithm ensures that a failed archive-push will not stall continuous archiving and that concurrent archiving from multiple sources into a single WAL archive has no risk of archive corruption.

To speed up archiving, you can specify the --batch-size option to copy WAL segments in batches of the specified size. If --batch-size option is used, then you can also specify the -j option to copy the batch of WAL segments on multiple threads.

WAL segments copied to the archive are synced to disk unless the --no-sync flag is used.

You can use archive-push in thearchive_command PostgreSQL parameter to set upcontinuous WAL archiving.

For details, see sectionsArchiving Options andCompression Options.

archive-get

pg_probackup archive-get -B backupdir --instance=instancename --wal-file-path=walfilepath --wal-file-name=walfilename [-j numthreads] [--batch-size=batchsize] [--prefetch-dir=prefetchdirpath] [--no-validate-wal] [--help] [remoteoptions] [loggingoptions]

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 pg_probackup as part of therestore_command when restoring backups using a WAL archive. You do not need to set it manually.

To speed up recovery, you can specify the --batch-size option to copy WAL segments in batches of the specified size. If --batch-size option is used, then you can also specify the -j option to copy the batch of WAL segments on multiple threads.

For details, see section Archiving Options.

catchup

pg_probackup catchup -b catchupmode --source-pgdata=pathtopgdataonremoteserver --destination-pgdata=pathtolocaldir [--help] [-j | --threads=numthreads] [--stream] [--dry-run] [--temp-slot] [-P | --perm-slot] [-S | --slot=slotname] [--exclude-path=PATHNAME] [-T OLDDIR=NEWDIR] [connectionoptions] [remoteoptions]

Creates a copy of a PostgreSQL instance without using the backup catalog.

-b _`catchupmode`_, --backup-mode=_`catchupmode`_

Specifies the catchup mode to use. Possible values are:[FULL](#pbk-catchup-modes-full),[DELTA](#pbk-catchup-modes-delta), and[PTRACK](#pbk-catchup-modes-ptrack).

--source-pgdata=_`pathtopgdataonremoteserver`_

Specifies the path to the data directory of the instance to be copied. The path can be local or remote.

--destination-pgdata=_`pathtolocaldir`_

Specifies the path to the local data directory to copy to.

-j _`numthreads`_, --threads=_`numthreads`_

Sets the number of parallel threads forcatchup process.

--stream

Copies the instance in STREAM WAL delivery mode, including all the necessary WAL files by streaming them from the server via replication protocol.

--dry-run

Displays the total size of the files to be transferred by catchup. This flag initiates a trial run of catchup, which does not actually create, delete or move files on disk. WAL streaming is skipped with --dry-run. This flag also allows you to check that all the options are correct and cloning/synchronising is ready to run.

-x=pathprefix, --exclude-path=pathprefix

Specifies a prefix for files to exclude from the synchronization of PostgreSQL instances during copying. The prefix must contain a path relative to the data directory of an instance. If the prefix specifies a directory, all files in this directory will not be synchronized.

Warning

This option is dangerous since excluding files from synchronization can result in incomplete synchronization; use with care.

--temp-slot

Creates a temporary physical replication slot for streaming WAL from the PostgreSQL instance being copied. It ensures that all the required WAL segments remain available if WAL is rotated while the backup is in progress. This flag can only be used together with the --stream flag and cannot be used together with the --perm-slot flag. The default slot name is pg_probackup_slot, which can be changed using the --slot/-S option.

-P, --perm-slot

Creates a permanent physical replication slot for streaming WAL from the PostgreSQL instance being copied. This flag can only be used together with the --stream flag and cannot be used together with the --temp-slot flag. The default slot name is pg_probackup_perm_slot, which can be changed using the --slot/-S option.

-S _`slotname`_, --slot=_`slotname`_

Specifies the replication slot for WAL streaming. This option can only be used together with the --stream flag.

-T _`OLDDIR`_=_`NEWDIR`_, --tablespace-mapping=_`OLDDIR`_=_`NEWDIR`_

Relocates the tablespace from the OLDDIR to the NEWDIR directory at the time of recovery. Both OLDDIR and NEWDIR must be absolute paths. If the path contains the equals sign (=), escape it with a backslash. This option can be specified multiple times for multiple tablespaces.

Additionally, connection options, remote mode options can be used.

For details on usage, see the sectionCloning and Synchronizing PostgreSQL Instance.

Options

This section describes command-line options for pg_probackup 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 thepg_probackup.conf configuration file located in the backup catalog.

For details, see the section called “Configuring pg_probackup”.

If an option is specified using more than one method, command-line input has the highest priority, while thepg_probackup.conf settings have the lowest priority.

Common Options

The list of general options.

-B _`directory`_, --backup-path=_`directory`_, BACKUP_PATH

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 pg_probackup commands, you are recommended to specify it once in the BACKUP_PATH environment variable. In this case, you do not need to use this option each time on the command line.

-D _`directory`_, --pgdata=_`directory`_, PGDATA

Specifies the absolute path to the data directory of the database cluster. This option is mandatory only for theadd-instance command. Other commands can take its value from the PGDATA environment variable, or from the pg_probackup.conf configuration file.

-i _`backupid`_, --backup-id=_`backupid`_

Specifies the unique identifier of the backup.

-j _`numthreads`_, --threads=_`numthreads`_

Sets the number of parallel threads for backup,restore, merge,validate, checkdb, andarchive-push processes.

--progress

Shows the progress of operations.

--help

Shows detailed information about the options that can be used with this command.

Recovery Target Options

Ifcontinuous WAL archiving is configured, you can use one of these options together with restore or validate commands to specify the moment up to which the database cluster must be restored or validated.

--recovery-target=immediate|latest

Defines when to stop the recovery:

--recovery-target-timeline=_`timeline`_

Specifies a particular timeline to be used for recovery. By default, the timeline of the specified backup is used.

--recovery-target-lsn=_`lsn`_

Specifies the LSN of the write-ahead log location up to which recovery will proceed.

--recovery-target-name=_`recoverytargetname`_

Specifies a named savepoint up to which to restore the cluster.

--recovery-target-time=_`time`_

Specifies the timestamp up to which recovery will proceed. If the time zone offset is not specified, the local time zone is used.

Example: --recovery-target-time="2027-05-02 11:21:00+00"

--recovery-target-xid=_`xid`_

Specifies the transaction ID up to which recovery will proceed.

--recovery-target-inclusive=_`boolean`_, ``

Specifies whether to stop just after the specified recovery target (true), or just before the recovery target (false). This option can only be used together with--recovery-target-name,--recovery-target-time,--recovery-target-lsn or--recovery-target-xid options. The default depends on therecovery_target_inclusive parameter.

--recovery-target-action=pause|promote|shutdown

Specifiesthe action the server should take when the recovery target is reached.

Default: pause

Retention Options

You can use these options together withbackup anddelete commands.

For details on configuring retention policy, see the sectionConfiguring Retention Policy.

--retention-redundancy=_`redundancy`_, ``

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.

Default: 0

--retention-window=_`window`_, ``

Number of days of recoverability. Must be a non-negative integer. The zero value disables this setting.

Default: 0

--wal-depth=_`waldepth`_

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.

Default: 0

--delete-wal

Deletes WAL files that are no longer required to restore the cluster from any of the existing backups.

--delete-expired

Deletes backups that do not conform to the retention policy defined in the pg_probackup.conf configuration file.

--merge-expired, ``

Merges the oldest incremental backup that satisfies the requirements of retention policy with its parent backups that have already expired.

--dry-run

Displays the current status of all the available backups, without deleting or merging expired backups, if any.

Pinning Options

You can use these options together withbackup andset-backup commands.

For details on backup pinning, see the sectionBackup Pinning.

--ttl=_`ttl`_

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).

Example: --ttl=30d

--expire-time=_`time`_

Specifies the timestamp up to which the backup will stay pinned. Must be an ISO-8601 complaint timestamp. If the time zone offset is not specified, the local time zone is used.

Example: --expire-time="2027-05-02 11:21:00+00"

Logging Options

You can use these options with any command.

--no-color

Disable coloring for console log messages of warning and error levels.

--log-level-console=_`loglevel`_

Controls which message levels are sent to the console log. Valid values are verbose,log, info,warning, error andoff. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. The off level disables console logging.

Default: info

Note

All console log messages are going to stderr, so the output of show andshow-config commands does not mingle with log messages.

--log-level-file=_`loglevel`_

Controls which message levels are sent to a log file. Valid values are verbose, log,info, warning,error, and off. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. The off level disables file logging.

Default: off

--log-filename=_`logfilename`_

Defines the filenames of the created log files. The filenames are treated as a strftime pattern, so you can use %-escapes to specify time-varying filenames.

Default: pg_probackup.log

For example, if you specify the pg_probackup-%u.log pattern,pg_probackup generates a separate log file for each day of the week, with %u replaced by the corresponding decimal number:pg_probackup-1.log for Monday, pg_probackup-2.log for Tuesday, and so on.

This option takes effect if file logging is enabled by the--log-level-file option.

--error-log-filename=_`errorlogfilename`_

Defines the filenames of log files for error messages only. The filenames are treated as a strftime pattern, so you can use %-escapes to specify time-varying filenames.

Default: none

For example, if you specify the error-pg_probackup-%u.log pattern, pg_probackup generates a separate log file for each day of the week, with %u replaced by the corresponding decimal number: error-pg_probackup-1.log for Monday,error-pg_probackup-2.log for Tuesday, and so on.

This option is useful for troubleshooting and monitoring.

--log-directory=_`logdirectory`_

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.

Default: $BACKUP_PATH/log/

--log-format-console=_`logformat`_

Defines the format of the console log. Only set from the command line. Note that you cannot specify this option in the pg_probackup.conf configuration file through the set-config command and that the backup command also treats this option specified in the configuration file as an error. Possible values are:

Default: plain

--log-format-file=_`logformat`_

Defines the format of log files used. Possible values are:

Default: plain

--log-rotation-size=_`logrotationsize`_

Maximum size of an individual log file. If this value is reached, the log file is rotated once a pg_probackup command is launched, except help and version commands. The zero value disables size-based rotation. Supported units: kB, MB, GB, TB (kB by default).

Default: 0

--log-rotation-age=_`logrotationage`_

Maximum lifetime of an individual log file. If this value is reached, the log file is rotated once a pg_probackup command is launched, except help and version commands. The time of the last log file creation is stored in$BACKUP_PATH/log/log_rotation. The zero value disables time-based rotation. Supported units: ms, s, min, h, d (min by default).

Default: 0

Connection Options

You can use these options together withbackup,catchup, andcheckdb commands.

Alllibpq environment variables are supported.

-d _`dbname`_, --pgdatabase=_`dbname`_, PGDATABASE

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, PGDATABASE environment variable, or the pg_probackup.conf configuration file, pg_probackup tries to take this value from the PGUSER environment variable, or from the current user name if PGUSER variable is not set.

-h _`host`_, --pghost=_`host`_, PGHOST

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.

Default: localhost

-p _`port`_, --pgport=_`port`_, PGPORT

Specifies the TCP port or the local Unix domain socket file extension on which the server is listening for connections.

Default: 5432

-U _`username`_, --pguser=_`username`_, PGUSER

User name to connect as.

-w, --no-password

Disables a password prompt. If the server requires password authentication and a password is not available by other means such as a.pgpass file or PGPASSWORD 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.

-W, --password

Forces a password prompt. (Deprecated)

Compression Options

You can use these options together withbackup andarchive-push commands.

--compress-algorithm=_`compressionalgorithm`_

Defines the algorithm to use for compressing data files. Possible values are zlib,pglz, and none. If set to zlib or pglz, this option enables compression. By default, compression is disabled. For thearchive-push command, thepglz compression algorithm is not supported.

Default: none

--compress-level=_`compressionlevel`_

Defines compression level (0 through 9, 0 being no compression and 9 being best compression). This option can be used together with the --compress-algorithm option.

Default: 1

--compress

Alias for --compress-algorithm=zlib and--compress-level=1.

Archiving Options

These options can be used with thearchive-push command in thearchive_command setting and the archive-get command in therestore_command setting.

Additionally, remote mode options and logging options can be used.

--wal-file-path=_`walfilepath`_

Provides the path to the WAL file in_archivecommand_ and_restorecommand_. Use the %p variable as the value for this option or explicitly specify the path to a file outside of the data directory. If you skip this option, the path specified in pg_probackup.conf will be used.

--wal-file-name=_`walfilename`_

Provides the name of the WAL file in_archivecommand_ and_restorecommand_. Use the %f variable as the value for this option for correct processing. If the value of --wal-file-path is a path outside of the data directory, explicitly specify the filename.

--overwrite

Overwrites archived WAL file. Use this flag together with thearchive-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, archive-push reports that a WAL segment already exists, and aborts the operation. If the file to replace has not changed, archive-push skips this file regardless of the --overwrite flag.

--batch-size=_`batchsize`_

Sets the maximum number of files that can be copied into the archive by a single archive-push process, or from the archive by a single archive-get process.

--archive-timeout=_`waittime`_

Sets the timeout for considering existing .part files to be stale. By default, pg_probackup waits 300 seconds. This option can be used only with archive-push command.

--no-ready-rename

Do not rename status files in the archive_status directory. This option should be used only if archivecommand contains multiple commands. This option can be used only with archive-push command.

--no-sync

Do not sync copied WAL files to disk. You can use this flag to speed up archiving process. Using this flag can result in WAL archive corruption in case of operating system or hardware crash. This option can be used only with archive-push command.

--prefetch-dir=_`path`_

Directory used to store prefetched WAL segments if --batch-size option is used. Directory must be located on the same filesystem and on the same mountpoint thePGDATA/pg_wal is located. By default files are stored in PGDATA/pg_wal/pbk_prefetch directory. This option can be used only with archive-get command.

--no-validate-wal

Do not validate prefetched WAL file before using it. Use this option if you want to increase the speed of recovery. This option can be used only with archive-get command.

Remote Mode Options

This section describes the options related to runningpg_probackup operations remotely via SSH. These options can be used with add-instance,set-config,backup,catchup,restore,archive-push, andarchive-get commands.

For details on configuring and using the remote mode, see the section called “Configuring the Remote Mode” andthe section called “Using pg_probackup in the Remote Mode”.

--remote-proto=_`proto`_

Specifies the protocol to use for remote operations. Currently only the SSH protocol is supported. Possible values are:

You can omit this option if the--remote-host option is specified.

--remote-host=_`destination`_, ``

Specifies the remote host IP address or hostname to connect to.

--remote-port=_`port`_

Specifies the remote host port to connect to.

Default: 22

--remote-user=_`username`_

Specifies remote host user for SSH connection. If you omit this option, the current user initiating the SSH connection is used.

--remote-path=_`path`_

Specifies pg_probackup installation directory on the remote system.

--ssh-options=_`sshoptions`_

Provides a string of SSH command-line options. For example, the following options can be used to set keep-alive for SSH connections opened by pg_probackup:--ssh-options="-o ServerAliveCountMax=5 -o ServerAliveInterval=60". For the full list of possible options, seessh_config manual page.

Remote WAL Archive Options

This section describes the options used to provide the arguments for remote mode options inarchive-get used in therestore_command command when restoring ARCHIVE backups or performing PITR.

--archive-host=_`destination`_

Provides the argument for the --remote-host option in the archive-get command.

--archive-port=_`port`_

Provides the argument for the --remote-port option in the archive-get command.

Default: 22

--archive-user=_`username`_

Provides the argument for the --remote-user option in the archive-get command. If you omit this option, the user that has started the PostgreSQL cluster is used.

Default: PostgreSQL user

Incremental Restore Options

This section describes the options for incremental cluster restore. These options can be used with therestore command.

-I _`incrementalmode`_, --incremental-mode=_`incrementalmode`_

Specifies the incremental mode to be used. Possible values are:

Partial Restore Options

This section describes the options for partial cluster restore. These options can be used with therestore command.

--db-exclude=_`dbname`_

Specifies the name of the database to exclude from restore. All other databases in the cluster will be restored as usual, includingtemplate0 and template1. This option can be specified multiple times for multiple databases.

--db-include=_`dbname`_

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 template0 andtemplate1. This option can be specified multiple times for multiple databases.

Versioning

pg_probackup followssemantic versioning.

Authors

Postgres Professional, Moscow, Russia.

Credits

pg_probackup utility is based on pg_arman, which was originally written by NTT and then developed and maintained by Michael Paquier.