Python sqlite3 set_progress_handler 如何中止超时查询

Python 的 sqlite3 没有把“这条查询最多运行几秒”直接做成 execute 参数。要中止长查询，应使用 Connection.set_progress_handler()：SQLite 每执行约 n 条虚拟机指令就回调一次检查函数，函数返回非零值时，当前查询会被终止并抛出数据库异常。connect(timeout=...) 主要解决锁等待，不等于查询执行超时。

先把两种“超时”分开

如果另一个连接持有写锁，connect(timeout=5) 可以让 SQLite 在等待锁时放弃；但 SQL 已经开始执行后，复杂连接、排序或聚合仍可能继续消耗 CPU。此时需要的是“执行预算”：从查询开始计时，超过截止时间就主动取消。

用截止时间注册进度回调

下面的函数只演示取消边界，不依赖真实业务表。回调不要做打印、网络请求或复杂计算，只做一次单调时钟比较；n=1000 是起点，实际项目应根据查询成本和可接受的取消延迟压测调整。

import sqlite3
import time


def execute_with_budget(connection, sql, params=(), budget_seconds=2.0):
    # 用单调时钟计算预算，避免系统时间校准影响超时判断。
    deadline = time.monotonic() + budget_seconds

    def progress_handler():
        # 返回非零值会让 SQLite 终止当前查询。
        return 1 if time.monotonic() >= deadline else 0

    connection.set_progress_handler(progress_handler, 1000)
    try:
        return connection.execute(sql, params).fetchall()
    except sqlite3.DatabaseError as exc:
        # 只把“预算已过期”归类为主动取消，其余数据库错误继续抛出。
        if time.monotonic() >= deadline:
            raise TimeoutError("SQLite 查询超过执行预算") from exc
        raise
    finally:
        # 清掉连接级回调，避免影响下一条 SQL。
        connection.set_progress_handler(None, 0)

这里的关键不是“每两秒强行杀线程”，而是让 SQLite 在自己的虚拟机执行点安全地看到取消信号。回调触发有粒度，实际中止时刻可能略晚于预算；如果 n 设得过大，延迟会更明显，设得过小则会增加回调成本。

异常判断与资源清理怎么做

进度回调返回非零值后，当前 Python 版本的文档将结果描述为数据库异常；不同 Python/SQLite 组合的具体子类可能不同，所以更稳妥的做法是捕获 sqlite3.DatabaseError，再结合本地的截止时间判断是否为主动取消。不要仅凭异常类型认定超时，也不要把所有数据库错误都改写成 TimeoutError。

清理必须放在 finally。因为 progress handler 挂在连接对象上，如果只在成功路径清理，下一条看似无关的查询也可能被旧截止时间立刻中止。连接关闭前同样可以显式清理，便于复用连接池或长生命周期连接。

上线前检查这几个边界

• 预算单位：用秒表达给调用方，用 monotonic() 做比较，不把系统时间字符串参与计算。
• 回调粒度：先用中等 n 值测量取消延迟，再结合 SQL 类型调整，不要盲目追求最小数字。
• 错误归因：只有本地截止时间已到且查询因回调退出时，才包装成超时；语法错误、锁错误和磁盘错误应保留原异常。
• 连接状态：取消后检查事务和游标状态，必要时回滚或重新建立连接，再进入下一次业务操作。

常见问题

1. 能不能直接用 signal.alarm 给 sqlite3 查询计时？

不建议把信号闹钟当作通用方案。它受运行线程和平台限制，还会把中断处理带到 Python 进程层；进度回调更贴近 SQLite 的执行边界。

2. n 越小，超时就越精确吗？

通常取消响应会更快，但回调次数也更多。它只能改善检查粒度，不能保证精确到某个毫秒；应使用代表性 SQL 压测后取平衡值。

3. 查询没超时，为什么回调还要清理？

因为回调是连接级注册状态，不是单条 execute 的局部变量。清理是为了让连接回到可预测的默认状态。

把锁等待、查询执行和错误归因分开，set_progress_handler 才能成为可靠的查询预算控制点，而不是一个“万能 timeout”开关。