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:STREAMandARCHIVE.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 asData+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 comparinguncompressed-bytestodata-bytesif 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 comparingpgdata-bytestouncompressed-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 ofbackup_content.controlfile. 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 asN 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 betweenMin SegnoandMax Segnoare present.DEGRADED— some WAL segments betweenMin SegnoandMax Segnoare 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-waloption 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-idattribute 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-segmentsarray provides with information about intervals of missing segments inDEGRADEDtimelines. InOKtimelines, thelost-segmentsarray is empty.The
backupsarray 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.
Note
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.