Python sqlite3 autocommit怎样区分连接事务与显式事务

Python 的 sqlite3 事务控制容易混淆，是因为“连接使用哪种事务策略”和“当前 SQLite 是否正处在未提交事务中”是两个层次。先记住一条实用结论：新代码优先在 connect() 中明确写出 autocommit=True 或 autocommit=False；只有兼容旧代码时，才把 LEGACY_TRANSACTION_CONTROL 与 isolation_level 放在一起理解。

官方地址：https://docs.python.org/3/library/sqlite3.html

如果一组写操作必须“一起成功或一起撤销”，不要只看 autocommit 这个名字，而要明确事务边界、提交点和异常路径。

• autocommit=True 使用 SQLite 的自动提交模式，commit() 和 rollback() 在该模式下不起作用。
• autocommit=False 采用 PEP 249 风格的持续事务控制，需要显式提交或回滚。
• LEGACY_TRANSACTION_CONTROL 把控制权交给旧式 isolation_level 逻辑；它是当前默认值，但不是新代码的首选。

先把两个 autocommit 概念分开

Connection.autocommit 是 Python sqlite3 暴露的连接级策略，有 True、False 和 LEGACY_TRANSACTION_CONTROL 三种允许取值。它决定 Python 如何打开、提交和回滚事务。

而 Connection.in_transaction 反映的是底层 SQLite 的状态：当前是否有未提交的改动。它是只读状态查询，不是切换策略的开关。因此不要把“autocommit=True”和“in_transaction 永远为 False”简单画等号；前者是连接配置，后者是某个时刻的状态。

autocommit 的三种取值怎样选

Python 官方文档建议把事务行为交给 autocommit 属性控制，并建议使用 False 作为 PEP 249 风格的值。当前文档中它仍默认为 LEGACY_TRANSACTION_CONTROL，未来默认值会改变，所以依赖默认值会让升级时难以判断行为。

autocommit=True：让每个写入边界更直接

下面的连接明确选择 SQLite 自动提交模式。每条语句的提交边界不再由 con.commit() 收束；在这个模式下调用 commit() 或 rollback() 没有实际作用。

import sqlite3

# 明确使用 SQLite 自动提交模式，避免依赖库的默认策略。
con = sqlite3.connect(":memory:", autocommit=True)
try:
    # 参数化 SQL 只绑定数据，不把用户输入拼进 SQL 文本。
    con.execute("CREATE TABLE task(id INTEGER PRIMARY KEY, name TEXT)")
    con.execute("INSERT INTO task(name) VALUES(?)", ("导入日报",))
    print(con.execute("SELECT name FROM task").fetchone())
finally:
    # 事务提交与连接释放是两个动作，连接仍要由调用方关闭。
    con.close()

这种模式适合每个写操作都能独立完成的场景。如果“创建任务”和“写审计记录”必须成组成功，就不应把两条写入分散在自动提交边界中。

autocommit=False：把一组操作放进显式提交边界

autocommit=False 的重点不是“完全不自动做任何事”，而是让 sqlite3 按 PEP 249 风格保持事务打开，应用通过 commit() 或 rollback() 明确收束一组变更。成功路径和失败路径都要写出来。

import sqlite3

con = sqlite3.connect(":memory:", autocommit=False)
try:
    # 建表和业务写入属于同一连接事务，异常时统一回滚。
    con.execute("CREATE TABLE account(id INTEGER PRIMARY KEY, balance INTEGER)")
    con.execute("INSERT INTO account(balance) VALUES(?)", (100,))
    con.execute("UPDATE account SET balance = balance - ? WHERE id = ?", (30, 1))
    con.commit()
except sqlite3.Error:
    # 只回滚当前未提交变更，并把原始异常继续交给上层处理。
    con.rollback()
    raise
finally:
    # close 不等于 commit；未提交的变更不能靠 close 作为业务提交点。
    con.close()

如果要检查这一组写入是否仍在底层事务中，可以读取 con.in_transaction。它适合诊断“现在是否有未提交变更”，不适合替代业务层的提交策略。

with con 是事务边界，不是连接生命周期

Connection 可以作为上下文管理器使用：代码块正常结束时提交，代码块抛出未捕获异常时回滚。这个上下文管理器只负责已有事务的提交或回滚，不会自动创建连接，也不会自动关闭连接；autocommit=True 时它不介入。

import sqlite3

con = sqlite3.connect(":memory:", autocommit=False)
try:
    con.execute("CREATE TABLE event(id INTEGER PRIMARY KEY, message TEXT)")
    # with 只包住需要原子提交的业务操作，成功自动 commit。
    with con:
        con.execute("INSERT INTO event(message) VALUES(?)", ("开始同步",))
        con.execute("INSERT INTO event(message) VALUES(?)", ("同步完成",))
    # with 块结束后连接仍然可用，查询和后续事务可以继续执行。
    print(con.execute("SELECT COUNT(*) FROM event").fetchone()[0])
finally:
    # 上下文管理器不会关闭连接，所以这里必须释放它。
    con.close()

需要注意，异常仍会从 with 块向外传播。若调用方要把某类业务异常转换为用户提示，应在外层捕获；不要因为自动回滚就吞掉原始异常。

兼容旧项目时再看 isolation_level

当 autocommit 为 LEGACY_TRANSACTION_CONTROL 时，isolation_level 才会控制旧式事务行为。它不是新模式下的第二个开关：当 autocommit 为 True 或 False 时，isolation_level 不起作用。

import sqlite3

# 兼容旧式代码：只有 LEGACY 模式下 isolation_level 才参与控制。
con = sqlite3.connect(":memory:",
                      isolation_level="IMMEDIATE",
                      autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)
try:
    con.execute("CREATE TABLE log(message TEXT)")
    # 旧式规则会在特定写语句前隐式开启事务，提交点仍由代码负责。
    con.execute("INSERT INTO log(message) VALUES(?)", ("legacy",))
    con.commit()
finally:
    # 兼容旧代码不代表可以省略连接关闭。
    con.close()

如果把 isolation_level=None 设在旧式模式下，则不会隐式开启事务，底层保持 SQLite 自动提交；应用可以通过 SQL 自己发出 BEGIN、COMMIT 和 ROLLBACK。这是一种兼容路径，不要与新式 autocommit=True 的 Python 连接策略混写成一个概念。

遇到“提交不生效”时按这张表排查

def transaction_state(con):
    # autocommit 是连接策略，in_transaction 是当前底层状态。
    print({
        "autocommit": con.autocommit,
        "isolation_level": con.isolation_level,
        "in_transaction": con.in_transaction,
    })

常见问题

autocommit=True 还能手动使用 BEGIN 吗？

可以把事务控制交给 SQL，但这时应明确由 SQL 的 BEGIN、COMMIT 和 ROLLBACK 负责边界，不要再期待 Python 的 con.commit() 替你完成同一件事。

autocommit=False 和 with con 是二选一吗？

不是。autocommit=False 可以提供持续的连接事务策略，with con 则把某一段业务代码标成成功提交、异常回滚的局部边界，两者可以组合。

为什么不能只用 in_transaction 判断是否应该 commit？

因为它只告诉你底层当前是否有未提交变更，不表达这批变更是否已经完成业务校验，也不表达异常时应该回滚到哪里。提交点仍应由业务流程决定。

新项目应该写哪个默认值？

不要省略策略。若每条写入独立完成，写出 autocommit=True；若多条写操作要保持原子性，优先考虑 autocommit=False 并明确提交或回滚。只有为了兼容旧代码，才保留 LEGACY_TRANSACTION_CONTROL。

总结一下：Connection.autocommit 决定 Python 采用哪种事务控制方式，with con 划定一段可提交或回滚的业务边界，in_transaction 只报告底层当前状态，而 isolation_level 主要属于旧式兼容路径。把这四个概念分开，sqlite3 的“自动提交”和“显式事务”就不会再互相覆盖。