TurboKV: Insanely fast Rust key-value store
TurboKV: Insanely fast Rust key-value store
TurboKV：极速 Rust 键值存储
A fast, embedded key-value store in Rust TurboKV is an async embedded key-value database with atomic batches, ordered range scans, configurable durability, compression, and background compaction. TurboKV 是一个用 Rust 编写的快速嵌入式键值数据库，支持异步操作、原子批处理、有序范围扫描、可配置的持久性、压缩以及后台压缩（compaction）功能。
Installation cargo add turbokv cargo add tokio —features full Or add the dependencies directly: [dependencies] turbokv = “0.6” tokio = { version = “1”, features = [“full”] }
安装方式：运行 cargo add turbokv 和 cargo add tokio --features full，或者直接在 Cargo.toml 中添加依赖：[dependencies] turbokv = "0.6" 和 tokio = { version = "1", features = ["full"] }。
TurboKV’s persisted Bloom-filter format uses hardware AES. Build x86/x86_64 targets with RUSTFLAGS=“-C target-feature=+aes,+sse2”, and ARM/AArch64 targets with RUSTFLAGS=“-C target-feature=+aes,+neon”. You may instead use -C target-cpu=native when the binary will run only on the same CPU model or a feature superset.
TurboKV 的持久化布隆过滤器（Bloom-filter）格式使用硬件 AES 加速。构建 x86/x86_64 目标时请使用 RUSTFLAGS="-C target-feature=+aes,+sse2"，构建 ARM/AArch64 目标时请使用 RUSTFLAGS="-C target-feature=+aes,+neon"。如果二进制文件仅在相同 CPU 型号或其超集上运行，也可以使用 -C target-cpu=native。
Quick start use turbokv::{Db, DbOptions, WriteBatch}; #[tokio::main] async fn main() -> Result<(), Box
use turbokv::{Db, DbOptions, WriteBatch};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let db = Db::open_with_options("./my-database", DbOptions::durable()).await?;
db.insert(b"user:1", b"Ada").await?;
assert_eq!(db.get(b"user:1").await?, Some(b"Ada".to_vec()));
let mut batch = WriteBatch::new();
batch.put(b"user:2", b"Grace");
batch.put(b"user:3", b"Linus");
batch.delete(b"user:1");
db.write_batch(&batch).await?;
for (key, value) in db.scan_prefix(b"user:").await? {
println!("{} = {}", String::from_utf8_lossy(&key), String::from_utf8_lossy(&value));
}
db.close().await?;
Ok(())
}Runnable examples: basic: insert, get, update, and remove; batch_writes: atomic puts and deletes; range_queries: ordered range and prefix scans; concurrent: shared access from Tokio tasks; persistence: paranoid WAL recovery; configuration: cache, memtable, and compression options.
可运行示例包括：basic（插入、获取、更新和删除）、batch_writes（原子写入和删除）、range_queries（有序范围和前缀扫描）、concurrent（来自 Tokio 任务的共享访问）、persistence（严格的 WAL 恢复）、configuration（缓存、内存表和压缩选项）。
API breakdown Durability presets: API 解析：持久性预设
| Preset | Acknowledgement boundary | Use case |
|---|---|---|
| DbOptions::fast() | In-memory visibility; no WAL | Caches and reproducible data |
| DbOptions::durable() | Appended to the WAL without a per-write sync | Process-crash recovery with periodic power-loss checkpoints; recommended default |
| DbOptions::paranoid() | WAL group completed sync_all before return | Strongest mode, subject to filesystem/device guarantees |
| 预设 | 确认边界 | 使用场景 |
|---|---|---|
| DbOptions::fast() | 内存可见；无 WAL | 缓存和可重现数据 |
| DbOptions::durable() | 追加到 WAL，无需每次写入同步 | 进程崩溃恢复，带有周期性断电检查点；推荐默认值 |
| DbOptions::paranoid() | 返回前完成 WAL 组的 sync_all | 最强模式，受限于文件系统/设备保证 |
Durable does not leave the WAL unsynchronized forever. A successful explicit or background memtable flush and a clean close synchronize it; rotating a full WAL segment also synchronizes the finalized segment. Durable 模式不会让 WAL 永远处于未同步状态。成功的显式或后台内存表（memtable）刷新以及正常关闭都会同步它；轮转已满的 WAL 段也会同步已完成的段。
With the defaults, the memtable rotates at approximately 64 MiB, the background task checks for immutable memtables every 60 seconds, and a WAL segment rotates at 1 GiB. These checkpoints let older writes survive a power loss when the filesystem and device honor the sync, but they do not impose an exact 64 MiB loss bound: flush is asynchronous, memory accounting is approximate, and a large mutation can cross a threshold. 默认情况下，内存表大约在 64 MiB 时轮转，后台任务每 60 秒检查一次不可变内存表，WAL 段在 1 GiB 时轮转。当文件系统和设备遵循同步要求时，这些检查点允许旧的写入在断电后幸存，但它们并不强制要求精确的 64 MiB 丢失界限：刷新是异步的，内存计算是近似的，且大型变更可能会跨越阈值。
Use Paranoid when every successful acknowledgement must cross a storage sync barrier. One open Db or Engine exclusively owns its data directory. Use close() or close_with_status() for a clean shutdown; dropping a handle is not a clean shutdown contract.
当每次成功的确认都必须跨越存储同步屏障时，请使用 Paranoid 模式。一个打开的 Db 或 Engine 独占其数据目录。请使用 close() 或 close_with_status() 进行正常关闭；丢弃句柄（dropping a handle）并不构成正常关闭的契约。
Database operations: Keys and values are arbitrary byte sequences supplied through AsRef<[u8]>; strings need to be encoded by the caller. Mutation APIs copy their inputs before returning. Point and collecting reads return owned VecAsRef<[u8]> 提供的任意字节序列；字符串需要由调用者进行编码。变更 API 在返回前会复制其输入。点查询和集合读取返回拥有的 Vec<u8> 值。空值是有效数据，与已删除的键不同。
Opening and configuration API: 打开与配置 API：
| Parameters | Result and behavior |
|---|---|
| Db::open(path) | Opens or creates the directory with DbOptions::durable(). The open handle exclusively owns the directory. |
| Db::open_with_options(path, options) | Opens with explicit durability, memory, cache, and compression settings. Rejects contradictory settings such as sync_writes = true with the WAL disabled. |
| DbOptions::fast() | Returns the no-WAL preset. |
| DbOptions::durable() | Returns the process-crash-recoverable WAL preset. |
| DbOptions::paranoid() | Returns the sync-before-acknowledgement preset. |
| options.with_compression(compression) | Builder-style update that returns the modified options. |
| 参数 | 结果与行为 |
|---|---|
| Db::open(path) | 使用 DbOptions::durable() 打开或创建目录。打开的句柄独占该目录。 |
| Db::open_with_options(path, options) | 使用显式的持久性、内存、缓存和压缩设置打开。拒绝矛盾的设置（例如在禁用 WAL 时设置 sync_writes = true）。 |
| DbOptions::fast() | 返回无 WAL 预设。 |
| DbOptions::durable() | 返回可进程崩溃恢复的 WAL 预设。 |
| DbOptions::paranoid() | 返回同步前确认的预设。 |
| options.with_compression(compression) | 构建器风格的更新，返回修改后的选项。 |
All presets start with a 64 MiB memtable, a 64 MiB block cache, and LZ4 compression. Their public fields can be adjusted before opening: 所有预设均以 64 MiB 内存表、64 MiB 块缓存和 LZ4 压缩启动。它们的公共字段可以在打开前进行调整：
wal_enabled: bool: Append mutations to the WAL. Disabling it permits process-crash data loss until a successful flush or close. (将变更追加到 WAL。禁用它可能导致进程崩溃时的数据丢失，直到成功刷新或关闭。)sync_writes: bool: Await a WAL sync barrier before acknowledging each mutation group. Requires wal_enabled. (在确认每个变更组之前等待 WAL 同步屏障。需要开启 wal_enabled。)memtable_size: usize: Approximate in-memory byte threshold that triggers a memtable rotation and background flush. (触发内存表轮转和后台刷新的近似内存字节阈值。)block_cache_size: usize: Decompressed SSTable block-cache budget in bytes. Set to 0 to disable the cache. (解压后的 SSTable 块缓存预算，单位为字节。设置为 0 可禁用缓存。)compression: Compression: SSTable compression for newly written data: Lz4, Snappy, Zstd, or None. Existing tables retain their encoded format. (新写入数据的 SSTable 压缩方式：Lz4、Snappy、Zstd 或 None。现有表保留其编码格式。)
Point, bulk, and batch operations: 点操作、批量操作和批处理操作：
insert(key, value): Inserts or replaces the key. The selected durability boundary is reached before success. (插入或替换键。在成功前达到选定的持久性边界。)insert_many(entries): Copies the full iterator and applies entries in order; the last duplicate key wins. This is a bulk API, not one atomic visibility transition. (复制完整迭代器并按顺序应用条目；最后一个重复键生效。这是一个批量 API，而非原子可见性转换。)get(key): Returns None for missing or deleted keys and Some(Vec::new()) for a stored empty value. (对于缺失或已删除的键返回 None，对于存储的空值返回 Some(Vec::new())。)remove(key): Writes a tombstone; deleting a missing key is allowed. (写入墓碑；允许删除缺失的键。)take(key): Atomically returns and removes the latest value; a missing key returns None without writing a tombstone. It serializes mutations while resolving the value. (原子地返回并移除最新值；缺失的键返回 None 且不写入墓碑。它在解析值时序列化变更。)contains_key(key): Resolves the same state as get and currently incurs its value allocation. (解析与 get 相同的状态，目前会产生值分配。)write_batch(batch): Publishes all operations atomically; readers see either the state before the batch or the complete batch. The last operation for a duplicate key wins. With the WAL enabled, one record or complete batch must fit in the WAL’s u32 payload length. (原子地发布所有操作；读取者要么看到批处理前的状态，要么看到完整的批处理。重复键的最后一个操作生效。启用 WAL 后，单条记录或完整批处理必须适合 WAL 的 u32 有效载荷长度。)