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
Six chapters that take you from first principles all the way to production-grade distributed systems. Each chapter is self-contained and builds on the previous.
| 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, simulation | How FDB achieves correctness and why it’s trusted at Apple scale |
| 3. The Layer Concept | Key encoding, subspace pattern, atomicity | How to turn an ordered KV store into any data model |
| 4. How Real Systems Use FDB | CloudKit, mvsqlite, Document Layer, TiKV | That the patterns in this repo are battle-tested in production |
| 5. This Repository | The five lab implementations | How to navigate, run, and extend the labs |
| 6. Reading Guide | Papers, books, source code to read next | Where to go to become a true expert |
How to Read This
If you have 2 hours: Read chapters 1–3, then pick any one lab and read its Architecture Walk-through.
If you have a day: Read all six chapters, then work through all five labs in order (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–3 and the Interview Q&A sections at the end of each lab guide.
If you just want to run the code: Jump straight to Chapter 5 — This Repository for quick-start instructions, 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.