遇到 SQLite 报 database is locked，通常是写操作被阻塞，最直接的解决办法是检查是否有未提交的事务，并在高并发场景下开启 WAL 模式。
先说结论：这个问题多数是因为写锁冲突，优先检查长事务和并发写入策略
- 先确认：是否有进程独占数据库文件或事务未提交
- 先处理：开启 WAL 模式并设置合理的 busy_timeout
- 再验证：重新执行写入操作并监控日志
命令速用版
如果是命令行环境或支持 PRAGMA 的工具，可以尝试以下设置来缓解锁等待：
PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;
第一行开启预写日志模式，第二行设置锁等待超时时间为 5000 毫秒。注意这些设置针对当前连接生效，持久化配置需写入数据库文件或应用初始化代码中。
为什么会这样
SQLite 默认使用回滚日志（Rollback Journal），在进行写操作时需要对数据库文件加独占锁。如果另一个连接正在写入，或者有一个读事务未结束（在某些隔离级别下），新的写请求就会拿不到锁。
当应用层没有正确处理事务提交，或者多个进程同时尝试写入同一个文件时，SQLite 会返回 SQLITE_BUSY 错误，上层驱动通常将其映射为 database is locked。此外，如果数据库文件位于不支持文件锁的网络文件系统（如 NFS）上，锁机制也会失效或行为异常。
分步处理
1. 检查未提交的事务
查看应用日志，确认是否有长时间运行的事务没有 commit 或 rollback。在代码中确保每个写操作都在 try-catch-finally 块中正确关闭事务。
2. 开启 WAL 模式
在数据库初始化时执行：
PRAGMA journal_mode=WAL;
WAL 模式允许读操作和写操作并发进行，减少写锁阻塞读的情况，也能改善部分写并发场景。执行后可通过 PRAGMA journal_mode; 确认是否返回 wal。
3. 设置忙等待超时
在连接建立后设置：
PRAGMA busy_timeout=5000;
这会让 SQLite 在遇到锁时等待指定毫秒数，而不是立即报错。数值需要根据业务容忍度调整，公开资料中没有看到可靠的量化数据表明具体多少毫秒最佳，通常建议从 3000 到 10000 之间尝试。
4. 检查文件系统
确认数据库文件不在 NFS、CIFS 等网络共享存储上。SQLite 官方文档明确指出本地文件系统之外的锁行为可能不可靠。如果必须在共享存储使用，需评估锁文件机制是否兼容。
怎么验证是否生效
1. 重新执行之前报错的写入操作，观察是否不再抛出异常。
2. 在高并发测试下，监控应用日志中 database is locked 出现的频率是否下降。
3. 使用 lsof | grep .sqlite 或类似命令查看数据库文件是否被异常进程长时间占用。
常见坑
1. PRAGMA 作用域：PRAGMA 设置通常只对当前数据库连接生效，重启连接后可能失效，需确保在每次建立连接时初始化配置。
2. 多进程写入：SQLite 适合读多写少，如果多个进程频繁同时写入，即使开启 WAL 也会 serialized（串行化），性能会下降，这不是锁报错但需注意。
3. 备份锁死：某些备份工具在复制数据库文件时会加锁，导致业务写入失败，备份前建议先 vacuum 或使用 SQLite 在线备份 API。
参考来源
- SQLite 官方文档 - Locking And Concurrency In SQLite: https://www.sqlite.org/lockingv3.html
- SQLite 官方文档 - Write-Ahead Logging: https://www.sqlite.org/wal.html
- SQLite 官方文档 - PRAGMA busy_timeout: https://www.sqlite.org/pragma.html#pragma_busy_timeout
原文链接：https://www.zjcp.cc/ask/10828.html