前言
很多使用SQLite的开发者都会遇到一个疑惑:开启WAL(预写日志)模式后,程序正常退出,目录下依然残留 .db-wal 和 .db-shm 两个文件。不少人第一反应是数据库崩了、文件异常,甚至直接手动删除,结果引发数据丢失。本文讲清楚这两个文件是什么、什么时候会残留、以及安全的处理方案。
环境:SQLite 3.30+,默认WAL行为
一、三个文件分别是什么
当开启WAL模式后,数据库不再只有单个xxx.db主文件,会配套生成两个附属文件:
| 文件 | 作用 | 是否持久数据 |
|---|---|---|
| xxx.db | SQLite主数据库文件,存放已经Checkpoint合并完成的数据 | ✅ 核心数据 |
| xxx.db-wal | WAL预写日志,保存已提交但还没有合并进主库的数据变更 | ✅ 属于数据库一部分,删了丢数据 |
| xxx.db-shm | WAL共享内存索引文件,多连接并发读写时用来快速定位WAL内页,协调读写快照 | ❌ 临时索引,无持久数据 |
WAL核心原理
传统DELETE日志模式:修改数据时先写回滚日志,再直接修改主库;写阻塞读,并发差。
WAL模式:修改不直接写主库,新变更追加到wal文件。等到合适时机执行Checkpoint,把wal里的数据页回写到主db。
优势:读不阻塞写、写不阻塞读,并发能力大幅提升;减少频繁fsync,写入性能更好
开启语句:
二、为什么程序关闭后,wal、shm还在?
很多文档说:最后一个连接关闭时会自动Checkpoint并清理wal/shm。这个结论有前提条件,不满足就会残留。
常见原因
连接没有真正关闭(最高发)
程序异常崩溃、被强制kill、代码抛异常跳过close、连接池/ORM持有隐藏连接、线程残留连接。SQLite没有机会执行收尾Checkpoint和文件删除逻辑。Python、Java、Go很多ORM和数据库驱动都有这个坑:代码主流程走完,底层连接还没释放。
关闭的只是只读连接
只读连接关闭不会触发最终Checkpoint,也不会清理wal/shm。必须是读写连接作为最后一个连接关闭,才会尝试自动清理。自动Checkpoint是PASSIVE模式,不会强制合并
连接关闭时自动执行的是PASSIVE检查点:非阻塞,只合并没有被任何读快照占用的数据页。如果还有别的连接持有旧读快照,合并到一半就停止,wal文件保留。开启了持久化WAL配置
SQLITE_FCNTL_PERSIST_WAL:显式配置关闭连接后保留wal文件,用于流复制、增量同步场景。SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE:关闭连接时跳过Checkpoint。目录权限不足
Checkpoint执行成功,但进程没有删除文件权限,wal/shm残留。
✅ 重要结论:文件残留 ≠ 数据库损坏
下次打开数据库时,SQLite会自动读取wal完成恢复,shm自动重建。
❌ 高危操作:不要手动删除 .db-wal,wal内包含已经提交未入库的数据,删除直接丢数据;shm删掉一般不会损坏库,但也不建议手动操作。
三、手动安全合并与清理方案
方式1:sqlite3命令行操作(最常用)
直接打开数据库,手动执行FULL检查点,再退出:
执行后返回结果如下图:

busy, log, checkpointed 解释:
busy:1=还有读者占用,无法完全合并;0=无阻塞,合并完成
log:wal文件总页数
checkpointed:本次成功合并的页数
更强选项(谨慎使用)
⚠️ 限制:如果同时有其他进程打开数据库(哪怕只读),FULL也可能busy,无法清掉wal。
方式2:程序内控制
业务优雅退出流程参考:
停止所有写入请求
等待所有查询、读连接执行完毕并关闭
使用读写连接执行 FULL Checkpoint
再关闭最后一个连接
四、避坑
备份WAL数据库:不能只拷贝xxx.db,要么同时拷贝db+wal,要么优先使用SQLite内置
backupAPI备份NFS网络共享盘不适合WAL:shm共享内存机制无法跨机器,容易锁异常、损坏
想要切回传统回滚日志模式:
切换前建议先执行FULL checkpoint清空wal不要依赖进程退出自动回收连接来清理wal,必须显式close所有连接
五、总结
.db-wal 是未合并的事务日志,.db-shm 是并发快照索引;WAL文件残留大多是连接未释放、自动检查点非阻塞导致,属于正常现象,不等于数据库损坏。
日常开发记住两条底线:
不手动删wal;
需要彻底合并清理,在无其他连接占用的前提下执行
PRAGMA wal_checkpoint(FULL)。