权衡 SQLite WAL 增长与 Litestream 检查点阻塞-未完纪

原文标题： WAL Truncate Threshold Configuration
作者： Litestream 文档贡献者（原页面未署个人名；作者信息据候选记录）
来源： Litestream 官方指南
原文日期： 原页面未注明

SQLite 使用预写日志（WAL）记录数据库页的改动。检查点会把 WAL 中的已提交内容写回数据库文件；如果长期没有适当的检查点，WAL 会继续增长。问题在于，最彻底的截断可能要等待正在读写的事务结束。对长查询、报表或导出任务来说，这可能意味着写入延迟。

Litestream 的这份指南介绍三种互补的检查点触发条件：按页数触发的紧急截断、较频繁的被动检查点，以及按时间触发的被动检查点。它们分别处理 WAL 增长上限、常规清理和周期性整理。

三种检查点条件

1. 紧急截断阈值：`truncate-page-n`

指南给出的默认值是 121359 页，标注约为 500 MB。超过该页数后，Litestream 会优先尝试 PASSIVE 检查点；如果无法让同步偏移回到阈值以下，则可能改为强制 TRUNCATE。强制截断会等待活跃读者和写入者完成，因此可能阻塞两类事务。它的角色是防止 WAL 持续失控增长，而不是日常优先执行的清理。

约 500 MB 是指南对页数的近似换算，不是所有数据库都适用的硬上限。实际字节数会受 SQLite 页大小等条件影响；有时数据库逻辑上已重启 WAL，磁盘上的 -wal 文件仍保留曾达到的高水位大小。

页面对被动优先行为标注了 v0.5.15：跨过阈值时先执行 PASSIVE，若 WAL 被重启且同步偏移降到阈值以下，就跳过阻塞式 TRUNCATE 及其边界快照。候选记录指出，这个行为尚未独立确认其发布范围，因此不要把它当成所有 0.5.x 安装都必然具备的行为。配置前应核对实际运行的 Litestream 版本和对应文档。

2. 页数触发的被动检查点

min-checkpoint-page-count 默认是 1000 页，指南粗略标为约 4 MB。超过阈值会尝试 SQLite 的 PASSIVE 检查点。它不会等待活跃读写事务结束；遇到忙碌状态时可能返回 SQLITE_BUSY，Litestream 记录跳过并继续运行。它用于平时控制 WAL 体量，不负责强制截断文件。

3. 时间触发的被动检查点

checkpoint-interval 默认是 1m。距离上次尝试达到间隔后，Litestream 会再尝试一次 PASSIVE 检查点；只有 WAL 至少有一页时才触发。它同样不等待活动事务结束。

文档中的一组配置如下：

dbs:
  - path: /path/to/db
    min-checkpoint-page-count: 1000
    checkpoint-interval: 1m
    truncate-page-n: 121359
    replicas:
      - url: s3://mybucket/db

从 Litestream v0.5.0 起，配置字段 max-checkpoint-page-count 被 truncate-page-n 取代。若旧配置还包含前者，应按正在使用的版本文档迁移字段；不要原样复制已失效的旧键。

怎样选择阻塞与磁盘空间的取舍

默认保留三种条件，适合读写事务通常较短的应用：被动检查点负责日常清理，较高的截断阈值为异常增长留一道保护。代价是，如果 WAL 到达紧急阈值而被动检查点无法将它降下来，强制 TRUNCATE 可能等待长读事务并暂停写入。

如果应用会持续数分钟甚至数小时地读数据，例如分析查询、批处理读取、复杂报表或数据导出，可以考虑把 truncate-page-n 设为 0，避免 Litestream 触发这类强制截断：

dbs:
  - path: /path/to/db
    min-checkpoint-page-count: 1000
    checkpoint-interval: 1m
    truncate-page-n: 0

这并不意味着 WAL 会自动变小，也不能保证系统在任何情况下都绝不阻塞或写入永不失败。长读事务可能阻止检查点前进，WAL 因此持续增长；磁盘空间耗尽仍然会造成故障，WAL 变大也会拖慢恢复并增加存储消耗。选择这一配置时，应同时监控 WAL 与磁盘空间，安排长读事务的停止或收敛方式，并为最坏情况预留容量。

只有在应用自行管理检查点、并且有外部增长监控时，才考虑同时禁用时间和紧急检查点：

dbs:
  - path: /path/to/db
    checkpoint-interval: 0
    truncate-page-n: 0

min-checkpoint-page-count 不能设为 0，它至少为 1；因此页数触发的被动检查点仍然启用。

观察 WAL 增长和写入阻塞

WAL 文件持续增大、磁盘空间告警和恢复变慢，都是增长失控的迹象。可以先观察文件大小；若可直接使用 SQLite，也可以请求一次被动检查点并查看返回信息：

ls -lh /path/to/db-wal
sqlite3 /path/to/db "PRAGMA wal_checkpoint(PASSIVE);"

若应用出现写入超时、database is locked 错误或写入延迟上升，应进一步查看 Litestream 日志。跨过阈值后，下面两种记录含义不同：

wal restarted by passive checkpoint, skipping truncate checkpoint wal_size=... threshold=...
forcing truncate checkpoint wal_size=... threshold=...

第一条表示被动检查点成功把同步偏移降到了阈值以下，因而跳过阻塞式截断；第二条表示仍需强制 TRUNCATE，这才是可能等待活跃读者和写入者、造成写入停顿的检查点。长读事务是常见原因之一。可以提高 truncate-page-n、禁用强制截断，或从应用侧缩短读事务及长查询时长；这几种选择分别把成本转移到更大的 WAL、磁盘监控或应用改造上。

升级配置后，指南建议检查检查点日志并定期观察 WAL 文件大小：

tail -f /var/log/litestream.log | grep checkpoint
watch -n 5 'ls -lh /path/to/db-wal'

候选记录还提示，若采用 synchronous=NORMAL，需要接受掉电时持久性方面的取舍；busy_timeout、foreign_keys 等 SQLite 选项要逐连接设置。多个复制器同时写向同一个目标可能破坏恢复链。这些是配置边界提示，不构成对任何生产环境的验证；修改前先记录原有设置、监控基线与回退方式。

来源： WAL Truncate Threshold Configuration — Litestream
作者： Litestream 文档贡献者（原页面未署个人名）
转载许可： 原页面未注明本文的转载许可信息。

文章版权归作者所有，未经允许请勿转载。

THE END