Page layout

For DBAs and operators

The page header (24 bytes)

• pd_lsn: LSN of the last WAL record that changed this page. A dirty page may not be written until WAL up to this LSN is flushed (the WAL-before-data rule).
• pd_checksum: set when data checksums are enabled. initdb enables checksums by default since PostgreSQL 18 (use --no-data-checksums to opt out).
• pd_lower / pd_upper: start and end of the free space. pd_upper - pd_lower is what is left.
• pd_special: start of the special space. It is 8192 (empty) for heap pages; B-tree pages keep sibling links and the level there.
• pd_prune_xid: oldest XID that might make pruning worthwhile (used by HOT pruning).

Line pointers and tuples

Each line pointer (ItemIdData) is 4 bytes: offset, length and a 2-bit state: LP_NORMAL, LP_REDIRECT (HOT chain start), LP_DEAD (dead; the pointer itself stays until VACUUM has removed the index entries that point to it) or LP_UNUSED. Because indexes point at the line pointer, not the byte offset, PostgreSQL can move tuples inside the page (to defragment it) without touching any index.

A heap tuple starts with a 23-byte header padded to 24: t_xmin, t_xmax, t_cid, t_ctid, t_infomask2 (number of attributes plus HOT flags), t_infomask (hint bits such as HEAP_XMIN_COMMITTED, HEAP_XMAX_INVALID) and t_hoff. A null bitmap follows if any column is NULL. Tuples are aligned to 8 bytes (MAXALIGN), so a 34-byte tuple occupies 40.

Look at a real page with pageinspect

CREATE EXTENSION pageinspect;
CREATE TABLE pl (id int, name text);
INSERT INTO pl VALUES (1,'alice'),(2,'bob'),(3,'carol');

SELECT lsn, lower, upper, special, pagesize
  FROM page_header(get_raw_page('pl', 0));
--    lsn    | lower | upper | special | pagesize
-- 0/183C660 |    36 |  8080 |    8192 |     8192

SELECT lp, lp_off, lp_len, t_xmin, t_xmax, t_ctid, t_infomask
  FROM heap_page_items(get_raw_page('pl', 0));
-- lp | lp_off | lp_len | t_xmin | t_xmax | t_ctid | t_infomask
--  1 |   8152 |     34 |    765 |      0 | (0,1)  |       2050
--  2 |   8120 |     32 |    765 |      0 | (0,2)  |       2050
--  3 |   8080 |     34 |    765 |      0 | (0,3)  |       2050

-- after the next SELECT has set the commit hint bit, t_infomask is 2306
SELECT * FROM heap_tuple_infomask_flags(2306, 0);  -- decode the bits

Note lower = 24 + 3 × 4 = 36. After UPDATE pl SET name = 'bobby' WHERE id = 2 the old version gets t_xmax = 766 and t_ctid = (0,4), and the new one appears at lp 4. Its t_infomask2 has HEAP_ONLY_TUPLE set because the update was HOT.

Support notes

• Hint bits are set by the first reader after commit. That read can dirty the page (and with checksums or wal_log_hints, write a full-page image to WAL if it is the first change to that page since the last checkpoint), which surprises people who see writes after a bulk load.
• Corruption reports such as ERROR: invalid page in block 1234 of relation "base/16384/16397" (preceded in the server log by LOG: page verification failed, calculated checksum 20919 but expected 15254) refer to these 8 kB blocks. amcheck (verify_heapam) can scan a table for header inconsistencies.
• A row cannot span pages; large values are moved out of line by TOAST. The maximum row size on a page is about 8160 bytes.
• block_size is a compile-time constant; practically every build uses 8 kB.

PostgreSQL 18 source trail: bufpage.h defines page layout and line pointers; htup_details.h defines the heap tuple header.