LWLock: BufferMapping
Waiting to associate a data block with a buffer in the buffer pool
PostgreSQL wait event dossier
ClassLWLock
Event
BufferMapping
VersionsPG 13-18
Evidence3 source location(s)
Official description
Waiting to associate a data block with a buffer in the buffer pool
| PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 |
|---|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Trigger mechanism
The buffer manager hashes a relation/fork/block tag into a partition protected by BufferMappingLock. Lookup, insertion, eviction, and tag reassignment briefly take that partition lock; broad concurrent misses or buffer churn increase collisions.
Normal or trouble?
- Normal: Brief waits occur when pages enter or leave shared buffers.
- Investigate: Sustained recurrence suggests a working set that churns through shared buffers, many parallel scans, or concentrated access mapping into a few partitions.
Diagnostic SQL
Sessions waiting on LWLock/BufferMapping
Current LWLock cohort
Lock and relation context for these sessions
Response
- Correlate with buffer hit ratio and read volume by database and statement.
- Look for a new scan, undersized cache, or concurrency jump.
- Reduce concurrent scan fan-out or fix the access path before simply enlarging shared_buffers.
Source evidence
- PostgreSQL 18.6 · src/backend/storage/lmgr/lwlock.c:152 —
BufferMapping - 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:377 —
BufferMapping
Related controls and signals
- GUCs: [guc:shared_buffers] · [guc:max_parallel_workers_per_gather]
- Metrics: [metric:waiting_sessions] · [metric:wait_event_share] · [metric:buffer_hit_ratio] · [metric:blocks_read]
Typical incident pattern
A plan regression launches many concurrent large scans; buffer-table partitions become hot while useful pages churn out of cache.