SQLITE_BUSY是SQLite中最常见的错误码之一，返回码数值为5。它的含义是数据库连接尝试获取某个锁时，另一个连接正在占用该锁，导致当前操作无法继续。典型表现为执行INSERT或UPDATE语句时抛出database is locked异常，或者在BEGIN TRANSACTION之后提交失败。由于SQLite采用文件级锁机制，多个连接并发访问同一个数据库文件时非常容易触发这个问题。要彻底解决SQLITE_BUSY，需要先理解SQLite的锁机制，再从连接管理和代码编写习惯入手。
一、理解SQLite的锁机制
SQLite在事务提交时对整个数据库文件加锁，而不是像MySQL那样支持行级锁。一个数据库连接在同一时刻可能处于UNLOCKED、SHARED、RESERVED、PENDING、EXCLUSIVE五种状态之一。读操作只需要SHARED锁，多个连接可以同时持有SHARED锁进行并发读取；但写操作需要EXCLUSIVE锁，同一时刻只允许一个连接持有。
这意味着SQLite的并发模型是“多读单写”。当连接A正在写事务中时，连接B尝试写入就会失败并返回SQLITE_BUSY。值得注意的是，SQLite默认情况下不会等待锁释放，而是立即返回错误，这就是为什么很多开发者感觉错误来得毫无征兆。
另一个容易混淆的错误码是SQLITE_LOCKED，它与SQLITE_BUSY不同：SQLITE_LOCKED表示同一个连接内部的锁冲突，例如在遍历游标的同时对同一张表执行写入，而SQLITE_BUSY是不同连接之间的锁冲突。分清这两个错误码有助于定位问题根源。
二、产生SQLITE_BUSY的常见原因
第一种常见原因是多个连接同时写入。典型场景是Web应用中多个请求各自打开数据库连接并执行写操作，当两个请求的写事务时间上重叠，后到的那个就会收到SQLITE_BUSY。
第二种原因是事务未及时提交或回滚。如果代码中执行了BEGIN之后因为异常没有走到COMMIT或ROLLBACK，该连接会一直持有写锁，其他连接的写入全部失败。这类问题在异常处理不完善的代码里尤其高发。
第三种原因是连接复用与多线程使用不当。SQLite连接不是线程安全的，如果多个线程共享同一个连接对象且未做串行化处理，可能出现锁状态混乱。此外，长事务中夹带了耗时操作（比如在事务内发起网络请求），会显著拉长锁的持有时间，放大冲突概率。
三、核心解决方案：busy_timeout与WAL模式
最直接有效的手段是设置忙等待超时。设置之后，SQLite获取不到锁时不会立即报错，而是循环重试，直到超时才返回SQLITE_BUSY。绝大多数偶发性的锁冲突都可以靠这个参数解决。下面是Python中的示例：
import sqlite3
# 设置忙等待时间为5000毫秒
conn = sqlite3.connect("app.db", timeout=5)
# 也可以通过PRAGMA语句设置
conn.execute("PRAGMA busy_timeout = 5000;")
第二个重要手段是启用WAL（Write-Ahead Logging）模式。默认的回滚日志模式下，写操作会阻塞读操作；而WAL模式允许读写并发，写操作不再阻塞读，大幅减少锁冲突。启用方式如下：
-- 开启WAL模式，只需执行一次，该设置会持久化到数据库文件 PRAGMA journal_mode = WAL;
需要注意的是，WAL模式下写入仍然依赖一个wal-index共享内存文件，写与写之间依旧互斥，所以它解决的是读写并发问题，不能让多个连接同时写。WAL模式还要求所有连接必须位于同一台主机上，网络文件系统上不建议使用。
四、从代码架构上根治锁冲突
除了参数配置，代码层面的规范同样关键。推荐的做法是为整个应用建立一个统一的写入口，例如使用一个单独的写线程配合队列，所有写请求进入队列后由该线程串行执行。这样从架构上保证了同一时刻只有一个连接在写，SQLITE_BUSY自然消失。以下是Python中用队列实现单写入口的简单示意：
import sqlite3, threading, queue
write_queue = queue.Queue()
write_conn = sqlite3.connect("app.db", check_same_thread=False)
write_conn.execute("PRAGMA journal_mode = WAL;")
write_conn.execute("PRAGMA busy_timeout = 5000;")
def writer_worker():
while True:
sql, params, result = write_queue.get()
try:
cur = write_conn.execute(sql, params)
write_conn.commit()
result.put(cur.lastrowid)
except Exception as e:
write_conn.rollback()
result.put(e)
write_queue.task_done()
threading.Thread(target=writer_worker, daemon=True).start()
其次是养成良好的事务习惯。事务要尽量短，只包含数据库操作，不要在事务内执行文件IO、网络请求或耗时的计算逻辑。所有写事务都使用try-finally结构保证最终执行提交或回滚，避免锁被异常路径长期占用。
最后是合理的重试机制。对于高并发场景，即使设置了busy_timeout，仍可能在极端情况下拿到SQLITE_BUSY，建议在业务代码中包裹一层指数退避重试逻辑，初次失败后等待几十毫秒再重试，通常重试两三次即可成功。
五、排查问题的实用技巧
如果做了上述配置后错误依旧存在，可以用.dbconfig或PRAGMA命令检查当前配置是否生效，例如执行PRAGMA journal_mode;确认是否返回wal。还可以检查是否存在遗留的锁持有者，比如某个进程异常退出后没有释放锁，这时可以在确保没有活跃连接的情况下删除同名的journal或wal文件来恢复。对于嵌入式场景，务必确认没有其他程序（如数据库查看工具）还打开着这个文件。
总结一下，解决SQLITE_BUSY的组合拳是：启用WAL模式、设置合理的busy_timeout、建立统一写入口或串行化写入、保证事务短小并及时释放。这四项措施配合使用，基本可以让database is locked错误从日志中彻底消失。
SQLite错误码SQLITE_BUSY数据库锁修改时间：2026-09-02 13:10:41