Python sqlite3 事务模式与自动提交边界

Python 的 sqlite3 事务问题，核心不在于“有没有调用 commit()”，而在于你是否明确了连接采用哪一种事务控制方式。当前 Python 官方文档推荐使用 Connection.autocommit：False 表示由应用显式提交或回滚，True 表示启用 SQLite 的自动提交模式，而 LEGACY_TRANSACTION_CONTROL 则把控制权交给旧式的 isolation_level。

如果把这三层混在一起，常见结果是：异常发生后只有部分数据落盘、以为 with conn: 会关闭连接、修改了 isolation_level 却没有任何效果，或者在已经自动提交的模式下继续调用 rollback() 并期待它撤销写入。下面把数据一致性当作需要保护的资产，逐层拆开这些边界。

三种模式先看清：谁决定提交时机

先记住一个总原则：autocommit 是当前推荐的事务控制入口；只有当它取值为 sqlite3.LEGACY_TRANSACTION_CONTROL 时，isolation_level 才继续决定 legacy 行为。它们不是两个可以同时独立生效的开关。

当前文档中，sqlite3.connect() 的 autocommit 默认仍是 LEGACY_TRANSACTION_CONTROL，并说明未来默认值会改变。因此新代码不要依赖“默认行为”，最好在连接创建处直接写明选择。

一笔写入到底什么时候算完成

一条 INSERT 执行成功，不等于业务事务已经完成。对于显式事务模式，可以把一次业务写入看成四个边界：建立连接、执行一组变更、提交或回滚、关闭连接。真正把变更变成可持久化结果的是 commit()，不是 execute()。

import sqlite3

def add_order(db_path: str, user_id: int, amount: int) -> None:
    # 显式声明事务策略，避免依赖不同 Python 版本的默认值。
    conn = sqlite3.connect(db_path, autocommit=False)
    try:
        # 同一事务内完成订单和审计记录，任一步失败都不应只落一半。
        conn.execute(
            "INSERT INTO orders(user_id, amount) VALUES(?, ?)",
            (user_id, amount),
        )
        conn.execute(
            "INSERT INTO order_audit(user_id, action) VALUES(?, ?)",
            (user_id, "created"),
        )
        conn.commit()  # 只有这里成功后，当前事务才完成持久化。
    except Exception:
        conn.rollback()  # 把当前事务内的两条变更一起撤销。
        raise
    finally:
        conn.close()  # 事务边界和连接生命周期是两件事，都要明确处理。

这个结构保护的是“订单与审计记录必须同时存在”的不变量。rollback() 只能影响仍处于当前事务中的变更；如果连接已经处于 autocommit=True，它不会把已经独立提交的写入追回。

连接上下文管理器解决什么，不解决什么

Connection 可以作为上下文管理器使用。正常离开 with 代码块时，它会提交打开的事务；代码块抛出未捕获异常时，它会回滚。这个机制适合把“提交还是回滚”绑定到一段业务代码，但它不会替你关闭连接。

import sqlite3

def add_product(db_path: str, sku: str, stock: int) -> None:
    conn = sqlite3.connect(db_path, autocommit=False)
    try:
        # with 只管理事务结果，不负责连接的 close。
        with conn:
            conn.execute(
                "INSERT INTO products(sku, stock) VALUES(?, ?)",
                (sku, stock),
            )
            # 这里抛出异常时，with 会回滚并继续向外传播异常。
    finally:
        conn.close()  # 连接仍需由应用显式关闭。

因此不要把 with conn: 误写成“自动关闭数据库连接”的语法。官方文档明确区分了这两件事：上下文管理器只负责提交或回滚；如果需要关闭资源，仍应显式调用 close()，或者组合使用专门的关闭上下文。

legacy 模式下 isolation_level 才会接管行为

如果项目需要兼容旧代码，可以显式使用 sqlite3.LEGACY_TRANSACTION_CONTROL，再设置 isolation_level。此时 DEFERRED、IMMEDIATE 和 EXCLUSIVE 代表不同的 SQLite BEGIN 行为；None 则表示不由连接隐式开启事务，应用可以自己执行 BEGIN、COMMIT 或 ROLLBACK。

import sqlite3

def open_legacy_connection(db_path: str) -> sqlite3.Connection:
    # 只有显式选择 legacy 后，isolation_level 才控制隐式事务。
    return sqlite3.connect(
        db_path,
        autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL,
        isolation_level="IMMEDIATE",
    )

conn = open_legacy_connection("orders.db")
try:
    # IMMEDIATE 由底层 SQLite 选择相应 BEGIN 方式，仍需显式提交。
    conn.execute(
        "UPDATE orders SET status=? WHERE id=?",
        ("paid", 1001),
    )
    conn.commit()  # legacy 模式不会因为 execute 成功就替你完成业务提交。
except sqlite3.Error:
    conn.rollback()  # 数据库错误时释放当前未提交的修改。
    raise
finally:
    conn.close()  # 无论提交还是回滚，都关闭连接。

一个容易忽略的边界是：在 legacy 模式下，只有执行 INSERT、UPDATE、DELETE 或 REPLACE 时，非 None 的 isolation_level 才会触发隐式事务；其他语句不一定触发同样的事务处理。executescript() 还会在执行脚本前隐式提交待处理事务，因此不要把它当成普通的多条 execute() 拼接。

用 in_transaction 复查状态，不要猜

Connection.in_transaction 反映的是底层 SQLite 自动提交状态，适合在排查“当前是否仍在事务中”时使用。但它不等价于 Python 侧 autocommit 属性本身，也不能替代业务层的提交策略。

import sqlite3

conn = sqlite3.connect(":memory:", autocommit=False)
try:
    conn.execute("CREATE TABLE events(id INTEGER PRIMARY KEY, name TEXT)")
    # 观察事务状态，用于排查边界，不把它当作提交动作。
    print("after create:", conn.in_transaction)

    conn.execute("INSERT INTO events(name) VALUES(?)", ("ready",))
    print("after insert:", conn.in_transaction)

    conn.commit()  # 状态检查不能替代提交，最终动作仍由 commit 决定。
    print("after commit:", conn.in_transaction)
finally:
    conn.close()  # 诊断结束后释放连接资源。

如果排查的是“为什么写入没有保存”，优先沿着这条证据链检查：连接使用的 autocommit 值、是否处于 legacy、写入后是否显式 commit()、异常路径是否调用 rollback()，以及关闭连接前是否仍有待提交修改。

按业务场景选择并留下复查清单

事务模式的选择不是越新越好，而是要让“哪些数据必须一起成功”变得可读。可以按下面的方式落地：

• 订单、库存、审计等成组写入：优先显式使用 autocommit=False，把提交放在完整业务单元末尾，异常时统一回滚。
• 每条写入都可独立保存：可以选择 autocommit=True，但不要再把 rollback() 当成撤销最近一条写入的手段。
• 维护旧项目：明确写出 LEGACY_TRANSACTION_CONTROL 和 isolation_level，不要让连接默认值掩盖迁移风险。
• 需要自己发出 BEGIN 的场景：legacy 下使用 isolation_level=None，并把 SQL 级事务命令和异常处理写在同一个函数里。
• 所有模式：把 close() 当作资源生命周期动作单独处理，不能用提交或回滚替代关闭连接。

最后给出一份适合代码评审的检查表：

相关问题

autocommit=False 和 isolation_level="DEFERRED" 是一回事吗？

不是。前者是推荐的 Python 侧事务控制方式；后者是 legacy 模式下选择 SQLite BEGIN 行为的参数。只有 autocommit 取 legacy 常量时，isolation_level 才会接管。

调用 close() 会自动提交吗？

不要依赖它提交。显式事务存在待处理修改时，关闭连接可能回滚未提交内容；正确做法是在成功路径先 commit()，在异常路径先 rollback()，最后再 close()。

为什么 with conn: 结束后连接还可以使用？

因为连接上下文管理器只负责事务提交或回滚，不负责关闭连接。需要结束连接时仍要显式调用 close()。

把 autocommit 当作模式选择，把 commit/rollback 当作业务边界，把 close 当作资源边界，Python sqlite3 的事务行为就不再依赖“默认值碰巧符合预期”。