Chapter 2: Access Methods

Summary

Access Methods (AMs) are PostgreSQL’s abstraction for how data is stored and retrieved. Every table is managed by a Table AM (almost always the heap), and every index is managed by an Index AM (B-tree, hash, GiST, GIN, BRIN, or SP-GiST). PostgreSQL 12+ exposes both as pluggable APIs, letting extensions provide entirely new storage engines or index types without modifying the core.

Overview

PostgreSQL separates what the executor wants (scan a table, insert a tuple, look up a key) from how the AM accomplishes it. Two callback structs sit at the centre of this design:

Each AM registers a handler function (e.g., heap_tableam_handler, bthandler) that returns a pointer to the filled-in routine struct. The executor then calls through these function pointers, never knowing which concrete AM is behind the relation.

Architecture Diagram

                        Executor
                           |
              +------------+------------+
              |                         |
       table_scan_*()            index_scan_*()
              |                         |
      +-------v--------+      +--------v--------+
      | TableAmRoutine  |      | IndexAmRoutine   |
      | (tableam.h)     |      | (amapi.h)        |
      +-------+---------+      +--------+---------+
              |                         |
    +---------+          +---------+---------+---------+---------+
    |                    |         |         |         |         |
  Heap AM           B-tree     Hash      GiST      GIN      BRIN
  (heap/)           (nbtree/)  (hash/)   (gist/)   (gin/)   (brin/)
                                                              |
                                                           SP-GiST
                                                           (spgist/)

Key Source Files

How the Pieces Fit Together

Table Access

1. table_beginscan() calls scan_begin in the TableAmRoutine.
2. The heap AM creates a HeapScanDescData (which embeds a TableScanDescData).
3. table_scan_getnextslot() calls scan_getnextslot to fetch tuples.
4. Visibility is checked via HeapTupleSatisfiesVisibility().

Index Access

1. index_beginscan() calls ambeginscan in the IndexAmRoutine.
2. For a B-tree, btbeginscan() allocates BTScanOpaqueData.
3. index_getnext_slot() calls amgettuple, which walks the tree and returns TIDs. The executor then calls index_fetch_tuple on the table AM to retrieve the heap tuple.

Planner Integration

The planner calls amcostestimate to get selectivity and cost for each potential index path. Flags like amcanorder, amcanunique, and amsearcharray on IndexAmRoutine tell the planner which plan shapes are valid.

Chapter Contents

Connections

• Chapter 1 (Storage and Buffer Manager): AMs read and write pages through the buffer manager. The heap page layout (PageHeaderData, ItemIdData) is the foundation for the heap AM.
• Chapter 3 (Query Executor): The executor drives all AM operations through the TableAmRoutine and IndexAmRoutine interfaces.
• Chapter 4 (MVCC and Concurrency): Visibility rules in heapam_visibility.c determine which tuples the heap AM returns. Index AMs rely on the table AM for final visibility checks.
• Chapter 5 (WAL and Recovery): Every AM writes WAL records for crash safety. Each AM has its own *_xlog.c module.