Python sqlite3 怎样使用上下文管理事务

我在把一组配置写进 SQLite 时，最容易误解的地方不是 SQL，而是 with con: 到底替我管理了什么。结论很明确：sqlite3.Connection 作为上下文管理器，会在代码块正常结束时提交事务，发生未捕获异常时回滚事务；它不会替你关闭连接，也不会因为进入 with 就凭空开启一个新事务。

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

Connection 上下文管理器到底负责什么

把连接对象交给 with，实际得到的是一个事务边界。写入成功时离开代码块会调用提交逻辑；代码块抛出异常，或者提交本身失败时，会回滚待处理事务，原异常仍然会继续向外抛出。

因此，下面这种写法适合把几条必须同时成功的写入放进同一边界：

import sqlite3

con = sqlite3.connect(":memory:")
try:
    con.execute("CREATE TABLE account(id INTEGER PRIMARY KEY, name TEXT UNIQUE)")
    with con:
        # 使用参数绑定，避免把外部字符串拼进 SQL。
        con.execute("INSERT INTO account(name) VALUES(?)", ("alice",))
        con.execute("INSERT INTO account(name) VALUES(?)", ("bob",))
        # 代码块正常结束时，Connection 会提交这组写入。
finally:
    # with con 只负责事务；连接仍然需要显式关闭。
    con.close()

如果第二条写入触发唯一约束错误，第一条写入也会随事务一起回滚。异常不要在上下文内部静默吞掉，否则调用方无法知道这组操作没有完成。

用一个事务包住成组写入

更贴近业务代码的结构是先准备连接，再把“必须原子完成”的操作集中到一个 with con 中。查询可以放在事务内，也可以放在提交之后；关键是不要把无关的慢操作塞进写事务，避免锁持有时间变长。

import sqlite3

def save_order(db_path, order_id, item_name):
    con = sqlite3.connect(db_path)
    try:
        # 建表属于示例初始化；真实项目通常在迁移脚本中完成。
        con.execute("CREATE TABLE IF NOT EXISTS orders(id INTEGER PRIMARY KEY, item TEXT NOT NULL)")
        with con:
            # 两个写入要么一起提交，要么一起回滚。
            con.execute("INSERT INTO orders(id, item) VALUES(?, ?)", (order_id, item_name))
            con.execute("INSERT INTO orders(id, item) VALUES(?, ?)", (order_id + 100000, "audit:" + item_name))
    except sqlite3.Error:
        # 记录或转换异常后继续抛出，不能把失败伪装成成功。
        raise
    finally:
        # 无论提交还是回滚，连接都要释放。
        con.close()

这里的重点是职责分离：with con 管提交和回滚，finally 管连接生命周期。两层职责写在一起，后续改成连接池或服务函数时也更容易替换。

为什么 with con 不等于 close

官方文档特别强调，Connection 上下文管理器不会隐式关闭连接。只写 with con:，代码块结束后连接对象仍然存在；如果长期创建连接而不调用 close()，还会留下文件句柄和未处理资源。

如果希望把“关闭连接”也纳入上下文，可以使用 contextlib.closing，并在里面再嵌套事务上下文：

from contextlib import closing
import sqlite3

def add_user(db_path, username):
    # closing 负责 close；内部的 with con 负责 commit 或 rollback。
    with closing(sqlite3.connect(db_path)) as con:
        with con:
            # 参数元组最后的逗号不能省略，否则不是单元素元组。
            con.execute("INSERT INTO users(name) VALUES(?)", (username,))
        # 离开内层 with 后事务已经结束，离开外层 with 才关闭连接。

如果项目不想引入嵌套结构，也可以继续用 try/finally。两种方式的目标相同：提交/回滚和关闭连接分别有明确的负责人。

autocommit 与 isolation_level 怎么选

Python 3.12 起，sqlite3.connect() 增加了 autocommit 参数，当前文档推荐通过它控制事务行为。设置为 False 时采用 DB-API 风格的事务控制，需要显式 commit() 或 rollback()；设置为 True 时进入 SQLite 的自动提交模式，此时 commit() 和 rollback() 不起作用；默认值目前仍是兼容旧行为的 LEGACY_TRANSACTION_CONTROL。

import sqlite3

def update_status(db_path, task_id, status):
    # Python 3.12+ 可显式选择推荐的 DB-API 事务语义。
    con = sqlite3.connect(db_path, autocommit=False)
    try:
        with con:
            # 事务提交点由 with con 的正常退出决定。
            con.execute("UPDATE task SET status = ? WHERE id = ?", (status, task_id))
    finally:
        # autocommit 的选择不改变连接需要关闭这一事实。
        con.close()

旧代码里常见的 isolation_level 仍然有兼容价值，但它只在 autocommit=LEGACY_TRANSACTION_CONTROL 时生效。不要一边显式选择新的 autocommit 语义，一边又期待 isolation_level 改写事务行为。

几个容易踩到的边界

• 只读查询不一定需要写事务。 如果代码块没有待处理事务，退出上下文时可能没有提交或回滚动作。
• 关闭前要关注未提交变更。 在合适的事务模式下，带有待处理变更的 close() 可能回滚它们；需要保留的数据应先明确提交。
• 连接关闭不是游标关闭的替代说明。 简单场景可直接使用 Connection 的 execute() 快捷方法；复杂查询仍要管理好返回对象的使用范围。
• 不要把异常处理写成“无条件提交”。 先判断业务操作是否完整，再让上下文管理器根据正常退出或异常退出选择提交、回滚。

最后的使用判断

如果目标是“这一组写入必须原子完成”，使用 with con；如果目标是“连接一定释放”，再加 closing 或 finally。两者不是同一件事。对 Python 3.12 及以上的新代码，可以显式考虑 autocommit=False；对需要兼容旧运行环境的项目，则应先确认当前 Python 版本和既有事务约定，再决定是否迁移。

相关问题

sqlite3 的 with 代码块抛异常后还会继续向外抛吗？ 会。上下文管理器负责回滚待处理事务，但不会自动吞掉原异常。

为什么 with sqlite3.connect(...) 没有自动关闭连接？ 因为 Connection 的上下文协议专门承担事务提交和回滚，关闭连接需要 close()、closing 或 finally。

新项目应该优先写 isolation_level 还是 autocommit？ 当前 Python 文档推荐用 autocommit 控制事务；isolation_level 主要用于兼容旧的 legacy 事务控制。