summarize_wal

summarize_wal starts the WAL summarizer process to enable incremental backup. It is a sighup setting present in PG17–18; the latest recorded boot default is off.

Note

Fact — official short description: “Starts the WAL summarizer process to enable incremental backup.”

Identity

Type , Valuebool: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueWrite-Ahead Log / Summarization: Upstream classification
Latest boot value , Valueoff: off

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	`off`	—	off

How it works

Starts the WAL summarizer process to enable incremental backup. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The WAL summarizer records which blocks changed over WAL ranges so pg_basebackup can construct incremental backups. It can run on a primary or standby, but cannot summarize WAL generated at wal_level=minimal.

Monitor and change summarize_wal together with wal_summary_keep_time, 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 summarize_wal 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

Enabling it with wal_level=minimal and expecting usable summary files.
Treating WAL summaries as a WAL archive or a backup by themselves.
Turning the summarizer off and expecting wal_summary_keep_time cleanup to continue.
Taking an incremental backup without checking summarizer progress and summary coverage.

wal_summary_keep_time · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command