Skip to content

MiniPostgres: A Database Kernel in Twelve Chapters

This is the main textbook for MiniPostgres. Read it in order to follow one relational kernel from SQL text to verified behavior. Each chapter names its source owners, runs copyable experiments, and states where the teaching model differs from PostgreSQL.

MiniPostgres is a synchronous, single-process Python database kernel. It is not a PostgreSQL-compatible server: there is no wire protocol, psql, production file-format compatibility, or complete SQL dialect. Use the chapters to learn mechanisms, then use the reference material to inspect exact project scope and evidence.

Book contents

  1. Meet MiniPostgres — position, environment, the direct Database API, and the full-book map.
  2. The SQL Front End — positioned lexing, recursive-descent parsing, catalog-aware binding, three-valued logic, and numeric widening.
  3. Pages and the Buffer Pool — checksummed 8192-byte pages, stable slotted-page TIDs, pin ownership, Clock replacement, and the free-space map.
  4. MVCC, Tuple Versions, and Snapshots — xmin/xmax history, creator/deleter visibility, snapshots, Read Committed, and Repeatable Read.
  5. Persistent B+Tree Indexes — ordered key encoding, point and range access, split propagation, borrowing, merging, root contraction, and unique-build visibility.
  6. Statistics and Cost-Based Planning — exact ANALYZE, MCVs and histograms, selectivity, SeqScan/IndexScan crossover, bounded join dynamic programming, and EXPLAIN.
  7. Volcano Execution — executor trees, pull-based open/next/close, expression evaluation with INT64 semantics, and EXPLAIN ANALYZE.
  8. Isolation Levels, Write Conflicts, and EPQ — snapshot policy, serialization conflicts, and post-wait predicate rechecks.
  9. Locks and Deterministic Deadlock Detection — FIFO tuple/key locks, wait-for graphs, and deterministic victim selection.
  10. WAL, Checkpoints, and Recovery — full-page images, LSN gates, sharp checkpoints, torn-tail repair, and REDO-only recovery.
  11. VACUUM and HOT — reclamation horizons, index cleanup, stable-slot reuse, HOT chains, and pruning.
  12. Testing Methodology — the repository's five verification layers and differential checking against PostgreSQL 18.

How to use the book

Run commands from the repository root with uv run. Chapter outputs are observations from this tree, not illustrative guesses. Exercises never require you to edit the tutorial's src/ tree in place: make proposed diffs in a throwaway branch or reason from the folded reference answer, and use each exercise's acceptance checks.

For claims outside the chapter narrative, continue to:

Start with Chapter 1.