pgBackRest
Back up and restore PostgreSQL with pgBackRest, keeping the backup repository and the WAL archive in XNS storage.
Overview
pgBackRest is a backup and restore tool for PostgreSQL. It takes full, differential and incremental backups, archives the write-ahead log (WAL) continuously, and restores to the latest point or to a chosen time. With XNS, the pgBackRest repository lives in a bucket on your Relayer, using pgBackRest’s s3 repository type with path-style URIs over HTTPS.
Tested with pgBackRest 2.59.3 and PostgreSQL 17.11 on 2026-10-18 against Relayer build 59a37e64.
The run created the stanza, checked WAL archiving, took a full backup, changed data, took an incremental backup, and ran verify. It then restored into an empty data directory, started PostgreSQL on it, and compared checksums of the table data with the original: they were identical. Last, it deleted the stanza, which left the repository empty.
Connect to XNS
Every S3 tool connects to your Relayer with the same settings. Enter them exactly as shown; the notes below the table cover the two that most tools get wrong by default.
| Setting | Value |
|---|---|
| Endpoint (HTTP) | http://<relayer-host>:9000, where <relayer-host> is the address of the machine running your Relayer. Always available. |
| Endpoint (HTTPS) | https://<relayer-host>:9443, available only after a certificate is installed on the Relayer. Port 9000 never serves HTTPS. |
| Region | us-east-1 |
| Addressing | Path-style. In tools that ask, turn on force path style or path-style access, and turn off virtual-hosted style. |
| Signature | Signature Version 4 (V4). Version 2 is refused. |
| Access key and secret key | For a tool, create a scoped key: IAM → Create IAM User in the Relayer UI. The secret is shown once, so copy it then. The install’s root pair is on Configure → Credentials; keep it for administration. |
| Bucket | Create it first: Files → Create Bucket in the Relayer UI, or let the tool create it. Names are 3-63 characters of lowercase letters, digits, hyphens and periods. |
HTTPS and certificates. The Relayer UI offers two certificates for port 9443: Let’s Encrypt, which needs a domain managed in Cloudflare and a Cloudflare API token, or self-signed. Most tools refuse a self-signed certificate unless certificate verification is turned off in the tool. On a private network, plain HTTP on port 9000 avoids the question.
Path-style. A tool left on virtual-hosted style (often labeled Amazon S3 or AWS) sends the bucket name in the hostname, and the Relayer cannot find the bucket. Choose the tool’s S3 compatible or generic S3 option and set path-style.
Not supported: server-side encryption with customer-provided keys (SSE-C) or KMS keys (SSE-KMS), bucket website hosting and bucket replication. Server-side encryption with AES256 is accepted. See Encryption at the Gateway, Identity and Access and Configure.
Prerequisites
- pgBackRest on the PostgreSQL server, from your distribution or the PostgreSQL package repository (
sudo apt install pgbackrest; see the pgBackRest user guide). - HTTPS on port 9443. pgBackRest always connects to S3 over TLS, so it cannot use port 9000. Install a certificate on the Relayer first (see the table above).
- A bucket and a scoped key on your Relayer (see the table above). A key with the ReadWrite policy is enough.
Step 1: Configure the repository
Edit /etc/pgbackrest/pgbackrest.conf. Name the stanza after your cluster (here main) and set pg1-path to its data directory.
[global]
repo1-type=s3
repo1-path=/pgbackrest
repo1-s3-bucket=<bucket>
repo1-s3-endpoint=<relayer-host>
repo1-storage-port=9443
repo1-s3-uri-style=path
repo1-s3-region=us-east-1
repo1-s3-key=<access key>
repo1-s3-key-secret=<secret key>
repo1-retention-full=2
start-fast=y
[main]
pg1-path=/var/lib/postgresql/17/mainrepo1-s3-endpointis the host name only, with nohttps://and no port; the port goes inrepo1-storage-port.repo1-s3-uri-style=pathis required; the default,host, puts the bucket in the host name.- The key can be left out of the file and set in the environment as
PGBACKREST_REPO1_S3_KEYandPGBACKREST_REPO1_S3_KEY_SECRET, which is what the tested run did. If it stays in the file, make the file readable only by thepostgresuser. - If PostgreSQL listens on a port other than 5432, add
pg1-port=<port>to the stanza, or pgBackRest reportsunable to find primary cluster. - With a self-signed certificate, add
repo1-storage-verify-tls=n. The alternative,repo1-storage-ca-filepointing at the certificate, was not tested.
Step 2: Turn on WAL archiving
In postgresql.conf, then restart PostgreSQL:
wal_level = replica
archive_mode = on
archive_command = 'pgbackrest --stanza=main archive-push %p'Step 3: Create the stanza and back up
Run these as the postgres user:
pgbackrest --stanza=main stanza-create
pgbackrest --stanza=main check
pgbackrest --stanza=main --type=full backup
pgbackrest --stanza=main --type=incr backup
pgbackrest --stanza=main info
pgbackrest --stanza=main verifycheck confirms that a WAL segment reached the repository. Schedule the backups with cron or a systemd timer.
Step 4: Restore
Stop PostgreSQL and empty the data directory (or restore to a new server with the same configuration), then run as postgres:
pgbackrest --stanza=main restoreStart PostgreSQL. It replays the archived WAL from the repository, then promotes to a new timeline. To stop at a point in time, add --type=time "--target=2026-10-18 12:00:00+00" to the restore.
Step 5: Remove a stanza (optional)
pgbackrest --stanza=main stop
pgbackrest --stanza=main --force stanza-deleteThis deletes the stanza’s backups and WAL archive from the bucket.
Known limits
- HTTPS only. Pointed at port 9000, pgBackRest fails with
TLS error…wrong version number, because port 9000 is plain HTTP. - The certificate must match the host name. Connecting by IP address to a certificate issued for a name fails verification; use the name, or set
repo1-storage-verify-tls=n. repo1-s3-uri-style=pathis required. With the default, pgBackRest looks up<bucket>.<relayer-host>and fails withunable to get address.- A repository holds many small objects: the test repository, for a small database with two backups and its WAL, held about 1,000 objects.
- Not supported by the Relayer: SSE-KMS (
repo1-s3-kms-key-id) and SSE-C. pgBackRest’s own repository encryption (repo1-cipher-type=aes-256-cbc) works on the client and needs neither; it was not tested here.
