jonnify·persistence /echo-persistence/local-store/cubdb

Module 4 · Chapter II — The local store

CubDB architecture.

The durable local tier is a single embedded database: CubDB, an append-only, immutable B-tree on one file. Every property the native engine relies on — crash-safe commits, free snapshots, the page log itself — is a consequence of those two words, append-only and immutable. This module builds it from the write path out, by working the figure rather than reading a benchmark.

A CubDB write. Nothing is overwritten. Tap a stage, or run a write and watch a block append to the file and the current version advance.
1 · writekey = value 2 · B-treecopy the path, new nodes 3 · fileappend a block 4 · headernew current version the one file (grows rightward): ▲ current
readout · Tap a stage, or run a write. A write copies only the changed B-tree path, appends those new nodes plus a header to the end of the file, and the latest header is the new current version. The old data is untouched.
§1

Two words do the work

store.design.md

Append-only means a write never modifies an existing byte; it adds to the tail. That alone gives crash-safety — a torn final write is simply ignored, and the last complete header wins — and it makes a commit a single atomic act: write the header. Immutable means the B-tree is copy-on-write, so an update rewrites the path to the changed leaf as new nodes and leaves every old node, and old root, exactly where it was. Together they make old versions free to keep, which is the whole basis of the next module.

The cost of never overwriting is that the file only grows, so dead data accumulates and must occasionally be swept up. Each of those three — the append-only file, the immutable B-tree, and compaction — is a dive.

§2

The three dives

module 4
Dive 4.1

The append-only file

Commits append; the last header is the truth. Append writes, then crash mid-commit and watch the torn tail get discarded with no harm done.

 Dive 4.2

The immutable B-tree

Copy-on-write. Update a key and watch only the root-to-leaf path get rewritten as new nodes, the old tree left whole and still readable.

 Dive 4.3

Compaction

The file only grows. Watch dead nodes pile up across writes, then compact — live data copied to a fresh file, the rest reclaimed.
§3

Build & check

What you build

A one-paragraph note placing CubDB in the storage ladder from the landing: which tier it is, what it stores (the page log / LSN log), and why an embedded single-file store is the right shape for it — in your own words, no numbers.

Check

Answer without code: why is an append-only commit crash-safe, and why does keeping an old version cost nothing? If both answers point back to “nothing is overwritten,” you have the module.

§4

References & sources