wal_recycle

wal_recycle recycles WAL files by renaming them. It is a superuser setting present in PG12–18; the latest recorded boot default is on.

Note

Fact — official short description: “Recycles WAL files by renaming them.”

Identity

Type , Valuebool: Upstream pg_settings type
Context , Valuesuperuser: Settable at runtime by a superuser
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueWrite-Ahead Log / Settings: Upstream classification
Latest boot value , Valueon: on

Lifecycle

Fact	Value
First observed	PG12
Present in	PG12–19 Beta 3
Removed in	No
Introduction commit	`475861b2615d` — Add wal_recycle and wal_init_zero GUCs.
Commit date	2019-04-02
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG12–19 Beta 3	`on`	—	on

How it works

Recycles WAL files by renaming them. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

With on, PostgreSQL renames no-longer-needed WAL segments for future use rather than creating new files. Reuse is usually cheaper, but on copy-on-write storage fresh allocation can perform better and avoid preserving extents.

Monitor and change wal_recycle together with wal_init_zero, wal_segment_size, min_wal_size. Validate on the relevant server role and real workload, then use its superuser 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	Establish durability and recovery objectives first, then tune wal_recycle from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP	Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes	Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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

Common pitfalls

Assuming recycled renames are always faster than new allocation on copy-on-write storage.
Disabling recycling without measuring segment creation latency during WAL bursts.
Expecting a session change to alter files already recycled or removed.
Treating recycling as a WAL retention limit rather than a file-reuse policy.

wal_init_zero · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings