skip to content

With pgBackRest, what is a stanza, and what steps take a new PostgreSQL cluster to its first backup with WAL archiving proven to work?

level: juniorimportance: should knowfreq 42%

answer

  1. one cluster, one named configuration
  2. name it for its function
  3. archive_command calls archive-push
  4. stanza-create, then check
  5. 2.59 and the root user

basics

~20 s

A stanza is pgBackRest's named configuration for one PostgreSQL cluster: its data path, repositories and options. Set archive_command to pgbackrest archive-push, run stanza-create, prove archiving with check, then take the first backup, which is automatically a full.

solid answer

~50 s

A **stanza** is the configuration for one PostgreSQL cluster: where its data directory is (`pg1-path`), which repositories (`repo1`, `repo2`, ...) hold its backups and WAL, and any per-cluster options. The primary and every replica share the name, so name it after the cluster's job (`analytics`), not after a host. Setup goes like this. Write `pgbackrest.conf` with `[global]` repository settings and an `[analytics]` section. Set `archive_mode = on`, which needs a restart, and `archive_command = 'pgbackrest --stanza=analytics archive-push %p'`. Run `stanza-create`, which initialises the stanza in every configured repository, then `check`, which forces a WAL switch and waits for that segment to reach the repository. Finally run `backup`: the default type is `incr`, but with no full to base it on pgBackRest takes a full. Run everything as `postgres`; since 2.59 only `restore` may run as root without `allow-root`.

code

ini · 11 lines
ini
# /etc/pgbackrest/pgbackrest.conf
[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
start-fast=y

[global:archive-push]
compress-level=3

[analytics]
pg1-path=/var/lib/postgresql/18/main

go deeper

for a junior

Recall that a stanza is one PostgreSQL cluster's backup configuration, and the order of setup: archive_command with archive-push, stanza-create, check, then backup.

for a middle

Explain why check matters: it forces a WAL switch and waits for that segment in the repository, catching a broken archive before a backup stalls waiting for WAL.

for a senior

Show operating habits: name the stanza by function so failovers do not confuse it, run every command as postgres, and know the 2.59 allow-root change before upgrading.

for a principal

Treat the stanza as the unit of backup policy: one cluster, one name across replicas and repositories, with conventions that every team's automation can rely on.

## What a stanza is pgBackRest organises everything around the **stanza**. A stanza is the configuration for one PostgreSQL **database cluster**, meaning one data directory served by one postmaster. It records where that cluster lives, which repositories hold its backups and archived WAL, and how it is backed up. A database server normally carries one stanza. A dedicated backup host carries one stanza for each cluster it protects. Every command takes `--stanza=<name>`, and the repository files each stanza's backups and WAL under that name. Two consequences matter in practice: - **The stanza is the whole cluster, not one database.** pgBackRest takes physical backups of the data directory, so every database in the cluster lands in the same backup set. - **The name outlives hosts.** The primary and all of its replicas use the same stanza. The user guide therefore recommends naming it after the cluster's function (`analytics`, `dw`), not after a host such as `db01`, which may be a replica tomorrow. ## The configuration file `pgbackrest.conf` uses an INI-like format. Global settings such as `repo1-path` and `repo1-retention-full` go in `[global]`. Cluster settings go in the stanza's own section, including `pg1-path`, which must equal the server's `data_directory`. A section can also be scoped to one command, and the more specific section wins: | precedence | section | typical use | |---|---|---| | 1 (highest) | `[analytics:archive-push]` | a cheaper `compress-level` for archiving this stanza only | | 2 | `[analytics]` | `pg1-path` and per-cluster overrides | | 3 | `[global:archive-push]` | archiving options for every stanza | | 4 (lowest) | `[global]` | repositories, retention, `start-fast` | ## Wiring PostgreSQL's WAL archiving A backup of a running cluster can only be restored together with the WAL written while the backup ran, so archiving must work first. In `postgresql.conf`: - `archive_mode = on`. This setting takes effect only after a **restart**. - `archive_command = 'pgbackrest --stanza=analytics archive-push %p'`. A reload is enough for this one. PostgreSQL then calls `archive-push` once for every completed segment. pgBackRest compresses the segment, checksums it and stores it in each configured repository. The matching `archive-get` command is what a later restore writes into `restore_command`. The core semantics of `archive_command` belong to the PostgreSQL PITR topic. This topic covers pgBackRest's side. ## stanza-create, check, then the first backup 1. **`stanza-create`** initialises the stanza's metadata (`archive.info` and `backup.info`) in the repository. With several repositories configured it creates the stanza in each one and skips any that already have it, so rerunning it after adding a repository is safe. 2. **`check`** proves the archiving path end to end. On the primary it calls `pg_create_restore_point('pgBackRest Archive Check')` and `pg_switch_wal()`, then waits up to `archive-timeout` (60 seconds by default) for that segment to appear in the repositories. A broken `archive_command` shows up here, not later as a backup that cannot finish. 3. **`backup`**: the default `--type` is `incr`. An incremental needs a full to build on, so on an empty stanza pgBackRest reports that no prior backup exists and takes a **full**. Setting `start-fast=y` forces a checkpoint so the backup begins at once. Without it, the backup waits for the next scheduled checkpoint. 4. **`info`** then lists the new backup with its label (ending in `F` for full), its WAL range and its sizes. ## Running as the right user Run every command as the operating-system user that owns the cluster and the repository, usually `postgres`. Since **pgBackRest 2.59** this rule is enforced: `allow-root` defaults to false for every command except `restore`. A `backup`, `check` or `expire` run as root therefore fails with an error saying the command must not be run as the root user. The reason is file ownership: a command run as root can leave root-owned files in the repository or the spool path, and later commands running as `postgres` cannot read them. `restore` is exempt because it is built to recreate the ownership recorded in the backup manifest. ## Mistakes interviewers listen for - Treating a stanza as one database, or creating several stanzas for one cluster. - Copying files into the repository directory with `cp` instead of calling `archive-push`. - Reloading after changing `archive_mode` and then wondering why nothing is archived. - Skipping `check`, so the first sign of a broken archive is a backup that times out waiting for WAL. - Running scheduled jobs as root, which pgBackRest 2.59 now refuses.

  • After upgrading to pgBackRest 2.59, a root cron job running pgbackrest backup starts failing. Why, and what is the right fix?
    In 2.59, `allow-root` defaults to false for every command except `restore`, so the backup fails with an error saying it must not be run as root. The concern is ownership: commands run as root can leave root-owned files in the repository or spool path, and later runs as `postgres` cannot read them. Move the job to the repository owner, usually `postgres`. Setting `allow-root=y` also works but is discouraged.
  • Why does the pgBackRest guide advise naming a stanza after the cluster's function rather than its host?
    The same stanza name is used on the primary and on every replica, and after a failover a different host is the primary. A function name such as `analytics` or `dw` stays accurate through failovers and rebuilds. A host name such as `db01` becomes misleading the first time the roles swap.
  • In pgbackrest.conf, how do you give archive-push its own settings without changing backups?
    Use a command-scoped section. `[global:archive-push]` applies to archive-push for every stanza, and `[analytics:archive-push]` applies to one stanza. Precedence runs `[stanza:command]`, then `[stanza]`, then `[global:command]`, then `[global]`. A lower `compress-level` there makes archiving cheaper while backups keep their own compression.

  • A stanza is one database inside the cluster, so each database gets its own stanza.
  • archive_command can simply cp the segment into the pgBackRest repository directory.
  • Changing archive_mode only needs a configuration reload.
  • Run pgBackRest as root so it can read every file in the data directory.
  • The first backup fails unless you pass --type=full explicitly.
  • stanza-create has to be run once per repository with --repo.

Assumes pgBackRest 2.59, where only restore may run as root unless allow-root is set; earlier releases allowed every command to run as root.