📖 Local build — commit and timestamp are injected automatically on Cloudflare Pages.

Preface — Why This Book Exists

• How This Book Is Structured
• Who This Book Is For
• A Note on Style
• FoundationDB Layers — Go Implementations
  • Layout
  • Prerequisites
  • Bootstrap the cluster
  • Running a demo
  • Documentation (mdbook)

“In many of the more relaxed civilizations on the Outer Eastern Rim of the Galaxy, the Hitchhiker’s Guide has already supplanted the great Encyclopaedia Galactica as the standard repository of all knowledge and wisdom.” — Douglas Adams

This book aims to be that for FoundationDB: the practical, opinionated, source-level guide you wished existed when you first opened the docs.

There is no shortage of FoundationDB material on the internet. There is a tidy official documentation site, a handful of conference talks, a research paper (SIGMOD 2021), and a famous CMU Database Group talk by Markus Pilman. Each piece is good. None of them together is enough to build a layer.

What’s missing is the connective tissue:

• The history of how FDB got here — why the original storage engine was literally SQLite’s B-tree (KeyValueStoreSQLite), why that was replaced by Redwood, and what Sharded RocksDB is doing in the codebase as of 7.3.
• The source-level mechanics — what a commit actually does on the wire, how many fsync calls it costs, what the Resolver’s in-memory data structure looks like, how Flow’s actor model compiles down to C++.
• The numbers — concrete latency budgets, throughput ceilings, transaction volume curves, and what changes them. Not “FDB is fast” but “a 3-node cluster on c5.4xlarge sustains ≈55,000 cross-shard commits/sec at p99 < 8 ms, here is the workload, here is how to reproduce it.”
• The patterns — five hands-on labs in this repo that turn that theory into Go code you can run, modify, and break.

This book is what happens when you treat FoundationDB the way Brendan Gregg treats Linux performance, or the way Designing Data-Intensive Applications treats distributed systems: with curiosity, citations, and the willingness to follow a function call across a process boundary into another machine.

If you finish this book you should be able to:

1. Explain to a colleague exactly what happens during db.Transact(...) — every network hop, every disk write, every B-tree page touched.
2. Read the FoundationDB source tree (fdbserver/, fdbclient/, fdbrpc/, flow/) and know which files to open for a given question.
3. Design a new layer (graph, vector index, time series, queue) from scratch, choosing the right key encoding, conflict-range strategy, and atomic op primitives.
4. Reproduce the published benchmarks and reason about why your workload deviates from them.
5. Submit a meaningful PR to apple/foundationdb — fix a bug, add a test, improve a doc, optimize a hot path. The contributing chapter is a real path, not a token gesture.

How This Book Is Structured

The book has two parts. Part I — Background is a deep, source-level guide to FoundationDB itself. Read it in order; each chapter is a prerequisite for the next. Part II — Labs is five independent Go implementations you can run; pick any order, but each lab’s walk-through assumes you know Part I.

Who This Book Is For

• Backend engineers who use FDB-backed services (CloudKit, Snowflake metadata, Tigris, etc.) and want to understand the substrate.
• Database engineers designing a new storage system or evaluating FDB.
• Distributed systems students who have read DDIA and want a single open-source system to study end-to-end.
• Interview candidates preparing for senior systems roles — the “Interview Questions” sections at the end of each chapter are designed for exactly this.
• Aspiring FDB contributors — the final chapter is your runway.

A Note on Style

This book quotes the FoundationDB source tree liberally. All citations are to apple/foundationdb at the time of writing (release-7.3 branch unless noted). Where source files have moved between releases, I give the older path too. Code excerpts are short and used only for explanation; the project’s Apache 2.0 license permits this, and the original copyright stays with the FoundationDB authors.

Where I cite latency or throughput numbers, I cite the hardware and workload. Treat every number as falsifiable; the reproduction recipe is always nearby.

Now — don’t panic — and turn the page.

FoundationDB Layers — Go Implementations

Five self-contained Go implementations that show different ways to build a “layer” on top of FoundationDB. Modeled after real projects (mvsqlite, fdb-record-layer) but pared down for clarity.

Layout

Prerequisites

1. Docker — to run a local single-node FDB cluster
2. FoundationDB client library on the host (libfdb_c) — required by the Go bindings (CGO)
   • macOS: brew install foundationdb (or install the official .pkg from Apple’s release page)
3. Go 1.22+

Bootstrap the cluster

docker compose up -d
./scripts/bootstrap-fdb.sh

This creates ./fdb.cluster at the repo root. Every demo reads it via the relative path ../fdb.cluster.

To shut down: docker compose down (data persists in ./fdb-data).

To wipe everything: docker compose down -v && rm -rf fdb-data fdb-config fdb.cluster.

Running a demo

Each option is an independent Go module:

cd option-a-leveldb
go run ./demo

See each folder’s docs/ for an architecture walk-through.

Documentation (mdbook)

The docs are structured as an mdbook under book/. To read them locally:

# Install mdbook (once)
brew install mdbook

# Build the book (output → book/dist/)
mdbook build

# Or serve with live-reload
mdbook serve --port 3001

The book is organized into two parts:

• Background — The Hitchhiker’s Guide split into six chapters (storage stack, FDB internals, the layer concept, real-world systems, repo overview, further reading)
• Labs — One overview + architecture walk-through per option