LWLock: WALBufMapping
Waiting to replace a page in WAL buffers
PostgreSQL wait event dossier
ClassLWLock
Event
WALBufMapping
VersionsPG 13-18
Evidence3 source location(s)
Official description
Waiting to replace a page in WAL buffers
| PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 |
|---|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Trigger mechanism
WALBufMappingLock coordinates the mapping between WAL page numbers and the finite wal_buffers slots. A backend needs it when advancing to or replacing a WAL buffer page.
Normal or trouble?
- Normal: Short waits appear as WAL generation advances through buffer pages.
- Investigate: Sustained contention suggests WAL generation is turning over buffers faster than the write path advances, often during write bursts or checkpoints.
Diagnostic SQL
Sessions waiting on LWLock/WALBufMapping
Current LWLock cohort
Lock and relation context for these sessions
Response
- Correlate with WAL bytes, WAL writes, and checkpoint timing.
- Check whether wal_buffers is repeatedly exhausted during bursts.
- Smooth write bursts and fix WAL device latency before tuning buffer size.
Source evidence
- PostgreSQL 18.6 · src/backend/access/transam/xlog.c:1999 —
WALBufMapping - PostgreSQL 18.6 · src/backend/storage/lmgr/lwlock.c:739 —
pgstat_report_wait_start - PostgreSQL 18.6 · src/backend/utils/activity/wait_event_names.txt:319 —
WALBufMapping
Related controls and signals
- GUCs: [guc:wal_buffers] · [guc:checkpoint_timeout] · [guc:max_wal_size]
- Metrics: [metric:waiting_sessions] · [metric:wait_event_share] · [metric:wal_bytes] · [metric:wal_write_time]
Typical incident pattern
A bulk load saturates WAL generation while the WAL device stalls, forcing frequent WAL buffer remapping.