wal_log_hints

wal_log_hints — Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification. Observed in PG9.4–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification.”

Identity

Type , Valuebool: Upstream pg_settings type
Context , Valuepostmaster: Requires a server restart
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 , Valueoff: off

Lifecycle

Fact	Value
First observed	PG9.4
Present in	PG9.4–19 Beta 3
Removed in	No
Introduction commit	`961bf59fb7a7` — Rename wal_log_hintbits to wal_log_hints, per discussion on pgsql-hackers.
Commit date	2013-12-21
Discussion	—

Default history

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

How it works

Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification. The value is fixed when the server starts, so changing it requires a restart.

When data checksums are off, this forces full-page WAL for the first hint-bit change after a checkpoint, giving pg_rewind the block-change safety it needs. With checksums enabled, equivalent hint logging already occurs, so the setting adds no further effect.

Monitor and change wal_log_hints together with wal_compression, full_page_writes, wal_level. Validate on the relevant server role and real workload, then use its postmaster 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_log_hints 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	`on`	different	`'on'`
OLAP	`on`	different	`'on'`
CRIT	`on`	different	`'on'`
TINY	`on`	different	`'on'`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.4–19 Beta 3 = on (dcs); OLAP: PG9.4–19 Beta 3 = on (dcs); CRIT: PG9.4–19 Beta 3 = on (dcs); TINY: PG9.4–19 Beta 3 = on (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to keep pg_rewind viable even when data checksums are not the mechanism forcing hint-bit WAL; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

Assuming it logs every hint update rather than the first page image after a checkpoint.
Turning it on but not completing the restart before relying on pg_rewind.
Forgetting that checksums already force the relevant hint WAL behavior.
Confusing pg_settings base units with human-readable configuration units.
Benchmarking throughput without a crash-recovery and archive-restore test.

wal_compression · full_page_writes · wal_level · wal_buffers · max_wal_senders · max_replication_slots