Pebble — High-Performance Embedded Key-Value Store in Go

Introduction

Pebble is an embedded key-value store written in Go by Cockroach Labs. It serves as the default storage engine for CockroachDB, replacing their earlier RocksDB dependency. Pebble draws on LevelDB and RocksDB design principles but is implemented in pure Go, eliminating CGo overhead and simplifying deployment.

What Pebble Does

• Stores ordered key-value pairs on disk using an LSM-tree architecture
• Provides MVCC-aware iteration for databases that need multi-version concurrency control
• Supports range deletions and merge operations for efficient bulk data management
• Handles concurrent reads and writes safely within a single Go process
• Delivers crash consistency through a write-ahead log and atomic manifest updates

Architecture Overview

Pebble implements a Log-Structured Merge-tree with multiple compaction levels. Writes go to an in-memory batch and MemTable backed by a WAL. When the MemTable fills, it flushes to Level 0 as a sorted table (SSTable). Background goroutines compact SSTables across levels to reduce read amplification. Pebble uses a custom table format with block-level compression, Bloom filters, and a two-level index for fast point and range lookups.

Self-Hosting & Configuration

• Import as a Go module: go get github.com/cockroachdb/pebble
• Open a database directory with pebble.Open() and customizable Options
• Tune MemTableSize and L0CompactionThreshold for your write throughput needs
• Configure LBaseMaxBytes to control when compaction triggers across levels
• Set Cache size to manage the block cache for frequently accessed data

Key Features

• Pure Go implementation with zero CGo dependencies simplifies cross-compilation and debugging
• MVCC-aware key comparison supports timestamp-based versioning natively
• Range tombstones delete large key ranges without scanning individual keys
• Write batches provide atomic multi-key commits with deferred application
• Extensive test suite including metamorphic testing to catch correctness bugs

Comparison with Similar Tools

• RocksDB — C++ LSM engine with more tuning knobs and wider language bindings; Pebble trades some flexibility for Go-native simplicity
• LevelDB — The original inspiration; simpler but lacks features like range deletions and MVCC awareness
• BadgerDB — Go-native LSM store separating keys and values; Pebble keeps values inline for lower read amplification
• BoltDB (bbolt) — B+ tree design in Go; excels at read-heavy workloads but single-writer limits write throughput
• SQLite — Full SQL engine embedded in C; far more features but heavier than a pure key-value store

FAQ

Q: Is Pebble production-ready? A: Yes. Pebble is the default storage engine for CockroachDB, which runs in production at major enterprises. It has extensive testing including randomized metamorphic tests.

Q: Can I use Pebble outside of CockroachDB? A: Absolutely. Pebble is a standalone Go library. Any Go application can import and use it as an embedded key-value store.

Q: How does Pebble handle concurrency? A: Multiple goroutines can read and write concurrently. Pebble uses internal synchronization to manage MemTable access, WAL writes, and compaction without external locking.

Q: Why choose Pebble over BadgerDB? A: Pebble stores values inline with keys, reducing read amplification for workloads that frequently access values. BadgerDB separates values into a value log, which helps when values are large but adds garbage collection complexity.

Sources

• https://github.com/cockroachdb/pebble
• https://github.com/cockroachdb/pebble/blob/master/docs/rocksdb.md