# jpmoll/bd2 architecture

> Architecture diagram of the GitHub repository jpmoll/bd2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jpmoll/bd2
- Repository: https://github.com/jpmoll/bd2

## Overview

ISAM is a PostgreSQL 18 index access method for integer keys. PostgreSQL invokes its access-method glue to build an index from heap TIDs, insert entries, search equality or ranges, and remove dead entries during VACUUM. The C-only core stores and searches those entries across primary pages, a sparse page index, and per-page overflow chains; PostgreSQL retains the actual rows. The README also documents index statistics and a B-tree comparison. The graph follows documented calls and excerpts; it does not infer unsampled wiring.

Main entry points: [`src/isam_am.c`](https://github.com/jpmoll/bd2/blob/main/src/isam_am.c) (Access method), [`src/isam_core.c`](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c) (Primary pages), [`sql/isam--1.0.sql`](https://github.com/jpmoll/bd2/blob/main/sql/isam--1.0.sql) (AM registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pg["PostgreSQL integration"]
  node_sqlam["AM registration<br/>[isam--1.0.sql]"]
  node_am["Access method<br/>[isam_am.c]"]
  node_build["Index build<br/>[isam_am.c]"]
  node_insert["Tuple insertion<br/>[isam_am.c]"]
  node_scan["Index scans<br/>[isam_am.c]"]
  node_vacuum["Bulk deletion<br/>[isam_am.c]"]
  node_info["Index statistics<br/>[isam_am.c]"]
end

subgraph group_core["ISAM core"]
  node_construct["ISAM construction<br/>[isam_core.c]"]
  node_range["Range lookup<br/>[isam_core.c]"]
  node_coreinsert["Core insertion<br/>[isam_core.c]"]
  node_corevacuum["Core vacuum<br/>[isam_core.c]"]
  node_corestats["Core statistics<br/>[isam_core.c]"]
end

subgraph group_storage["Index storage"]
  node_primary[("Primary pages<br/>[isam_core.c]")]
  node_sparse[("Sparse index<br/>[isam_core.c]")]
  node_overflow[("Overflow chains<br/>[isam_core.c]")]
end

node_postgres(("PostgreSQL"))
node_heap[("Heap tuples")]

node_postgres -->|"loads extension"| node_sqlam
node_postgres -->|"invokes handler"| node_am
node_am -->|"dispatches build"| node_build
node_build -->|"scans TIDs"| node_heap
node_build -->|"calls constructor"| node_construct
node_construct -->|"writes pages"| node_primary
node_construct -->|"writes index"| node_sparse
node_construct -->|"initializes file"| node_overflow
node_am -->|"dispatches insert"| node_insert
node_insert -->|"calls insertion"| node_coreinsert
node_coreinsert -->|"updates pages"| node_primary
node_coreinsert -->|"adds overflow"| node_overflow
node_am -->|"dispatches scan"| node_scan
node_scan -->|"calls range search"| node_range
node_range -->|"reads pages"| node_primary
node_range -->|"locates page"| node_sparse
node_range -->|"reads chains"| node_overflow
node_scan -->|"returns heap TIDs"| node_postgres
node_am -->|"dispatches vacuum"| node_vacuum
node_vacuum -->|"calls vacuum"| node_corevacuum
node_corevacuum -->|"removes entries"| node_primary
node_corevacuum -->|"marks deletions"| node_overflow
node_postgres -->|"requests statistics"| node_info
node_info -->|"reads statistics"| node_corestats
node_corestats -->|"counts pages"| node_primary
node_corestats -->|"counts nodes"| node_overflow

click node_sqlam "https://github.com/jpmoll/bd2/blob/main/sql/isam--1.0.sql"
click node_am "https://github.com/jpmoll/bd2/blob/main/src/isam_am.c"
click node_build "https://github.com/jpmoll/bd2/blob/main/src/isam_am.c"
click node_insert "https://github.com/jpmoll/bd2/blob/main/src/isam_am.c"
click node_scan "https://github.com/jpmoll/bd2/blob/main/src/isam_am.c"
click node_vacuum "https://github.com/jpmoll/bd2/blob/main/src/isam_am.c"
click node_info "https://github.com/jpmoll/bd2/blob/main/src/isam_am.c"
click node_construct "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"
click node_range "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"
click node_coreinsert "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"
click node_corevacuum "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"
click node_corestats "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"
click node_primary "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"
click node_sparse "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"
click node_overflow "https://github.com/jpmoll/bd2/blob/main/src/isam_core.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sqlam,node_am,node_build,node_insert,node_scan,node_vacuum,node_info toneBlue
class node_construct,node_range,node_coreinsert,node_corevacuum,node_corestats,node_postgres,node_heap toneAmber
class node_primary,node_sparse,node_overflow toneMint
```

## Components

### PostgreSQL integration

- [AM registration](https://github.com/jpmoll/bd2/blob/main/sql/isam--1.0.sql): `sql/isam--1.0.sql`
- [Access method](https://github.com/jpmoll/bd2/blob/main/src/isam_am.c): `src/isam_am.c`
- [Index build](https://github.com/jpmoll/bd2/blob/main/src/isam_am.c): `src/isam_am.c`
- [Tuple insertion](https://github.com/jpmoll/bd2/blob/main/src/isam_am.c): `src/isam_am.c`
- [Index scans](https://github.com/jpmoll/bd2/blob/main/src/isam_am.c): `src/isam_am.c`
- [Bulk deletion](https://github.com/jpmoll/bd2/blob/main/src/isam_am.c): `src/isam_am.c`
- [Index statistics](https://github.com/jpmoll/bd2/blob/main/src/isam_am.c): `src/isam_am.c`

### ISAM core

- [ISAM construction](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`
- [Range lookup](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`
- [Core insertion](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`
- [Core vacuum](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`
- [Core statistics](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`

### Index storage

- [Primary pages](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`
- [Sparse index](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`
- [Overflow chains](https://github.com/jpmoll/bd2/blob/main/src/isam_core.c): `src/isam_core.c`

### Other components

- **PostgreSQL**
- **Heap tuples**

## Connections

- PostgreSQL → AM registration: loads extension (evidence: `README.md`)
- PostgreSQL → Access method: invokes handler (evidence: `README.md`)
- Access method → Index build: dispatches build (evidence: `src/isam_am.c`)
- Index build → Heap tuples: scans TIDs (evidence: `src/isam_am.c`)
- Index build → ISAM construction: calls constructor (evidence: `src/isam_am.c`)
- ISAM construction → Primary pages: writes pages (evidence: `src/isam_core.c`)
- ISAM construction → Sparse index: writes index (evidence: `README.md`)
- ISAM construction → Overflow chains: initializes file (evidence: `src/isam_core.c`)
- Access method → Tuple insertion: dispatches insert (evidence: `README.md`)
- Tuple insertion → Core insertion: calls insertion (evidence: `src/isam_am.c`)
- Core insertion → Primary pages: updates pages (evidence: `src/isam_core.c`)
- Core insertion → Overflow chains: adds overflow (evidence: `src/isam_core.c`)
- Access method → Index scans: dispatches scan (evidence: `README.md`)
- Index scans → Range lookup: calls range search (evidence: `src/isam_am.c`)
- Range lookup → Primary pages: reads pages (evidence: `src/isam_core.c`)
- Range lookup → Sparse index: locates page (evidence: `README.md`)
- Range lookup → Overflow chains: reads chains (evidence: `src/isam_core.c`)
- Index scans → PostgreSQL: returns heap TIDs (evidence: `README.md`)
- Access method → Bulk deletion: dispatches vacuum (evidence: `README.md`)
- Bulk deletion → Core vacuum: calls vacuum (evidence: `README.md`)
- Core vacuum → Primary pages: removes entries (evidence: `src/isam_core.c`)
- Core vacuum → Overflow chains: marks deletions (evidence: `src/isam_core.c`)
- PostgreSQL → Index statistics: requests statistics (evidence: `README.md`)
- Index statistics → Core statistics: reads statistics (evidence: `README.md`)
- Core statistics → Primary pages: counts pages (evidence: `src/isam_core.c`)
- Core statistics → Overflow chains: counts nodes (evidence: `src/isam_core.c`)
