Noxu DB：Berkeley DB Java Edition的Rust移植版

# noxu 来源: https://codeberg.org/gregburd/noxu ## Noxu DB - crates.io (https://crates.io/crates/noxu-db) - docs.rs (https://docs.rs/noxu-db) - license (https://codeberg.org/gregburd/noxu/src/branch/main/LICENSE) 一个嵌入式事务性键值数据库引擎，使用 Rust 编写。Noxu DB 提供 ACID 事务、日志结构 B+ 树、基于检查点的崩溃恢复以及可选的主-副本复制——所有这些都集成在单个库中，无需外部数据库进程。 ## 快速开始 `` use noxu_db::{Environment, EnvironmentConfig, DatabaseConfig, DatabaseEntry, OperationStatus}; use std::path::PathBuf; fn main() -> noxu_db::Result<()> { // 打开一个环境 let env_config = EnvironmentConfig::new(PathBuf::from("/tmp/mydb")) .allow_create(true) .transactional(true); let env = Environment::open(env_config)?; // 打开一个数据库 let db_config = DatabaseConfig::new().allow_create(true); let db = env.open_database(None, "mydb", &db_config)?; // 插入一条记录 let key = DatabaseEntry::from_bytes(b"hello"); let value = DatabaseEntry::from_bytes(b"world"); db.put(None, &key, &value)?; // 读回来 let mut result = DatabaseEntry::new(); let status = db.get(None, &key, &mut result, None)?; assert_eq!(status, OperationStatus::Success); assert_eq!(result.data(), b"world"); // 使用事务获得 ACID 保证 let txn = env.begin_transaction(None, None)?; db.put(Some(&txn), &DatabaseEntry::from_bytes(b"key2"), &DatabaseEntry::from_bytes(b"val2"))?; txn.commit()?; // 用游标遍历 let mut cursor = db.open_cursor(None, None)?; let mut k = DatabaseEntry::new(); let mut v = DatabaseEntry::new(); while cursor.get_next(&mut k, &mut v, None)? == OperationStatus::Success { println!("{:?} => {:?}", k.data(), v.data()); } cursor.close()?; // 清理 db.close()?; env.close()?; Ok(()) } `` ## 特性 - **ACID 事务**——可序列化事务，记录级锁定和死锁检测。支持可配置的持久化策略。 - **B 树存储**——经典的 B+ 树，包含内部节点 (IN)、底层内部节点 (BIN) 和叶子节点 (LN)。键前缀编码和 BIN-delta 技术降低内存和 I/O 开销。 - **预写日志**——仅追加日志，带 CRC32 校验和、可配置的文件大小和内存映射 I/O。日志文件使用 `.ndb` 扩展名和十六进制命名（例如 `00000000.ndb`）。 - **崩溃恢复**——基于检查点的三阶段恢复：定位日志末尾、重建树、重放/撤销操作。通过定期检查点保证恢复时间有界。 - **缓存淘汰**——基于 LRU 的淘汰器，带有双优先级队列和按操作缓存模式控制（Default、KeepHot、EvictLn、EvictBin、MakeEvictable）。显式的内存预算跟踪。 - **日志清理**——后台垃圾回收过期日志条目，跟踪文件利用率并支持可配置阈值。 - **复制和高可用**——主-副本复制，支持自动选举、基于 VLSN 的日志流、网络恢复、主节点迁移以及可配置的一致性和持久化策略。 - **序列化绑定**——结构化数据的元组和条目绑定，包括派生宏的实体持久化（直接持久化层）。 - **集合视图**——基于迭代器的数据库集合抽象，支持排序映射和排序集合语义。 - **400+ 配置参数**——通过经过验证的、类型化的配置框架对每个子系统进行细粒度调优。 ## 工作空间结构 Noxu DB 组织为一个包含 16 个 crate 的 Cargo 工作空间： | Crate | 用途 | |-------|------| | `noxu-util` | LSN、VLSN、紧凑整数、统计信息、守护线程 | | `noxu-latch` | 独占锁和共享/独占锁（基于 `parking_lot`） | | `noxu-config` | 400+ 带有验证的类型化配置参数 | | `noxu-log` | 预写日志：文件管理器、日志管理器、条目 I/O | | `noxu-tree` | B+ 树：IN、BIN、LN、键前缀化、分裂 | | `noxu-txn` | 事务、记录级锁定、死锁检测 | | `noxu-evictor` | 带有内存预算的 LRU 缓存淘汰 | | `noxu-cleaner` | 日志文件垃圾回收、利用率跟踪 | | `noxu-recovery` | 基于检查点的崩溃恢复 | | `noxu-dbi` | 内部实现：EnvironmentImpl、DatabaseImpl、CursorImpl | | `noxu-engine` | 引擎编排、守护进程生命周期、环境打开/关闭 | | `noxu-db` | 公开 API：Environment、Database、Cursor、Transaction | | `noxu-bind` | 序列化绑定（元组、条目、流式） | | `noxu-collections` | 基于迭代器的数据库集合视图 | | `noxu-persist` | 派生宏的实体持久化 (DPL) | | `noxu-rep` | 主-副本高可用、选举、VLSN 跟踪 | ## 构建 `` cargo build # 构建所有 crate cargo test # 运行所有测试（2200+） cargo test -p noxu-db # 测试单个 crate cargo clippy # 代码检查 cargo fmt # 格式化 `` 需要 Rust 1.85+（2024 edition）。 ## 设计原则 - **正确性第一。** 算法和不变量严格按照其规范实现。与预期行为偏差即为错误。 - **地道 Rust。** RAII 锁、`Result` 错误处理、封闭层次结构的枚举、开放扩展点的 trait。 - **最少依赖。** 核心依赖：`parking_lot`、`thiserror`、`log`、`bytes`、`crc32fast`、`byteorder`、`memmap2`、`fs2`。 - **无 unsafe。** 核心 crate 的目标是零 `unsafe`。仅在内存映射 I/O 和堆外缓存场景允许例外。 - **无 async。** 核心引擎使用阻塞 I/O 并显式管理线程。仅复制网络可能使用 async。 - **自有日志格式。** Noxu DB 使用 Rust 原生的磁盘格式——`.ndb` 文件——不与任何其他数据库兼容。 ## 致谢 Noxu DB 的架构借鉴了跨越数十年的嵌入式数据库设计的研究和工程成果。B+ 树配合预写日志和检查点恢复遵循嵌入式数据库文献中确立的结构。记录管理的日志结构方法、BIN-delta 写入优化以及内存预算记账模型源自已发表的事务性嵌入式存储技术。复制子系统实现了 Flexible Paxos 用于领导者选举（Howard, Malkhi, and Spiegelman, 2016）、Phi Accrual Failure Detector（Hayashibara et al., 2004）以及基于 VLSN 的日志流。自适应替换缓存策略（Megiddo and Modha, 2003）及其 CART 变体（Bansal and Modha, 2004）可作为可选的淘汰策略。Clock with Adaptive Replacement 策略参考了 Jiang 和 Zhang（2005）的工作。 ## 许可证 根据以下任一许可证进行许可： - Apache License, Version 2.0（LICENSE-APACHE (https://codeberg.org/gregburd/noxu/src/branch/main/LICENSE-APACHE) 或 http://www.apache.org/licenses/LICENSE-2.0） - MIT License（LICENSE-MIT (https://codeberg.org/gregburd/noxu/src/branch/main/LICENSE-MIT) 或 http://opensource.org/licenses/MIT）