Python sqlite3 backup 的 progress 回调参数怎么解释

Python 的 sqlite3.Connection.backup() 用于把一个 SQLite 连接中的数据库复制到另一个连接。最容易看错的是 progress 回调：它不是直接传入百分比，而是每轮收到 status、remaining、total 三个整数。把这三个值分清后，进度展示和重试日志就都顺了。

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

Python sqlite3 backup 的参数关系先理清

调用方向是源连接执行 src.backup(dst)，其中 dst 是接收备份的目标连接。官方签名可以简化理解为：backup(target, pages=-1, progress=None, name='main', sleep=0.250)。name 用来选择 main、temp 或通过 ATTACH 挂载的数据库名。

progress 要接收三个位置参数；pages 小于等于 0 时倾向于一次复制整个数据库，设置为正数则分批复制。分批的意义是让回调有更多观察点，也给并发访问留下更细的重试机会。

status、remaining、total 分别代表什么

因此进度公式是 copied = total - remaining，百分比是 copied / total * 100。回调频率取决于 pages 和底层备份状态，不应假设每次正好增加相同百分比。

import sqlite3

def show_progress(status, remaining, total):
    # remaining 是未复制页数，total 是本次备份总页数。
    copied = total - remaining
    # 空库或特殊状态下先保护分母，避免日志计算出错。
    percent = copied / total * 100 if total else 100.0
    print(f"status={status}, copied={copied}/{total}, progress={percent:.1f}%")

src = sqlite3.connect("source.db")
dst = sqlite3.connect("backup.db")
try:
    # pages=16 让进度回调按较小批次获得观察点。
    with dst:
        src.backup(dst, pages=16, progress=show_progress, sleep=0.25)
finally:
    # 无论备份是否抛出异常，都释放两个连接。
    dst.close()
    src.close()

pages 和 sleep 怎么配才不误导

pages 越小，回调通常越细，日志更密，单轮工作也更短；但回调和重试管理的开销会增加。pages=-1 适合简单的一次性复制，却不适合需要持续展示进度的脚本。可以先用 16、64 这类小批量观察锁竞争，再按数据库规模调整。

sleep 是备份在等待下一次尝试时的间隔，不能保证两次回调之间恰好休眠这个时间。status 也只是每轮返回的状态信息；判断“备份流程是否走完”时，应以 backup() 正常返回和目标连接可用为主，不要只看某个整数。

相关问题

为什么不能直接把 status 显示成百分比？

status 描述的是迭代状态，不是完成比例。百分比必须用 total - remaining 与 total 计算。

remaining 变小但日志不连续正常吗？

正常。回调按备份迭代触发，pages、锁等待和底层状态都会影响回调间隔。

目标库需要手动 commit 吗？

建议用目标连接的上下文管理器包住备份，并在结束后关闭连接；不要把未关闭连接当成成功凭据。

记住一个判断顺序：先确认源与目标连接，再按 remaining/total 算进度，最后结合 pages 和 sleep 调整观测粒度。这样解释回调参数时，数字和备份行为才能对应起来。