SQLite在事务提交时需要借助日志文件来保证原子性和崩溃恢复能力，而采用哪种方式来管理这些日志，就是由PRAGMA journal_mode决定的。这个看似简单的配置项，实际上直接影响数据库文件的形态、并发性能以及跨平台表现。很多开发者在遇到写入性能瓶颈或者并发读写冲突时，第一反应是优化SQL语句，却忽略了日志模式这个可以立竿见影的调优点。本文将系统讲解五种日志模式的原理、切换语法和实际使用中的坑。
一、journal_mode支持的五种模式详解
执行PRAGMA journal_mode;可以查看当前数据库的日志模式，默认值是delete模式。SQLite一共提供了五种日志模式，每种模式在事务回滚机制和文件处理方式上都有明显差异。
第一种是delete模式，也是默认模式。事务开始时创建回滚日志文件，事务提交后将日志文件直接删除。这种方式最通用，兼容性最好，但每次事务都会带来文件的创建和删除操作，频繁写入时性能开销不小。
第二种是truncate模式，与delete类似，区别在于提交事务时不是删除日志文件，而是将日志文件截断为零长度。这样可以避免反复创建删除文件带来的目录项更新，在某些文件系统上比delete略快。
第三种是persist模式，提交事务时不删除也不截断日志文件，而是把文件头部重写为零，表示日志内容失效。这种模式适合文件删除代价很高的场景，比如某些嵌入式设备或者NOR闪存文件系统。
第四种是memory模式，回滚日志完全保存在内存中，不产生磁盘文件。写入速度最快，但一旦程序崩溃或断电，数据库可能损坏，只能用于对数据完整性没有要求的临时数据。
第五种是wal模式，即Write-Ahead Logging，预写日志模式。它采用完全不同的机制：修改不直接写入主数据库文件，而是先追加到独立的wal文件中，读取时结合主文件和wal文件的内容返回结果。这是最值得深入研究的模式，下一节单独展开。
二、WAL模式的原理与并发优势
WAL模式的核心思想是“先写日志，后写数据”。传统模式是写主文件加回滚日志，而WAL模式把顺序反过来，所有新修改都追加写入wal文件，主数据库文件保持不动。当wal文件增长到一定阈值时，SQLite会执行checkpoint操作，把wal文件中的内容合并回主文件。
这种机制带来的最大好处是并发能力的提升。在delete模式下，写事务会持有排它锁，此时读操作完全被阻塞；而在WAL模式下，读操作读取主文件，写操作追加wal文件，两者互不干扰，实现了“读不阻塞写、写不阻塞读”。对于多线程访问或者读写混合频繁的应用，这个特性可以带来数倍的性能提升。
启用WAL模式的命令如下：
-- 切换到WAL模式 PRAGMA journal_mode = WAL; -- 查询当前模式，返回 wal 表示设置成功 PRAGMA journal_mode;
需要注意两点：第一，WAL模式是持久化的，设置一次后数据库文件会记住这个状态，后续连接默认就是WAL模式，不需要每次都设置。第二，WAL模式下会产生额外的-wal和-shm文件，备份数据库时必须一并处理，或者先执行PRAGMA wal_checkpoint(TRUNCATE);合并日志后再备份主文件。
三、切换模式的注意事项与常见问题
切换日志模式并非在任意时刻都能成功。如果当前有活跃的事务持有锁，切换请求会失败并维持原模式。因此建议在建立连接后、执行任何业务SQL之前完成模式设置。另外，memory模式和wal模式之间不能直接切换，必须先切回delete或truncate作为过渡。
关于模式的持久性也要区分清楚：只有wal模式是持久化保存在数据库文件中的，其他四种模式都属于连接级别的设置，每个新连接都需要重新执行对应的PRAGMA语句。这一点在实际项目中经常被忽视，导致开发者以为设置了truncate模式就全局生效，结果新连接又回到了默认的delete模式。
还有一个常见场景是错误代码处理。切换wal模式失败的典型原因包括：数据库文件位于网络文件系统上（如NFS），WAL依赖的共享内存机制在这种环境下不可靠；数据库是内存数据库（:memory:），根本没有持久化日志的需求；最后一个连接异常退出后-shm文件残留，此时新连接通常会自动恢复，但如果文件系统权限有问题就会失败。下面是一段Python示例，展示如何安全地设置WAL模式并处理返回值：
import sqlite3
conn = sqlite3.connect("app.db")
# 设置WAL模式，返回值应该是 'wal'
mode = conn.execute("PRAGMA journal_mode=WAL;").fetchone()[0]
if mode.lower() != "wal":
print("切换失败，当前模式:", mode)
else:
print("已启用WAL模式")
# 建议同时调整检查点策略，避免wal文件无限增长
conn.execute("PRAGMA wal_autocheckpoint=1000;")
conn.close()最后补充一个性能调优建议：WAL模式下PRAGMA synchronous的默认值是FULL，对于大部分应用可以降级为NORMAL，在掉电时最多丢失最近一个事务而不会损坏数据库文件，安全性仍有保障，写入速度却明显提升。两者配合使用，是SQLite在高并发写入场景下的标准优化组合。
四、如何选择合适的日志模式
选择依据主要看三个维度：并发需求、数据安全要求和运行环境。如果应用存在多个连接同时读写，WAL模式几乎是唯一的选择；如果是单线程的嵌入式设备，追求极致简单可靠，默认的delete模式就足够了；如果文件删除操作代价高昂，考虑truncate或persist；如果只是内存中的临时计算，memory模式可以提供最快的速度。
还要考虑跨平台分发的问题。WAL模式要求所有访问该数据库的SQLite版本不低于3.7.0，且不支持只读介质。如果你的数据库文件需要被旧版本工具打开，或者放在只读文件系统上，就应该避免WAL模式。权衡这些条件后，再结合实际的压测数据做决定，通常就能找到最适合自己业务的日志模式配置。
SQLitePRAGMA journal_mode日志模式修改时间：2026-09-03 01:36:52