Parameter · Write-Ahead Log / Settings
wal_log_hints
Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification.
- Default:
off - Type: bool
- Applies: Restart required
In plain words
PostgreSQL sometimes changes a page just to remember a small hint (for example "this row's transaction is known committed"). Normally such hint-only changes are not written to WAL. wal_log_hints = on logs a full page image the first time a page gets such a hint after a checkpoint.
Tools like pg_rewind need this (or data checksums) to see every changed page. The cost is some extra WAL.
For DBAs and operators
Hint bits (HEAP_XMIN_COMMITTED, etc.) are set by readers to avoid repeated pg_xact lookups. They are not crash-critical, so normally only the buffer is dirtied. But a torn write of such a page is dangerous when data checksums are on (the checksum would not match), and pg_rewind needs to know every block changed on the old primary after the fork. Both cases therefore WAL-log the first hint-bit change after a checkpoint as an FPI.
- With data checksums enabled this already happens and
wal_log_hintshas no additional effect. Since PostgreSQL 18,initdbenables checksums by default, so many new clusters are covered; clusters upgraded withpg_upgradekeep whatever they had (SHOW data_checksums;). - Without checksums,
pg_rewindrefuses to run: "target server needs to use either data checksums or "wal_log_hints = on"". - Extra WAL appears mostly after large reads of freshly loaded data (the first SELECT or VACUUM sets hints on every page). Watch
wal_fpiinpg_stat_wal.
It is a postmaster-level setting recorded in pg_control; set it on all members of an HA cluster that might be rewound.
How to change it
Change in postgresql.conf or ALTER SYSTEM, then restart the server.
See it in context
Full-page writes Page layout Write-ahead log (WAL) Commit log, hint bits and subtransactions