Learn pgBackRest - Core Concepts & Main Architecture

#Introduction

After understanding the history and philosophy in episode 1, it's time to dissect the anatomy of pgBackRest. If episode 1 answered "why," episode 2 answers "how it's put together" — and this matters because all the configuration and commands in the following episodes reference these concepts. Understand the architecture and every command feels logical; don't, and you'll only be memorizing commands.

Three key concepts you must master: the stanza, the repository, and the backup process. All three will appear in nearly every line of configuration and every command we write.

#pgBackRest Architecture

#Stanza: Backup Unit per Database Cluster

A stanza is the backup unit for one PostgreSQL cluster. Each cluster (primary, or later in episode 18, standby) has its own stanza with a freely chosen name we decide — for example main, prod, or analytics. The stanza separates all data (backups, WAL, metadata) between clusters inside the same repository.

[global]
repo1-path = /var/lib/pgbackrest
 
[main]
pg1-path = /var/lib/postgresql/16/main

Here [main] is the stanza for the cluster whose PGDATA is at /var/lib/postgresql/16/main. A single repository can hold many stanzas — imagine one host with three clusters: main, reports, warehouse, each with its own stanza.

#Repository: Backup Storage Destination

The repository is where all backups and WAL are stored. Three repository types are supported:

• Local: a directory on the same host as the database (repo1-path).
• Remote: a directory on another host, accessed via SSH (repo1-host).
• Object storage: S3-compatible, Azure Blob, or GCS (repo1-type=s3 etc.).

pgBackRest supports up to two repositories (repo1, repo2) at once — the common pattern is one local for fast recovery and one object storage for off-site. We'll build this configuration in episode 12.

#Backup Process: Full, Differential, Incremental

pgBackRest organizes backups into three complementary types:

• Full: copies the entire cluster data. The foundation of all other backups.
• Differential: only the changes since the last full backup.
• Incremental: only the changes since any last backup.

Full (Sun) ── Diff (Mon) ── Incr (Tue) ── Incr (Wed)
   └── basis      └── since Full   └── since Incr  └── since Incr

Because each backup only stores the changes, this combination saves space and time — we'll break down the details in episode 5.

#Main Components

#The pgbackrest Binary

One binary does everything. Check the available commands:

pgbackrest help

Core commands: backup (create a backup), restore (recover), archive-push (accept WAL from PostgreSQL), archive-get (send WAL during restore), info (status), check (validation), stanza-create (initialize a stanza), and expire (retention).

#The /etc/pgbackrest.conf Config

All options are stored in a config file (INI format). Its structure has two parts: [global] for options that apply to all stanzas, and [stanza-name] for cluster-specific options:

[global]
repo1-path = /var/lib/pgbackrest
log-level-file = info
process-max = 4
 
[main]
pg1-path = /var/lib/postgresql/16/main
pg1-port = 5432

Both global and per-stanza options can be overridden per command via --option arguments, for example pgbackrest --stanza=main --type=diff backup.

#archive_command in postgresql.conf

This is the bridge between PostgreSQL and pgBackRest. When archive_mode=on, every time WAL is rotated PostgreSQL calls archive_command — which we point at pgBackRest:

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

%p is the full path of the WAL being archived. pgBackRest copies, compresses, and encrypts that WAL into the repository. The reverse direction (during restore) uses archive-get, which is integrated automatically by the restore command.

#One-Way Data Flow

Let's follow the data path in a single backup cycle:

1. PostgreSQL writes transactions to WAL, then rotates the WAL.
2. archive_command calls pgbackrest archive-push %p → WAL enters the repository.
3. pgbackrest backup copies the data files + consults the already-archived WAL for consistency.
4. In a disaster, pgbackrest restore copies the data files back + uses archive-get to replay WAL up to the desired point.

 PostgreSQL ──archive-push──▶ Repository ◀──backup── pgbackrest
      ▲                                  │
      └──────── archive-get ─────────────┘
                 (during restore)

#The Most Commonly Used Commands

Throughout this series you'll use these five commands in nearly every episode:

pgbackrest --stanza=main stanza-create
pgbackrest --stanza=main check
pgbackrest --stanza=main backup --type=full
pgbackrest info
pgbackrest --stanza=main restore

Note the pattern: --stanza determines which cluster is touched, followed by the command you want to run. info displays the status of all stanzas and backups in a table.

#Conclusion

Key takeaways:

• Stanza = backup unit per cluster; one repository can hold many stanzas.
• Repository = backup destination: local, remote (SSH), or object storage.
• Backup process = full (foundation), differential (since last full), incremental (since last backup).
• Components = the pgbackrest binary, the /etc/pgbackrest.conf config, archive_command in postgresql.conf.
• Flow = archive-push in, consistent backup, restore + archive-get out.

In the next episode we'll install and configure pgBackRest for real — from installing the distribution package or building from source, creating the user and directories, to writing your first /etc/pgbackrest.conf with correct [global] and [stanza] sections. It's time to get your hands on the keyboard!