SQLite提前触发'database locked'异常，超时设置未生效问题咨询

为什么20秒超时设置没生效？ #

SQLite的timeout参数并非你理解的「总等待锁的时长」——它实际定义的是每次尝试获取锁的间隔时间，SQLite会在这个间隔内重复尝试获取锁，但如果检测到锁被其他连接长期持有（比如对方开启事务后未提交），不会一直等到20秒，而是提前抛出锁定错误。

另外两个关键诱因：

• 隐式事务未闭合：SQLite默认是隐式事务模式，执行写操作后如果没调用commit()或rollback()，连接会一直持有写锁。这种情况下，其他连接的等待会被快速终止。
• 高并发写冲突：你的应用有10+线程同时可能写库，SQLite是写独占锁机制，同一时刻只能有一个连接写。当多个写请求同时到来，锁竞争会非常激烈，很容易在短时间内触发错误。

解决建议 #

• 严格管控事务生命周期：所有写操作必须及时提交/回滚，用上下文管理器避免遗漏：

  with conn:
      conn.execute("INSERT INTO your_table VALUES (?)", (data,))
  # 上下文会自动处理commit，异常时自动rollback
  

• 启用WAL模式：这是提升SQLite并发性能最有效的手段，WAL允许读操作与写操作并行，大幅缩短写锁持有时间：

  conn = sqlite3.connect('database.db', timeout=20.0)
  conn.execute("PRAGMA journal_mode=WAL;")
  

  注意：所有连接必须使用WAL模式，且数据库目录要有写入权限。
• 替换为连接池：不要给每个线程单独创建连接，用线程安全的连接池（比如SQLAlchemy的连接池）管理连接，避免连接滥用导致的锁混乱。
• 缩小事务粒度：不要在事务中执行非数据库操作（比如API调用、文件读写），尽量让事务只包含必要的DB操作，减少锁持有时间。
• 控制写并发度：如果业务允许，用线程池限制同时执行写任务的线程数量，降低锁竞争概率。

内容的提问来源于stack exchange，提问作者Cas