wal_init_zero

wal_init_zero writes zeroes to new WAL files before first use. It is a superuser setting present in PG12–18; the latest recorded boot default is on.

Note

Fact — official short description: “Writes zeroes to new WAL files before first use.”

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

Writes zeroes to new WAL files before first use. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

With on, newly created WAL segments are zero-filled, which preallocates blocks on many filesystems. Copy-on-write filesystems may turn that work into unnecessary allocation and fragmentation; off still creates a correctly sized file by writing its last byte.

Monitor and change wal_init_zero together with wal_recycle, 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_init_zero 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

Disabling zero-fill on a conventional filesystem and moving allocation stalls into peak WAL creation.
Keeping zero-fill on copy-on-write storage without measuring allocation and fragmentation cost.
Assuming an apparently sparse file means PostgreSQL changed wal_segment_size.
Changing a session value and expecting already-created WAL segments to be rewritten.

wal_recycle · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings