遇到多线程 SQLite 报错 busy，最直接的办法是设置 busy_timeout 让程序等待锁释放，但要想彻底解决并发问题，通常还需要开启 WAL 模式并确保连接使用方式正确。
先说结论：单纯设置超时参数只能缓解报错，不能提升并发上限，生产环境建议配合 WAL 模式使用
- 先确认：检查报错是否为 SQLITE_BUSY 以及当前连接是否跨线程共享
- 先处理：设置 busy_timeout 毫秒数，并开启 journal_mode=WAL
- 再验证：观察高并发下是否不再出现数据库锁定错误
命令速用版
如果你能直接执行 SQL 命令，可以在连接建立后立刻执行以下 pragma 设置：
PRAGMA busy_timeout=5000;
PRAGMA journal_mode=WAL;如果是代码驱动，通常在连接字符串或初始化函数中配置，例如 Python sqlite3 连接时传入 timeout 参数。
为什么会这样
SQLite 是文件型数据库，写操作时会锁定整个数据库文件。默认情况下，如果一个线程正在写入，其他线程尝试写入或读取（取决于锁级别）会立即收到 SQLITE_BUSY 错误。
busy_timeout 的作用是告诉 SQLite 引擎：当遇到锁时，不要马上报错，而是等待指定的毫秒数，直到锁释放或超时。但这只是“等待”，并不是“解锁”。
分步处理
1. 设置超时时间
在建立数据库连接后，执行 PRAGMA busy_timeout=毫秒数。建议值根据业务容忍度设置，例如 3000 毫秒。
2. 开启 WAL 模式
执行 PRAGMA journal_mode=WAL;。WAL（Write-Ahead Logging）允许读写并发，读者不会阻塞写者，写者也不会阻塞读者，能显著减少 busy 错误的发生概率。
3. 检查线程安全配置
确保你的数据库连接对象使用方式符合驱动要求。某些驱动默认不允许跨线程共享连接对象，需要为每个线程创建独立连接，或启用驱动层面的线程安全选项。
怎么验证是否生效
1. 查看应用日志，确认 SQLITE_BUSY 或 database is locked 错误消失。
2. 在高并发场景下观察响应时间，如果超时设置过大，可能会看到请求耗时增加，这说明锁竞争依然存在，只是从报错变成了等待。
3. 使用 SQLite 命令行工具执行 PRAGMA journal_mode; 确认返回 wal。
常见坑
1. 长事务持有锁
如果某个事务执行时间过长，即使设置了 timeout，其他线程也可能等到超时。尽量保持事务短小，避免在事务中进行网络请求或复杂计算。
2. 连接对象跨线程共享
除非驱动明确支持 serialized 模式，否则不要在多个线程间直接传递同一个连接对象。这可能导致不可预知的锁定行为或崩溃。
3. 忽略驱动默认值
不同编程语言的 SQLite 驱动对 timeout 的默认设置不同，有的默认为 0，有的默认为 5 秒。不要假设默认值足够用，显式设置更可靠。
参考来源
- SQLite Official Documentation - PRAGMA busy_timeout: https://www.sqlite.org/pragma.html#pragma_busy_timeout
- SQLite Official Documentation - WAL Mode: https://www.sqlite.org/wal.html
- SQLite Official Documentation - Thread Safety: https://www.sqlite.org/threadsafe.html
原文链接：https://www.zjcp.cc/ask/10825.html