wal_keep_size

Definition PG 18 manual

Specifies the minimum size of past WAL files kept in the pg_wal directory, in case a standby server needs to fetch them for streaming replication. If a standby server connected to the sending server falls behind by more than wal_keep_size megabytes, the sending server might remove a WAL segment still needed by the standby, in which case the replication connection will be terminated. Downstream connections will also eventually fail as a result. (However, the standby server can recover by fetching the segment from archive, if WAL archiving is in use.)

This sets only the minimum size of segments retained in pg_wal; the system might need to retain more segments for WAL archival or to recover from a checkpoint. If wal_keep_size is zero (the default), the system doesn't keep any extra segments for standby purposes, so the number of old WAL segments available to standby servers is a function of the location of the previous checkpoint and status of WAL archiving. 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

The sender keeps at least wal_keep_size megabytes of past WAL in pg_wal so a lagging standby can continue streaming without an older segment disappearing. If the standby falls behind beyond the available files, streaming disconnects; an archive can supply the missing segment if one exists.

This is a retention floor, not an exact reservation or a maximum. Checkpoint recovery needs, archiving, replication slots, and recent WAL-usage estimates can retain more. A value of zero means PostgreSQL reserves no extra WAL specifically for standbys, not that pg_wal contains no old WAL.

Replication slots retain WAL according to an individual consumer's confirmed position and are usually more precise. wal_keep_size is still useful as simple insurance for slotless or temporarily reconnecting standbys, but capacity should be based on peak WAL rate multiplied by the intended outage window.

Operational considerations

Treating wal_keep_size as a maximum for pg_wal usage.

Reading 0 as 'retain no WAL' rather than 'retain no extra WAL for standby purposes'.

Sizing from average WAL rate and failing during batch-generated peaks.

Assuming it guarantees recovery after a standby exceeds the retained window.

Forgetting the predecessor parameter wal_keep_segments when comparing PG12 and PG13.

Workload guidance

OLAP: Static retention can be overwhelmed by a short bulk-load burst. Use slots or an archive for consumers that must survive such bursts, and size any wal_keep_size floor against peak rather than average WAL generation.

OLTP: Prefer monitored replication slots plus a tested archive for durable protection. If a nonzero floor is needed, calculate it from peak WAL bytes per second and tolerated disconnection time, then add margin and alert on replication lag.

SMALL: Leave it at 0 when slots and archive recovery are reliable. Otherwise choose a modest bounded floor that cannot consume the disk budget during an unrelated archive or slot incident.