cockroachdb/pebble
GitHub: cockroachdb/pebble
Pebble 是受 RocksDB 启发、专为 CockroachDB 优化的 Go 语言键值存储引擎，提供高性能嵌入式存储能力。
Stars: 5915 | Forks: 559
# Pebble [](https://github.com/cockroachdb/pebble/actions/workflows/ci.yaml) [](https://godoc.org/github.com/cockroachdb/pebble) [覆盖率](https://storage.googleapis.com/crl-codecover-public/pebble/index.html)
#### [夜间基准测试](https://cockroachdb.github.io/pebble/)
Pebble 是一个受到 LevelDB/RocksDB 启发的键值存储，专注于性能和 CockroachDB 的内部使用。Pebble 继承了 RocksDB 的文件格式以及一些扩展，例如范围删除墓碑、表级布隆过滤器和 MANIFEST 格式的更新。
Pebble 特意不追求包含 RocksDB 中的每一项特性，而是专注于 CockroachDB 所需的使用场景和特性集：
* 块表（Block-based tables）
* 检查点（Checkpoints）
* 索引批次（Indexed batches）
* 迭代器选项（下/上界、表过滤器）
* 层级压缩（Level-based compaction）
* 手动压缩（Manual compaction）
* 合并操作（Merge operator）
* 前缀布隆过滤器（Prefix bloom filters）
* 前缀迭代（Prefix iteration）
* 范围删除墓碑（Range deletion tombstones）
* 反向迭代（Reverse iteration）
* SSTable 摄取（SSTable ingestion）
* 单次删除（Single delete）
* 快照（Snapshots）
* 表级布隆过滤器（Table-level bloom filters）
RocksDB 拥有大量在 Pebble 中未实现的功能：
* 备份（Backups）
* 列族（Column families）
* 按范围删除文件（Delete files in range）
* FIFO 压缩风格（FIFO compaction style）
* 前向迭代器/尾部迭代器（Forward iterator / tailing iterator）
* 哈希表格式（Hash table format）
* 内存表布隆过滤器（Memtable bloom filter）
* 持久化缓存（Persistent cache）
* 锁定迭代器键/值（Pin iterator key / value）
* 纯表格式（Plain table format）
* SSTable 后端摄取（SSTable ingest-behind）
* 子压缩（Sub-compactions）
* 事务（Transactions）
* 通用压缩风格（Universal compaction style）
***警告***：如果与使用了 Pebble 不支持的某个功能的 RocksDB 数据库一起使用，Pebble 可能会静默损坏数据或行为异常。购买者自负风险！
## 生产就绪
Pebble 在 CockroachDB v20.1（2020 年 5 月发布）中作为 RocksDB 的替代存储引擎引入，并当时已成功用于生产环境。Pebble 在 CockroachDB v20.2（2020 年 11 月发布）中成为默认存储引擎。Pebble 被 CockroachDB 的用户大规模用于生产环境，被认为稳定且生产就绪。
## 优势
Pebble 在 RocksDB 的基础上提供了多项改进：
* 通过内存表跳表中的反向链接实现更快的反向迭代。
* 更快的提交管道，实现更好的并发性。
* 索引批次的无缝合并迭代。批次中的突变在概念上占据了另一个内存表层级。
* L0 子层和刷新拆分，用于实现 L0 的并发压缩，并在大量写入负载期间减少读放大。
* 通过使用写时复制 B 树保存文件元数据，在包含大量 SSTable 的 LSM 中实现更快的 LSM 编辑。
* 仅删除的压缩，可以丢弃完全落在范围删除边界内的 SSTable。
* 块属性收集器和过滤器，使迭代器能够跳过与用户定义的键值属性无关的表、索引块和数据块。
* 范围键 API，允许定义覆盖一段键空间的键值对，具有用户定义的语义，并在迭代期间进行交错处理。
* 更小、更易理解的代码库。
有关实现差异的更多详细信息，请参阅 [Pebble 与 RocksDB：实现差异](docs/rocksdb.md) 文档。
## RocksDB 兼容性
Pebble `v1` 力求与 RocksDB 6.2.1（CockroachDB 使用的最新版本 RocksDB）的前向兼容性。前向兼容性意味着由 RocksDB 6.2.1 生成的数据库可以升级以供 Pebble 使用。`v1` 系列的 Pebble 版本可以打开由 RocksDB 6.2.1 生成的数据库。自引入以来，Pebble 采用了各种不兼容的格式更改，这些更改通过新的“格式主版本”进行门控。Pebble `v2` 及更高版本不支持打开由 RocksDB 生成的数据库。由 RocksDB 生成的数据库只能在使用早期版本的 Pebble 通过格式主版本升级迁移后，才能与较新版本的 Pebble 一起使用。请参阅下方关于格式主版本的章节。
即使是支持 RocksDB 的 Pebble 版本也仅提供与 CockroachDB 所使用的功能和配置子集的兼容性。RocksDB 的功能和配置范围太大，无法充分测试和记录所有不兼容之处。以下列表包含已知的不兼容项。
* Pebble 对 WAL 回收的使用仅与 RocksDB 的 `kTolerateCorruptedTailRecords` WAL 恢复模式兼容。旧版 RocksDB 会自动将不兼容的 WAL 恢复模式映射到 `kTolerateCorruptedTailRecords`。新版 RocksDB 将禁用 WAL 回收。
* 列族。Pebble 不支持列族，也不在打开可能包含列族的数据库时尝试检测其使用。
* 哈希表格式。Pebble 不支持哈希表 SSTable 格式。
* 纯表格式。Pebble 不支持纯表 SSTable 格式。
* SSTable 格式版本 3 和 4。Pebble 不支持版本 3 和版本 4 格式的 SSTable。SSTable 格式版本由 `BlockBasedTableOptions::format_version` 选项控制。请参阅 [#97](https://github.com/cockroachdb/pebble/issues/97)。
## 格式主版本
随着时间的推移，Pebble 引入了新的物理文件格式。向后不兼容的更改通过引入“格式主版本”来进行。默认情况下，当 Pebble 打开数据库时，它默认使用支持的最低版本。在 `v1` 中，这是 `FormatMostCompatible`，它与 RocksDB 6.2.1 双向兼容（具有上述注意事项）。
由 RocksDB 或 Pebble `v1` 及更早版本创建的数据库必须先升级到兼容的格式主版本，然后才能运行较新版本的 Pebble。较新版本的 Pebble 将拒绝打开不再支持的格式的数据库。
要选择新的格式，用户可以在提供给 [`Open`](https://pkg.go.dev/github.com/cockroachdb/pebble#Open) 的 [`Options`](https://pkg.go.dev/github.com/cockroachdb/pebble#Options) 中设置 `FormatMajorVersion`，或者使用 [`DB.RatchetFormatMajorVersion`](https://pkg.go.dev/github.com/cockroachdb/pebble#DB.RatchetFormatMajorVersion) 在运行时升级格式主版本。
格式主版本的升级是永久性的；无法选择恢复到更早的格式。
下表概述了格式主版本的历史，以及支持该格式的 Pebble 版本范围。
| 名称 | 值 | 迁移方式 | Pebble 支持 |
|---------------------------------------|------|-------------|---------------------|
| FormatMostCompatible | 1 | 无 | v1 |
| FormatVersioned | 3 | 无 | v1 |
| FormatSetWithDelete | 4 | 无 | v1 |
| FormatBlockPropertyCollector | 5 | 无 | v1 |
| FormatSplitUserKeysMarked | 6 | 后台 | v1 |
| FormatSplitUserKeysMarkedCompacted | 7 | 阻塞 | v1 |
| FormatRangeKeys | 8 | 无 | v1 |
| FormatMinTableFormatPebblev1 | 9 | 无 | v1 |
| FormatPrePebblev1Marked | 10 | 后台 | v1 |
| FormatSSTableValueBlocks | 12 | 无 | v1 |
| FormatFlushableIngest | 13 | 无 | v1, v2, master |
| FormatPrePebblev1MarkedCompacted | 14 | 阻塞 | v1, v2, master |
| FormatDeleteSizedAndObsolete | 15 | 无 | v1, v2, master |
| FormatVirtualSSTables | 16 | 无 | v1, v2, master |
| FormatSyntheticPrefixSuffix | 17 | 无 | v2, master |
| FormatFlushableIngestExcises | 18 | 无 | v2, master |
| FormatColumnarBlocks | 19 | 无 | v2, master |
升级到迁移方式列为“后台”的格式主版本可能会触发后台活动来重写物理文件格式，通常通过压缩实现。升级到迁移方式列为“阻塞”的格式主版本将会阻塞，直到迁移完成。如果通过 `RatchetFormatMajorVersion` 升级活动数据库，数据库可以继续提供读写服务，但方法调用在迁移完成之前不会返回。
可以通过 `RatchetFormatMajorVersion` 方法升级现有存储。如果数据库不使用自定义比较器、合并器或块属性收集器，也可以使用支持该格式的最新版本的 `pebble` 工具。例如：
```
# 警告：仅在不需要自定义 comparer/merger/property collector 时使用。
go run github.com/cockroachdb/pebble/cmd/pebble@v1.1.3 db upgrade
```
作为参考，下表列出了 CockroachDB 各个版本支持的 Pebble 格式主版本范围。
| CockroachDB 版本 | 最早支持 | 最新支持 |
|------------------|------------------------------|-----------------------------|
| 20.1 至 21.1 | FormatMostCompatible | FormatMostCompatible |
| 21.2 | FormatMostCompatible | FormatSetWithDelete |
| 22.1 | FormatMostCompatible | FormatSplitUserKeysMarked |
| 22.2 | FormatMostCompatible | FormatPrePebblev1Marked |
| 23.1 | FormatSplitUserKeysMarkedCompacted | FormatFlushableIngest |
| 23.2 | FormatPrePebblev1Marked | FormatVirtualSSTables |
| 24.1 | FormatFlushableIngest | FormatSyntheticPrefixSuffix|
| 24.2 | FormatVirtualSSTables | FormatSyntheticPrefixSuffix|
| 24.3 | FormatSyntheticPrefixSuffix | FormatColumnarBlocks |
## 谱系
Pebble 基于 LevelDB 的不完整 Go 版本：
https://github.com/golang/leveldb
LevelDB 的 Go 版本基于 C++ 原始版本：
https://github.com/google/leveldb
优化和灵感来自 RocksDB：
https://github.com/facebook/rocksdb
## 快速开始
### 示例代码
```
package main
import (
"fmt"
"log"
"github.com/cockroachdb/pebble"
)
func main() {
db, err := pebble.Open("demo", &pebble.Options{})
if err != nil {
log.Fatal(err)
}
key := []byte("hello")
if err := db.Set(key, []byte("world"), pebble.Sync); err != nil {
log.Fatal(err)
}
value, closer, err := db.Get(key)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s %s\n", key, value)
if err := closer.Close(); err != nil {
log.Fatal(err)
}
if err := db.Close(); err != nil {
log.Fatal(err)
}
}
```
标签：CockroachDB, EVTX分析, Go, LevelDB, RocksDB, Ruby工具, SSTable, 前缀迭代, 单删除, 压缩, 反向迭代, 合并操作, 块表, 存储引擎, 布隆过滤器, 快照, 手动压缩, 数据库, 日志审计, 检查点, 索引批处理, 范围删除, 表级布隆过滤器, 迭代器, 键值存储