jonnify·persistence /echo-persistence/cubdb/the-append-only-file

Module 4 · Dive 4.1

The append-only file.

CubDB writes by appending and never by overwriting. Each commit adds its data and ends with a header; the last complete header is, by definition, the current state. That makes a commit a single atomic act and crash recovery a non-event — a half-written tail is just ignored. Append a few commits, then crash one mid-write.

§1

The last header wins

interactive
Append-only commits. Each commit appends data then a header; the marker tracks the current version. Crash mid-commit and the torn tail is fenced off on the next open.
file offset → current
readout · Commit appends data + a header and the current version moves to it. Crash mid-commit appends a torn header — on the next open CubDB scans back to the last good header, so the torn tail simply never existed.
§2

Atomicity for free

store.design.md

A database that overwrites in place has to work to stay consistent through a crash — journals, double-writes, fsync dances — because a torn overwrite corrupts existing data. Append-only sidesteps all of it: existing bytes are never at risk, so the only question on recovery is “where does the good data end,” answered by scanning to the last valid header. The commit becomes visible exactly when its header lands, and not a moment before. This is the property the native engine leans on to call a page durable, and it is why the durable tier could be a single embedded file rather than a server.

§3

References & sources