知识条目 / SQLite

SQLite 报 database is locked 如何解决?

SQLite 写操作串行执行,锁冲突多来自长事务、未关闭游标与多进程并发写,可通过 WAL、busy_timeout 和缩短事务缓解。

SQLite 同一时刻只允许一个写事务。database is locked 表示等待锁失败,常见于长写事务、连接未提交/回滚、以及多进程同时写入同一文件。

处理步骤

  1. 确认并发模型明确是否有多个进程或线程共享同一数据库文件,以及使用的日志模式。
  2. 缩短写事务避免在事务中执行网络或耗时计算,写操作后及时提交,读取结束及时关闭游标。
  3. 启用 WAL 与等待切换到 WAL 模式提升读写并发,并设置 busy_timeout 让冲突时等待而非立即失败。
  4. 串行化写入高频写入场景应由单一写线程或队列串行化,避免多个连接争抢写锁。

示例

PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;
PRAGMA synchronous=NORMAL;

-- 检查是否有长时间未结束的事务
PRAGMA wal_checkpoint(PASSIVE);

WAL 模式仍只允许一个写者;网络文件系统上的锁语义不可靠,不建议把 SQLite 放在共享盘。

关键词

sqlite · database is locked · sqlite_busy · wal · busy_timeout · 锁 · 事务

官方文档

同库知识