Interactive visualization of VACUUM across three heap pages. Run DELETE and watch nothing get reclaimed, page-prune to reach LP_DEAD, then step VACUUM through heap scan, index cleanup, and heap cleanup that frees the slots.
A DELETE in PostgreSQL reclaims nothing on its own. It stamps the tuple's t_xmax and moves on: the row is still physically on the page, the indexes still point at it, and the free space map still thinks the page is full. Nothing is reclaimed until VACUUM arrives.
The first scenario deletes six rows, inserts four more (the table grows), then steps VACUUM through its three phases: heap scan and prune, index cleanup, and the heap cleanup that flips LP_DEAD to LP_UNUSED and records the free space in the FSM. The same INSERT afterwards lands in the freed slots. The second scenario puts a page prune in the middle: the bytes come back on each page, the free space map isn't told, and the INSERT squeezes two rows onto the last page before extending the table. Free play has every statement as a button. Click any line pointer for its full state.
Table vacuum_demo, heap pages
Index vacuum_demo_pkey: id → (page, line pointer)
live tuple dead tuple, still on the page LP_DEAD: bytes gone, slot still taken LP_UNUSED: slot reusable index entry for a dead tuple
Dead tuples
Index entries
Free space the FSM knows
Table size
Line pointerclick any line pointer above
Why page pruning isn't enough
Opportunistic page pruning is the shortcut: it runs during ordinary reads and writes, works entirely inside a single page, and does real work. It strips the storage off dead tuples, so the bytes come back to the page, and flags their line pointers LP_DEAD. It doesn't record that space in the free space map, so an INSERT asking the FSM for room is still sent elsewhere; the one exception is the last page of the table, which an INSERT checks directly when the FSM has nothing to offer. It also cannot remove the index entries that still reference those TIDs, so it cannot free the LP_DEAD slots, and it cannot reach across pages.
VACUUM is what finishes the job. Phase 1 scans and prunes the heap, reclaiming the dead tuples' bytes, setting their line pointers LP_DEAD, and collecting the TIDs. Phase 2 walks every index and removes the entries pointing at them, the step pruning can never do. Only then is phase 3 safe: those LP_DEAD line pointers become LP_UNUSED, the slots are reusable, and the page's free space is written to the FSM. The distinction that trips people up is that the bytes were already reclaimed during the prune; what VACUUM adds is cleaning the index, releasing the slots, and telling the FSM, on every page of the table.
Page pruning leaves the free space map untouched: on PostgreSQL 18 it reclaims the bytes on the page, but `pg_freespace` keeps reporting the old value until VACUUM's heap cleanup pass records the new one. The visualizer used to update the FSM at the prune. Each heap page now shows both numbers while they differ, and an `INSERT` after a prune alone fills the last page and then extends the table. The page also opens on two guided scenarios now, one statement per step with a short caption, and the original buttons moved under free play. The all visible mark on a page is now a stored bit that only VACUUM sets and any INSERT or DELETE clears, so a page added by an INSERT no longer shows as all visible before a VACUUM has seen it.