wal_log_hints

Definition PG 18 manual

When this parameter is on, the PostgreSQL server writes the entire content of each disk page to WAL during the first modification of that page after a checkpoint, even for non-critical modifications of so-called hint bits.

If data checksums are enabled, hint bit updates are always WAL-logged and this setting is ignored. You can use this setting to test how much extra WAL-logging would occur if your database had data checksums enabled.

This parameter can only be set at server start. The default value is 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.

Operational considerations

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.

Workload guidance

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.

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.

SMALL: Start from safe defaults and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.