3.2. Restoring a Cluster #
3.2.1. Full Restore #
To restore the database cluster from a backup, run the restore command with at least the following options:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
-ibackup_id
Where:
backup_dir
is the backup catalog that stores all backup files and meta information.instance_name
is the backup instance for the cluster to be restored.backup_id
specifies the backup to restore the cluster from.
If you restore ARCHIVE backups or perform PITR, pg_probackup3 creates a recovery configuration file once all data files are copied into the target directory. This file includes the minimal settings required for recovery, except for the password in the primary_conninfo parameter; you have to add the password manually or use the --primary-conninfo
option, if required. pg_probackup3 writes recovery 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, Postgres Pro replays all available archived WAL segments, so the cluster is restored to the latest state possible within the current timeline. You can change this behavior by using the recovery target options with the restore
command, as explained in Section 3.2.4.
If the cluster to restore contains tablespaces, pg_probackup3 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_probackup3 restore -Bbackup_dir
--instance=instance_name
-Ddata_dir
-j 4 -ibackup_id
-T tablespace1_dir=tablespace1_newdir
-T tablespace2_dir=tablespace2_newdir
3.2.2. Incremental Restore #
The speed of restore from backup can be significantly improved by replacing only invalid and changed pages in already existing Postgres Pro data directory using incremental restore options with the restore command.
Note
Currently, incremental restore is only available in the PRO mode. Support for BASE and DIRECT modes will be implemented in future releases.
To restore the database cluster from a backup in incremental mode, run the restore command with the following options:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
-Ddata_dir
-Iincremental_mode
Where incremental_mode
can take one of the following values:
CHECKSUM — read all data files in the data directory, validate header and checksum in every page and replace only invalid pages and those with checksum and LSN not matching with corresponding page in backup. This is the simplest, the most fool-proof incremental mode. Recommended to use by default.
LSN — read the
pg_control
in the data directory to obtain redo LSN and redo TLI, which allows you to determine a point in history(shiftpoint), where data directory state shifted from target backup chain history. If shiftpoint is not within reach of backup chain history, then restore is aborted. If shiftpoint is within reach of backup chain history, then read all data files in the data directory, validate header and checksum in every page and replace only invalid pages and those with LSN greater than shiftpoint. This mode offers a greater speed up compared to CHECKSUM, but rely on two conditions to be met. First, the data checksums parameter must be enabled in the data directory (to avoid corruption due to hint bits). This condition will be checked at the start of incremental restore and the operation will be aborted if checksums are disabled. Second, thepg_control
file must be synchronized with the state of the data directory. This condition cannot be checked at the start of the restore, so it is the user's responsibility to ensure thatpg_control
contains valid information. Therefore, it is not recommended to use LSN mode in any situation wherepg_control
cannot be trusted or has been tampered with: for example, afterpg_resetxlog
execution or after a restore from backup without recovery being run.NONE — regular restore without any incremental optimizations.
Regardless of the chosen incremental mode, pg_probackup3 will check that postmaster
in given destination directory is not running and system-identifier
is the same as in the backup.
An example of using incremental restore with a tablespace in CHECKSUM mode:
================================================================================================================================ Instance Version ID End time Mode WAL Mode TLI Duration Data WAL Zalg Zratio Start LSN Stop LSN Status ================================================================================================================================ inst 17 1-full 2025-08-05 16:14:10+0700 FULL STREAM 1 1s 47MB - none 1.46 0/A3000028 0/A3000160 OK inst 17 1-delta 2025-08-05 16:14:33+0700 DELTA STREAM 1 1s 21MB - none 3.18 0/A5000028 0/A5000160 OK inst 17 2-delta 2025-08-05 16:14:37+0700 DELTA STREAM 1 0ms 21MB - none 3.18 0/A6000028 0/A6000160 OK backup_user@backup_host:~$ ./pg_probackup3 restore -D /mnt/node -B /mnt/b3b --instance=inst -I checksum --backup-id 2-delta -T /mnt/ts1=/mnt/ts2 --threads=1 [2025-08-05 16:20:38.061117] [264669] [0x79693fc1a4c0] [info] command: ./pg_probackup3 restore -D /mnt/node -B /mnt/backups --instance=inst -I checksum --backup-id 2-delta -T /mnt/ts1=/mnt/ts2 --threads=1 [2025-08-05 16:20:38.061244] [264669] [0x79693fc1a4c0] [info] execute command: 'restore', instance 'inst', backup_id '2-delta' [2025-08-05 16:20:38.061855] [264669] [0x79693fc1a4c0] [info] Start validate 2-delta ... [2025-08-05 16:20:38.065368] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #0 out of 8 [2025-08-05 16:20:38.088840] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #1 out of 8 [2025-08-05 16:20:38.112253] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #2 out of 8 [2025-08-05 16:20:38.193395] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #3 out of 8 [2025-08-05 16:20:38.213982] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #4 out of 8 [2025-08-05 16:20:38.235532] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #5 out of 8 [2025-08-05 16:20:38.256768] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #6 out of 8 [2025-08-05 16:20:38.278902] [264669] [0x79693d5a66c0] [info] Validating backup 1-full chunk #7 out of 8 [2025-08-05 16:20:38.300380] [264669] [0x79693fc1a4c0] [info] Validate time 235ms [2025-08-05 16:20:38.301628] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #0 out of 8 [2025-08-05 16:20:38.305281] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #1 out of 8 [2025-08-05 16:20:38.368129] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #2 out of 8 [2025-08-05 16:20:38.371719] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #3 out of 8 [2025-08-05 16:20:38.375494] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #4 out of 8 [2025-08-05 16:20:38.379185] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #5 out of 8 [2025-08-05 16:20:38.383215] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #6 out of 8 [2025-08-05 16:20:38.386733] [264669] [0x79693d5a66c0] [info] Validating backup 1-delta chunk #7 out of 8 [2025-08-05 16:20:38.390220] [264669] [0x79693fc1a4c0] [info] Validate time 89ms [2025-08-05 16:20:38.391428] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #0 out of 8 [2025-08-05 16:20:38.395259] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #1 out of 8 [2025-08-05 16:20:38.399093] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #2 out of 8 [2025-08-05 16:20:38.402872] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #3 out of 8 [2025-08-05 16:20:38.405935] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #4 out of 8 [2025-08-05 16:20:38.468891] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #5 out of 8 [2025-08-05 16:20:38.472336] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #6 out of 8 [2025-08-05 16:20:38.475977] [264669] [0x79693d5a66c0] [info] Validating backup 2-delta chunk #7 out of 8 [2025-08-05 16:20:38.479477] [264669] [0x79693fc1a4c0] [info] Validate time 88ms [2025-08-05 16:20:38.479859] [264669] [0x79693fc1a4c0] [info] INFO: Backup 2-delta is valid [2025-08-05 16:20:38.479992] [264669] [0x79693fc1a4c0] [info] Start restore of backup 2-delta into /mnt/node [2025-08-05 16:20:38.481239] [264669] [0x79693fc1a4c0] [info] Backup 1-delta is chosen as shiftpoint, its Stop LSN will be used as shift LSN [2025-08-05 16:20:38.483006] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #0 out of 8 [2025-08-05 16:20:38.532219] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #1 out of 8 [2025-08-05 16:20:38.569631] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #2 out of 8 [2025-08-05 16:20:38.608792] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #3 out of 8 [2025-08-05 16:20:38.633202] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #4 out of 8 [2025-08-05 16:20:38.733030] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #5 out of 8 [2025-08-05 16:20:38.764890] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #6 out of 8 [2025-08-05 16:20:38.804717] [264669] [0x79693d5a66c0] [info] Restoring 2-delta chunk #7 out of 8 [2025-08-05 16:20:38.839108] [264669] [0x79693fc1a4c0] [info] Restore time 356ms [2025-08-05 16:20:38.839256] [264669] [0x79693fc1a4c0] [info] Removing redundant files in destination directory [2025-08-05 16:20:38.848171] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #0 out of 8 [2025-08-05 16:20:38.860342] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #1 out of 8 [2025-08-05 16:20:38.918134] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #2 out of 8 [2025-08-05 16:20:38.929649] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #3 out of 8 [2025-08-05 16:20:38.942811] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #4 out of 8 [2025-08-05 16:20:38.954785] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #5 out of 8 [2025-08-05 16:20:38.970253] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #6 out of 8 [2025-08-05 16:20:38.983111] [264669] [0x79693d5a66c0] [info] Restoring 1-delta chunk #7 out of 8 [2025-08-05 16:20:38.995516] [264669] [0x79693fc1a4c0] [info] Restore time 148ms [2025-08-05 16:20:38.997560] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #0 out of 8 [2025-08-05 16:20:39.032484] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #1 out of 8 [2025-08-05 16:20:39.062668] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #2 out of 8 [2025-08-05 16:20:39.134805] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #3 out of 8 [2025-08-05 16:20:39.160183] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #4 out of 8 [2025-08-05 16:20:39.189998] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #5 out of 8 [2025-08-05 16:20:39.219022] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #6 out of 8 [2025-08-05 16:20:39.249562] [264669] [0x79693d5a66c0] [info] Restoring 1-full chunk #7 out of 8 [2025-08-05 16:20:39.279275] [264669] [0x79693fc1a4c0] [info] Restore time 282ms [2025-08-05 16:20:39.280742] [264669] [0x79693fc1a4c0] [info] INFO: Restore of backup 2-delta completed.
3.2.3. Partial Restore #
You can restore particular databases using partial restore options with the restore command. The sections below describe all supported partial restore methods.
3.2.3.1. Partial Restore by Name #
If you have enabled partial restore before taking backups, you can restore specific databases by name using the --db-include-name
and --db-exclude-name
options.
To restore only the specified databases, run the restore command with the following options:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-include-name=dbname
The --db-include-name
option can be specified multiple times. For example, to restore only the databases db1
and db2
, run the following command:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-include-name=db1 --db-include-name=db2
To exclude one or more databases from restore, use the --db-exclude-name
option:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-exclude-name=dbname
The --db-exclude-name
option can be specified multiple times. For example, to exclude the databases db1
and db2
, run the following command:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-exclude-name=db1 --db-exclude-name=db2
Note
After the Postgres Pro cluster is successfully started, drop the excluded databases using the DROP DATABASE
command.
To decouple a single cluster containing multiple databases into separate clusters with minimal downtime, run partial restore of the cluster as a standby using the --restore-as-replica
option for specific databases.
Note
The template0
and template1
databases are always restored.
Warning
Options --db-exclude-name
and --db-include-name
cannot be used together.
3.2.3.2. Partial Restore by OID #
You can restore particular databases without any special preparations using the --db-include-oid
and --db-exclude-oid
.
To restore the specified databases only, run the restore command with the following options:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-include-oid=dboid
The --db-include-oid
option can be specified multiple times. For example, to restore only the db1
and db2
databases with OIDs dboid1
and dboid2
, respectively, run the following command:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-include-oid=dboid1 --db-include-oid=dboid2
To exclude one or more databases from restore, use the --db-exclude-oid
option:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-exclude-oid=dboid
The --db-exclude-oid
option can be specified multiple times. For example, to exclude the db1
and db2
databases with OIDs dboid1
and dboid2
, respectively, from restore, run the following command:
pg_probackup3 restore -Bbackup_dir
--instance=instance_name
--db-exclude-oid=dboid1 --db-exclude-oid=dboid2
Note
After the Postgres Pro cluster is successfully started, drop the excluded databases using the DROP DATABASE
command.
To decouple a single cluster containing multiple databases into separate clusters with minimal downtime, run partial restore of the cluster as a standby using the --restore-as-replica
option for specific databases.
Note
The template0
and template1
databases are always restored.
Warning
Options --db-exclude-oid
and --db-include-oid
cannot be used together.
3.2.4. Performing Point-in-Time Recovery (PITR) #
You can restore the cluster to its state at an arbitrary point in time (recovery target) using recovery target options with the restore command.
Before starting PITR, make sure the following conditions are met:
You have configured continuous WAL archiving with the
wal_level
parameter set toreplica
before taking backups.You are taking regular full and incremental backups using pg_probackup3.
You can use both STREAM and ARCHIVE backups for point-in-time recovery as long as the WAL archive contains an unbroken sequence of segments from the backup time to your recovery target time.
Follow the steps below to restore the cluster state at the exact point in time. Use your own values when applicable.
Stop the server:
pg_ctl stop -D /path/to/database/data
Remove the data directory (
PGDATA
):rm -rf /path/to/database/data mv -f /path/to/database/logs/pg_logfile.log /tmp/demo/logs/pg_logfile.log.old
This step is optional, as you can use a different directory for restore.
The log file preservation is recommended for diagnostic purposes.
Run the
restore
command with the following options:pg_probackup3 restore -B
backup_dir
--instance=instance_name
--recovery-target-time="2024-04-10 18:18:26+03" --recovery-target-action=promoteStart the server:
pg_ctl start -D /path/to/database/data
After the recovery is complete, a new instance will be automatically promoted to primary, and a new timeline will be created.
Refer to the section called “Recovery Target Options” for other supported PITR methods.