max_slot_wal_keep_size

Definition PG 18 manual

Specify the maximum size of WAL files that replication slots are allowed to retain in the pg_wal directory at checkpoint time. If max_slot_wal_keep_size is -1 (the default), replication slots may retain an unlimited amount of WAL files. Otherwise, if restart_lsn of a replication slot falls behind the current LSN by more than the given size, the standby using the slot may no longer be able to continue replication due to removal of required WAL files. You can see the WAL availability of replication slots in pg_replication_slots. If this value is specified without units, it is taken as megabytes. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

At checkpoint time PostgreSQL compares a slot's restart_lsn with the current WAL position. With the default -1 there is no parameter-imposed maximum; a stalled consumer can therefore retain enough WAL to fill pg_wal.

With a finite limit, required segments can be released when a slot falls too far behind. The slot can move through unreserved to lost status, and its consumer may need a new base backup or logical resynchronization. The cap protects server storage by sacrificing the guarantee that an indefinitely lagging slot remains usable.

Enforcement is checkpoint-based, so it is neither instantaneous nor an exact byte ceiling. pg_replication_slots exposes restart_lsn, wal_status, invalidation_reason, and safe_wal_size; these are the operational signals needed before the slot reaches the limit.

Operational considerations

Leaving -1 and assuming a stalled slot cannot fill the disk.

Treating the finite value as an instantaneous hard ceiling despite checkpoint-based enforcement.

Setting it too low and invalidating a healthy consumer during a planned bulk load.

Assuming a consumer can always resume after its required WAL has been removed.

Confusing this per-slot retention cap with the wal_keep_size retention floor.

Workload guidance

OLAP: Allow for expected bulk-WAL bursts, but do not make the cap effectively unlimited. Schedule consumers and batch jobs together, verify archive availability, and pause or repair a lagging consumer before it consumes the disk budget.

OLTP: Set a finite limit within the pg_wal emergency budget and derive it from peak WAL generation times the maximum supported repair window. Alert while safe_wal_size is still positive, and document the resynchronization path for every consumer.

SMALL: Use a stricter finite cap and a short repair objective. On a small volume, preserving the primary is usually more important than keeping a stale replica or CDC slot resumable forever.