Stoolap 持久化内幕:10分钟看懂 WAL 预写日志、崩溃恢复与崩溃安全机制

原创2026-10-13 23:10:021,985 阅读

Stoolap 持久化内幕:10分钟看懂 WAL 预写日志、崩溃恢复与崩溃安全机制

Stoolap 是一款用 Rust 编写的现代嵌入式 SQL 数据库(A Modern Embedded SQL Database written in Rust)。当你用 file:// 连接串打开它时,所有数据都靠 WAL 预写日志(Write-Ahead Log) 保护:先写日志、后改内存、再落冷数据。本文带你完整看懂 Stoolap 的持久化内幕——WAL 如何工作、断电后崩溃恢复怎么重放日志、以及各种极端崩溃场景下"零数据丢失"的崩溃安全(Crash Safety)机制是如何保证的。

Stoolap 高性能嵌入式 SQL 数据库:WAL 预写日志与崩溃恢复持久化架构概览

一、持久化三件套:WAL、冷 Volume、备份快照

Stoolap 的持久化层由三个组件构成,各司其职:

组件 角色 落盘时机
WAL 预写日志 记录所有变更,崩溃后的恢复依据 每次提交
冷 Volume(冷段) 不可变列式存储,存放封存的历史数据 后台 checkpoint 周期性 seal
备份快照(Snapshot) 手动/时点备份,用于灾难恢复 PRAGMA SNAPSHOT

一句话概括它的核心不变量:对任意一行数据,最新的来源永远获胜(Hot 覆盖 Cold,新的 Volume 覆盖旧的 Volume)。详细架构可见官方文档 persistence.md。

二、WAL 预写日志:每次提交的"保命符"

1. 提交顺序:先日志,后内存

一个事务提交时,Stoolap 严格按这个顺序执行:

  1. 变更先写入 WAL 文件;
  2. WAL 按 sync_mode 配置 fsync 到磁盘;
  3. 变更再应用到内存结构;
  4. 最后才向客户端确认提交完成。

这个顺序就是"预写"(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):

  1. 加载 manifest 与冷 Volume:读每张表的 manifest.bin 和冷段文件,拿到 checkpoint LSN 作为重放起点;
  2. (仅老版本迁移) 若存在 v0.3.7 的 snapshots/ 而无 volumes/,自动一次性迁移到 Volume 格式;
  3. 重放 WAL:从 checkpoint LSN 之后开始,走两阶段恢复——只应用已提交事务的条目;INSERT 若 row_id 已在冷段中则幂等跳过;
  4. 重建热索引:从恢复出的数据重建 BTree / Hash 等热索引;
  5. 同步自增计数器:保证 AUTO_INCREMENT 不与冷段中的最大 row_id 冲突;
  6. 恢复后 seal:若重放把大量行灌进了热缓冲,立刻封存进冷 volume 并持久化 manifest,避免所有查询被巨大的热缓冲拖慢;
  7. 开放服务:数据库就绪,对上层应用完全透明。

整个过程由 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 Studio 图形化界面:Open DB 打开持久化数据库、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 全部热数据,推荐保持

三个实用要点:

  1. WAL 会涨到下个 checkpoint 才截断——高写入场景盯一下磁盘水位;
  2. 热缓冲越大查询越慢——Stoolap 会在 seal 后自动把冷数据放进毫秒级可加载的列式 volume,大表建议让 hot_max_rows 触发提前 seal;
  3. 备份策略:维护前先 PRAGMA SNAPSHOT,冷备直接整目录拷贝,热备用文件系统快照(ZFS / LVM)。

写在最后

Stoolap 的持久化可以浓缩成三句话:

  • WAL 预写日志保证"提交即落盘",日志魔数 + 链式 LSN + CRC 让撕裂写入可被精确识别;
  • 崩溃恢复 = 加载冷 Volume → 两阶段重放 WAL → 重建索引与计数器 → 立即 seal,全自动且对应用透明;
  • 崩溃安全 = 原子 manifest 写入这一唯一状态跃迁点,使"崩前是准备、崩后是清理",六大崩溃场景全部零丢失,并由随机断电测试持续验证。

想深入源码,推荐从 wal_manager.rs(日志协议)与 engine.rs(恢复主流程)读起,架构全貌见 docs/_docs/architecture/persistence.md。

登录后查看全文
stoolap