pgBackRest: a PostgreSQL backup tool built around stanzas, repositories and parallel WAL

What pgBackRest solves that pg_dump and pg_basebackup do not

pg_dump produces a logical dump. pg_basebackup produces a physical copy of a running cluster. pgBackRest sits in the physical camp but adds the parts that break down at scale: parallel compression, checksum verification of every file, resumable backups, and a WAL archive that can be pushed and fetched asynchronously. The README states that compression is usually the bottleneck during backup operations, and that is the specific problem the parallel processing and lz4/zstd support are aimed at.

The intended user is a PostgreSQL operator with a database large enough that a serial backup no longer fits the maintenance window, or a restore no longer fits the recovery objective. The features listed in the README make that audience explicit: multiple repositories, block-level incremental backups, delta restore, tablespace remapping, and S3, Azure and GCS repository support. A single-node development database does not need any of that, and the configuration surface is correspondingly larger than a one-line pg_dump cron job.

Stanzas, the manifest, and how a backup actually moves

The unit of configuration in pgBackRest is the stanza, which the search data shows is one of the first things new users ask about. A stanza binds a PostgreSQL cluster to a set of repositories and a retention policy. Everything else (backup, restore, archive-push, archive-get) operates against that stanza name.

The mechanism, as the README describes it, works like this. pgBackRest talks to PostgreSQL over a custom protocol rather than requiring remote access to the database, so a repository host can drive backups without a direct PostgreSQL connection. Compression and checksum calculation happen in stream while files are copied. If the repository lives on a separate repository host, compression runs on the PostgreSQL host and the data is transmitted already compressed. Every file in the backup gets a checksum recorded in a manifest, and those checksums are rechecked during restore and verify.

Two details in that design matter more than they first appear. First, after copying files, the backup waits until every WAL segment required to make it consistent has reached the repository. A backup is not considered complete until it is actually restorable. Second, the manifest is what makes delta restore and backup resume possible: on a delta restore, files not present in the backup are removed first, checksums are generated for what remains, matching files are left in place, and only the rest is restored. That is a different approach from blindly re-copying a cluster.

Installing pgBackRest and creating a first stanza

The README points to pgbackrest.org for documentation and release notes, and the repository ships a meson.build and meson_options.txt at the top level, so a source build goes through meson. Distribution packages are the normal path for most users; the project publishes a distribution tarball, announced in the news feed on 2026-07-20.

For a source build, the top-level build files indicate the toolchain. The README does not spell out the configure commands, and the repository files do not contain a usage example, so check the documentation on pgbackrest.org for the exact build and install steps before compiling.

The first real task after installation is defining a stanza. The README does not give a command example for stanza creation, and no command, flag or option name for it appears in the README or the repository files, so consult the configuration reference on pgbackrest.org for the exact syntax and the option names for the repository path and PostgreSQL data directory.

Once the stanza exists and is verified, the README describes full, differential and incremental backup types, with block-level incrementals that copy only the changed parts of files. The README does not include the command line for running a backup either, so the same documentation page is the place to get it. What the README does state is the completion condition: after the backup finishes copying files, it waits until every WAL segment required to make the backup consistent reaches the repository, so a backup that reports success is consistent.

Where the design costs you: verification, WAL retention and scope

Page checksum validation is a good example of a trade-off stated plainly in the README. Failures do not stop the backup. Warnings with details of which pages failed go to the console and the file log. That is the right call for availability, but it means a backup can complete successfully while the source cluster has corruption that has already been copied. If nobody reads the log, the warning is silent. This is a monitoring problem, not a backup problem, and pgBackRest deliberately does not solve it for you.

WAL retention is the second sharp edge. The README says the WAL archive can be maintained for all backups or strictly for the most recent ones, and that in the latter case WAL required to keep older backups consistent is still maintained. Retention policy and restore capability are therefore coupled: shorten the archive and you shorten the window you can actually restore to. Getting this wrong is discovered at restore time, which is the worst possible moment.

Scope is the third. The material describes a Unix-oriented build with meson and no Windows server support, and the search data shows people looking for pgBackRest on Windows and Kubernetes. Kubernetes is not covered in the README either; the project documents PostgreSQL backup, not container orchestration. If your platform is Windows, this is not the tool.

pgBackRest vs Barman: two answers to the same problem

Barman is the comparison people search for most often alongside pgBackRest, and the difference is architectural rather than cosmetic. Barman is a Python-based backup server that manages PostgreSQL clusters, typically over streaming replication and SSH, with its own catalog of backups. pgBackRest is a C tool that installs on the PostgreSQL host and speaks its own protocol to repository hosts and object stores.

The practical consequence is where the work happens. pgBackRest compresses on the PostgreSQL host and transmits compressed data when the repository is remote, and it can push and fetch WAL asynchronously with parallelism. Barman's model centers on the backup server pulling from the database. Which is better depends on your constraints: if you want a separate server that owns retention and cataloging, Barman's shape fits. If you want compression and WAL transfer offloaded from the database and a repository that can be local, remote, S3, Azure or GCS, pgBackRest's shape fits. Neither is a drop-in for the other, and the README gives no migration path between them.

Licence and the cost of staying current

The repository lists a LICENSE file at the top level, and the metadata reports the licence as NOASSERTION, meaning the licence could not be automatically classified. The README does not restate the licence terms, so read the LICENSE file directly before you depend on it. This is not legal advice; it is a note that the machine-readable licence field is not conclusive here.

Upgrade cost is visible in the release cadence. The current stable release is v2.59.1, dated 2026-08-17, supporting PostgreSQL 19beta3. v2.59.0, dated 2026-07-20, added PostgreSQL 19 support, and v2.58.0, dated 2026-01-19, was titled Object Storage Improvements. The pattern is roughly one feature release per quarter with patch releases for new PostgreSQL versions. That means pgBackRest tracks PostgreSQL majors closely, and a PostgreSQL major upgrade will generally require a pgBackRest upgrade alongside it. The last push to the repository was on 2026-09-17, so the project is being worked on, but the release notes are the authority on what changed, not the commit log.

Editorial conclusion

Adopt pgBackRest if you run PostgreSQL at a size where compression time, WAL archiving latency or restore duration is a real operational cost, and you are willing to define a stanza, a repository and a retention policy up front. Do not adopt it if you only need periodic logical dumps of a small database, or if you need a Windows server build, since the material describes a Unix-oriented build via meson. Before committing, verify three things: that your PostgreSQL version is covered by the current release line, that the repository type you intend to use (local, S3, Azure or GCS) is one your storage actually supports, and that your retention policy keeps enough WAL to make the oldest backup you intend to restore consistent.

Frequently asked questions

Official sources

1. Issues
2. pgbackrest/pgbackrest on GitHub
3. Project website
4. README
5. Releases