pgBackRest physical backups

komp.ac uses pgBackRest to create and inspect physical PostgreSQL backups. The supplied server commands cover backup setup, full, differential, and incremental backups, repository checks, and backup information.

This is the physical-backup side of PostgreSQL protection. For the separately implemented single-database archive, see pg_dump logical dumps.

Restoration is not exposed by komp.ac

The current server has no restore RPC and the server Makefile has no restore target. Recovery must be performed separately by a PostgreSQL operator using the deployment’s reviewed pgBackRest recovery procedure. Do not build a client workflow that expects komp.ac to restore the database.

What the backup contains

A physical backup covers the complete PostgreSQL cluster selected by the stanza, not one komp.ac profile or table. It includes PostgreSQL-managed application data such as:

• profiles, table definitions, and table rows;
• accounts, journals, periods, and approvals;
• users, roles, and grants;
• migration records, sequences, and PostgreSQL indexes.

It does not include files outside PostgreSQL, including server environment variables, deployment secrets, the pgBackRest configuration, external services, or the original Search subsystem’s tantivy_indexes directory.

If PostgreSQL is ever recovered from one of these backups, rebuild the external Search index from the recovered database. Search2 and Analytics read PostgreSQL directly and do not have that separate index.

Backup and WAL model

The recovery material has two parts:

full backup
└── optional differential or incremental backups
    └── archived WAL after and between backups

• A full backup copies the entire configured PostgreSQL cluster and starts a backup chain.
• A differential backup copies files changed since its associated full backup.
• An incremental backup copies files changed since the immediately previous backup of any type.
• Archived write-ahead log, or WAL, records changes between backups and is required for recovery beyond a backup’s exact state.

Differential and incremental backups are not standalone exports. pgBackRest records their dependencies in its repository. A successful incremental run therefore does not, by itself, prove that the complete chain and required WAL are recoverable.

Configuration

Start from the two examples supplied in the server repository:

• config/pgbackrest.conf.example configures the repository, retention policy, stanza, and PostgreSQL connection details;
• config/postgresql.pgbackrest.conf.example configures PostgreSQL WAL archiving.

The pgBackRest example currently contains:

[global]
repo1-path=/var/lib/pgbackrest
repo1-retention-full=2
repo1-retention-diff=7
repo1-retention-archive=14
repo1-retention-archive-type=incr
start-fast=y
process-max=4
log-level-console=info
log-level-file=info

[komp_ac]
pg1-path=/var/lib/postgresql/data
pg1-port=5432
pg1-user=postgres

These are examples, not guaranteed production values. In particular, confirm repository placement, capacity, retention, encryption and access control for the deployment’s failure model.

PostgreSQL must archive WAL to the same stanza. The supplied PostgreSQL example is:

archive_mode = on
archive_command = 'pgbackrest --config=/etc/pgbackrest/pgbackrest.conf --stanza=komp_ac archive-push %p'
archive_timeout = 60s

Apply PostgreSQL configuration changes using the restart or reload procedure required by the changed settings. Verify archiving with make backup-check before relying on the backups for recovery.

Makefile and server configuration

The Make targets use these defaults:

PGBACKREST=pgbackrest
PGBACKREST_CONFIG=/etc/pgbackrest/pgbackrest.conf
PGBACKREST_STANZA=komp_ac

They may be overridden for one invocation:

make backup-check \
  PGBACKREST=/usr/bin/pgbackrest \
  PGBACKREST_CONFIG=/etc/pgbackrest/pgbackrest.conf \
  PGBACKREST_STANZA=komp_ac

The gRPC backup service uses:

PGBACKREST_BIN=pgbackrest
PGBACKREST_CONFIG=/etc/pgbackrest/pgbackrest.conf
PGBACKREST_STANZA=komp_ac

The service reads those variables when it is created. Restart komp.ac after changing them. Make variable overrides do not alter the running server, and neither interface rewrites PostgreSQL’s archive_command.

Initial setup

For a new backup installation:

1. Install pgBackRest on the PostgreSQL host.
2. Create and review the real pgBackRest and PostgreSQL configurations from the examples.
3. Enable WAL archiving and apply the PostgreSQL configuration.
4. Run make backup-stanza-create once for the new stanza.
5. Run make backup-check and resolve every error.
6. Create the first base with make backup-full.
7. Inspect it with make backup-info.
8. Schedule full, differential, and incremental backups according to the required recovery window.
9. Monitor failures, WAL continuity, repository capacity, retention, and backup age.
10. Prove recoverability using an isolated recovery procedure owned outside komp.ac.

make backup is only an alias for make backup-incr; it does not choose a sensible schedule automatically.

Nothing schedules backups automatically

Neither the Makefile nor the Rust server starts backups on a timer. Configure an external scheduler and include recurring full backups. Do not let incremental backups depend indefinitely on one old full backup.

Continue with pgBackRest commands, pgBackRest server operations, and pgBackRest safety.