Free space map and visibility map

For DBAs and operators

Free space map (<relfilenode>_fsm)

One byte per heap page stores a category: free space divided by 32 (so 0–255). FSM pages are organised as a tree of binary max-trees: each upper node holds the maximum of its children, so the root tells you the largest free space anywhere. A search descends towards any leaf with enough space; each FSM page remembers a "next slot" (fp_next_slot) where the next search starts, so concurrent inserters spread across pages rather than piling onto one.

• The FSM is only a hint. It is updated mainly by VACUUM and when an inserter finds a page fuller than advertised. If no page qualifies, the table is extended (when several backends are waiting to extend it, several pages are added at once).
• Tables without VACUUM history (e.g. after a bulk load) may have no FSM yet.
• B-tree indexes have an FSM too, but it only tracks completely empty, recyclable pages.

CREATE EXTENSION pg_freespacemap;
SELECT blkno, avail FROM pg_freespace('orders') WHERE avail > 1000 LIMIT 10;

Visibility map (<relfilenode>_vm)

Two bits per heap page: ALL_VISIBLE and ALL_FROZEN. One 8 kB VM page covers about 32,000 heap pages (256 MB of table). Only VACUUM sets the bits (and COPY FREEZE); any INSERT, UPDATE or DELETE on the page clears them (and the PD_ALL_VISIBLE flag in the page header); a row lock (SELECT … FOR UPDATE) clears only the all-frozen bit.

• Index-only scans check the VM bit for each heap page. If it is set, the heap is not visited. EXPLAIN ANALYZE shows Heap Fetches: N; a high number means many referenced heap pages are not currently marked all-visible. Investigate the write pattern and vacuum cadence before changing settings (see autovacuum_vacuum_insert_threshold for insert-heavy tables).
• VACUUM skips all-visible pages. An aggressive VACUUM (when the table's relfrozenxid age exceeds vacuum_freeze_table_age, with VACUUM FREEZE, and every anti-wraparound autovacuum) only skips all-frozen pages. Pages are only skipped in runs of at least 32 consecutive skippable pages, so that OS read-ahead keeps working.
• Since PostgreSQL 18, normal VACUUM also eagerly scans some all-visible but not all-frozen pages to freeze them early, capped by vacuum_max_eager_freeze_failure_rate (default 0.03). The VACUUM log shows … scanned, N eagerly scanned.

SELECT relpages, relallvisible, relallfrozen   -- relallfrozen is new in 18
  FROM pg_class WHERE relname = 'orders';

CREATE EXTENSION pg_visibility;
SELECT * FROM pg_visibility_map_summary('orders');
-- all_visible | all_frozen
--         443 |          0

Both files are tiny. FSM updates are not WAL-logged (it is only a hint and corrects itself over time); VM changes are WAL-logged, so the VM is crash-safe. A corrupted VM can make index-only scans return wrong results: pg_check_visible() and pg_truncate_visibility_map() in pg_visibility exist for that case.