pgBackRest

Last update: December 22 2025

pgBackRest is a PostgreSQL backup tool with S3 support for Linux.

Customize pgBackRest

1. Configure access to S3.
2. Configure PostgreSQL to archive the WAL.
3. Install pgBackRest.
4. Create a configuration and set up backups.

1. Set up access to S3

Access can be configured by the Account Owner or a user with the role of iam_admin.

1. Create a service user with role with access to S3. If you have created a service user with the role object_storage_user or s3.bucket.user, the bucket must have an access access policy.
2. Issue an S3 key to the user.

2. Configure PostgreSQL for WAL archiving

1. Open the CLI.

2. Open the postgresql.conf file:

   sudo nano /etc/postgresql/16/main/postgresql.conf

3. Set the values of the parameters:

   wal_level = replica
   archive_mode = on
   archive_command = 'pgbackrest --stanza=main archive-push %p'
   max_wal_senders = 3

4. Remove the # before each of the listed parameters and the comments after them.

5. To exit the nano text editor while saving your changes, press Ctrl+X → Y+Enter.

6. Apply the changes:

   sudo systemctl restart postgresql

3. Install pgBackRest

Install pgBackRest:

sudo apt install -y pgbackrest

4. Create a configuration and set up backups

1. Create a configuration directory:

   sudo mkdir -p /etc/pgbackrest

2. Open the configuration file /etc/pgbackrest.conf:

   nano /etc/pgbackrest.conf

3. Complete the /etc/pgbackrest.conf file:

   [main]
   pg1-path=/var/lib/postgresql/<postgresql_version>/main   
   
   [global]
   repo1-type=s3
   repo1-s3-endpoint=<s3_domain>
   repo1-s3-bucket=<bucket_name>
   repo1-s3-region=<pool>
   repo1-s3-key=<access_key>
   repo1-s3-key-secret=<secret_key>
   repo1-path=<path_to_repository>
   repo1-retention-full=<number_of_backups>
   log-level-console=info

   Specify:

   • <postgresql_version> - PostgreSQL data catalog;
   • <s3_domain> - S3 API domain depends on pool in which S3 is located;
   • <bucket_name> - S3 bucket name. The bucket must have vHosted-addressing;
   • <pool> - pool where S3 is located;
   • <access_key> - field value Access key from S3 key;
   • <secret_key> - field value Secret key from the S3 key;
   • <path_to_repository> - the root of the pgBackRest repository;
   • <number_of_backups> - number of backups stored simultaneously.

4. To exit the nano text editor while saving your changes, press Ctrl+X → Y+Enter.

5. Make the postgres user the owner of the configuration:

   sudo chown -R postgres:postgres /var/lib/pgbackrest
   sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf

6. Initialize stanza, a logical unit for pgBackRest that combines the cluster and the repository:

   sudo -u postgres pgbackrest --stanza=main --log-level-console=info stanza-create
   sudo -u postgres pgbackrest --stanza=main --log-level-console=info check

   Here:

   • stanza-create - checks the data catalog and repository, creates metadata for the backup;
   • check - confirms that the setting is correct.

Working with pgBackRest

Create a full backup

1. Open the CLI.

2. Create a full backup:

   sudo -u postgres pgbackrest --stanza=main --type=full backup

Create an incremental backup

At least one full backup must be done to perform an incremental backup.

1. Open the CLI.

2. Create an incremental backup:

   sudo -u postgres pgbackrest --stanza=main --type=incr --log-level-console=info backup

View information about saved backups

1. Open the CLI.

2. Look at the information about the backups that have been saved:

   sudo -u postgres pgbackrest --stanza=main info

Restore a cluster from backup

1. Open the CLI.

2. Stop PostgreSQL before restoring the cluster:

   sudo systemctl stop postgresql

3. Restore backup - the last backup created is automatically selected:

   sudo -u postgres pgbackrest --stanza=main restore

4. Start the PostgreSQL job:

   sudo systemctl start postgresql

5. Check the list of clusters:

   sudo pg_lsclusters

6. Check the list of databases:

   sudo -u postgres psql -c "\l"