BiteSizedChunks.comLearn one small thing at a time.
Course contentsShow
← Databases & SQL
Lesson 833 of 1,9538. PostgreSQL InternalsFree lesson

The Anatomy of a PostgreSQL Page

You will map out how data is structured in 8KB pages including headers, line pointers, and tuple placement.

In this lesson, you will learn how PostgreSQL organizes data on disk by peering inside the fundamental 8KB storage unit known as a "page."

The 8KB Architecture

In PostgreSQL, tables and indexes aren’t stored as continuous streams of data; they are carved into fixed-size blocks called pages (usually 8KB). Think of a page as a container that holds rows (tuples) alongside the management metadata required to find them quickly.

A page is divided into three distinct sections:

  1. Page Header (24 bytes): This sits at the very beginning of the page. It stores metadata, such as the page's checksum, the unique Page ID, and pointers to the start and end of the free space.
  2. Line Pointers (Item Pointers): Immediately following the header is an array of "line pointers." Each pointer is 4 bytes and acts like a map; it stores the offset (where the row starts) and the length of a specific tuple on that page.
  3. The Free Space: This is the middle area of the page. Interestingly, PostgreSQL fills this from end-to-start.
  4. Tuples (Data): The actual rows are stored in the remaining space, growing backwards from the end of the page toward the line pointers.

Visualizing the Layout

If you could look at the raw bytes of a page, it would look conceptually like this:

[ Page Header ]  (Fixed 24 bytes)
[ Line Ptr 1 ]   (Offset/Length for Row A)
[ Line Ptr 2 ]   (Offset/Length for Row B)
[    ...     ]
[ Free Space ]   (Variable size)
[ Row B Data ]   (Grows upward)
[ Row A Data ]   (Grows upward)

Why this structure?

This layout is incredibly clever for database performance. By using Line Pointers, the database doesn't have to move the actual row data if it needs to reorganize the page. It only needs to update the small 4-byte pointer. Furthermore, having the free space in the middle allows the page to accommodate rows of varying sizes—if you update a row and it grows (or shrinks), PostgreSQL simply adjusts the pointers and the free space buffer without needing to shift the entire table structure.

Key Takeaway: PostgreSQL pages use a "header-pointer-data" layout where line pointers act as a lookup index, allowing the database to manage variable-length rows efficiently within a rigid 8KB footprint.