Python sqlite3 多线程共享连接时报错怎么改

这个报错最常见的原文是：SQLite objects created in a thread can only be used in that same thread。它通常说明主线程创建了 sqlite3.Connection，随后把连接或游标交给了线程池。Python 的 sqlite3.connect() 默认开启 check_same_thread=True，所以连接跨线程使用会抛出 ProgrammingError。

最稳妥的改法是：不要共享连接，让每个工作线程为同一个数据库文件打开自己的连接；一项写入任务在自己的事务中完成，成功就提交，异常就回滚。只有确实需要共享一个连接时，才使用 check_same_thread=False，并用锁把执行和提交包起来。

为什么共享 Connection 会触发 ProgrammingError

Connection 是带状态的资源，创建时就记录了创建线程。下面这种写法把主线程的连接传进线程池，错误与 SQL 语句内容无关：

import sqlite3
from concurrent.futures import ThreadPoolExecutor

con = sqlite3.connect("tasks.db")  # 连接归属于创建它的线程

def save_task(name):
    # 这里运行在线程池线程，默认连接检查会拒绝跨线程使用
    con.execute("INSERT INTO task(name) VALUES (?)", (name,))
    con.commit()

with ThreadPoolExecutor(max_workers=2) as pool:
    pool.submit(save_task, "编译报告")

不要先把问题归结为 SQLite 文件锁。文件锁处理的是多个连接之间的数据库访问竞争，而这里连 SQL 执行前的线程归属检查都没有通过。可以先记录 threading.get_ident()，确认创建连接和使用连接的线程是否相同。

每个工作线程创建自己的连接

把连接创建动作放到任务函数内部，能把连接、游标、事务和异常处理放在同一个线程边界中。多个连接仍然指向同一个 tasks.db 文件，但不会互相复用 Python 连接对象：

import sqlite3
from concurrent.futures import ThreadPoolExecutor

DB = "tasks.db"

def save_task(name):
    # 每次任务使用自己的连接，避免跨线程传递 Connection
    con = sqlite3.connect(DB, timeout=10)
    try:
        with con:
            # with 负责成功提交或异常回滚，不负责关闭连接
            con.execute("INSERT INTO task(name) VALUES (?)", (name,))
    finally:
        # 连接不再使用时显式释放
        con.close()

with ThreadPoolExecutor(max_workers=4) as pool:
    list(pool.map(save_task, ["编译报告", "测试报告", "部署报告"]))

这里的 with con 是事务上下文，不是连接生命周期上下文。正常离开代码块时提交，异常离开时回滚；close() 仍然需要显式调用。写任务尽量缩短事务范围，减少其他连接等待数据库锁的时间。

必须共享连接时，先关闭检查再串行化写入

某些旧代码确实依赖一个共享连接。这时可以显式设置 check_same_thread=False，但它只关闭了 Python 的线程检查，不会替你安排多个线程如何交替执行 SQL。共享连接上的写入、提交和回滚应由同一把锁保护：

import sqlite3
from threading import Lock
from concurrent.futures import ThreadPoolExecutor

con = sqlite3.connect("tasks.db", check_same_thread=False)
db_lock = Lock()

def save_task(name):
    with db_lock:
        try:
            # 锁覆盖 SQL 和 commit，避免事务状态被别的线程插入
            con.execute("INSERT INTO task(name) VALUES (?)", (name,))
            con.commit()
        except Exception:
            # 回滚也必须在同一把锁内完成
            con.rollback()
            raise

try:
    with ThreadPoolExecutor(max_workers=4) as pool:
        list(pool.map(save_task, ["编译报告", "测试报告", "部署报告"]))
finally:
    # 所有任务结束后再关闭共享连接
    con.close()

这个方案的代价是写操作实际上被锁串行化，线程数增加不一定带来更高写入吞吐。若没有共享连接的强约束，仍然优先使用每线程连接。Python 官方文档也明确提醒：关闭线程检查后，写操作可能需要由用户自行串行化。

用独立连接确认提交，而不是只看当前线程结果

排查时可以按下面的清单逐项确认：

如果使用较新的 Python 事务接口，要把 autocommit、isolation_level 和项目支持的 Python 版本一起确认；不要把不同版本的默认行为混在同一个排查结论里。对本文这个线程错误而言，第一优先级仍是连接归属，其次才是提交策略。

常见问题

把 check_same_thread 改成 False 就一定安全了吗？

不一定。它允许连接被多个线程访问，但共享写连接仍要由应用串行化；没有锁时，事务和游标状态可能互相干扰。

每个线程一个连接会不会写入不同的数据库？

只要传入同一个数据库文件路径，就会访问同一个文件。要特别检查相对路径的当前工作目录，并避免把 :memory: 当成共享文件使用。

with con 能代替 con.close() 吗？

不能。连接上下文管理器负责提交或回滚事务，不负责关闭连接；线程任务结束后仍应显式关闭。

读操作也必须加锁吗？

每线程独立连接时，通常不需要共享锁；共享连接时，至少要把游标和事务状态纳入同一套同步策略，最简单的做法是让读写都遵守同一资源边界。

因此，修复顺序可以固定为：先确认哪个线程创建了连接，再优先改成每线程连接；只有保留共享连接的明确理由时，才关闭线程检查并把写入、提交、回滚一起锁住。