[017] WAL and archiving area — one pass

[lesovsky]

Roadmap 0.12.0 feature [017]. The WAL/archiving code area is entered once, so four related pieces ship together.

What ships

• New archiver screen — nine columns over pg_stat_archiver plus a .ready backlog count, reached by cycling the existing w hotkey (wal ↔ archiver) with a two-item W menu. Nothing is diffed: counters render cumulative and never-archived cells render blank rather than 0.
• record/report support — the screen records with no recorder change, and report -W changes from a boolean to a string flag.
• PG 19 — a fpi,KiB column on the wal screen from the new wal_fpi_bytes, placed next to the fpi counter and inside the diffed range. PG 14–18 layouts are byte-identical.
• Verbose-panel backlog now uses a function a pg_monitor role can actually call.

Breaking change

pgcenter report -W is now a string flag: -W w for pg_stat_wal, -W a for the archiver.

The common legacy shape fails in a way worth knowing: pgcenter report -W -f dump.tar has -f consumed as the flag's value, so it exits with report type is not specified, quit — and with code 0, because main() prints and returns without os.Exit(1). A wrapper using || alert will not fire and will keep an empty output file. Documented in doc/release-notes/v0.12.0.md; the exit code is registered as tech debt [034], since it affects every failure path of report, not just this flag.

Why the verbose panel changed

pg_ls_dir has ACL {postgres} — superuser only — while pg_ls_waldir and pg_ls_archive_statusdir are {postgres, pg_monitor}. So the panel's archiving backlog never worked for the most common monitoring role; it showed n/a. ADR [010] assumed otherwise and is marked superseded in part.

Two consequences, both accepted and recorded: a cluster with a missing archive_status directory now reports a bare 0 instead of n/a (the new function is missing_ok=true), and the walk stats every file rather than listing names.

Cost, measured rather than assumed

On a live stand with 200 005 .ready files, under a pg_monitor-only role with verbose mode on and a concurrent pgcenter record: the backlog query takes ~1108 ms against a 1 s refresh interval, and the effective refresh rate goes from 1.0 s/tick on master to 1.9 s/tick.

Throttling was prepared and then deliberately not applied: the cost is linear at ~5.5 µs per file, so a five-thousand-segment backlog costs ~28 ms. The measured doubling needs 3.1 TB of unarchived WAL — a state noticed long before the refresh rate matters. Numbers are in the tech-spec's Decision 20 rather than the debt register, at the roadmap owner's direction.

Verification

• Full suite in the project CI image on PG 14–19 fixtures: 1085 pass / 86 skip / 0 fail, zero races. Every skip is an EOL cluster absent from the image; none in the PG 14–19 range and none in this feature.
• make lint and make vuln clean.
• 34/34 acceptance criteria, the last ten on a live stand: working and broken archiving, archive_mode=off, both navigation entry paths checked separately for a duplicated subtitle, a 60-column terminal, and the privilege-degradation path.
• No test expectation was weakened. Test_filterViews was strengthened — the counts alone would still have passed with the archiver view dropped.

Known limitations

A wal recording made on PG 19 by a pre-0.12 pgcenter replays against the new 8-column layout and fails with an error beginning diff failed. Narrow (PG 19 is beta), documented in the release notes.

report -W a prints N−1 rows for an N-tick recording — the report always discards the first sample, which for a pass-through screen is real data. Pre-existing behaviour shared with activity.

🤖 Generated with Claude Code