必须在每次连接建立后立即执行PRAGMA journal_mode=WAL，因其为连接级设置而非数据库文件级；否则新连接默认仍为DELETE模式，导致WAL不生效。
必须在每次连接建立后立即执行 PRAGMA journal_mode=WAL，否则 WAL 模式不会生效——这是最常被忽略的硬性前提。
为什么 WAL 模式不生效？
SQLite 的 PRAGMA 设置是连接级（per-connection）的，不是数据库文件级。即使你用一个连接启用了 WAL，其他新打开的连接默认仍是 DELETE 模式。多线程/连接池场景下尤其容易踩坑：
- 使用
sqlite3.connect()新建连接时，WAL 不会自动继承 - 连接池（如
concurrent.futures或自定义池）中复用的连接，若未在获取后重置 PRAGMA，可能仍处于旧模式 - Python 进程重启后，所有连接都重置为默认行为
如何确保每次连接都启用 WAL
推荐在连接创建后、执行任何业务 SQL 前，强制设置 WAL 及配套参数：
import sqlite3
<p>def get_db_connection(db_path):
conn = sqlite3.connect(db_path)</p><h1>必须在此处设置，且顺序重要：先 journal_mode，再其他</h1><pre class="brush:php;toolbar:false;">conn.execute("PRAGMA journal_mode=WAL")
conn.execute("PRAGMA synchronous=NORMAL")
conn.execute("PRAGMA wal_autocheckpoint=5000")
conn.execute("PRAGMA cache_size=-20000")
return conn使用示例
with get_db_connection("app.db") as conn: cursor = conn.cursor() cursor.execute("INSERT INTO logs (msg) VALUES (?)", ("hello",)) conn.commit()
注意：PRAGMA journal_mode=WAL 执行成功会返回 ('wal',)；若返回 ('delete',)，说明执行失败（常见于文件系统不支持、权限不足或数据库被其他进程独占锁定）。
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
立即学习“Python免费学习笔记（深入）”；
验证 WAL 是否真正运行
不能只看 PRAGMA 返回值，还要结合文件系统和运行时行为交叉确认：
- 检查数据库目录是否存在
app.db-wal和app.db-shm两个文件（.wal文件存在且大小非零是关键信号） - 执行
PRAGMA journal_mode;确认返回值为wal - 高并发写入时，观察是否仍有大量
database is locked错误——若仍有，大概率是没真正启用 WAL，或写入事务过大阻塞 checkpoint - 用
PRAGMA wal_checkpoint;手动触发检查点，返回值三元组中第三个数字（pages written）大于 0 表示 WAL 正在被清理
WAL 模式下容易被忽略的副作用
启用 WAL 后，SQLite 行为变化明显，但文档很少强调这些隐性约束：
-
PRAGMA synchronous对 WAL 的影响与 DELETE 模式不同：设为OFF时，WAL 日志写入内存而非磁盘，崩溃可能导致 WAL 文件丢失，但主数据库文件仍完整；而FULL会强制刷 WAL 和主库，性能损失更大 -
wal_autocheckpoint是“软限制”：它只在执行写操作时检查 WAL 大小，若长时间无写入，WAL 文件不会自动收缩——需配合定期PRAGMA wal_checkpoint(TRUNCATE) - SQLite 不允许在 WAL 模式下执行
VACUUM；如需压缩，必须先切回DELETE模式（PRAGMA journal_mode=DELETE），再VACUUM，最后重新启用 WAL
真正决定 WAL 效果的，从来不是“有没有开”，而是“每个连接有没有开 + 配套参数是否匹配业务负载 + WAL 文件有没有被及时回收”。这三个环节漏掉任何一个，性能提升都会打折扣。
