Pay attention to the following limitations and considerations for the restore process:
Tablespace remapping: When changing the location of tablespaces via mapping, the target directories must exist and be writable.
All parent backups in the chain (from the specified backup up to the full backup) must be present and available. If any link in the chain is missing, restore is impossible.
Backups with the statuses CORRUPT, ORPHAN,
INVALID, ERROR, or DELETED
cannot be restored. Only backups with the OK status
are suitable for restore.
A backup must be successfully completed at the time of creation.
Interrupted or corrupted backups cannot be restored. Using
the --no-validate flag is not recommended, as
restoring from a corrupted backup will lead to an inconsistent database.
A backup must contain at least ten files to pass
validation (protection against an empty PGDATA or
permission issues).
Backup segmentation: chunk_no of each segment
must be less than total_chunks. All segments
must be present for a successful restore.
For a full restore, the PGDATA directory must be
completely empty. Otherwise, the restore will fail.
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.5.
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.
Note the syntax for multiple tablespace mappings: instead of multiple
-T flags, use a single flag with
colon-separated mapping pairs. For example:
pg_probackup3 restore -Bbackup_dir--instance=instance_name-Ddata_dir-j 4 -ibackup_id-T tablespace1_dir=tablespace1_newdir:tablespace2_dir=tablespace2_newdir
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.
Incremental restore limitations and considerations:
During incremental restore, if PGDATA is empty but
a tablespace contains data, the --force flag must
be specified explicitly to clear the tablespace.
During incremental restore, files and directories that are missing in the new backup are automatically deleted, which may lead to data loss if used incorrectly.
If PGDATA and all tablespaces are empty, the mode
automatically switches to a full restore.
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, the
pg_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
that pg_control contains valid information.
Therefore, it is not recommended to use LSN mode in any situation
where pg_control cannot be trusted or has
been tampered with:
for example, after pg_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.
You can restore particular databases using partial restore options with the restore command. The sections below describe all supported partial restore methods.
The following considerations apply to all partial restore methods:
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.
The template0 and
template1 databases are always restored.
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 databases by name, the backup must contain a database map. Without a map, filtering is possible only by OID.
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
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-include-name and --db-exclude-name
options can be specified multiple times, but
cannot be used together. For example,
to restore the db1 and db2
databases, run the following command:
pg_probackup3 restore -Bbackup_dir--instance=instance_name--db-include-name=db1 --db-include-name=db2
To exclude the same databases as in the previous example, run:
pg_probackup3 restore -Bbackup_dir--instance=instance_name--db-exclude-name=db1 --db-exclude-name=db2
You can restore particular databases
without any special preparations (unlike
partial restore by name)
using the --db-include-oid and --db-exclude-oid
options.
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
During restore, only WAL records for the included databases are processed, ignoring others, which speeds up the operation.
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-include-oid and --db-exclude-oid
options can be specified multiple times, but
cannot be used together. For example,
to restore only the db1 database with the
dboid1 OID and db2 with
dboid2, run the following command:
pg_probackup3 restore -Bbackup_dir--instance=instance_name--db-include-oid=dboid1 --db-include-oid=dboid2
To exclude the same databases as in the previous example, run:
pg_probackup3 restore -Bbackup_dir--instance=instance_name--db-exclude-oid=dboid1 --db-exclude-oid=dboid2
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 to
replica 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 -Bbackup_dir--instance=instance_name--recovery-target-time="2024-04-10 18:18:26+03" --recovery-target-action=promote
Start 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.
You can also extract a specific segment from the archive for manual
recovery to a point in time or for diagnostic purposes by running the
archive-get command with the --wal-file-path
option containing an absolute path to the target file:
pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=/var/lib/pgsql/data/pg_wal/RECOVERYXLOG --wal-file-name=000000010000000000000001
Refer to the section called “Recovery Target Options” for other supported PITR methods.
Remote restore in pg_probackup3 is a functionality that allows restoring backups directly to a remote host without the need to manually copy archive files. This approach significantly reduces recovery time and minimizes manual operations during disaster recovery, migration, or automated deployment. It is particularly useful in infrastructures with centralized backup storage where recovery is performed onto isolated remote servers.
The remote restore functionality consists of the following main components:
The send-backup command in the pg_probackup3 utility to send data to a remote server through a specified port using multithreading.
The pgpro_backupstream utility, manually started on the remote server, to receive, extract, and restore the data.
The following conditions must be met to perform remote restore:
On the local system:
The pg_probackup3 utility and the
libpgprobackup library must be installed.
The backup catalog must be accessible.
On the remote system:
The pgpro_backupstream utility must be installed.
pgpro_backupstream requires manual startup.
The PGDATA directory must be empty and writable.
The incremental restore mode is not currently supported.
The specified port must be open and available for incoming connections.
To restore an instance to a remote host, perform the following steps:
On the local system's side, run the send-backup command via the pg_probackup3 utility to send the backup data to the remote host over the specified port:
pg_probackup3 send-backup -Bbackup_dir--instance=instance_name-ibackup_id-pport-hhost[--no-merge] [remote_wal_archive_options]
Using the --no-merge flag will prevent the backup
chain from being merged before the data transfer. Otherwise, the backup
chain will be merged into a temporary file, which will be deleted after
the transfer is complete.
If the WAL archive is located on a separate server, specify its access
parameters — --archive-host,
--archive-port, and --archive-user
(remote WAL archive options).
The send-backup command will retrieve the necessary
WAL files directly from the remote archive.
On the remote system's side, run the restore command
via the pgpro_backupstream utility to receive
the backup data and perform restore:
pgpro_backupstream restore -Dpath_to_restore[-pport]
If the port is not specified, STDIN is used.
Run the pgpro_backupstream utility on the remote system before initiating the data transfer with the send-backup command.