wlw/srdb
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档：更新 DESIGN.md，使用英文注释和调整项目结构说明

Browse Source
This commit is contained in:
bourdon
2025-10-09 01:33:22 +08:00
parent 6499464f1c
commit 8019f2d794
38 changed files with 4297 additions and 2750 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
DESIGN.md
View File

@@ -1,6 +1,6 @@
# SRDB 设计文档：WAL + mmap B+Tree
> 模块名：`code.tczkiot.com/srdb`
> 模块名：`code.tczkiot.com/wlw/srdb`
> 一个高性能的 Append-Only 时序数据库引擎
## 🎯 设计目标
@@ -19,10 +19,10 @@
│ SRDB Architecture │
├─────────────────────────────────────────────────────────────┤
│ Application Layer │
│ ┌───────────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Database │->│ Table │->│ Engine │ │
│ │ (Multi-Table) │ │ (Schema) │ │ (Storage) │ │
│ └───────────────┘ └──────────┘ └───────────┘ │
│ ┌───────────────┐ ┌──────────────────────────┐ │
│ │ Database │->│ Table │ │
│ │ (Multi-Table) │ │ (Schema + Storage) │ │
│ └───────────────┘ └──────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Write Path (High Concurrency) │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
@@ -38,10 +38,10 @@
├─────────────────────────────────────────────────────────────┤
│ Storage Layer (Persistent) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ SST Files (B+Tree Format + Compression) │ │
│ │ SST Files (B+Tree Format + Binary Encoding) │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ File Header (256 bytes) │ │ │
│ │ │ - Magic, Version, Compression │ │ │
│ │ │ - Magic, Version, Metadata │ │ │
│ │ │ - MinKey, MaxKey, RowCount │ │ │
│ │ ├─────────────────────────────────────────┤ │ │
│ │ │ B+Tree Index (4 KB nodes) │ │ │
@@ -49,8 +49,9 @@
│ │ │ - Internal Nodes (Order=200) │ │ │
│ │ │ - Leaf Nodes → Data Offset │ │ │
│ │ ├─────────────────────────────────────────┤ │ │
│ │ │ Data Blocks (Snappy Compressed) │ │ │
│ │ │ - JSON serialized rows │ │ │
│ │ │ Data Blocks (Binary Format) │ │ │
│ │ │ - 有 Schema: 二进制编码 │ │ │
│ │ │ - 无 Schema: JSON 格式 │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Secondary Indexes (Optional) │ │
@@ -88,59 +89,32 @@
```
srdb/ ← 项目根目录
├── go.mod ← 模块定义: code.tczkiot.com/srdb
├── go.mod ← 模块定义: code.tczkiot.com/wlw/srdb
├── DESIGN.md ← 本设计文档
├── CLAUDE.md ← Claude Code 指导文档
│
├── database.go ← 数据库管理 (多表)
├── table.go ← 表管理
├── table.go ← 表管理 (带 Schema)
├── errors.go ← 错误定义和处理
│
├── engine/ ← 存储引擎
│ └── engine.go ← 核心引擎实现 (583 行)
├── wal.go ← WAL 实现 (Write-Ahead Log)
├── memtable.go ← MemTable 实现 (map + sorted slice)
├── sstable.go ← SSTable 文件 (读写器、管理器、编码)
├── btree.go ← B+Tree 索引 (构建器、读取器)
├── version.go ← 版本控制 (MANIFEST 管理)
├── compaction.go ← Compaction 压缩合并
│
├── wal/ ← Write-Ahead Log
│ ├── wal.go ← WAL 实现 (208 行)
│ └── manager.go ← WAL 管理器
├── schema.go ← Schema 定义与验证
├── index.go ← 二级索引管理器
├── index_btree.go ← 索引 B+Tree 实现
├── query.go ← 查询构建器和表达式求值
│
├── memtable/ ← 内存表
│ ├── memtable.go ← MemTable 实现 (130 行)
│ └── manager.go ← MemTable 管理器 (多版本)
├── examples/ ← 示例程序目录
│ ├── webui/ ← Web UI 管理工具
│ └── ... (其他示例)
│
├── sst/ ← SSTable 文件
│ ├── format.go ← 文件格式定义
│ ├── writer.go ← SST 写入器
│ ├── reader.go ← SST 读取器 (mmap, 147 行)
│ ├── manager.go ← SST 管理器
│ └── encoding.go ← 序列化/压缩
│
├── btree/ ← B+Tree 索引
│ ├── node.go ← 节点定义 (4KB)
│ ├── builder.go ← B+Tree 构建器 (125 行)
│ └── reader.go ← B+Tree 读取器
│
├── manifest/ ← 版本控制
│ ├── version_set.go ← 版本集合
│ ├── version_edit.go ← 版本变更
│ ├── version.go ← 版本信息
│ ├── manifest_writer.go ← MANIFEST 写入
│ └── manifest_reader.go ← MANIFEST 读取
│
├── compaction/ ← 压缩合并
│ ├── manager.go ← Compaction 管理器
│ ├── compactor.go ← 压缩执行器
│ └── picker.go ← 文件选择策略
│
├── index/ ← 二级索引 (新增)
│ ├── index.go ← 索引实现
│ ├── manager.go ← 索引管理器
│ └── README.md ← 索引使用文档
│
├── query/ ← 查询系统 (新增)
│ ├── builder.go ← 查询构建器
│ └── expr.go ← 表达式求值
│
└── schema/ ← Schema 系统 (新增)
├── schema.go ← Schema 定义与验证
├── examples.go ← Schema 示例
└── README.md ← Schema 使用文档
└── webui/ ← Web UI 静态资源
└── ...
```
### 运行时数据目录结构
@@ -162,7 +136,7 @@ database_dir/ ← 数据库目录
│ ├── 000002.sst
│ └── 000003.sst
│
└── index/ ← 索引目录 (可选)
└── idx/ ← 索引目录 (可选)
├── idx_name.sst ← 字段 name 的索引
└── idx_email.sst ← 字段 email 的索引
```
@@ -283,14 +257,20 @@ B+Tree 节点格式:
│ ├─ Child Pointer 2 (8 bytes) │
│ └─ ... │
│ │
│ Leaf Node: │
│ ├─ Data Offset 1 (8 bytes) │
│ ├─ Data Size 1 (4 bytes) │
│ ├─ Data Offset 2 (8 bytes) │
│ ├─ Data Size 2 (4 bytes) │
│ Leaf Node (interleaved storage): │
│ ├─ (Offset, Size) Pair 1 │
│ │ ├─ Data Offset 1 (8 bytes) │
│ │ └─ Data Size 1 (4 bytes) │
│ ├─ (Offset, Size) Pair 2 │
│ │ ├─ Data Offset 2 (8 bytes) │
│ │ └─ Data Size 2 (4 bytes) │
│ └─ ... │
└─────────────────────────────────────┘
解释：
- interleaved storage: 交叉存储
优势:
✅ 固定大小 (4 KB) - 对齐页面
✅ 可以直接 mmap 访问
@@ -513,7 +493,6 @@ type Table struct {
name string
dir string
schema *schema.Schema
engine *engine.Engine
}
使用示例:
@@ -571,7 +550,7 @@ Flush 流程 (后台):
↓
4. 构建 B+Tree 索引
↓
5. 写入数据块 (Snappy 压缩)
5. 写入数据块 (二进制格式)
↓
6. 写入 B+Tree 索引
↓
@@ -630,22 +609,23 @@ Flush 流程 (后台):
### 代码规模
```
核心代码: 5399 行 (不含测试和示例)
├── engine: 583 行
├── wal: 208 行
├── memtable: 130 行
├── sst: 147 行 (reader)
├── btree: 125 行 (builder)
├── manifest: ~500 行
├── compaction: ~400 行
├── index: ~400 行
├── query: ~300 行
├── schema: ~200 行
└── database: ~300 行
核心代码: ~13,000 行 (不含测试和示例)
├── table.go: 表管理和存储引擎
├── wal.go: WAL 实现
├── memtable.go: MemTable 实现
├── sstable.go: SSTable 文件读写
├── btree.go: B+Tree 索引
├── version.go: 版本控制 (MANIFEST)
├── compaction.go: Compaction 压缩
├── index.go: 二级索引
├── query.go: 查询构建器
├── schema.go: Schema 验证
├── errors.go: 错误处理
└── database.go: 数据库管理
测试代码: ~2000+ 行
示例代码: ~1000+ 行
总计: 8000+ 行
总计: 16,000+ 行
```
### 写入性能
@@ -692,10 +672,10 @@ Flush 流程 (后台):
```
示例 (100 万条记录，每条 200 bytes):
- 原始数据: 200 MB
- Snappy 压缩: 100 MB (50% 压缩率)
- 二进制编码: ~180 MB (紧凑格式)
- B+Tree 索引: 20 MB (10%)
- 二级索引: 10 MB (可选)
- 总计: 130 MB (65% 压缩率)
- 总计: ~210 MB (无压缩)
```
## 🔧 实现状态
@@ -704,14 +684,14 @@ Flush 流程 (后台):
```
核心存储引擎:
- [✅] Schema 定义和解析
- [✅] WAL 实现 (wal/)
- [✅] MemTable 实现 (memtable/，使用 map+slice)
- [✅] 基础的 Insert 和 Get
- [✅] SST 文件格式定义 (sst/format.go)
- [✅] B+Tree 构建器 (btree/)
- [✅] Schema 定义和解析 (schema.go)
- [✅] WAL 实现 (wal.go)
- [✅] MemTable 实现 (memtable.go，使用 map+slice)
- [✅] 基础的 Insert 和 Get (table.go)
- [✅] SST 文件格式定义 (sstable.go)
- [✅] B+Tree 构建器 (btree.go)
- [✅] Flush 流程 (异步)
- [✅] mmap 查询 (sst/reader.go)
- [✅] mmap 查询 (sstable.go)
```
### Phase 2: 优化和稳定 ✅ 已完成
@@ -721,9 +701,9 @@ Flush 流程 (后台):
- [✅] 批量写入优化
- [✅] 并发控制优化
- [✅] 崩溃恢复 (WAL 重放)
- [✅] MANIFEST 管理 (manifest/)
- [✅] Compaction 实现 (compaction/)
- [✅] MemTable Manager (多版本管理)
- [✅] MANIFEST 管理 (version.go)
- [✅] Compaction 实现 (compaction.go)
- [✅] MemTable Manager (多版本管理，table.go)
- [✅] 性能测试 (各种 *_test.go)
- [✅] 文档完善 (README.md, DESIGN.md)
```
@@ -733,14 +713,15 @@ Flush 流程 (后台):
```
高级功能:
- [✅] 数据库和表管理 (database.go, table.go)
- [✅] Schema 系统 (schema/)
- [✅] 二级索引 (index/)
- [✅] 查询构建器 (query/)
- [✅] Schema 系统 (schema.go，强制要求)
- [✅] 二级索引 (index.go, index_btree.go)
- [✅] 查询构建器 (query.go)
- [✅] 条件查询 (AND/OR/NOT)
- [✅] 字符串匹配 (Contains/StartsWith/EndsWith)
- [✅] 版本控制和自动修复
- [✅] 统计信息 (engine.Stats())
- [✅] 压缩和编码 (Snappy)
- [✅] 统计信息 (table.Stats())
- [✅] 二进制编码和序列化 (ROW1 格式)
- [✅] 统一错误处理 (errors.go)
```
### Phase 4: 示例和文档 ✅ 已完成
@@ -817,15 +798,15 @@ Flush 流程 (后台):
- 优势: 列裁剪，压缩率高
- 劣势: 实现复杂，Flush 慢
最终实现 (V3): 行式存储 + Snappy
- 优势: 实现简单，Flush 快
- 劣势: 压缩率稍低
最终实现 (V3): 行式存储 + 二进制格式
- 优势: 实现简单，Flush 快，紧凑高效
- 劣势: 相比列式压缩率稍低
权衡:
- 追求简单和快速实现
- 行式 + Snappy 已经有 50% 压缩率
- 二进制格式已经足够紧凑
- 满足大多数时序数据场景
- 如果未来需要，可以演进到列式
- 如果未来需要，可以演进到列式或添加压缩
```
### 为什么用 B+Tree 而不是 LSM Tree？
@@ -868,6 +849,33 @@ mmap 方式:
✅ OS 自动优化
```
### 为什么不使用压缩（Snappy/LZ4）？
```
压缩的优势:
- 减少磁盘空间
- 可能减少 I/O
压缩的劣势:
- CPU 开销（压缩/解压）
- 查询延迟增加
- mmap 零拷贝失效（需要先解压）
- 实现复杂度增加
最终决策: 不使用压缩
- 优先考虑查询性能
- 保持 mmap 零拷贝优势
- 二进制格式已经足够紧凑
- 现代存储成本较低
- 如果真需要压缩，可以在应用层或文件系统层实现
权衡:
✅ 查询延迟更低
✅ 实现更简单
✅ mmap 零拷贝有效
❌ 磁盘占用稍大
```
## 🎯 总结
SRDB 是一个功能完善的高性能 Append-Only 数据库引擎：
@@ -883,7 +891,7 @@ SRDB 是一个功能完善的高性能 Append-Only 数据库引擎：
**技术亮点:**
- 简洁的 MemTable 实现 (map + sorted slice)
- B+Tree 索引，4KB 节点对齐
- Snappy 压缩，50% 压缩率
- 高效的二进制编码格式
- 多版本 MemTable 管理
- 后台 Compaction
- 版本控制和自动修复
@@ -904,12 +912,8 @@ SRDB 是一个功能完善的高性能 Append-Only 数据库引擎：
- ❌ 传统 OLTP 系统
**项目成果:**
- 核心代码: 5399 行
- 测试代码: 2000+ 行
- 示例程序: 13 个完整示例
- 核心代码: ~13,000 行
- 测试代码: ~2,000+ 行
- 示例程序: 13+ 个完整示例
- 文档: 完善的设计和使用文档
- 性能: 达到设计目标
---
**项目已完成并可用于生产环境！** 🎉