Inside the 8KB Page: PostgreSQL Page Layout Visualized

Interactive visualization of PostgreSQL's 8KB page: header, line pointers, free space, and tuple data.

Each 8KB page has four key regions: a 24-byte header, line pointers (4 bytes each, growing forward from the header), free space, and tuple data (packed backward from the end of the page).

Two scenarios step through it one statement at a time. How a page fills inserts rows until the line pointers and the tuples meet. What a DELETE leaves behind deletes rows, runs VACUUM, and shows which line pointer the next row is given. Free play hands over the same page: insert rows, delete any of them with the × on its card, and VACUUM in any order. Click a region of the map or a tuple card for the byte-level detail.

Header 24 B
Free Space 8168 B
0 8192
True proportions
header line pointers free space tuples dead tuple small regions are drawn larger than they are
Rows
0
pd_lower
24
pd_upper
8192
Free Space
8168 B
Page region click a region of the page above
Tuples on this page page_demo (id int, title text, created_at timestamptz, amount numeric)

What VACUUM does to the page

VACUUM walks the page, drops the dead tuples, and runs PageRepairFragmentation to slide the surviving tuples together so the freed bytes coalesce into one contiguous block of free space. The live tuples move, but they keep their line pointer slot numbers: an index entry points at a tuple by (block, offset), so the slot number has to stay stable even as the tuple's physical offset changes.

A dead tuple's line pointer does not jump straight to free. After the DELETE it is still LP_NORMAL; pruning marks it LP_DEAD; only once VACUUM has cleared the matching index entries does it become LP_UNUSED and available again. The next INSERT fills an LP_UNUSED slot before extending the array, so a low slot number can carry a brand-new row. Trailing unused slots are dropped from the end of the array, pulling pd_lower back down; interior unused slots stay put as gaps waiting to be reused.

Changelog

  • Two guided scenarios, *How a page fills* and *What a DELETE leaves behind*, step through the page one statement at a time with a caption for each step. The original controls are under Free play, each stat shows its previous value after a statement, and the region detail stays folded until a region of the map is clicked.
  • Added VACUUM: remove dead tuples, compact the page, and reuse freed line pointers.
  • Deleted tuples now show as in-place dead space on the page map until reclaimed.
  • First release: interactive 8KB page map with header, line pointers, free space, and tuple data.