Database is locked 错误源于SQLite写锁机制：同一时刻仅允许一个连接执行写操作，其他写请求超时后抛出该错误；根本原因是事务过长或小事务未合并，而非磁盘权限或文件占用。
为什么SQLite会报 Database is locked 错误
这不是磁盘权限或文件被占用的问题，而是 SQLite 的写锁机制在起作用：同一时刻只允许一个连接执行写操作（INSERT/UPDATE/DELETE），其他连接尝试写入就会阻塞，超时后抛出 Database is locked。常见于多线程、Flask/FastAPI 多请求、或短连接高频写入场景。
根本原因往往不是“锁没释放”，而是事务持续时间太长，或大量小事务没合并。
timeout 参数到底怎么设才有效
timeout 是 sqlite3.connect() 的关键参数，单位是秒，它控制「等待写锁释放的最大时间」，不是连接超时，也不是语句执行超时。
- 设为
0：不等待，立刻报错 —— 适合实时性要求高、能主动重试的场景 - 设为
5.0或10.0：较稳妥，覆盖多数慢查询或临时阻塞 - 设为
30.0以上需警惕：大概率说明事务设计有问题，不是靠加 timeout 能解决的 - 注意：该值对只读查询（
SELECT）无效，只影响写操作等待
示例：
立即学习“Python免费学习笔记（深入）”；
import sqlite3
conn = sqlite3.connect("app.db", timeout=5.0) # ✅ 关键设置
cursor = conn.cursor()
cursor.execute("INSERT INTO logs (msg) VALUES (?)", ("hello",))
conn.commit()
比加 timeout 更重要的事务优化
加 timeout 是兜底手段，真正治本的是缩短事务持有锁的时间。SQLite 的锁粒度是整库，事务越长，冲突概率指数上升。
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 避免在事务里做耗时操作：如 HTTP 请求、文件读写、复杂计算 —— 这些必须挪到
commit()之后 - 批量写入用单个
executemany()，别用循环 + 多次execute()+ 每次commit() - 显式控制事务边界：用
conn.execute("BEGIN")和conn.commit()替代隐式事务，防止意外长事务 - 读写分离：纯查询尽量用
isolation_level=None（即 autocommit 模式），避免无意中开启事务
反例（极易锁库）：
for item in huge_list:
cursor.execute("INSERT INTO t VALUES (?)", (item,))
conn.commit() # ❌ 每次都 commit → N 次锁获取/释放
正例：
cursor.executemany("INSERT INTO t VALUES (?)", huge_list)
conn.commit() # ✅ 一次锁，一次提交
多线程下还锁？检查 check_same_thread
Python 的 sqlite3 默认禁止跨线程共享连接对象，若强行复用（比如全局 conn），可能触发未定义行为，表现为偶发锁错误或崩溃。
- 确认是否真需要多线程共用连接：绝大多数情况不需要，应为每个线程创建独立
connect() - 如果必须共享（如某些 ORM 配置），务必显式设
check_same_thread=False，但要自行保证线程安全 - 更推荐方案：用
threading.local()绑定连接，或改用连接池（如SQLAlchemy的QueuePool）
正确做法示例：
# 每个线程自己 connect，最简单可靠
def worker():
conn = sqlite3.connect("app.db", timeout=5.0)
# ... do work
conn.close()
真正麻烦的从来不是 timeout 设多少，而是事务里混进了日志打印、外部 API 调用、或者忘了 close() 导致连接泄漏 —— 这些问题不会报错，但会让锁冲突越来越频繁。
