// SQLite 错误参考

SQLITE_BUSY:数据库已锁定

另一个连接持有 SQLite 需要的锁,通常是另一个进程中的写入者。设置忙超时,让写事务保持简短,或切换到 WAL 模式。

结果代码
SQLITE_BUSY
名称
5
类别
主要结果代码
错误信息
database is locked

它的意思

SQLite 每个数据库文件一次只允许一个写入者。当一个连接需要另一个连接(在同一进程或不同进程中)持有的锁时,该调用会失败,并显示 SQLITE_BUSY 以及消息 database is locked,除非设置了忙等待处理程序,在这种情况下 SQLite 会先重试直到超时。

默认情况下没有忙碌处理器,因此失败会立即发生。在回滚日志模式下,读操作会阻止写操作提交,而写操作在提交时也会阻止新的读操作;WAL 模式则允许读操作和一个写操作同时进行。

常见原因

  • 两个进程或线程同时写入同一个数据库,而且没有设置 busy timeout。
  • 一个长时间的写事务(或从未提交的 BEGIN )会持有锁,而其他事务则在等待。
  • 用如下语句启动的读事务 BEGIN DEFERRED 在另一个连接正在写入时尝试升级为写事务;WAL 模式下这会返回 SQLITE_BUSY_SNAPSHOT 且等待无济于事。
  • 你自己程序中未关闭的游标或未执行完的语句会让读事务一直处于打开状态。
  • 数据库文件位于网络文件系统上,其锁定机制不可靠。

如何修复它

  1. 设置忙碌超时后,SQLite 会等待并重试,而不是立即失败。大多数语言绑定都提供此设置(Python 的 sqlite3 默认等待 5 秒;可以通过 sqlite3.connect(path, timeout=30))。SQL 写法:

    PRAGMA busy_timeout = 5000;  -- milliseconds
  2. 将数据库切换为预写日志(WAL)模式,读取不再阻塞写入,写入也不再阻塞读取。

    PRAGMA journal_mode = WAL;
  3. 写事务请用 BEGIN IMMEDIATE,它会预先拿好写锁。繁忙的连接随后要在 BEGIN (在适用超时之处)等满整个超时时间,而不是中途失败。

    BEGIN IMMEDIATE;
    UPDATE counters SET n = n + 1 WHERE name = 'visits';
    COMMIT;
  4. 保持事务简短,及时提交,并完成或重置每个语句(关闭游标),以确保没有连接占用锁超过必要时间。

  5. 把数据库放在本地磁盘上,而不是网络共享里。

安全地复现它

对同一个演示用数据库文件使用两个独立的连接。

-- Connection 1 (for example the sqlite3 shell):
BEGIN IMMEDIATE;
INSERT INTO t VALUES (1);
-- Connection 2, same file, no busy timeout:
INSERT INTO t VALUES (2);   -- Runtime error: database is locked (5)

问题

SQLITE_BUSY 和 SQLITE_LOCKED 有什么区别?

SQLITE_BUSY 表示另一个数据库连接持有冲突的锁,该连接通常在另一个进程中。 SQLITE_LOCKED 表示冲突发生在你自己的连接内,或在共享缓存的连接之间,例如语句还在读取某张表时把它删除了。

WAL 模式能解决数据库被锁定的问题吗?

它消除了大多数读写冲突,但一次仍然只有一个写入者,因此并发写入仍需要设置忙超时。

相关错误

更多主要结果代码错误

代码和消息文本来自 SQLite 结果和错误代码文档。浏览完整的 SQLite 错误列表 或者 搜索每个数据库错误.

// 错误更少,修复更快

在 SQLly 中使用 SQLite

适用于 macOS、Windows 和 Linux 的原生 SQL 客户端,智能感知能理解你的数据库模式,高危语句有防护,错误信息清晰,支持 SQLite 以及你使用的其他数据库。