Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture

MuroDB is an embedded SQL database with optional at-rest encryption. The runtime stack is organized in layers:

sql/ (lexer → parser → planner → executor)
  ↓
schema/ (catalog: table/index definitions)
  ↓
tx/ (transaction: dirty page buffer, commit/rollback)
  ↓
btree/ (B-tree: insert/split, delete, search, scan)
  ↓
wal/ (WAL: encrypted records, crash recovery)
  ↓
storage/ (pager: encrypted page I/O, LRU cache, freelist)
  ↓
crypto/ (AES-256-GCM-SIV, Argon2 KDF, HMAC-SHA256)

Additional modules:

  • fts/ - Full-text search (bigram tokenizer, postings B-tree, BM25, BOOLEAN/NATURAL mode)
  • concurrency/ - parking_lot::RwLock (thread) + fs4 file lock (process)

How To Read This Section

If your goal is “reconstruct internals after a long break”, read in this order:

  1. Reading Guide
  2. Files, WAL, and Locking
  3. Storage
  4. Catalog Format
  5. B-tree
  6. Query Planning & Execution
  7. Cryptography
  8. WAL & Crash Resilience

Module Map

ModuleFilesRole
storage/page.rs, pager.rs, freelist.rs4096B encrypted page I/O
crypto/aead.rs, kdf.rs, hmac_util.rsEncryption primitives
btree/node.rs, ops.rs, cursor.rs, key_encoding.rsB-tree operations
wal/record.rs, writer.rs, reader.rs, recovery.rsWAL + crash recovery
tx/transaction.rs, lock_manager.rsTransactions
schema/catalog.rs, column.rs, index.rsSystem catalog
sql/lexer.rs, parser.rs, ast.rs, planner.rs, executor.rs, eval.rsSQL processing
fts/tokenizer.rs, postings.rs, index.rs, query.rs, scoring.rs, snippet.rsFull-text search
concurrency/mod.rsConcurrency control

Concurrency Model

  • Thread-level: parking_lot::RwLock - multiple readers, single writer
  • Process-level: fs4 file lock - prevents concurrent access from multiple processes
  • API routing:
    • Database::query acquires a shared lock for read-only statements.
    • Database::execute acquires an exclusive lock for general SQL execution.
    • CLI routes read-only statements to query unless an explicit transaction is active.
  • Handle model:
    • Database::query takes &mut self because read execution may refresh pager/catalog state from disk before running.
    • For concurrent reads in one process, open additional read-only handles (Database::open_reader) and run query on each handle.

For on-disk file contracts (main DB file / .wal / .lock), see Files, WAL, and Locking. For catalog key/value binary layouts, see Catalog Format.