transaction-correctness

事务正确性指南

Turso 专门使用 WAL（预写日志）模式。

文件：.db、.db-wal（没有 .db-shm——Turso 使用内存中的 WAL 索引）

WAL 机制

写入路径

1. 写入者将帧（页面数据）追加到 WAL 文件（顺序 I/O）
2. COMMIT = 头部中 db_size 非零的帧（标记事务结束）
3. 检查点完成前，原始 DB 保持不变

读取路径

1. 读取者获取读取标记（mxFrame = 最后一个有效的提交帧）
2. 对每个页面：检查 WAL 中截至 mxFrame 的内容，若未找到则回退到主 DB
3. 读取者在其读取标记处看到一致的快照

检查点

将 WAL 内容传回主 DB。

WAL grows → checkpoint triggered (default: 1000 pages) → pages copied to DB → WAL reused

检查点类型：

• PASSIVE：非阻塞，在活动读取者所需的页面处停止
• FULL：等待读取者，完成所有内容的检查点
• RESTART：类似 FULL，同时将 WAL 重置到开头
• TRUNCATE：类似 RESTART，同时将 WAL 文件截断为零长度

WAL 索引

SQLite 使用共享内存文件（-shm）存放 WAL 索引。Turso 不使用该文件——它使用内存数据结构（frame_cache 哈希映射、原子读取标记），因为不支持多进程访问。

并发规则

• 同一时间只有一个写入者
• 读取者不会阻塞写入者，写入者也不会阻塞读取者
• 检查点必须在活动读取者所需的页面处停止

恢复

崩溃时：

1. 第一个连接获取排他锁
2. 重放 WAL 中有效的提交
3. 释放锁，恢复正常操作

Turso 实现

关键文件：

• WAL 实现 - WAL 实现
• 页面管理、事务

连接私有与共享

每个连接私有：

• Pager - 页面缓存、脏页面、保存点、提交状态
• WalFile - 连接的快照视图：
  • max_frame / min_frame - 此连接快照的帧范围
  • max_frame_read_lock_index - 此连接持有的读取锁槽位
  • last_checksum - 滚动校验和状态

连接间共享：

• WalFileShared - 全局 WAL 状态：
  • frame_cache - 页面到帧的索引（替代 .shm 文件）
  • max_frame / nbackfills - 全局 WAL 进度
  • read_locks[5] - 读取标记槽位（内嵌帧值的 TursoRwLock）
  • write_lock - 排他写入者锁
  • checkpoint_lock - 检查点串行化锁
  • file - WAL 文件句柄
• DatabaseStorage - 主 .db 文件
• BufferPool - 共享内存分配

正确性不变式

1. 持久性：返回成功前，COMMIT 记录必须完成 fsync
2. 原子性：部分事务对读取者始终不可见
3. 隔离性：每个读取者看到一致的快照
4. 不丢失更新：检查点不能覆盖未提交的更改

参考资料

• SQLite WAL
• WAL 文件格式