With pg_probackup3, you can manage backups from the command line:
To view the list of existing backups for every instance, run the command:
pg_probackup3 show -B backup_dir
pg_probackup3 displays the list of all the available backups. For example:
BACKUP INSTANCE 'dev', version 3 ================================================================================================================================= Instance Version ID End time Mode WAL Mode TLI Duration Data WAL Zalg Zratio Start LSN Stop LSN Status ================================================================================================================================= dev 17 1-full 2024-12-10 14:51:34+0000 FULL STREAM 1 1s 38MB - none 1.00 0/A000028 0/A000138 OK dev 17 1-delta 2024-12-10 14:52:02+0000 DELTA STREAM 1 11MB - none 1.00 0/D000028 0/D000180 OK dev 17 2-delta 2024-12-10 14:52:28+0000 DELTA STREAM 1 22MB - none 1.00 0/10000028 0/10000138 OK dev 17 1a-full 2024-12-10 14:54:10+0000 FULL ARCHIVE 1 1s 75MB - none 1.00 0/12000028 0/12000138 OK dev 17 1a-delta 2024-12-10 14:54:32+0000 DELTA ARCHIVE 1 17MB - none 1.00 0/14000028 0/14000138 OK
For each backup, the following information is provided:
Instance — the instance name.
Version — Postgres Pro major version.
ID — the backup identifier.
End time — the backup end time.
Mode — the method used to take this backup. Possible
values: FULL, DELTA, PTRACK.
WAL Mode — WAL delivery mode. Possible values: STREAM
and ARCHIVE.
TLI — timeline identifiers of the current backup and its
parent.
Duration — the time it took to perform the backup.
Data — the size of the data files in this backup.
This value does not include the size of WAL files. For
STREAM backups, the total size of the backup can be calculated
as Data + WAL.
WAL — the uncompressed size of WAL files that
need to be applied during recovery for the backup to reach a
consistent state.
compress-alg — compression algorithm used during
backup. Possible values:
zlib,
lz4, zstd,
none.
Zratio — compression ratio calculated as
“uncompressed-bytes” / “data-bytes”.
Start LSN — WAL log sequence number corresponding to the
start of the backup process. REDO point for Postgres Pro
recovery process to start from.
Stop LSN — WAL log sequence number corresponding to the
end of the backup process. Consistency point for
Postgres Pro recovery process.
Status — backup status. Possible values:
OK — the backup is complete and valid.
DONE — the backup is complete, but was not
validated.
RUNNING — the backup is in progress.
MERGING — the backup is being merged.
MERGED — the backup data files were
successfully merged, but its metadata is in the process
of being updated. Only full backups can have this status.
DELETING — the backup files are being deleted.
CORRUPT — some of the backup files are corrupt.
ERROR — the backup was aborted because of an
unexpected error.
ORPHAN — the backup is invalid because one of
its parent backups is corrupt or missing.
HIDDEN_FOR_TEST — a test script marked the
backup as nonexistent. (pg_probackup3
never sets this status by itself.)
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 the show command with the backup ID:
pg_probackup3 show -Bbackup_dir--instance=instance_name-ibackup_id
The sample output is as follows:
# Backup 2-delta information. backup_id=2-delta parent_backup_id=1-delta backup_mode=delta tli=1 start_lsn=268435496 stop_lsn=268435768 # start-time 2024-12-10 14:52:28+0000 start_time=1733842348 # end-time 2024-12-10 14:52:28+0000 end_time=1733842348 recovery-time=0 data-bytes=22986632 uncompressed-bytes=22986632 compress-alg=none compress-level=1 server-version=170001 min_xid=0 min_multixact=0 backup_source=pro primary_conninfo=user=garbuz reusepass=1 channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=disable krbsrvname=postgres gssdelegation=0 target_session_attrs=any target_server_type=any hostorder=sequential load_balance_hosts=disable stream=true program-version=3.0.0 block-size=8192 xlog-block-size=8192 status = OK
Detailed output has additional attributes:
compress-alg — compression algorithm used during backup. Possible values:
zlib, lz4, zstd,
none.
compress-level — compression level used during backup.
block-size — the block_size
setting of Postgres Pro cluster at the backup start.
checksum-version — are
data block checksums
enabled in the backed up Postgres Pro
cluster. Possible values: 1, 0.
program-version — full version of pg_probackup3 binary used to create the backup.
start-time — the backup start time.
end-time — the backup end time.
end-validation-time — the backup validation end time.
expire-time — the point in time
when a pinned backup can be removed in accordance with retention
policy. This attribute is only available for pinned backups.
uncompressed-bytes — the size of data files before adding page headers and applying
compression. You can evaluate the effectiveness of compression
by comparing uncompressed-bytes to data-bytes if
compression if used.
pgdata-bytes — the size of Postgres Pro
cluster data files at the time of backup. You can evaluate the
effectiveness of an incremental backup by comparing
pgdata-bytes to uncompressed-bytes.
recovery-xid — transaction ID at the backup end time.
parent-backup-id — ID of the parent backup. Available only
for incremental backups.
primary_conninfo — libpq connection parameters
used to connect to the Postgres Pro cluster to take this backup. The
password is not included.
note — text note attached to backup.
content-crc — CRC32 checksum of backup_content.control file.
It is used to detect corruption of backup metainformation.
You can use the --format=tree option to see the
list of backups as a tree:
pg_probackup3 show -B backup_dir --format=tree
The sample output will look as follows:
BACKUP INSTANCE 'dev', version 3
├── 1-full
│ └── 1-delta
│ └── 2-delta
└── 1a-full
└── 1a-delta
You can also get the detailed information about the backup in the JSON format:
pg_probackup3 show -Bbackup_dir--instance=instance_name--format=json -i backup_id
The sample output is as follows:
[
{
"instance": "dev",
"backups": [
{
"id": "2-delta",
"parent-backup-id": "1-delta",
"status": "OK",
"start-time": "2024-12-10 14:52:28+0000",
"end-time": "2024-12-10 14:52:28+0000",
"backup-mode": "DELTA",
"wal": "STREAM",
"block-size": 8192,
"xlog-block-size": 8192,
"program-version": "3.0.0",
"server-version": 17,
"current-tli": 1,
"start-lsn": "0/10000028",
"stop-lsn": "0/10000138",
"data-bytes": 22986632,
"uncompressed-bytes": 22986632,
"wal-bytes": 0,
"compress-alg": "none",
"compress-level": 1,
"min-xid": 0,
"min-multixact": 0,
"backup-source": "pro"
}
]
}
]
To view the information about WAL archive for every instance, run the command:
pg_probackup3 show -Bbackup_dir[--instance=instance_name] --archive
pg_probackup3 displays the list of all the available WAL files grouped by timelines. For example:
BACKUP INSTANCE 'dev', version 3 ===================================================================================================================== TLI Parent TLI Switchpoint Min Segno Max Segno N segments Size Zratio N backups Status ===================================================================================================================== 1 0/0 000000010000000000000001 000000010000000000000006 6 96MB 1.17 1 OK
For each timeline, the following information is provided:
TLI — timeline identifier.
Parent TLI — identifier of the timeline from
which this timeline branched off.
Switchpoint — LSN of the moment when the timeline
branched off from its parent timeline.
Min Segno — the first WAL segment
belonging to the timeline.
Max Segno — the last WAL segment
belonging to the timeline.
N segments — number of WAL segments belonging to
the timeline.
Size — the size that files take on disk.
Zalg — compression algorithm used during backup.
Possible values:
zlib, lz4,
zstd, none.
Zratio — compression ratio calculated as
N segments * wal_segment_size * wal_block_size / Size.
N backups — number of backups belonging to the
timeline. To get the details about backups, use the
JSON format.
Status — status of the WAL archive for this
timeline. Possible values:
OK — all WAL segments between
Min Segno and Max Segno
are present.
DEGRADED — some WAL segments between
Min Segno and Max Segno
are missing. To find out which files are lost,
view this report in the JSON format.
This status may appear if several WAL files (in the middle of
the sequence) were deleted by the delete
command with the --delete-wal option according
to the retention policy. This status does not affect the restore
correctness, but it can be impossible to perform PITR of the
cluster to some recovery targets.
To get more detailed information about the WAL archive in the JSON format, run the command:
pg_probackup3 show -Bbackup_dir[--instance=instance_name] --archive --format=json
The sample output is as follows:
[
{
"instance": "dev",
"version": "3",
"timelines":
[
{
"tli": 1,
"parent-tli": 0,
"switchpoint": "0/0",
"min-segno": "000000010000000000000001",
"max-segno": "000000010000000000000006",
"n-segments": 6,
"size": 100663615,
"zratio": 1.17,
"status": "OK",
"backups": [
{
"id": "1-full",
"status": "OK",
"start-time": "2025-02-11 14:22:16+0000",
"end-time": "2025-02-11 14:22:16+0000",
"backup-mode": "FULL",
"wal": "STREAM",
"block-size": 8192,
"xlog-block-size": 8192,
"program-version": "3.0.0",
"server-version": 17,
"current-tli": 1,
"start-lsn": "0/5000028",
"stop-lsn": "0/5000128",
"data-bytes": 60748163,
"uncompressed-bytes": 60748163,
"wal-bytes": 0,
"compress-alg": "none",
"compress-level": 1,
"min-xid": 0,
"min-multixact": 0,
"backup-source": "pro"
}
]
}
]
}]
Most fields are consistent with the plain format, with some exceptions:
The size is in bytes.
The closest-backup-id attribute
contains the ID of the most recent valid backup that belongs to
one of the previous timelines. You can use this backup to perform
point-in-time recovery to this timeline. If
such a backup does not exist, this string is empty.
The lost-segments array provides with
information about intervals of missing segments in DEGRADED timelines. In OK
timelines, the lost-segments array is empty.
The backups array lists all backups
belonging to the timeline. If the timeline has no backups, this array is empty.
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 backups or merge chains of incremental backups.
During the merge, a brand-new backup is created, into which all the backups to be merged are added. All redundant backups are deleted only after the merge is successful. While this process requires additional disk space, it helps prevent data loss in case of any errors or system failures.
If several child backups relate to the same parent, such backups are not deleted after merge, and the disk space is not freed.
To merge an incremental backup to its parent full backup, run the merge command, specifying the backup ID of the most recent incremental backup you would like to merge:
pg_probackup3 merge -Bbackup_dir--instance=instance_name-ibackup_id
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_probackup3 in the remote mode.
To merge a chain of incremental backups, specify the IDs of the first and the last incremental backup in the chain:
pg_probackup3 merge -Bbackup_dir--instance=instance_name--merge-from-id=merge_from-ibackup_id
Or specify the first backup ID followed by the time interval (in hours) to merge all the backups created during this time:
pg_probackup3 merge -Bbackup_dir--instance=instance_name-ibackup_id--merge-interval=merge_interval
Before the merge, pg_probackup3 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_probackup3 show -Bbackup_dir--instance=instance_name-ibackup_id
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.
To delete a backup that is no longer required, run the following command:
pg_probackup3 delete -Bbackup_dir--instance=instance_name-ibackup_id
This command will delete the backup with the specified
backup_id, together with all the
incremental backups that descend from
backup_id, 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.
Before deleting backups, you can run the
delete 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.