Skip to content

MiniMongoDB: A Document Database in Miniature

中文版

MiniMongoDB is a deterministic, single-process Python kernel for learning how a document database owns values, matches arrays, applies atomic single-document updates, makes writes durable, replays an oplog, maintains multikey indexes, chooses query plans, and executes aggregation pipelines.

This book follows mechanisms in dependency order. Each chapter anchors its claims to concrete functions under src/minimongodb/, contrasts the miniature with real MongoDB, includes a measured experiment, and ends with exercises whose proposed source changes are not applied to src/.

Before you begin

You need Python 3.12+ and uv:

git clone https://github.com/system-in-miniature/mini-mongodb.git
cd mini-mongodb
uv sync
uv run pytest -q

MiniMongoDB is an in-process teaching kernel, not a MongoDB-compatible server. It has no MongoDB wire protocol or driver endpoint. Keep the mechanism mapping and differences open while reading so that equivalent, simplified, and opposite behaviors stay separate.

Book contents

  1. Meet MiniMongoDB — positioning, environment, the first insert/find, and the complete system map.
  2. The Document Model — BSON-shaped type tags, comparison order, typed identity, and dotted paths.
  3. Query Semantics — operators and the crucial distinction among array fan-out, exact whole values, and dotted paths.
  4. Update Operators — $set/$inc/$push/$pull, replacement updates, immutable _id, and copy-first atomicity.
  5. Durability and Recovery — journal-first publication, committed prefixes, checkpoints, and startup recovery.
  6. The Oplog — post-image rewriting and why replaying $inc as $set makes recovery idempotent.
  7. Secondary Indexes — compound, unique, and multikey indexes built from canonical typed keys.
  8. Planning and Explain — IXSCAN versus COLLSCAN, leftmost prefixes, selectivity, and scan counters.
  9. Aggregation Pipelines — $match/$project/$group/$sort/$limit as streaming and blocking stages.
  10. Relational versus Document — a systematic comparison with MiniPostgres and the limits of each model.

Reference material

Use the repository README for the implemented feature inventory and source directory guide. The mechanism mapping is the parity ledger; the differences chapter is the semantic boundary; and the lab guide collects runnable demonstrations. Construction-time plans are retained in the design history archive, but the tutorial, current source, and tests define behavior.