wal_keep_size

A reloadable minimum amount of old WAL retained for streaming standbys that might fall behind. It is present from PG13 in this catalog, defaults to 0 MB, and is unmodified by all Pigsty templates.

Note

Fact — official short description: “Sets the size of WAL files held for standby servers.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , ValueMB: Raw unit
Range , Value0 – 2147483647: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueReplication / Sending Servers: Upstream classification
Latest boot value , Value0: 0 B

Lifecycle

Fact	Value
First observed	PG13
Present in	PG13–19 Beta 3
Removed in	No
Introduction commit	`f5dff45962ec` — Rename wal_keep_segments to wal_keep_size.
Commit date	2020-07-20
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG13–19 Beta 3	`0`	`MB`	0 B

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

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.

wal_keep_segments · max_replication_slots · max_slot_wal_keep_size · archive_mode · max_wal_size · primary_slot_name