pgbackrest

pgbackrest [options] command

pgBackRest is a backup and restore solution for PostgreSQL designed for reliability at scale. It supports full, differential, and incremental backups, parallel processing, hardware-accelerated compression (gz, lz4, zstd), local and remote repositories, and storage backends including filesystem, S3, Azure Blob, and Google Cloud Storage. Backups can be verified end-to-end and restored to a point in time using PostgreSQL's recovery facilities.Operation is organized around a stanza, which represents a single PostgreSQL cluster and its backup repository. After stanza-create, the archive_command in postgresql.conf is set to pgbackrest --stanza=name archive-push %p so that every WAL segment is shipped to the repository. backup then captures the data directory and pairs it with the archived WAL to enable point-in-time recovery via restore.pgBackRest is implemented in C with a small Perl helper layer historically; modern versions are pure C. It is widely deployed in PostgreSQL operator stacks (Crunchy Data, CloudNativePG, Zalando) and in production database environments where pg_basebackup is insufficient.

backup

Create a full, differential, or incremental backup of a PostgreSQL cluster.

Restore a backup, optionally to a specific time, name, xid, LSN, or named recovery target.

Push a WAL segment to the repository (called from PostgreSQL archive_command).

Retrieve a WAL segment from the repository during recovery (called from restore_command).

Initialize a new stanza, creating the repository layout for a cluster.

Update stanza metadata after a major PostgreSQL upgrade.

Remove a stanza and all its backups and WAL.

Verify configuration, archive command, and repository accessibility.

Display backup and archive information for one or all stanzas.

Verify integrity of backups and WAL in the repository.

Apply retention policies, removing old backups and archived WAL.

List or fetch files directly from the repository.

Manage the pgBackRest server (used with TLS-based remote repositories).

Add, modify, or remove free-form annotations on a backup.

Stanza (PostgreSQL cluster) to operate on.

Backup type (full/diff/incr) or restore recovery target type.

Target for --type=time/name/xid/lsn restores.

Path to alternative pgbackrest.conf.

Base directory for configuration files.

Select a specific repository when multiple are configured.

Maximum parallel processes for compression and transfer.

Compression algorithm for backups and WAL.

Verbosity of console logging.

Restore only files that differ from the backup (faster repeated restores).

/etc/pgbackrest/pgbackrest.conf (or /etc/pgbackrest.conf)

Default configuration file. Defines stanzas, repository locations, retention, encryption, compression, and PostgreSQL connection details.

Process-wide defaults: repo1-path, repo1-cipher-type, process-max, log-level-*, compress-type.

Per-stanza settings: pg1-path, pg1-host, pg1-port, pg1-user, plus retention overrides such as repo1-retention-full.

The stanza name must match the value used in archive_command and on every host that touches the repository. Forgetting to run stanza-upgrade after a major PostgreSQL upgrade leaves the stanza misaligned with the new cluster. Restore is destructive: by default it overwrites PGDATA, so use --delta or restore to an empty directory when in doubt. Repository encryption keys, if used, must be backed up out of band — losing them makes the backups unreadable.

pgBackRest was created by David Steele at Crunchy Data and first released in 2013 as a more scalable alternative to pg_basebackup-based backup workflows. Originally written in Perl, it was progressively rewritten in C for performance, with the migration substantially complete by version 2.0. It has become a de-facto standard for production PostgreSQL backups and is bundled with the major PostgreSQL Kubernetes operators.

pg_basebackup(1), pg_dump(1), postgres(1), barman(1), wal-g(1)