wal_keep_segments

Definition PG 12 manual

Specifies the minimum number of past log file segments kept in the pg_wal directory, in case a standby server needs to fetch them for streaming replication. Each segment is normally 16 megabytes. If a standby server connected to the sending server falls behind by more than wal_keep_segments segments, 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 number 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_segments 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. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

Sets the number of WAL files held for standby servers. The parameter still exists in PG12 and is no longer recognized from PG13. PostgreSQL 13 replaced the segment-count interface with wal_keep_size, which expresses the retention floor in bytes rather than assuming a segment size.

This retained at least a count of old WAL segments for lagging standbys, so its byte effect changed with wal_segment_size. It was only a floor—not protection from every retention/removal condition—and PostgreSQL 13 replaced it with wal_keep_size.

Before upgrading, inspect wal_keep_size, wal_segment_size, max_slot_wal_keep_size, remove the old name from configuration, ALTER SYSTEM, role/database settings, and automation templates, and verify the replacement before starting PG13 or later.

Operational considerations

Copying the old integer directly to wal_keep_size without multiplying by wal_segment_size.

Treating the retained count as a maximum rather than a minimum floor.

Leaving the removed name in PG13+ automation.

Continuing to emit unknown parameter wal_keep_segments on PG13+.

Deleting only the setting name without migrating dependent application behavior.

Workload guidance

OLAP: Use the same migration path as OLTP, and also verify long batches, standbys, or large-object/extension workflows; removal of the old switch does not promise identical legacy behavior.

OLTP: Do not tune or continue emitting wal_keep_segments on PG13+. PostgreSQL 13 replaced the segment-count interface with wal_keep_size, which expresses the retention floor in bytes rather than assuming a segment size. Scan every configuration layer and regression-test the application before upgrade.

SMALL: Delete the obsolete setting and adopt the supported replacement directly; do not emulate legacy behavior in scripts without a demonstrated compatibility requirement.