Pebble

Pebble is CockroachDB’s embedded storage engine: a LevelDB/RocksDB-inspired, log-structured merge-tree (LSM) key-value store written entirely in Go. It targets the specific feature set CockroachDB needs rather than reimplementing every RocksDB capability, trading a smaller surface area for a codebase that is easier to reason about and extend.

Since becoming CockroachDB’s default storage engine in v20.2, Pebble has shipped its own format-major-version system, copy-on-write B-tree LSM metadata, block-property filtering, range keys, and delete-only compactions — features that go beyond a straight RocksDB port and are validated continuously through a metamorphic (randomized) test harness alongside its unit tests.

What You Get

• Block-based LSM storage engine - Open() a directory and get a full read/write key-value store with iterators, batches, and snapshots.
• Range keys and range deletions - first-class APIs for keyspan-scoped tombstones and range-keyed metadata interleaved during iteration.
• Pluggable comparators and mergers - custom Compare/Equal/Merge/Split functions let you define your own key ordering and value-merge semantics.
• Format major version migrations - a versioned on-disk format system with background or blocking migrations so stores can be upgraded in place.
• Companion pebble CLI tool - inspect, analyze, and upgrade on-disk stores (db analyze, db upgrade, lsm, find) without writing Go code.

Common Use Cases

• Embedding a storage engine in a distributed database - CockroachDB itself uses Pebble as its per-node KV storage layer under its SQL and Raft layers.
• Building a custom key-value store or cache - applications that need an ordered, durable, LSM-backed store without running a separate database process.
• Migrating off RocksDB CGo bindings - Go services that want to drop CGo/RocksDB dependencies in favor of a pure-Go storage engine with a compatible on-disk format path.
• High-throughput write workloads - workloads needing fast commit pipelines, L0 sublevels, and concurrent compactions to keep up with heavy write load.
• Debugging and upgrading existing Pebble/RocksDB stores - operators use the pebble tool to analyze SSTables, MANIFESTs, and WALs, or ratchet a store to a newer format major version.

Under The Hood

Architecture Pebble is organized in clear layers around the DB struct in db.go: writes go through a commit pipeline into an in-memory memTable (mem_table.go) backed by a write-ahead log (wal/, record/), which is later flushed into block-based SSTables (sstable/) organized into levels tracked by version_set.go and compaction_picker.go/compaction_scheduler.go. Reads merge across memtables, indexed batches, and on-disk levels via merging_iter.go against a consistent read_state.go snapshot, while internal/ supplies low-level primitives (skiplists, caches, keyspans) and objstorage/vfs abstract local versus remote file storage so the same LSM core can target disaggregated storage. Because every read/write/compaction path depends on this shared on-disk file and version-metadata contract, changing the core LSM abstraction would ripple through flush, ingest, and iteration code alike.

Tech Stack Pebble is pure Go (module requires Go 1.25) with no CGo dependency, relying on cockroachdb/errors and cockroachdb/redact for structured, wrapped errors, google/btree/RaduBerinde/axisds for the copy-on-write LSM metadata B-tree, and a mix of compression libraries (DataDog/zstd, klauspost/compress, golang/snappy, minio/minlz) for its SSTable blocks. spf13/cobra powers the bundled pebble CLI tool and prometheus/client_golang exposes engine metrics; the Makefile-driven build and an extensive GitHub Actions matrix (standard CI, cross-version, stress, nightly, and big-endian s390x runs) target it as an embedded library linked into CockroachDB and other Go binaries rather than a standalone service.

Code Quality Roughly a third of the repository’s Go files are tests, many built on cockroachdb/datadriven golden-file test cases plus a dedicated metamorphic/ package that fuzzes sequences of operations against reference implementations to catch correctness bugs standard unit tests would miss. Errors are wrapped through cockroachdb/errors rather than left as bare strings, an internal/invariants package adds runtime assertions in debug builds, and naming follows idiomatic Go conventions with strongly typed keys and pluggable comparator/merge function types. The CI matrix’s breadth — cross-version compatibility checks, stress runs, and non-x86 architecture testing — reflects the rigor expected of a storage engine that must never silently corrupt data.

What Makes It Unique Rather than cloning RocksDB feature-for-feature, Pebble makes several concrete engineering departures: a copy-on-write B-tree (instead of a flat list) for LSM version metadata keeps file-metadata edits fast even at large SSTable counts; block-property collectors and filters let iterators skip whole tables or blocks based on user-defined properties; indexed batches are merged into iteration as if they were another memtable level, avoiding a separate merge step; and delete-only compactions drop SSTables fully covered by a range tombstone instead of rewriting them. Combined with L0 sublevels and flush splitting for concurrent compaction under heavy write load, these choices target read/write amplification and metadata-edit latency specifically, building meaningfully on — rather than merely reimplementing — its RocksDB/LevelDB heritage.