必须在每次连接建立后立即执行PRAGMA journal_mode=WAL，因其为连接级设置而非数据库文件级；否则新连接默认仍为DELETE模式，导致WAL不生效。

怎样在python中配置sqlite3支持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',)，说明执行失败（常见于文件系统不支持、权限不足或数据库被其他进程独占锁定）。

python-flask-vue-creator

创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。

下载

验证 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