pgBackRest and Helpful Commands

Luke Hebert

July 2, 2025 - 4 minutes read - 824 words

pgBackRest is a reliable backup and restore solution for PostgreSQL that scales up to the largest databases and workloads. It provides continuous point-in-time recovery, so you can restore to any moment within your retention window. Below are the commands and workflows you will reach for most often when managing backups, handling failed restores, and cleaning up expired data.

Display Backup Information

Location: /data2/backup/pgbackrest

$ sudo pgbackrest --stanza=example info

With default backup configurations.

Note

If you are not excluding Postgres from the tarball or running incremental backups, the command above should return no valid backups. See the example below.

$ stanza: example
    status: error (no valid backups)
    cipher: none
    db (current)
        wal archive min/max (13): 00000003000000BF000000F4/00000003000000C000000006

Manual Clean Up

Get the backup ID using the info command.

$ sudo pgbackrest --stanza=example info
stanza: example
    status: ok
    cipher: none
    db (current)
        wal archive min/max (13): 00000003000000BF000000F4/00000003000000C000000008
        full backup: 20230502-153912F
            timestamp start/stop: 2023-05-02 15:39:12 / 2023-05-02 15:40:49
            wal start/stop: 00000003000000C000000008 / 00000003000000C000000008
            database size: 20.4GB, database backup size: 20.4GB
            repo1: backup set size: 20.4GB, backup size: 20.4GB

Important

The backup ID is the value after full backup:. In this example it is 20230502-153912F.

Remove an Old Failed Backup

$ sudo su
$ cd /data2/backup/pgbackrest/backup/example/
$ ls -aFlrth
total 8.0K
drwxr-x---. 3 postgres postgres   21 May  2 10:21 ../
drwxr-x---. 3 postgres postgres   18 May  2 15:40 backup.history/
drwxr-x---. 3 postgres postgres   72 May  2 15:40 20230502-153912F/
lrwxrwxrwx. 1 postgres postgres   16 May  2 15:40 latest -> 20230502-153912F/
-rw-r-----. 1 postgres postgres 1005 May  2 15:40 backup.info
-rw-r-----. 1 postgres postgres 1005 May  2 15:40 backup.info.copy
drwxr-x---. 4 postgres postgres  109 May  2 15:40 ./

$ rm -rf 20230502-153912F/

Alternative Method

Expire the backup:

$ sudo -u postgres pgbackrest --stanza=example expire --log-level-console=detail --log-path=/data2/backup/pgbackrest --repo1-path=/data2/backup/pgbackrest

Issue the stop command:

$ sudo -u postgres pgbackrest --stanza=example stop

Delete the stanza:

$ sudo -u postgres pgbackrest stanza-delete --force --log-level-console=detail --log-path=/data2/backup/pgbackrest --pg1-path=/data1/pgsql/13/data --repo=1 --repo1-path=/data2/backup/pgbackrest --stanza=example

Start the service:

$ sudo -u postgres pgbackrest --stanza=example start

Create a new stanza:

$ sudo -u postgres pgbackrest --stanza=example stanza-create --log-level-console=detail --log-path=/data2/backup/pgbackrest --repo1-path=/data2/backup/pgbackrest

Restoring Postgres Only

Restore Postgres from a backup tarball manually via the pgBackRest command line:

sudo /etc/init.d/postgres-13 stop
sudo rm -rf /data1/pgsql/13/data
sudo mv /data2/backup/pgbackrest /data2/backup/pgbackrest_back
sudo mkdir /data2/restore

Copy the tarball and place it in the restore directory:

cd /data2/restore

Example extraction command:

sudo tar -xzvf /data2/restore/202302282342_14-4-5-28479_example_backup.tar.gz --strip-components=2 -C /data2/backup/ /data2/backup/pgbackrest

Note

Replace 202302282342_14-4-5-28479_example_backup.tar.gz with your actual backup file name.

Run the restore:

sudo -u postgres pgbackrest --repo1-path=/data2/backup/pgbackrest --stanza=example --pg1-path=/data1/pgsql/13/data restore

Using pgBackRest Retention

Example configuration values:

example.backup.data_dump_versions = 2
example.backup_v2.pgbackup_compression = false

The retention setting -repo1-retention-full=2 is applied to keep the two most recent full backups.

Incremental Backup

sudo pgbackrest --stanza=example info
stanza: example
    status: ok
    cipher: none
    db (current)
        wal archive min/max (13): 00000003000000C00000000E/00000003000000C000000013
        full backup: 20230502-194620F
            timestamp start/stop: 2023-05-02 19:46:20 / 2023-05-02 19:47:57
            wal start/stop: 00000003000000C00000000F / 00000003000000C00000000F
            database size: 20.4GB, database backup size: 20.4GB
            repo1: backup set size: 20.4GB, backup size: 20.4GB
        incr backup: 20230502-194620F_20230502-200900I
            timestamp start/stop: 2023-05-02 20:09:00 / 2023-05-02 20:10:10
            wal start/stop: 00000003000000C000000013 / 00000003000000C000000013
            database size: 20.4GB, database backup size: 1.8GB
            repo1: backup set size: 20.4GB, backup size: 1.8GB
            backup reference list: 20230502-194620F

Expected Expire Log Entry

INFO: execute non-exclusive pg_stop_backup() and wait for all WAL segments to archive
2023-05-02 20:39:27.536 P00   INFO: backup stop archive = 00000003000000C000000015, lsn = C0/15000100
2023-05-02 20:39:27.538 P00 DETAIL: wrote 'backup_label' file returned from pg_stop_backup()
2023-05-02 20:39:27.538 P00   INFO: check archive for segment(s) 00000003000000C000000015:00000003000000C000000015
2023-05-02 20:39:27.598 P00   INFO: new backup label = 20230502-194620F_20230502-203918I
2023-05-02 20:39:27.727 P00   INFO: incr backup size = 1GB, file total = 7303
2023-05-02 20:39:27.728 P00   INFO: backup command end: completed successfully (9917ms)
2023-05-02 20:39:27.728 P00   INFO: expire command begin 2.36: --exec-id=29243-57c1b3cc --log-level-console=detail --log-path=/data2/backup/pgbackrest --repo1-path=/data2/backup/pgbackrest --stanza=example
2023-05-02 20:39:27.733 P00   INFO: option 'repo1-retention-archive' is not set - archive logs will not be expired
2023-05-02 20:39:27.733 P00   INFO: expire command end: completed successfully (5ms)
Successfully create pgbackrest backup

After the Backup Completes: Clean-Up for Expired Backups

[1079a5f4-57da-49d2-9896-3e2584b1ae71] Cleaning up old backup files
Deleted older backup files
[1079a5f4-57da-49d2-9896-3e2584b1ae71] Total 2 eb files need to be deleted
[1079a5f4-57da-49d2-9896-3e2584b1ae71] Eb deleted file count smaller than keep file count. No eb file needs to be deleted.
[1079a5f4-57da-49d2-9896-3e2584b1ae71] Keeping the 2 Latest example Backups
[1079a5f4-57da-49d2-9896-3e2584b1ae71] prepare temp directory started
[1079a5f4-57da-49d2-9896-3e2584b1ae71] prepare temp directory completed in 0.626267671585083 seconds
/tmp is single tenant RDS and this instance is enterprise edition
[1079a5f4-57da-49d2-9896-3e2584b1ae71] clean postgres backup started
[1079a5f4-57da-49d2-9896-3e2584b1ae71] pgbackrest will be initialized
[1079a5f4-57da-49d2-9896-3e2584b1ae71] Deleting completed full and incremental postgres backup files
2023-05-02 21:00:26.008 P00   INFO: stop command begin 2.36: --exec-id=12050-391ce019 --log-level-console=detail --log-path=/data2/backup/pgbackrest --stanza=example
2023-05-02 21:00:26.008 P00   INFO: stop command end: completed successfully (1ms)
2023-05-02 21:00:26.027 P00   INFO: stanza-delete command begin 2.36: --exec-id=12052-cfe49816 --force --log-level-console=detail --log-path=/data2/backup/pgbackrest --pg1-path=/data1/pgsql/13/data --repo=1 --repo1-path=/data2/backup/pgbackrest --stanza=example
2023-05-02 21:00:28.988 P00   INFO: stanza-delete command end: completed successfully (2962ms)
postgres
2023-05-02 21:00:29.126 P00   INFO: start command begin 2.36: --exec-id=12079-09c2bd5f --log-level-console=detail --log-path=/data2/backup/pgbackrest --stanza=example

References

pgBackRest Official Documentation
pgbackrest restore command reference