The Hitchhiker’s Guide to FoundationDB and Storage Layers
“Don’t Panic.”
This guide assumes you have seen a key–value store before but have never thought hard about what happens underneath. By the end you should be able to design and build your own layer on top of FoundationDB — not just copy one.
What This Guide Covers
Ten chapters that take you from first principles to source-level fluency. Read in order; each chapter is a prerequisite for the next.
| Chapter | Topic | What you’ll know after |
|---|---|---|
| 1. The Storage Stack | B-trees, LSM-trees, WAL, buffer pools | Why every database makes the same five trade-offs |
| 2. FoundationDB in Depth | MVCC, commit pipeline, cluster roles, watches, atomic ops | How FDB achieves correctness end-to-end |
| 3. Storage Engines | SQLite → Redwood → Sharded RocksDB, source-level | What is actually written to disk, and why it changed |
| 4. Flow, Actors, and Simulation | The C++ extension, the event loop, deterministic testing | How to read any .actor.cpp file in the source tree |
| 5. Performance | Latency, throughput, concurrency in concrete numbers | How to size and predict an FDB cluster’s behavior |
| 6. The Layer Concept | Key encoding, subspace pattern, conflict ranges | How to turn an ordered KV store into any data model |
| 7. The Record Layer — A Deep Dive | Apple’s open-source Record Layer, source-level | How CloudKit-grade record storage is built on FDB |
| 8. How Real Systems Use FDB | CloudKit, mvsqlite, Document Layer, TiKV, Snowflake | That the patterns in this repo are battle-tested in production |
| 9. This Repository | The five lab implementations | How to navigate, run, and extend the labs |
| 10. Reading Guide | Papers, books, source code to read next | Where to go to become a true expert |
| 11. Contributing to FoundationDB | Building from source, first-PR catalog | A real path to becoming an upstream contributor |
How to Read This
If you have 2 hours: Read chapters 1–3 (the storage stack, FDB in depth, and the storage-engine deep dive), then pick any one lab and read its Architecture Walk-through.
If you have a day: Read all ten chapters in order, then work through all five labs (A-leveldb → A-sqlite → B-leveldb → B-sqlite → C-record-layer). The labs increase in conceptual complexity.
If you’re preparing for a systems interview: Focus on chapters 1, 2, 5 (performance), and 6 (the layer concept), and the Interview Q&A sections at the end of each chapter.
If you want to contribute upstream: Read chapters 2, 3, and 4 carefully, then jump to Chapter 11 — Contributing for the runway.
If you just want to run the code: Jump straight to Chapter 9 — This Repository, then come back to the background chapters for depth.
Core Insight
Every database is a stack of layers, each one a client of the one below. FoundationDB occupies one specific layer: ordered, transactional, distributed key-value storage. Every layer above it — SQL, document model, LevelDB API, SQLite page store, record layer — is a pure encoding problem. Learn the encoding and you understand the database.
That is what this guide teaches.