What retains WAL, and what releases it · PostgreSQL

A full pg_wal filesystem stops the cluster. It is one of the most common ways a PostgreSQL server goes down, it is entirely preventable, and there are exactly four things that cause it.

The four mechanisms

Mechanism	Bounded by	Default bound
Checkpoint distance	`max_wal_size`	1 GB, soft
Replication slots	`max_slot_wal_keep_size`	unlimited
Unarchived segments	Nothing	unlimited
`wal_keep_size`	Itself	0

Two of those four are unbounded by default. That is the whole problem.

Replication slots

A slot records the position a consumer has reached, and PostgreSQL retains every segment from that position onward. It does this whether or not the consumer still exists.

A slot retains nothing until it reserves a position

This surprises people, and it matters when you are trying to work out whether a slot is the thing filling your disk.

Read-only / Safea slot created the ordinary way— EXECUTION VALIDATED on 18.6. Followed by three rounds of bulk writes, drops and checkpoints.

$ SELECT pg_create_physical_replication_slot('demo_slot');
SELECT slot_name, active, restart_lsn, wal_status FROM pg_replication_slots;

 pg_create_physical_replication_slot
-------------------------------------
(demo_slot,)                          <- no LSN returned

slot_name | active | restart_lsn | wal_status
-----------+--------+-------------+------------
demo_slot | f      |             |              <- BOTH NULL

pg_wal before: 257M, 16 segments
pg_wal after:  257M, 16 segments        <- no growth at all

A physical slot with no restart_lsn holds nothing. It starts reserving only when a standby connects to it, or when it is created with immediately_reserve.

Read-only / Safethe same slot, created with immediately_reserve, then some write traffic— EXECUTION VALIDATED on 18.6. The slot has never been connected to — active is false throughout. Four rounds of bulk write, DROP and CHECKPOINT followed.

$ SELECT pg_create_physical_replication_slot('demo_slot', immediately_reserve => true);
SELECT slot_name, active, restart_lsn,
     pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS wal_retained
FROM pg_replication_slots;

 pg_create_physical_replication_slot
-------------------------------------
(demo_slot,0/39247A98)                <- an LSN is returned

slot_name | active | restart_lsn | wal_retained
-----------+--------+-------------+--------------
demo_slot | f      | 0/39247A98  | 169 MB
standby1  | t      | 0/43BC14E0  | 0 bytes

169 megabytes pinned by a slot that no standby has ever used, while the slot with a live standby attached holds nothing at all. Dropping it and checkpointing twice released 64 MB and four segments — pg_wal went from 241 MB and 15 segments to 177 MB and 11.

Two checkpoints, because recycling happens at checkpoint time and the first one only establishes the new horizon.

At the 4,359 kB/s generation rate measured in lesson XII-02, an unattended reserving slot accumulates about 367 GB a day, indefinitely.

The abandoned slot is the classic outage

The sequence is always the same:

A standby is built, with a slot.
The standby is decommissioned, or fails, or is rebuilt with a new slot name.
Nobody drops the old slot.
WAL accumulates at the full generation rate.
Days or weeks later, pg_wal fills and the cluster stops.

It is silent for the entire period. The cluster is healthy, replication is not configured to that slot, and nothing reports it.

The query that would have caught it:

SELECT slot_name, slot_type, active, database,
       pg_size_pretty(pg_current_wal_lsn() - restart_lsn) AS wal_retained,
       wal_status,
       pg_size_pretty(safe_wal_size)                      AS safe_wal_size
  FROM pg_replication_slots
 ORDER BY pg_current_wal_lsn() - restart_lsn DESC;

active = f on a slot retaining a meaningful amount of WAL is the finding. Put it in monitoring with a threshold, not on a dashboard nobody reads.

wal_status is the summary PostgreSQL computes itself:

`wal_status`	Meaning
`reserved`	Within `max_wal_size`
`extended`	Beyond `max_wal_size` but within `max_slot_wal_keep_size`
`unreserved`	Beyond the limit; the slot will be invalidated if more WAL is needed
`lost`	Required WAL has been removed. The slot is unusable

Bounding it

-- cap what any one slot may retain
ALTER SYSTEM SET max_slot_wal_keep_size = '100GB';
SELECT pg_reload_conf();

The trade is explicit and worth being clear about: a slot that exceeds the cap is invalidated, and the standby that depended on it must be rebuilt from a fresh base backup. That is a real cost, and it is smaller than the primary going down.

Set it to a value that a healthy standby will never approach — large enough to survive a network partition or a long maintenance window, small enough that the filesystem cannot fill.

PostgreSQL 18 adds a second, complementary bound. From the release notes:

Allow inactive replication slots to be automatically invalidated using server variable idle_replication_slot_timeout

ALTER SYSTEM SET idle_replication_slot_timeout = '7d';

This addresses the abandoned-slot case directly rather than by proxy: a slot with no consumer for seven days is invalidated on time rather than on volume. The two settings answer different questions — one bounds space, the other bounds neglect — and both default to off.

Unarchived segments

With archive_mode = on, a segment cannot be recycled until archive_command has reported success for it. A failing archive command therefore fills the disk at the full generation rate, and it does so whether the failure is loud or silent.

Read-only / Safethe archiver's own view of itself— Captured on 18.6. Archiving is off on this cluster, hence the zeros.

$ psql -U postgres -x -c "SELECT * FROM pg_stat_archiver"

archived_count     | 0
last_archived_wal  |
last_archived_time |
failed_count       | 0
last_failed_wal    |
last_failed_time   |
stats_reset        | 2026-08-27 21:01:04.021891+00

The two comparisons that matter:

failed_count increasing means the command is failing now. Look at last_failed_wal and the server log for the command’s stderr.

last_archived_time falling behind means the archiver is not keeping up even though nothing is failing — the command is too slow for the generation rate. That is a capacity problem rather than an error, and it fills the disk just as effectively.

Lesson XIII-05 covers writing an archive_command that fails correctly.

The response, in order

When pg_wal is filling:

1. Establish which mechanism. One query each:

SELECT slot_name, active, pg_size_pretty(pg_current_wal_lsn() - restart_lsn) AS retained, wal_status
  FROM pg_replication_slots ORDER BY 3 DESC;

SELECT archived_count, failed_count, last_archived_time, last_failed_time, last_failed_wal
  FROM pg_stat_archiver;

SHOW wal_keep_size;
SHOW max_wal_size;

2. Act on the mechanism, not on the symptom. Drop the abandoned slot; fix or replace the archive command; lower wal_keep_size.

3. Then CHECKPOINT to allow recycling to proceed.

Never delete files from pg_wal by hand

This is the single most destructive instruction available on a PostgreSQL server, and it is the first thing an operator reaches for when a disk is full.

Deleting a WAL segment that recovery still needs makes the cluster unrecoverable. Not degraded, not slower — unrecoverable, because the chain from the last checkpoint’s redo location forward is broken and there is nothing that can reconstruct it.

The supported tool is pg_archivecleanup, which removes segments no longer required given a stated position, and it is for cleaning an archive, not pg_wal.

If the filesystem is genuinely full and the cluster will not start:

Free space elsewhere on the same filesystem if anything can be moved.
Add space, which on most systems is possible.
Move pg_wal to a larger filesystem and symlink it, with the cluster stopped.
Only then consider anything else, having taken a copy of the entire data directory first.

The emergency space to reclaim is never WAL. It is logs, temporary files, or anything else on that filesystem.

What min_wal_size does, and why pg_wal does not shrink

min_wal_size (80 MB by default) is not a floor on how much WAL exists. It is how many segment files PostgreSQL keeps around for recycling rather than deleting.

Writing WAL into a file that already exists is cheaper than creating one: the space is allocated, the filesystem metadata is settled, and on many filesystems the write avoids a metadata update entirely. So PostgreSQL renames used segments forward rather than deleting them.

The number kept is driven by an estimate of recent demand, which is the estimate= figure in the checkpoint log line:

distance=536114 kB, estimate=536114 kB

distance is how much WAL the last checkpoint interval actually produced; estimate is a smoothed prediction used to decide how many files to retain. It decays slowly, which is deliberate — a cluster that has one busy hour a day should not spend the other twenty-three recreating files it will need again.

Two consequences.

pg_wal does not shrink promptly after a write burst. The files are retained for reuse and the estimate decays over many checkpoints. A directory that is 40 GB after a bulk load and still 40 GB an hour later is behaving correctly.

du on pg_wal is not a measure of retention. It is retention plus recycling headroom. To know how much is genuinely required, read the slots, the archiver and pg_controldata’s redo location — not the directory size.

Raising min_wal_size on a cluster with bursty write patterns avoids the create-and-delete cycle at the cost of the space. Lowering it on a space-constrained cluster reclaims space at the cost of more file creation during bursts.

What to take from this

Four mechanisms retain WAL. Two — slots and unarchived segments — are unbounded by default.
Measured: an inactive slot with a reserved position pinned 169 MB and would have continued at 367 GB a day.
wal_status is PostgreSQL’s own summary. lost means the slot is unusable and the standby needs rebuilding.
Set max_slot_wal_keep_size, and in 18 also idle_replication_slot_timeout. Both default to off.
pg_stat_archiver: failed_count rising is an error; last_archived_time falling behind is a capacity problem. Both fill the disk.
Never delete files from pg_wal. It makes the cluster unrecoverable.

Cross-course references

Observability for Production Sysadmins — Part LIX (Database observability) covers alerting on each of the four retention causes separately, because the response differs and a single “pg_wal is large” alert does not distinguish them.
Linux for Production Sysadmins — Part XIV (Filesystems) covers why a separate filesystem for pg_wal turns a cluster-down into a bounded problem.