Stoolap 持久化内幕:10分钟看懂 WAL 预写日志、崩溃恢复与崩溃安全机制
Stoolap 持久化内幕:10分钟看懂 WAL 预写日志、崩溃恢复与崩溃安全机制
Stoolap 是一款用 Rust 编写的现代嵌入式 SQL 数据库(A Modern Embedded SQL Database written in Rust)。当你用 file:// 连接串打开它时,所有数据都靠 WAL 预写日志(Write-Ahead Log) 保护:先写日志、后改内存、再落冷数据。本文带你完整看懂 Stoolap 的持久化内幕——WAL 如何工作、断电后崩溃恢复怎么重放日志、以及各种极端崩溃场景下"零数据丢失"的崩溃安全(Crash Safety)机制是如何保证的。
一、持久化三件套:WAL、冷 Volume、备份快照
Stoolap 的持久化层由三个组件构成,各司其职:
| 组件 | 角色 | 落盘时机 |
|---|---|---|
| WAL 预写日志 | 记录所有变更,崩溃后的恢复依据 | 每次提交 |
| 冷 Volume(冷段) | 不可变列式存储,存放封存的历史数据 | 后台 checkpoint 周期性 seal |
| 备份快照(Snapshot) | 手动/时点备份,用于灾难恢复 | PRAGMA SNAPSHOT |
一句话概括它的核心不变量:对任意一行数据,最新的来源永远获胜(Hot 覆盖 Cold,新的 Volume 覆盖旧的 Volume)。详细架构可见官方文档 persistence.md。
二、WAL 预写日志:每次提交的"保命符"
1. 提交顺序:先日志,后内存
一个事务提交时,Stoolap 严格按这个顺序执行:
- 变更先写入 WAL 文件;
- WAL 按
sync_mode配置 fsync 到磁盘; - 变更再应用到内存结构;
- 最后才向客户端确认提交完成。
这个顺序就是"预写"(Write-Ahead)的含义——只要事务拿到了成功回执,对应的日志必然已经在磁盘上,所以已提交事务永远不会因崩溃丢失。
2. WAL 记录哪些操作
不仅 DML,DDL 也会记入日志:INSERT / UPDATE / DELETE / TRUNCATE,以及 CREATE TABLE、DROP TABLE、CREATE INDEX、ALTER TABLE、CREATE VIEW 等。因此恢复时连表结构和索引定义都能重建,而不仅仅是数据。
3. 日志条目的二进制格式:为"写到一半"而生
WAL 每条日志(wal_manager.rs 中定义)都以 4 字节魔数 WALE 开头,后跟 32 字节扩展头(版本号、标志位、LSN、上一条 LSN 链、载荷长度),结尾再挂一个 CRC32 校验:
┌─────────────────────────────────────────┐
│ Magic "WALE" │ Version │ Flags │ LSN │ Prev LSN │ Entry Size │ ... │ CRC32 │
└─────────────────────────────────────────┘
魔数 + 链式 LSN + CRC 的组合,让恢复器能精确定位"哪一条日志是完整的、哪一条被截断了"。事务级别还有专门的 COMMIT_MARKER / ABORT_MARKER 标志位(见 persistence.rs 的 record_commit),构成两阶段恢复:先扫描一遍日志标记哪些事务已提交,再只重放已提交事务的条目,未提交的一律丢弃。
4. 三种 sync_mode:耐久性与吞吐的权衡
通过连接串选择,打开数据库时生效(源码常量与默认值见 wal_manager.rs):
file:///path/to/db?sync_mode=normal
| 模式 | 值 | 行为 | 崩溃时最大数据丢失 |
|---|---|---|---|
| None | 0 | 不 fsync,仅写入 OS 页缓存,靠下个 checkpoint(默认 60s)封存落盘 | 约 60 秒 |
| Normal(推荐) | 1 | 每秒最多 fsync 一次 WAL,DDL 时强制 fsync,类似 SQLite 的 synchronous=NORMAL |
约 1 秒 |
| Full | 2 | 每次写 WAL 都 fsync,耐久最高、吞吐最低 | 0,零丢失 |
运行时可以用 PRAGMA sync_mode; 查询当前值。开发测试选 0,一般业务选 1,资金类关键数据选 2。
三、目录结构:一个 Stoolap 数据库长什么样
启用持久化后,数据库目录下会自动生成这套结构:
/path/to/database/
db.lock # 文件锁,防止多进程并发打开
wal/
wal_000001.log # WAL 日志段(写满 64MB 自动轮转)
checkpoint.meta # WAL 截断元数据
volumes/
table_name/
vol_XXXXXXXX.vol # 封存的冷段(列式、CRC32 校验)
manifest.bin # 段清单:volume 列表、墓碑、checkpoint LSN
snapshots/ # PRAGMA SNAPSHOT 产生的备份
table_name/snapshot-TIMESTAMP.bin
WAL 文件会持续增长,直到 checkpoint 把所有热数据 seal 进 volume 并原子持久化 manifest.bin 后,才会截断旧日志——截断永远发生在确认落盘之后。
四、崩溃恢复:重新打开数据库时的 7 步重放
崩溃后无需任何手动修复,Database::open("file:///...") 会自动触发恢复(入口在 engine.rs 的 open_engine):
- 加载 manifest 与冷 Volume:读每张表的
manifest.bin和冷段文件,拿到 checkpoint LSN 作为重放起点; - (仅老版本迁移) 若存在 v0.3.7 的
snapshots/而无volumes/,自动一次性迁移到 Volume 格式; - 重放 WAL:从 checkpoint LSN 之后开始,走两阶段恢复——只应用已提交事务的条目;
INSERT若 row_id 已在冷段中则幂等跳过; - 重建热索引:从恢复出的数据重建 BTree / Hash 等热索引;
- 同步自增计数器:保证 AUTO_INCREMENT 不与冷段中的最大 row_id 冲突;
- 恢复后 seal:若重放把大量行灌进了热缓冲,立刻封存进冷 volume 并持久化 manifest,避免所有查询被巨大的热缓冲拖慢;
- 开放服务:数据库就绪,对上层应用完全透明。
整个过程由 persistence.rs 的 replay_two_phase 驱动,应用无需感知任何"恢复中"状态。
五、崩溃安全设计:无论崩在哪一步,都不丢数据
Stoolap 的崩溃安全建立在一个关键设计上:manifest 的原子写入(fsync 后 rename)是唯一的状态跃迁点。它之前的操作都是"准备工作"(崩了就丢弃重来),之后的操作都是"清理工作"(可以重复执行)。
| 崩溃时机 | 恢复方式 | 数据丢失 |
|---|---|---|
| DML 执行中崩溃 | WAL 重放 | 无 |
| checkpoint 中、manifest 写入前崩溃 | 用旧 manifest,WAL 全量重放 | 无 |
| manifest 写入过程中崩溃 | 原子 rename:要么旧、要么新 | 无 |
| manifest 已写、WAL 未截断时崩溃 | Volume + 冗余 WAL,幂等重放 | 无 |
| compaction 中、manifest 前崩溃 | 旧 volume 原封不动 | 无 |
| compaction manifest 之后崩溃 | 新 volume 生效,旧文件成为孤儿被清理 | 无 |
另外,PRAGMA CHECKPOINT 截断 WAL 前会先把 checkpoint LSN 之后的 DDL 重新记录一遍,确保表结构不因日志截断而消失——这是"只丢数据不丢结构"防线上的最后一环。
六、崩溃安全不是纸上谈兵:测试如何随机"杀死"数据库
光有设计不够,Stoolap 用测试把崩溃场景真实打出来:
- tests/crash_soak_test.rs:崩溃浸泡测试。随机跑写入负载后,在 WAL 文件的随机字节偏移处截断(模拟写一半断电),然后验证恢复不变量——数据库能打开、行数非负、无主键重复、索引查询与全表扫描一致;
- tests/wal_torn_tail_test.rs:撕裂尾部测试。模拟最后一条日志被崩溃拦腰切断,验证所有完整提交都能恢复,且后续多次重开数据库数据依然一致;
- 配套还有 wal_truncation_rotation_test.rs(WAL 轮转与截断)、failpoint_io_test.rs(IO 故障点注入)等回归保障。
这套"在任意字节位置断电再重启"的测试思路,正是嵌入式数据库最核心的正确性验证方式。
七、备份与恢复:WAL 之外的最后一道防线
WAL 保的是"不丢已提交数据",PRAGMA SNAPSHOT 保的是"可回滚到某个时点":
PRAGMA keep_snapshots = 3; -- 每张表保留 3 份备份(默认值)
PRAGMA SNAPSHOT; -- 手动创建全量备份
PRAGMA RESTORE; -- 恢复到最新备份
PRAGMA RESTORE = '20260315-100000.000'; -- 恢复到指定时点
快照会捕获全部表结构、全部已提交数据(热 + 冷),索引与视图定义单独存入 ddl-{timestamp}.bin。也可以在图形化的 Stoolap Studio 里一键 Backup / Restore:
命令行下同样支持:stoolap -d "file:///path/to/db" --snapshot 创建备份;若 volume 损坏,可加 --reset-volumes --restore 先清理再恢复。
⚠️ 注意 db.lock 锁文件故意不删除——它基于 OS 的 flock 保护 inode,删文件会引入竞态;进程崩溃后锁会在下次打开时自动释放。
八、实践建议:如何配置你的持久化参数
| 参数 | 默认值 | 建议 |
|---|---|---|
sync_mode |
normal (1) | 开发用 0,生产用 1,关键业务用 2 |
checkpoint_interval |
60 秒 | 高写入负载可调小:恢复更快,磁盘 IO 更多 |
compact_threshold |
4 | 冷段数量超过该值触发合并 compaction |
keep_snapshots |
3 | 按备份保留策略调整 |
checkpoint_on_close |
on | 正常关闭时强制 seal 全部热数据,推荐保持 |
三个实用要点:
- WAL 会涨到下个 checkpoint 才截断——高写入场景盯一下磁盘水位;
- 热缓冲越大查询越慢——Stoolap 会在 seal 后自动把冷数据放进毫秒级可加载的列式 volume,大表建议让
hot_max_rows触发提前 seal; - 备份策略:维护前先
PRAGMA SNAPSHOT,冷备直接整目录拷贝,热备用文件系统快照(ZFS / LVM)。
写在最后
Stoolap 的持久化可以浓缩成三句话:
- WAL 预写日志保证"提交即落盘",日志魔数 + 链式 LSN + CRC 让撕裂写入可被精确识别;
- 崩溃恢复 = 加载冷 Volume → 两阶段重放 WAL → 重建索引与计数器 → 立即 seal,全自动且对应用透明;
- 崩溃安全 = 原子 manifest 写入这一唯一状态跃迁点,使"崩前是准备、崩后是清理",六大崩溃场景全部零丢失,并由随机断电测试持续验证。
想深入源码,推荐从 wal_manager.rs(日志协议)与 engine.rs(恢复主流程)读起,架构全貌见 docs/_docs/architecture/persistence.md。

