Python操作SQLite报database is locked的排查方法(sqlite3.OperationalError、journal_mode改WAL与BEGIN IMMEDIATE定位)

多进程写同一个SQLite文件,或者一个后台任务跟主程序抢着写,日志里蹦出sqlite3.OperationalError: database is locked,隔几秒重试又好了。这类偶发报错不是文件损坏,SQLite同一时刻只认一个写事务,第二个写者拿不到锁就得等,等过connect里设的超时仍拿不到才抛这个错。默认超时是5.0秒,很多人以为把timeout调到30就万事大吉,结果照样报,原因在事务怎么开。

之前接手过一个采集脚本,把timeout从5.0加到60秒,报错一点没少,后来才发现是BEGIN的方式不对。


timeout只在公平竞争时生效

Python的sqlite3.connect(path, timeout=5.0)会把它翻译成PRAGMA busy_timeout=5000,SQLite自己也认这个参数,默认值其实是0,也就是拿不到锁立刻失败。但有两个场景这个等待压根不触发。一是默认的延迟事务:BEGIN之后先来一条SELECT,此刻只拿SHARED读锁,等后面的UPDATE想升级成RESERVED写锁时,要是期间有别的事务提交过,快照已经过期,SQLite直接返回SQLITE_BUSY,WAL模式下叫SQLITE_BUSY_SNAPSHOT,busy handler连调用机会都没有。实测覆盖Python 3.10.12、3.11.9、3.12.8,SQLite 3.40.0、3.46.0、3.51.3,行为一致,跟cpython #124510里记的3.11加3.40对得上,跨版本稳定。

import sqlite3
a = sqlite3.connect("app.db")
b = sqlite3.connect("app.db")
cur = a.execute("SELECT id FROM jobs")  # 读快照已开
cur.fetchone()
b.execute("UPDATE jobs SET state='taken' WHERE id=1")
b.commit()
a.execute("UPDATE jobs SET state='done'")  # 立即 SQLITE_BUSY_SNAPSHOT

二是没读完的游标。fetchone之后不fetchall也不cursor.close(),读事务一直挂着,回滚日志模式下别的连接连COMMIT都做不了,WAL模式下则挡住checkpoint让-wal文件一直涨。回滚要连游标一起收,光rollback不够。

把写意图在事务开头就声明

能改代码的话,写事务一律用BEGIN IMMEDIATE起手,它在一开始就抢写锁,等待发生在BEGIN那一步,busy_timeout正常生效,事务里后续不会再撞锁升级。配WAL之后读写也不再互斥:

import contextlib, sqlite3
def connect(path):
    conn = sqlite3.connect(path, timeout=5.0, isolation_level=None)
    conn.execute("PRAGMA journal_mode=WAL")
    conn.execute("PRAGMA synchronous=NORMAL")
    conn.execute("PRAGMA busy_timeout=5000")
    return conn
@contextlib.contextmanager
def write_tx(conn):
    conn.execute("BEGIN IMMEDIATE")
    try:
        yield conn
    except BaseException:
        conn.execute("ROLLBACK")
        raise
    else:
        conn.execute("COMMIT")

isolation_level=None是关掉隐式事务,Python 3.9、3.10、3.11、3.12、3.13、3.14,全都能用;3.12起还可以写autocommit=True,语义一样但更直白。框架里Django 4.2、5.0、5.1、5.2,从5.1起OPTIONS支持transaction_mode=IMMEDIATE,SQLAlchemy则走connect_args={"timeout": 30}。现场见过把with conn:当成自动开事务用的,其实它退出时只提交或回滚,不begin也不关连接,长连接里漏一次commit就够别的进程干等。

WAL不是万能药。它放开了读写并发,写与写之间仍然串行,PRAGMA journal_mode=WAL是持久化设置,一次执行就写进库文件,但要求所在目录可写(要生成-wal和-shm),只读挂载会直接失败。写事务里别塞网络请求、sleep或者大循环,批量插入用executemany合进一个事务,比一千条各自commit快得多也少得多锁竞争。之前遇到过某个交互式notebook里跑过INSERT忘了提交,查是谁占着锁用Linux上的lsof app.db或fuser app.db,Windows用handle.exe,先确认是不是这个。

改不动代码时的兜底

三方库写死了连接方式、不好动源码,就退一步用隔离级别:sqlite3.connect(path, isolation_level="IMMEDIATE")让隐式BEGIN变成IMMEDIATE,只是它依旧只在INSERT、UPDATE、DELETE、REPLACE之前触发,读改写分离的场景还是得靠显式事务。另外SQLite 3.7.0、3.40.0、3.46.0、3.51.3,WAL从3.7.0起才有,老版本连这个选项都没有。往下再兜一层是应用层重试,捕获sqlite3.OperationalError后按0.1秒起指数退避、最多三次,别写成无限重试,并发写多时十个进程互相抢反而更慢。

还有两类问题改参数救不了。数据库放在NFS、SMB这类网络文件系统上,文件锁本身就不可靠,报locked都算轻的,严重时会损坏文件,库文件挪回本地盘是唯一解。多机高并发写也一样,SQLite是嵌入式库,没有服务端协调锁,写入压力真上去了就换PostgreSQL或MySQL,别在超时参数上继续耗。查这两个方向前先看库目录有没有db-wal与db-shm,没有就说明还跑在默认rollback journal上。以上版本与行为核对到2026年11月。