Learn pgBackRest - Stanza, Check & Your First Backup

#Introduction

Our configuration was correct in episode 3, but there's not yet a single real stanza in the repository. In episode 4 we do three things for the first time: create a stanza, validate the entire chain, and run your first full backup. These three moments are the "first heartbeat" of your backup system.

The order must not be reversed: the stanza must be created before check, and check must succeed before the backup. pgBackRest will indeed refuse commands that skip this sequence — but understanding why the order matters will save you from confusion when errors appear.

#Creating a Stanza with stanza-create

#Why the Stanza Must Be Created First

stanza-create registers the cluster's metadata in the repository: cluster identity (system identifier and timeline), PGDATA location, and archiving status. Without this registration, pgBackRest doesn't know which cluster it's managing — and refuses to accept backups or WAL.

#Running stanza-create

Create the main stanza

sudo -u postgres pgbackrest --stanza=main stanza-create

Note: we run the command as the postgres user. This is important because pgBackRest accesses the repository and database with the same user identity. A successful output is short and clean — no news is good news.

Note

All pgBackRest commands should preferably be run as the postgres user (via sudo -u postgres) when handling a local cluster. Alternatively, create a dedicated pgbackrest user — that's a practice we cover in episode 13 for remote mode. For now, sudo -u postgres is enough.

#Validation with pgbackrest check

#What Is Checked

pgbackrest check is a comprehensive "health check" that validates five things at once:

Database connection matches the configured pg1-host/pg1-path.
Cluster version and identity match the stanza that was created.
Repository is accessible and writable.
archive-push works — it archives a small test file.
archive-get works — it retrieves that test file back.

Let's run it:

Validate the entire chain

sudo -u postgres pgbackrest --stanza=main check

A successful output:

Healthy check output

P00   INFO: check command end: completed successfully (72ms)

#If Check Fails

The most common failure on the first try is WAL archiving not yet enabled. check runs a test archive-push that requires archive_mode=on in postgresql.conf. If it fails, enable it:

postgresql.conf

archive_mode = on
archive_command = 'pgbackrest --stanza=main archive-push %p'
archive_timeout = 60

then restart: sudo systemctl restart postgresql. If the error is about permissions or cluster identity, redo the directory owner verification (episode 3) and make sure the stanza was never created for a different cluster.

Tip

Make pgbackrest check a daily ritual, not a one-off. In episode 14 we'll schedule it as part of monitoring — a check failure is the fastest early signal for WAL archiving problems.

#Your First Full Backup

#Running the Backup

With a healthy stanza, it's time for the first full backup:

First full backup

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

--type=full copies the entire PGDATA into the repository. For a small database, this finishes in seconds. Notice the output shows per-file progress and a duration summary:

Full backup output

P00   INFO: backup command begin 2.59.0: ...
P01   INFO: backup file ... (100%)
P00   INFO: backup command end: completed successfully (2.1s)

#Reading Status with pgbackrest info

After the backup finishes, look at the stanza status:

Status of all stanzas

sudo -u postgres pgbackrest info

The output shows a summary per stanza — cluster version, archived WAL, and the backup list:

Info summary

stanza: main
    status: ok
    cipher: none
 
    db (current)
        wal archive min/max (16): 000000010000000000000001/...
        full backup: 20260813-090000F
            timestamp start/stop: 2026-08-13 09:00:00 / 09:00:02
            wal start/stop: ...
            database size: 24.8MB, backup size: 24.8MB

Backup labels like 20260813-090000F have meaning: the date-time the backup started, ending with a type letter (F = full, D = differential, I = incremental). This label is the identity used by the restore and expire commands later.

For a more structured view (used by monitoring scripts), there's a JSON format:

Info in JSON format

sudo -u postgres pgbackrest info --output=json

#The Daily Workflow Taking Shape

After episode 4, your daily cycle can already be:

pgbackrest --stanza=main check — make sure the chain is healthy.
PostgreSQL archives WAL automatically via archive_command.
pgbackrest --stanza=main backup --type=full — a scheduled full snapshot.
pgbackrest info — verify the newest backup shows up.

There's no automation yet — that comes in episode 10. For now, focus on mastering the manual commands.

Warning

Never run your first backup without stanza-create and a successful check. The backup will fail immediately with a stanza-not-found error, and you'll waste time diagnosing something that's really about ordering. The order: stanza-create → check → backup.

#Conclusion

Key takeaways:

stanza-create registers the cluster in the repository — required before anything else.
check validates the DB connection, repository, and archive-push/get all at once.
backup --type=full copies the entire PGDATA; the first backup is always full.
pgbackrest info reads the stanza status and backup labels (...F, ...D, ...I).
The golden order: stanza-create → check → backup.

In the next episode we'll dissect the three backup types — full, differential, and incremental — with example chains, how each works and their sizes, plus the retention settings (repo1-retention-full, repo1-retention-diff) that make the combination of the three space-efficient without losing recovery guarantees. Starting this episode, your backup strategy is no longer "full every day" but a planned system!