Postgres Replication Slots: Cap WAL Retention Before Disk Full
Every Postgres fleet eventually meets the same outage: the primary’s WAL volume fills, the server dies with No space left on device, and the whole cluster stops — not just the replica that was already behind. The usual cause is a replication slot nobody is watching. A slot holds WAL unconditionally, so a consumer that stops confirming LSNs quietly converts free disk into a countdown.
That countdown is now measurable instead of guessed. Dasha 1.10, released 2026-11-09, adds a replication slot invalidation forecast: it measures the server’s WAL rate over a 30-second to 5-minute window by sampling two LSNs on the server clock, then shows for every slot the WAL it retains, the remaining max_slot_wal_keep_size reserve, and the time left before that slot is lost. Useful — but a forecast only reads a clock that your configuration should already have bounded. Here is the architecture side of that problem.
What a slot actually retains
Two very different objects share one mechanism. A physical slot is a promise to one standby: WAL stays until that standby reports it has flushed past a given LSN. A logical slot is a promise to a decoder — pgoutput for a subscriber, Debezium, a CDC pipeline — and it retains WAL from restart_lsn or confirmed_flush_lsn onward. Checkpoint cannot recycle anything past the oldest of those positions across all slots, regardless of max_wal_size.
Do not confuse this with hot_standby_feedback, which is a row-retention problem (bloat on the primary), not a WAL-retention problem. A hot standby with a long-running query makes the primary keep dead tuples alive; a stalled slot makes the primary keep WAL alive. Both end in an outage, but only the slot fills pg_wal.
Measure retention, not slot count
Every slot has an LSN. Convert it to bytes and sort descending, and the real risk ranking falls out immediately:
SELECT slot_name,
slot_type,
active,
wal_status,
pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal,
pg_size_pretty(safe_wal_size) AS headroom_before_invalidation,
database,
plugin
FROM pg_replication_slots
ORDER BY pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) DESC;
The wal_status column is the state machine that matters. reserved means the slot is still inside its guaranteed reserve; extended means it has grown past it and is eating the reserve; unreserved means the next checkpoint may remove WAL the slot still needs; lost means it is already dead. safe_wal_size is the number of bytes you can still write before invalidation — and it is NULL when max_slot_wal_keep_size = -1, which is the default and means “no limit”. A NULL there is the single most expensive NULL in a Postgres cluster.
Do the capacity math
Set the reserve from peak WAL rate, not average:
max_slot_wal_keep_size >= peak_wal_rate × longest_acceptable_consumer_outage + margin
For a cumulative view, PostgreSQL 14+ keeps it in one place:
SELECT pg_size_pretty(wal_bytes::bigint) AS wal_total,
pg_size_pretty((wal_bytes / GREATEST(EXTRACT(epoch FROM now() - stats_reset), 1))::bigint)
AS avg_bytes_per_second
FROM pg_stat_wal;
An average hides the batch spike that actually kills you. Sample pg_current_wal_lsn() once a minute through your heaviest window — nightly ETL, month-end close, a bulk load — and use the worst five-minute stretch. A cluster averaging 8 MB/s can hit 60 MB/s during a rebuild; sizing to the average is how you get a 4 a.m. page.
Bound it in postgresql.conf
# pg_wal lives on a 2 TB volume; keep ~700 GB of real headroom
max_slot_wal_keep_size = '1TB' # default -1: a slot may fill the whole disk
wal_keep_size = '4GB' # covers short-lived standbys without a slot
max_wal_size = '64GB'
checkpoint_timeout = '15min'
Size max_slot_wal_keep_size to roughly half the pg_wal volume, minus max_wal_size and room for a checkpoint spike. Then accept the trade explicitly: setting it converts a cluster-wide panic into a scoped failure. The primary keeps running, the offending slot is invalidated, and one consumer dies instead of the database. Leaving it at -1 is a decision to let one forgotten slot take production down.
What invalidation costs, and how to recover
-- Skip a stalled logical slot forward; the consumer must accept the data gap
SELECT pg_replication_slot_advance('debezium_orders', pg_current_wal_lsn());
-- Reclaim a slot whose consumer is gone for good
SELECT pg_drop_replication_slot('debezium_orders');
-- After a physical slot is lost, the standby needs a fresh base backup
SELECT pg_create_physical_replication_slot('standby1');
A lost physical slot means pg_basebackup for that standby — minutes to hours depending on size. A lost logical slot means the consumer re-snapshots a table it thought was already replicated, which is a correctness conversation, not just an ops one. On PostgreSQL 17 and later, failover slots (sync_replication_slots) copy logical slot state to standbys so a promoted replica does not arrive without the slots your CDC pipeline depends on. Whether that matters for you is an honest test of your failover plan; the archive-mode failure mode in why failover breaks backups is the same class of surprise.
Alert on the transition, not the percentage
SELECT slot_name, slot_type, wal_status, pg_size_pretty(safe_wal_size) AS headroom
FROM pg_replication_slots
WHERE wal_status IN ('unreserved', 'lost')
OR (safe_wal_size IS NOT NULL AND safe_wal_size < 100::bigint * 1024 * 1024 * 1024);
Disk-usage alerts fire too late and too often; wal_status moving to unreserved is the signal that a decision is now urgent. Pair it with an ownership register — one named team per logical slot — and slot count becomes a capacity input rather than an accumulation. If you already run Dasha for index advice, as in our Dasha setup tutorial, the same instance now forecasts slot invalidation and discovers Patroni scopes from etcd or Consul, which removes most of the manual inventory work.
Where this bites in Houston
The recurring local pattern is a CDC pipeline — Postgres into Kafka for container events at the port, or meter and trading data for an energy desk — where the connector stops during a maintenance window and nobody notices until Monday. The slot keeps its promise to a consumer that is not there. Two rules close that gap: every logical slot has an owner and a maximum retention window agreed in advance, and the failover drill includes the slot inventory, not just the promotion. Our restore verification runbook is the checklist to fold that into.
If your fleet has CDC slots feeding downstream systems and nobody can name the retention limit on them, get a replication and failover review from our Postgres team before the next disk-full incident.
