# boltdb/bolt architecture

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

- Interactive diagram: https://gitdiagram.com/boltdb/bolt
- Repository: https://github.com/boltdb/bolt

## Overview

Bolt is an embedded Go key/value database: applications open a file-backed DB, run read or write transactions, and use buckets and cursors to access ordered keys and values. Writes are committed as paged data with freelist-managed allocation; platform files provide OS-specific locking and memory mapping. The CLI adds inspection, statistics, benchmarking, and compaction commands. Relationships below follow the README and shown excerpts; unsampled wiring is omitted rather than inferred.

Main entry points: [`db.go`](https://github.com/boltdb/bolt/blob/master/db.go) (DB lifecycle), [`tx.go`](https://github.com/boltdb/bolt/blob/master/tx.go) (Transactions), [`bucket.go`](https://github.com/boltdb/bolt/blob/master/bucket.go) (Buckets and values), [`node.go`](https://github.com/boltdb/bolt/blob/master/node.go) (B-tree nodes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Database API"]
  node_db["DB lifecycle<br/>[db.go]"]
  node_tx["Transactions<br/>[tx.go]"]
  node_bucket["Buckets and values<br/>[bucket.go]"]
  node_cursor["Ordered traversal<br/>[cursor.go]"]
end

subgraph group_engine["Storage Engine"]
  node_datafile[("Database file")]
  node_node["B-tree nodes<br/>[node.go]"]
  node_page["Page format<br/>[page.go]"]
  node_freelist["Page allocation<br/>[freelist.go]"]
end

subgraph group_platform["Platform I/O"]
  node_osio["Unix lock and mmap<br/>[bolt_unix.go]"]
  node_winio["Windows lock and mmap<br/>[bolt_windows.go]"]
end

subgraph group_cli["Bolt CLI"]
  node_cli["CLI commands<br/>[main.go]"]
end

node_application(("Application"))

node_application -->|"opens"| node_db
node_db -->|"starts"| node_tx
node_tx -->|"creates"| node_bucket
node_bucket -->|"seeks"| node_cursor
node_bucket -->|"updates"| node_node
node_cursor -->|"searches"| node_node
node_node -->|"writes"| node_page
node_db -->|"allocates pages"| node_freelist
node_tx -->|"writes free list"| node_freelist
node_db -->|"persists"| node_datafile
node_db -.->|"uses OS I/O"| node_osio
node_db -.->|"uses OS I/O"| node_winio

click node_db "https://github.com/boltdb/bolt/blob/master/db.go"
click node_tx "https://github.com/boltdb/bolt/blob/master/tx.go"
click node_bucket "https://github.com/boltdb/bolt/blob/master/bucket.go"
click node_cursor "https://github.com/boltdb/bolt/blob/master/cursor.go"
click node_node "https://github.com/boltdb/bolt/blob/master/node.go"
click node_page "https://github.com/boltdb/bolt/blob/master/page.go"
click node_freelist "https://github.com/boltdb/bolt/blob/master/freelist.go"
click node_osio "https://github.com/boltdb/bolt/blob/master/bolt_unix.go"
click node_winio "https://github.com/boltdb/bolt/blob/master/bolt_windows.go"
click node_cli "https://github.com/boltdb/bolt/blob/master/cmd/bolt/main.go"

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_db,node_tx,node_bucket,node_cursor toneBlue
class node_datafile,node_node,node_page,node_freelist toneAmber
class node_osio,node_winio toneMint
class node_cli toneRose
class node_application toneIndigo
```

## Components

### Database API

- [DB lifecycle](https://github.com/boltdb/bolt/blob/master/db.go): `db.go`
- [Transactions](https://github.com/boltdb/bolt/blob/master/tx.go): `tx.go`
- [Buckets and values](https://github.com/boltdb/bolt/blob/master/bucket.go): `bucket.go`
- [Ordered traversal](https://github.com/boltdb/bolt/blob/master/cursor.go): `cursor.go`

### Storage Engine

- **Database file**
- [B-tree nodes](https://github.com/boltdb/bolt/blob/master/node.go): `node.go`
- [Page format](https://github.com/boltdb/bolt/blob/master/page.go): `page.go`
- [Page allocation](https://github.com/boltdb/bolt/blob/master/freelist.go): `freelist.go`

### Platform I/O

- [Unix lock and mmap](https://github.com/boltdb/bolt/blob/master/bolt_unix.go): `bolt_unix.go`
- [Windows lock and mmap](https://github.com/boltdb/bolt/blob/master/bolt_windows.go): `bolt_windows.go`

### Bolt CLI

- [CLI commands](https://github.com/boltdb/bolt/blob/master/cmd/bolt/main.go): `cmd/bolt/main.go`

### Other components

- **Application**

## Connections

- Application → DB lifecycle: opens (evidence: `README.md`)
- DB lifecycle → Transactions: starts (evidence: `README.md`)
- Transactions → Buckets and values: creates (evidence: `tx.go`)
- Buckets and values → Ordered traversal: seeks (evidence: `bucket.go`)
- Buckets and values → B-tree nodes: updates (evidence: `bucket.go`)
- Ordered traversal → B-tree nodes: searches (evidence: `cursor.go`)
- B-tree nodes → Page format: writes (evidence: `node.go`)
- DB lifecycle → Page allocation: allocates pages (evidence: `db.go`)
- Transactions → Page allocation: writes free list (evidence: `tx.go`)
- DB lifecycle → Database file: persists (evidence: `README.md`)
- DB lifecycle → Unix lock and mmap: uses OS I/O
- DB lifecycle → Windows lock and mmap: uses OS I/O
