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
| Folder | Plugs in | Teaches |
|---|---|---|
| option-a-leveldb | Above LevelDB | LevelDB’s external API: iterators, snapshots, write batches |
| option-a-sqlite | Above SQLite | How SQL decomposes into storage ops; vtab query planning |
| option-b-leveldb | Below LevelDB | LevelDB internals: SST files, WAL, MANIFEST, CURRENT |
| option-b-sqlite | Below SQLite | SQLite internals: page model, VFS, journaling |
| option-c-record-layer | Directly on FDB | Native FDB layer: records + secondary indexes |
Prerequisites
- Docker — to run a local single-node FDB cluster
- FoundationDB client library on the host (
libfdb_c) — required by the Go bindings (CGO)- macOS:
brew install foundationdb(or install the official.pkgfrom Apple’s release page)
- macOS:
- 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