ADR-001: 使用 redb 替代 SQLite

状态

已采纳

背景

CipherFS 需要一个嵌入式数据库来存储：

• 文件元数据（路径、大小、哈希等）
• 块索引
• 版本历史
• 操作日志

最初考虑使用 SQLite（行业标准），但在 Rust 生态中存在一些问题。

决策

使用 redb 作为元数据存储。

考虑的选项

1. SQLite

优点：

• 行业标准，久经考验
• 丰富的 SQL 查询能力
• 大量文档和社区支持

缺点：

• 需要 C 编译器和 FFI 绑定
• 跨平台编译复杂（尤其是 Android/iOS）
• rusqlite 绑定增加编译时间
• 多数据库分片方案复杂

2. sled

优点：

• 纯 Rust
• fetch_and_update 原子操作
• watch_prefix 订阅功能
• 并发写入支持

缺点：

• 内存占用较高
• 1.0 版本尚未发布
• 稳定性存疑

3. redb（选中）

优点：

• 纯 Rust，无 C 依赖
• 单文件存储
• ACID 事务保证
• 零拷贝读取，性能优秀
• API 简洁，类型安全
• 跨平台编译简单

缺点：

• 相对较新
• 单写多读（不支持并发写入）
• 无 SQL 查询能力

4. RocksDB / LMDB

优点：

• 性能极高
• 久经考验

缺点：

• 需要 C/C++ 依赖
• 配置复杂
• 过于重量级

理由

1. 纯 Rust 生态：项目目标是纯 Rust 实现，避免 C 依赖简化编译和跨平台支持
2. 单文件存储：便于备份、迁移和同步
3. ACID 事务：确保引用计数等操作的原子性
4. 足够的性能：对于元数据存储场景，redb 性能绰绰有余

后果

优点

• 编译简单，cargo build 即可
• 跨平台支持（Linux/macOS/Windows/Android/iOS）
• 单文件数据库，易于管理
• 跨表事务保证数据一致性

缺点

• 不支持并发写入（单写多读）
• 无 SQL 查询，复杂查询需要手动实现
• 社区相对较小

缓解措施

• 并发写入：通过应用层排队处理
• 复杂查询：设计合理的表结构和索引

相关文档

• [废弃] multi_database_sharding.md - SQLite 分片方案（已废弃）

仓库中的源文件