Skip to content

C02 — pgBackRest Configuration & WAL Archiving

Whether write-ahead log is actually leaving the server the way it's supposed to. Most of pgBackRest's own configuration lives in a host file (pgbackrest.conf) with no SQL-accessible equivalent — see Third-Party Notices for exactly what had to be left out for that reason — so what's left here is what's actually visible from inside a database session: whether archive_command is configured at all, whether pg_stat_archiver shows archiving failures, and (PostgreSQL 17+) whether summarize_wal is on, a prerequisite for incremental backup.

3 checks, PGHF02-001 through PGHF02-003. Every check here is PGHF-namespace and built-in — see Metadata Columns Explained for what each field below actually means, and Resetting to Defaults for why these definitions can't be hand-edited in place.

PGHF02-001 — archive_command

An empty, disabled, or no-op archive_command (e.g. /bin/true) means WAL is silently not being archived — point-in-time recovery is impossible even though the server looks otherwise healthy.

How to fix

Set archive_mode/archive_command to a real archiving destination and confirm it actually succeeds, not just that it's configured:

ALTER SYSTEM SET archive_mode = on;
ALTER SYSTEM SET archive_command = 'pgbackrest --stanza=main archive-push %p';

archive_mode requires a restart; archive_command alone only needs a reload once archive_mode is already on. After restarting, watch pg_stat_archiver (PGHF02-002) to confirm last_archived_wal is advancing and last_failed_wal stays empty.

PGHF02-002 — pg_stat_archiver failures

Any recorded archiver failure means at least one WAL segment failed to archive on its first attempt — PostgreSQL retries, but persistent failures are exactly how PITR gaps and eventual disk exhaustion begin.

How to fix

  1. Check pg_stat_archiver.last_failed_wal/last_failed_time and the server log around that time for the archiver's actual error (permission denied, destination unreachable, disk full at the archive target, and similar are the usual causes).
  2. Fix the underlying cause (credentials, network path, disk space) rather than just the symptom.
  3. Once fixed, PostgreSQL retries automatically — confirm last_archived_wal catches back up to the current WAL position. If pg_wal is already under pressure, see PGHF14-001.
  4. SELECT pg_stat_reset_shared('archiver') clears the counters for a clean baseline once the underlying issue is actually resolved, not before.

PGHF02-003 — Incremental-backup readiness (summarize_wal)

Requires PostgreSQL 17+.

PG17's incremental pg_basebackup depends entirely on WAL summarization having run continuously — if summarize_wal was only turned on the day of the incremental-backup attempt, there's no summary history to diff against and it silently falls back to a full copy (or fails outright). The same "looks fine until the moment you need it" gap PGHF02-001 exists to catch for archive_command, just for the incremental-backup mechanism instead.

How to fix

ALTER SYSTEM SET summarize_wal = on;
SELECT pg_reload_conf();

This takes effect immediately but the summary history only starts accumulating from here forward — an incremental backup taken right after enabling this still has nothing to diff against for anything older. Wait for at least one full backup cycle's worth of summaries (pg_available_wal_summaries()) before relying on incremental backup for real recovery, and confirm with a test restore, not just a green check here.

Continue to C03 — Performance Parameters.