Python sqlite3 怎样用 set_trace_callback 追踪实际执行的 SQL

在 Python 的 sqlite3 调试中，如果只看业务代码里的 execute()，经常解释不了“为什么多了一条 SQL”或“事务到底什么时候触发”。直接做法是给连接注册 set_trace_callback()：SQLite 后端实际执行语句时，回调会收到一段 SQL 文本；调试结束后传入 None 即可关闭。

官方文档：https://docs.python.org/3/library/sqlite3.html

set_trace_callback 适合临时观察和定位 SQL 来源，不应直接替代审计日志。它能观察到事务管理和触发器带来的语句，但回调内部异常默认不会直接传回业务调用方。

最小接入：给连接安装可关闭的追踪回调

回调只需要接收一个字符串参数。下面的写法把追踪范围限制在一个连接对象上，并把关闭动作放进清理阶段：

import sqlite3

def trace_sql(statement: str) -> None:
    # 这里只做调试输出；生产日志应按字段和敏感信息要求脱敏。
    print(f"[sqlite-trace] {statement}")

connection = sqlite3.connect(":memory:")
connection.set_trace_callback(trace_sql)

try:
    # 这些调用会让 SQLite 后端产生可观察的 SQL 语句。
    connection.execute("create table user_profile (id integer primary key, name text)")
    connection.execute("insert into user_profile(name) values (?)", ("林默",))
    connection.execute("select id, name from user_profile where id = ?", (1,)).fetchone()
finally:
    # 传入 None 会移除追踪回调，避免连接继续输出调试信息。
    connection.set_trace_callback(None)
    connection.close()

这里有两个容易忽略的点：第一，回调安装在 Connection 上，不是某个游标上；第二，回调的返回值会被忽略，所以它不是改写 SQL 或拦截执行的接口。

回调看到的是什么：实际执行语句，而不是源码行号

set_trace_callback() 的参数是实际执行的语句文本。它不会替你提供 Python 文件名、调用栈或业务请求 ID，因此如果要把追踪信息和请求关联起来，需要在回调闭包中加入已经脱敏的上下文：

import sqlite3

def make_trace_callback(request_id: str):
    def trace(statement: str) -> None:
        # request_id 应使用内部短标识，不要把用户隐私或令牌拼进日志。
        print({"request_id": request_id, "sql": statement})
    return trace

connection = sqlite3.connect(":memory:")
connection.set_trace_callback(make_trace_callback("req-42"))
try:
    connection.execute("select 1")
finally:
    # 连接释放前先撤销回调，避免后续复用时带着旧请求上下文。
    connection.set_trace_callback(None)
    connection.close()

这个回调仍然只是观察入口。不要在其中执行同一个连接的额外 SQL，也不要把它设计成业务鉴权、SQL 审批或可靠的操作审计组件。

为什么会出现没有直接写在 execute() 里的语句

官方文档特别说明，后端执行的不只有传给 Cursor.execute() 的语句，还可能包括 sqlite3 模块的事务管理，以及当前数据库中定义的触发器。因此，追踪输出更适合回答“SQLite 实际看到了哪些语句”，而不是简单地把每条输出都归因给一行 Python 源码。

可以按下面三个来源理解日志：

• 业务调用：你的 execute()、executemany() 或游标操作直接形成的 SQL。
• 事务管理：连接的事务模式和提交边界可能让日志出现额外的事务相关语句。
• 数据库对象：触发器等数据库定义在执行过程中产生的关联语句。

排查时，先把日志按“直接调用、事务相关、触发器相关”分组，再回到数据库定义和连接配置核对。不要因为输出比源码多，就直接判断驱动重复执行了业务逻辑。

回调异常为什么没有直接抛回业务代码

追踪函数自身也可能出错，例如格式化上下文时访问了不存在的字段。Python 文档说明，追踪回调抛出的异常不会直接传播到触发 SQL 的业务调用方；开发调试时可以打开 enable_callback_tracebacks(True)，让回调异常输出到标准错误，帮助定位问题。

import sqlite3

sqlite3.enable_callback_tracebacks(True)

def trace(statement: str) -> None:
    # 调试阶段故意保留简单逻辑，避免回调异常掩盖原始 SQL 问题。
    print(statement.upper())

connection = sqlite3.connect(":memory:")
connection.set_trace_callback(trace)
try:
    connection.execute("select 1")
finally:
    # 调试开关和追踪回调都属于进程级/连接级行为，应在任务结束后恢复边界。
    connection.set_trace_callback(None)
    connection.close()

这个开关是辅助定位，不等于把回调异常变成正常的业务异常处理流程。如果回调承担了复杂逻辑，应该把它简化为低成本记录，并在测试中单独覆盖日志格式化函数。

调试完成后怎样正确关闭

最稳妥的顺序是“先关闭回调，再提交或回滚业务事务，最后关闭连接”。如果连接会被连接池复用，更要在归还连接前执行 set_trace_callback(None)，否则下一个请求可能继续写入上一个请求的调试上下文。

def close_connection(connection: sqlite3.Connection) -> None:
    try:
        # 先切断调试输出，避免 close 过程产生的语句混入业务日志。
        connection.set_trace_callback(None)
    finally:
        # 这里仅负责释放连接；提交或回滚应由拥有事务的业务层决定。
        connection.close()

不要在回调中调用 commit()、rollback() 或再次查询同一个连接。这样做会把观察逻辑和事务控制耦合起来，导致日志本身改变被观察的行为。

set_trace_callback 和相近工具怎么选

因此，常见的组合是：应用日志记录请求上下文，set_trace_callback 在开发或短时排障阶段观察 SQL，问题定位完成后立即关闭。若要长期保存操作记录，应设计独立的审计数据模型，而不是永久打开追踪回调。

常见问题

为什么回调里没有看到我以为会出现的所有内部动作？

回调观察的是 SQLite 后端实际执行的语句，不是 Python 解释器的每一步，也不是所有驱动内部动作的通用事件流。先确认动作是否真的形成了 SQL，再检查事务模式和触发器定义。

可以用回调统计生产环境的 SQL 次数吗？

可以做短时、低成本的诊断，但不宜把它当作完整性能统计方案。回调会增加日志开销，还可能暴露敏感 SQL 文本；长期指标应使用专门的应用指标和采样策略。

怎样停止追踪？

对同一个连接调用 connection.set_trace_callback(None)。如果连接会复用，把它放在归还连接池之前；如果连接不再使用，再调用 close()。

总结

Python sqlite3 的 set_trace_callback 是一个面向调试的连接级观察入口：用回调接收实际执行的 SQL，用 None 关闭，用 enable_callback_tracebacks(True) 辅助定位回调自身异常。解释日志时要把业务调用、事务管理和触发器分开；需要请求关联、审计和长期指标时，再交给应用日志或专门的观测系统。