SQLite WAL模式:db-wal、db-shm文件残留问题详解

前言

很多使用SQLite的开发者都会遇到一个疑惑:开启WAL(预写日志)模式后,程序正常退出,目录下依然残留 .db-wal 和 .db-shm 两个文件。不少人第一反应是数据库崩了、文件异常,甚至直接手动删除,结果引发数据丢失。本文讲清楚这两个文件是什么、什么时候会残留、以及安全的处理方案。

环境:SQLite 3.30+,默认WAL行为

一、三个文件分别是什么

当开启WAL模式后,数据库不再只有单个xxx.db主文件,会配套生成两个附属文件:

文件作用是否持久数据
xxx.dbSQLite主数据库文件,存放已经Checkpoint合并完成的数据✅ 核心数据
xxx.db-walWAL预写日志,保存已提交但还没有合并进主库的数据变更✅ 属于数据库一部分,删了丢数据
xxx.db-shmWAL共享内存索引文件,多连接并发读写时用来快速定位WAL内页,协调读写快照❌ 临时索引,无持久数据

WAL核心原理

传统DELETE日志模式:修改数据时先写回滚日志,再直接修改主库;写阻塞读,并发差。
WAL模式:修改不直接写主库,新变更追加到wal文件。等到合适时机执行Checkpoint,把wal里的数据页回写到主db。

  • 优势:读不阻塞写、写不阻塞读,并发能力大幅提升;减少频繁fsync,写入性能更好

  • 开启语句:

    PRAGMA journal_mode=WAL;

二、为什么程序关闭后,wal、shm还在?

很多文档说:最后一个连接关闭时会自动Checkpoint并清理wal/shm。这个结论有前提条件,不满足就会残留。

常见原因

  1. 连接没有真正关闭(最高发)
    程序异常崩溃、被强制kill、代码抛异常跳过close、连接池/ORM持有隐藏连接、线程残留连接。SQLite没有机会执行收尾Checkpoint和文件删除逻辑。

    Python、Java、Go很多ORM和数据库驱动都有这个坑:代码主流程走完,底层连接还没释放。


  2. 关闭的只是只读连接
    只读连接关闭不会触发最终Checkpoint,也不会清理wal/shm。必须是读写连接作为最后一个连接关闭,才会尝试自动清理。

  3. 自动Checkpoint是PASSIVE模式,不会强制合并
    连接关闭时自动执行的是 PASSIVE 检查点:非阻塞,只合并没有被任何读快照占用的数据页。如果还有别的连接持有旧读快照,合并到一半就停止,wal文件保留。

  4. 开启了持久化WAL配置
    SQLITE_FCNTL_PERSIST_WAL:显式配置关闭连接后保留wal文件,用于流复制、增量同步场景。
    SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE:关闭连接时跳过Checkpoint。

  5. 目录权限不足
    Checkpoint执行成功,但进程没有删除文件权限,wal/shm残留。

✅ 重要结论:文件残留 ≠ 数据库损坏
下次打开数据库时,SQLite会自动读取wal完成恢复,shm自动重建。
❌ 高危操作:不要手动删除 .db-wal,wal内包含已经提交未入库的数据,删除直接丢数据;shm删掉一般不会损坏库,但也不建议手动操作。

三、手动安全合并与清理方案

方式1:sqlite3命令行操作(最常用)

直接打开数据库,手动执行FULL检查点,再退出:

sqlite3 test.db
-- FULL:等待读者释放快照,尽可能完成全部合并
PRAGMA wal_checkpoint(FULL);
.exit

执行后返回结果如下图:

image.png

busy, log, checkpointed 解释:

  • busy:1=还有读者占用,无法完全合并;0=无阻塞,合并完成

  • log:wal文件总页数

  • checkpointed:本次成功合并的页数

更强选项(谨慎使用)

-- RESTART:阻止新写入,全力完成检查点,适合维护窗口,业务高峰期不要用
PRAGMA wal_checkpoint(RESTART);

⚠️ 限制:如果同时有其他进程打开数据库(哪怕只读),FULL也可能busy,无法清掉wal。

方式2:程序内控制

业务优雅退出流程参考:

  1. 停止所有写入请求

  2. 等待所有查询、读连接执行完毕并关闭

  3. 使用读写连接执行 FULL Checkpoint

  4. 再关闭最后一个连接

四、避坑

  1. 备份WAL数据库:不能只拷贝xxx.db,要么同时拷贝db+wal,要么优先使用SQLite内置backup API备份

  2. NFS网络共享盘不适合WAL:shm共享内存机制无法跨机器,容易锁异常、损坏

  3. 想要切回传统回滚日志模式:

    PRAGMA journal_mode=DELETE;

    切换前建议先执行FULL checkpoint清空wal

  4. 不要依赖进程退出自动回收连接来清理wal,必须显式close所有连接

五、总结

.db-wal 是未合并的事务日志,.db-shm 是并发快照索引;WAL文件残留大多是连接未释放、自动检查点非阻塞导致,属于正常现象,不等于数据库损坏。
日常开发记住两条底线:

  • 不手动删wal;

  • 需要彻底合并清理,在无其他连接占用的前提下执行 PRAGMA wal_checkpoint(FULL)。