explaingit

cockroachdb/pebble

★ 5,882GoAudience · developerComplexity · 4/5Setup · moderate

TLDR

Pebble is the storage engine powering CockroachDB, a Go library that handles reading and writing key-value data to disk with crash recovery, compaction, and point-in-time snapshots.

Mindmap

mindmap
  root((pebble))
    What it does
      Storage engine
      Key-value store
      Crash recovery
      Data compaction
    Tech stack
      Go
    Features
      Snapshots
      Range scans
      Write-ahead log
      Range deletes
    Use cases
      Database backend
      Go data layer
      CockroachDB storage
    Limits
      No column families
      No transactions
      No RocksDB compat
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Embed Pebble as the storage layer in a custom Go database to get crash-safe reads and writes without building it yourself.

USE CASE 2

Use Pebble's range scan API to efficiently iterate over sorted keys in a Go application.

USE CASE 3

Take point-in-time snapshots so reads see a consistent view of data even while writes are happening.

USE CASE 4

Replace LevelDB or RocksDB as the storage backend in a Go project that needs a production-tested alternative.

Tech stack

Go

Getting it running

Difficulty · moderate Time to first run · 30min

Pebble databases are not compatible with RocksDB databases that used unsupported features, mixing them can silently corrupt data.

In plain English

Pebble is a storage engine, which is the part of a database system responsible for actually reading and writing data to disk. It is built in Go by the team behind CockroachDB, a distributed database. Pebble takes inspiration from two well-known storage engines: LevelDB and RocksDB, meaning it shares their general approach of organizing data into sorted layers on disk, but it rewrites that approach in Go with a narrower feature set tuned for CockroachDB's specific needs. At its core, Pebble stores key-value pairs, which are simple pairs of a lookup key and its associated data. Applications can read and write individual entries, scan ranges of keys, take snapshots of the data at a point in time, and delete ranges of entries efficiently. The library handles all the complexity of keeping data consistent on disk, managing write-ahead logs to survive crashes, and periodically compacting data to keep reads fast. Pebble does not try to replicate every feature from RocksDB. It explicitly leaves out things like column families, certain table formats, and transaction support. The README warns that using Pebble with a database originally created by RocksDB can silently corrupt data if that database used features Pebble does not support, so mixing them is not recommended. The project has been used in production inside CockroachDB since 2020 and became the default storage engine in CockroachDB version 20.2. It ships with nightly benchmark results published publicly so performance regressions can be caught early. The source code is written in Go and is open source.

Copy-paste prompts

Prompt 1
Show me how to open a Pebble database in Go, write 3 key-value pairs, and read them back using a range scan iterator.
Prompt 2
How do I take a snapshot in Pebble and use it to read data at a fixed point in time while the main database continues accepting writes?
Prompt 3
Write Go code using Pebble to delete a range of keys efficiently with DeleteRange, and explain when this is better than deleting one key at a time.
Prompt 4
I'm migrating from LevelDB to Pebble in my Go project. What are the key API differences I need to handle and what features does Pebble not support?
Open on GitHub → Explain another repo

← cockroachdb on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.