wal_summary_keep_time

wal_summary_keep_time sets the time for which WAL summary files should be kept. It is a sighup setting present in PG17–18; the latest recorded boot default is 10 d.

Note

Fact — official short description: “Time for which WAL summary files should be kept.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Valuemin: Raw unit
Range , Value0 – 35791394: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueWrite-Ahead Log / Summarization: Upstream classification
Latest boot value , Value14400: 10 d

Lifecycle

Fact	Value
First observed	PG17
Present in	PG17–19 Beta 3
Removed in	No
Introduction commit	`174c480508ac` — Add a new WAL summarizer process.
Commit date	2023-12-20
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG17–19 Beta 3	`14400`	`min`	10 d

How it works

Time for which WAL summary files should be kept. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The summarizer deletes summary files older than this age, using file timestamps. The retention must exceed the longest interval between an incremental backup and the earlier backup it depends on; zero keeps summaries indefinitely, and cleanup stops while summarize_wal is off.

Monitor and change wal_summary_keep_time together with summarize_wal, wal_level, archive_mode. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Enable or tune wal_summary_keep_time only when using PostgreSQL incremental backup. Monitor summarizer progress and retain summaries across the complete WAL range between every dependent backup pair.
OLAP	Bulk writes increase summarizer work. Capacity-test backup interval, WAL peak, and backup window together; a summary gap makes an incremental backup fail.
Small nodes	Keep summarize_wal off when incremental backup is not used. If enabled, derive retention from the real backup chain and alert on summary-directory capacity.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Deleting summaries still needed to bridge the prior and next incremental backup.
Setting zero and never monitoring unbounded summary growth.
Turning summarize_wal off and expecting retention cleanup to continue.
Confusing pg_settings base units with human-readable configuration units.
Benchmarking throughput without a crash-recovery and archive-restore test.

summarize_wal · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command