Python sqlite3 autocommit 怎么切换：LEGACY_TRANSACTION_CONTROL 与提交回滚边界

Python 操作 sqlite3 时，事务逻辑最容易踩坑的地方从来不是SQL语句本身，而是数据库连接到底由谁负责触发提交。Python 3.12 起，Connection.autocommit 提供了更明确的事务模式选择；如果仍使用老版本的隐式规则，LEGACY_TRANSACTION_CONTROL 才会继续由 isolation_level 决定旧式表现。不少人把两套配置混着用，最后经常碰到写入操作看起来执行成功，程序跑完之后数据却没有按预期落盘的问题。

你只需要通过连接参数明确指定autocommit的取值，区分新规范事务模式和遗留兼容模式，就能完全掌握提交回滚的触发时机，避开隐式事务带来的各类落盘异常。

先把提交责任写在连接配置里

我们常见的订单写入逻辑，一般要同时做库存扣减和订单插入两步操作。只要第二步执行失败，第一步的修改也必须跟着回滚。用 autocommit=False 配置连接时，事务的控制权会完全交到应用代码手上：

import sqlite3

con = sqlite3.connect("orders.db", autocommit=False)

try:
    run_statement(
        "UPDATE inventory SET stock = stock - 1 WHERE sku = ? AND stock > 0",
        ("A-100",),
    )
    run_statement(
        "INSERT INTO orders(sku, quantity) VALUES (?, ?)",
        ("A-100", 1),
    )
    con.commit()
except Exception:
    con.rollback()
    raise
finally:
    con.close()

这里的 run_statement() 是项目数据层对 SQL 调用的统一封装，示例重点放在事务边界：两步写入都执行成功才提交；任意一步抛错就回滚。连接正式关闭前，不要把「调用过 SQL」误认为「已经持久化」，真正的事务边界是 commit()。

autocommit 的三个值分别代表什么

很多人以为 Connection.autocommit 只是简单的布尔开关，但在 Python 官方文档里它一共支持三个合法取值。生产环境迁移前，先把当前配置的取值和对应行为列进检查表：

这里有一个很容易混淆的概念：SQLite 底层本身也有「自动提交状态」，而 Python 的 Connection.autocommit 是 DB-API 层面的事务控制属性。想要观察当前连接是否存在未提交变更时，直接读取只读的 con.in_transaction 会更直观准确。

为什么 isolation_level 有时改了却没效果

不少老旧项目里的连接初始化代码是这么写的：

con = sqlite3.connect(
    "orders.db",
    isolation_level="IMMEDIATE",
    autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL,
)

在这个兼容模式下，isolation_level 可以是 "DEFERRED"、"IMMEDIATE" 或 "EXCLUSIVE"，分别对应旧式隐式事务的不同启动策略。关键是必须显式选择 LEGACY_TRANSACTION_CONTROL；如果连接已经使用 autocommit=False 或 True，isolation_level 就不会再控制事务行为。

迁移旧连接代码时按这个顺序验收

1. 先搜索所有 sqlite3.connect()，记录是否只传了 isolation_level。
2. 为每个写入用例补上成功提交和异常回滚两条路径，校验最终数据行数是否符合预期。
3. 打印或断言 con.autocommit 与 con.in_transaction，不要只看函数返回值就判定执行成功。
4. 如果必须保留原有旧行为，把 LEGACY_TRANSACTION_CONTROL 显式写出来，不要依赖不确定的默认值。
5. 批量写入完成后主动调用 commit()，连接关闭前再验证数据库文件里的实际结果。

官方默认值会随版本迭代调整，不能把默认表现当作长期生效的约定。尤其是升级 Python 版本之后，连接工厂、测试夹具和命令行脚本可能采用完全不同的事务模式，最好统一封装一个创建数据库连接的公共函数。

一段最小的提交与回滚测试

import sqlite3

con = sqlite3.connect(":memory:", autocommit=False)
run_statement("CREATE TABLE audit(event TEXT)")

run_statement("INSERT INTO audit VALUES (?)", ("ok",))
assert con.in_transaction is True
con.commit()
assert query_value("SELECT COUNT(*) FROM audit") == 1

try:
    run_statement("INSERT INTO missing_table VALUES (1)")
except sqlite3.Error:
    con.rollback()

assert query_value("SELECT COUNT(*) FROM audit") == 1
con.close()

测试不只要验证成功场景下的数据行数，还要确认失败路径不会把上一个事务的状态带到下一次写入流程里。针对真实业务场景，还需要补上进程异常、连接关闭和并发访问场景下的一致性校验。

常见问题

Python sqlite3 推荐用 autocommit 的哪个值？

文档推荐用 False 进行 PEP 249 事务控制，由应用显式调用 commit() 和 rollback()。

autocommit=True 时还能调用 commit() 吗？

可以调用，但在 SQLite 自动提交模式下，commit() 和 rollback() 不产生实际事务控制效果。

什么时候需要 LEGACY_TRANSACTION_CONTROL？

需要保持 Python 3.12 之前的 isolation_level 事务行为，或正在分阶段迁移旧连接代码时使用它。

如何确认当前连接是否还有未提交事务？

读取 Connection.in_transaction。它直接反映连接当前是否存在未提交的变更。

小结

sqlite3 事务迁移的核心不是把 isolation_level 换成另一个字符串，而是先决定应用要不要显式承担提交责任。新代码优先选择 autocommit=False，旧代码需要兼容时明确写出 LEGACY_TRANSACTION_CONTROL，再用提交、回滚和 in_transaction 三个检查点把行为完全锁住。