Introduction :
In PostgreSQL, data is persisted on disk and managed in memory using fixed-size blocks known as pages (or database blocks). The page is the fundamental unit of data storage and physical I/O in PostgreSQL.
- Standard Size: By default, each page is 8 KB (8,192 bytes).
- I/O Granularity: Whenever PostgreSQL reads from or writes to disk, it does so in full pagesānever individual rows or isolated bytes.
- Buffer Management: When a page is read from disk, it is loaded into shared memory (specifically,
shared_buffers) for processing. - Universal Structure: Both heap tables (actual data rows) and indexes are physically structured as sequential arrays of these 8 KB pages.
Overall Page Layout:
Below is the actual structure of the entire Page
Section Start Index End Index Description
--------------- ------------ --------- -----------
PageHeaderData 0 23 Fixed 24 bytes
ItemId Array 24 X X = pd_lower - 1; grows ā
Free Space X+1 Y Y = pd_upper - 1; shrinks from both sides
Heap Tuples Y+1 Z-1 tuples packed right-to-left; grows ā
Special Space Z 8191 Z = pd_special; empty when Z = 8192
All of these are written to the page array, and that is the page that gets flushed to disk.
We will explore the purpose of each section and what information it writes.
PageHeaderData:
Its size is 24 bytes: index 0 to 23. All data is stored only in these indices. It is fixed. Header cannot move beyond index 23.
It stores: pd_lsn, pd_checksum, pd_flags, pd_lower, pd_upper, pd_special, pd_pagesize_version, pd_prune_xid.
Deep Dive into PageHeaderData
Defined in src/include/storage/bufpage.h the page header occupies exactly 24 bytes (offsets 0 through 23). It never expands beyond index 23 because the flexible line pointer array starts immediately at offset 24.
The header consists of eight fields:
typedef struct PageHeaderData
{
PageXLogRecPtr pd_lsn; /* 8 bytes: LSN of last WAL record modifying this page */
uint16 pd_checksum; /* 2 bytes: page checksum */
uint16 pd_flags; /* 2 bytes: status flag bits */
LocationIndex pd_lower; /* 2 bytes: offset to start of free space */
LocationIndex pd_upper; /* 2 bytes: offset to end of free space */
LocationIndex pd_special; /* 2 bytes: offset to start of special space */
uint16 pd_pagesize_version; /* 2 bytes: page size (high bits) + layout version (low bits) */
TransactionId pd_prune_xid; /* 4 bytes: oldest prunable XID, or 0 if none */
ItemIdData pd_linp[]; /* flexible array member for line pointers */
} PageHeaderData;
pd_lsn:
An 8-byte log sequence number (LSN) recording the last change made to the page. It is crucial for consistency and recovery.
By comparing pd_lsn with the WAL, PostgreSQL decides whether a page needs to be updated or recovered during crash recovery or replication.
pd_checksum: pd_checksum is a 2-byte flag stored on the page. Checksums are a form of error detection used to ensure data integrity when data is stored on disk. When pd_checksum is set, it means that a checksum is calculated and stored alongside the page data. During read operations, PostgreSQL can verify the integrity of the page by recalculating the checksum and comparing it with the stored value. If they donāt match, it indicates a potential data corruption issue.
In PostgreSQL version 12, a new built-in tool called pg_checksums was introduced. This tool enables checksums on existing databases that were previously created without checksums. Before this version, users had to reinitialize the cluster using the ādata-checksums or -k flag during the initdb process to enable checksums.
pd_flags :
This 2-byte field holds a set of flags for page management, offering hints about the pageās status and its occupancy level.
PD_HAS_FREE_LINES: This flag suggests there might be some empty space on the page that could be used to store new data. However, itās not a guarantee. This information isnāt written in the transaction log (WAL), so it might not always be completely accurate.
PD_PAGE_FULL: This flag indicates that the page is likely full, and there might not be enough space to update existing data on the page. When this happens, PostgreSQL might need to do some cleanup (pruning) to free up space for the update.
pd_lower and pd_upper pointers: The lower pointer marks the endpoint of line pointers, while the upper pointer denotes the start of the most recent heap tuple. With the help of pd_lower and pd_upper pointers, PostgreSQL determines the available free space in a page.
pd_special: Itās a 2-byte integer serving as a pointer, marking the starting byte location of the special section within a page. Not all data types utilize this section; itās mainly employed by certain index types such as B-tree indexes to store structure-specific information. For example, in B-tree indexes, the special section might contain links to the pageās left and right sibling pages and other metadata pertinent to the index structure.
These links help optimize search operations by providing quick access to neighboring pages. Regular tables, which store actual data rows, usually donāt need a special section and utilize the entire page for storing data.
pd_pagesize_version: This 2-byte field is used to store the page size and a version indicator number. Starting from PostgreSQL 8.3, the version number is 4, and the default page size is 8 KB
pd_prune_xid: This is the last field of 4 bytes that gives a clue about whether itās worth cleaning up the page: it keeps track of the oldest transaction ID (XID) that hasnāt been cleaned up yet. If this value is relatively recent, it suggests that there may still be active transactions referencing data on the page. In this case, pruning might not be beneficial, as it could potentially remove data still needed by active transactions.
Conclusion:
The PageHeaderData serves as the control center for every PostgreSQL page. In just 24 bytes, it manages crash-recovery ordering (pd_lsn), validates data integrity (pd_checksum), tracks available free space (pd_lower and pd_upper), and coordinates on-access cleanup (pd_prune_xid). By decoupling the fixed header from dynamically growing rows, PostgreSQL ensures high-speed page parsing and robust storage reliability.
