WAL模式仅解除读写互斥,写并发仍为1;报database is locked主因是多写者争抢全局写锁,或长读事务阻塞checkpoint,timeout仅延长等待而不提升吞吐。

WAL 模式本身不能提升写并发,但能彻底解除读写互斥;真正起效的是配合 PRAGMA synchronous=NORMAL、连接串行化、批量事务这三件事。
为什么 WAL 模式下还报 database is locked
这是最常被误解的点:WAL 只解决「读阻塞写」和「写阻塞读」,不解决「写阻塞写」。SQLite 仍是单写者模型,任意时刻只有一个连接能执行写操作。
- 错误
sqlite3.OperationalError: database is locked出现时,大概率是多个线程/进程同时调用conn.execute("INSERT ..."),而非 WAL 未生效 - 若看到
SQLITE_BUSY_SNAPSHOT,说明某个长读事务(比如BEGIN后迟迟不COMMIT)导致 WAL checkpoint 卡住,-wal 文件持续膨胀 -
timeout参数(如sqlite3.connect(..., timeout=10))只是让第二个写请求等 10 秒再失败,不减少排队时间,反而拉高 P99 延迟
必须在每个新连接里执行的 WAL 初始化
PRAGMA journal_mode=WAL 不是持久化设置,每次新连接建立后都得重设——尤其在使用连接池或复用连接时容易遗漏。
- 正确做法:在
sqlite3.connect()后立即执行conn.execute("PRAGMA journal_mode=WAL"),并检查返回值是否为"wal" - 错误示范:只在初始化脚本里跑一次
sqlite3 db.db "PRAGMA journal_mode=WAL",后续 Python 连接仍走默认DELETE模式 - WAL 启用后会生成
.db-wal和.db-shm两个文件,它们必须与.db在同一目录、同属主、同权限,否则写入直接失败
真正提升吞吐的三个实操动作
光开 WAL 没用,要搭配以下三项才能把写吞吐从“每秒几条”拉到“每秒上千条”:
立即学习“Python免费学习笔记(深入)”;
- 把
PRAGMA synchronous=NORMAL加进连接初始化 —— WAL 模式下,NORMAL已足够安全,FULL(默认)会强制每次写都fsync,抵消 WAL 90% 的收益 - 禁用连接池,设
db.set_max_open_conns(1)(Python 中对应sqlite3.connect()的复用逻辑),让所有写请求串行进入单个连接;多连接争抢写锁只会放大database is locked - 把 N 条 INSERT 合并进一个事务:
conn.execute("BEGIN"); [cursor.execute(...) for _ in data]; conn.commit(),比逐条commit()快 10–100 倍 —— 这不是并发优化,是消灭写锁获取的固定开销
容易被忽略的 checkpoint 卡点
WAL 模式下,-wal 文件不会自动清空,靠后台 checkpoint 推进。一旦卡住,-wal 持续增长,磁盘爆满或查询变慢。
- 手动触发检查:
conn.execute("PRAGMA wal_checkpoint(TRUNCATE)"),返回三元组(busy, log, checkpointed);若busy == 1,说明有未提交的长读事务挡住了 checkpoint - 查长事务:
SELECT * FROM pragma_lock_status;(SQLite 3.32+)或简单用ps aux | grep sqlite看是否有长时间挂起的进程 - 生产环境建议加定时任务,每 5 分钟跑一次
PRAGMA wal_checkpoint,避免依赖自动机制



















