Files
archer/openspec/changes/add-realtime-progress/design.md
T
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-06 22:12:17 +08:00

9.6 KiB
Raw Blame History

Context

现状与动机见 proposal.md。与设计直接相关的几个约束:

  • 运行循环是单线程的(internal/app/app.go 的 execute → processChunk),计数分散在 Stats 结构体的裸字段里,直接加后台 goroutine 会产生 data race。
  • 唯一能让"长阻塞期间仍有输出"的办法是后台定时器:scan.Next、fsync、lag.Wait 都无法在阻塞点内部插入回调。
  • 扫描器(internal/scan)的状态不是并发安全的;进度不能从后台线程直接读扫描器或 writer。
  • 项目刻意保持零额外依赖(go.mod 只有 MySQL 驱动与压缩库),且需兼容 Windows conhost。
  • 现有 --progress N 是 int,默认 0 = 关闭;--statistics 与 --dry-run 输出在 stdout。

Goals / Non-Goals

Goals:

  • 终端里能一眼看到"进行到哪、还剩多久、是不是卡住了"。
  • 重定向到日志时可按需得到稳定、完整、可 tail 的进度行。
  • 估算成本有上界,估不出来就诚实地不显示。
  • 进度实现与归档逻辑解耦,可注入时钟与 writer 做单测。

Non-Goals:

  • 不做机器可读事件流(JSONL)、颜色、多行 TUI。
  • 不做精确 COUNT(*) 或后台异步计数。
  • 不改变 chunk / 事务 / 文件 / checkpoint 的任何语义。
  • 不为 export-all 脚本实现多表聚合进度(脚本可用 --progress on 获取日志行)。

Decisions

D1:新增 internal/progress 作为深模块

Reporter 对外只暴露少量方法:Start/Stop、Phase、AddRows、SetPosition、SetEstimate、Message、Snapshot。渲染、TTY 判定、速率窗口、ETA 全部藏在内部。app 只负责在正确的时机推送事件,不知道渲染细节。

替代方案是直接在 app.go 里加 ticker 和格式化逻辑,但 app.go 已经 600 行且承担编排职责;把渲染测试塞进 app 会让集成测试更难写。

D2:--progress 改为 auto|on|off|N,而不是新增一堆布尔开关

仓库已有 --progress N 的调用方(集成测试、脚本),必须保留 N>0 的行阈值语义。把 flag 实现为自定义 flag.Value:

  • auto(默认):TTY 时开启,非 TTY 静默。
  • on:始终开启,非 TTY 时退化为周期行。
  • off / 0:关闭。
  • N>0:开启并额外按行阈值触发。

替代方案是保留 int 并用 -1 表示 auto;但 --progress -1 语义不直观,且 argparse 风格上容易被误读为错误。字符串取值可以把三种意图明确写进 --help。

D3:进度写 stderr,消息也收口到 Reporter

stderr 是"给人看的诊断流",stdout 留给 --dry-run 和显式请求的 --statistics。这也让 archer ... > result.txt 不会把进度写进结果文件。

app.go 现有 6 处直接 fmt.Fprintln(os.Stderr, ...)(启动提示、指纹警告、purge 警告、中断警告、lag 等待)必须改走 Reporter.Message。Message 在 live 模式下先清当前行、打印整行消息,再在下一拍重绘;非 live 模式直接打印。main.go 的错误输出发生在 Run 返回之后,reporter 已停止,不需要改。

替代方案是让渲染器在检测到行长度变化时自行清行,但那样消息输出顺序无法保证,仍可能撕裂 live 行。

D4:TTY 判定与渲染

用标准库 os.Stderr.Stat() 判断 ModeCharDevice,不引入 x/term。live 模式单行渲染:

[###############-----]  58% ~4.12M rows  18.2k/s  scan 0.4s  shard 12  eta ~1m36s
  • 只用 \r 回到行首,行尾用空格补齐到上一次宽度,不使用 \x1b[K 或颜色,保证 conhost 正常。
  • 行宽目标 ≤ 100 字符;超宽时按优先级裁剪字段(先去掉分片序号与字节数,再缩短 bar),不换行。
  • 无百分比时省略 bar/百分比/ETA,只留 rows、rate、phase、elapsed。
  • 非 live 模式固定输出 progress: rows=... pct=... estimate=... rate=... phase=... elapsed=...,字段顺序稳定。

D5:阶段由主循环推送,Reporter 只记录

阶段切换点全部在 app 内:probe(setupSource)、resume(prepareFile 中 Manifest.Adopt)、estimate、scan/file/db/checkpoint(processChunk 内)、finalize(finish)、lag-wait(lag.OnWait)。Reporter 为每次 Phase() 调用累加前一阶段耗时并重置阶段计时。

扫描器与 writer 的状态不由后台线程读取:主循环在 chunk 完成后调用 SetPosition(bucket, seq, bytes, lastKey),把 writer 的 StatePosition/Stats 结果和当前键位置复制进快照。这样后台线程只接触 Reporter 内部数据。

D6:并发模型:互斥量保护快照

Reporter 内部一个 sync.Mutex 保护 snapshot 结构(计数、阶段、阶段开始时间、估算、位置、消息代数)。主循环的 AddRows/Phase/SetPosition 都是短临界区;ticker 每次加锁复制一份快照,解锁后渲染。相比把每个字段拆成 atomic.Int64,互斥量让"一组字段的一致快照"更容易保证,也避免 atomic.Value 里放结构体的分配开销。

Stats 继续由主循环独占,供 --statistics 使用;Reporter 不反向写 Stats。两者在结束时由 app 汇总。

D7:估算查询:有界、只读、可放弃

估算在 prepare 之后、进入扫描前执行一次:

  • 日期模式:SELECT MIN(shard_col), MAX(shard_col) FROM t WHERE (where) AND shard_col IS NOT NULL。
  • 非日期模式:仅当扫描键为单列整数类型时执行 SELECT MIN(key), MAX(key) FROM t WHERE (where)。
  • 复合键、字符串/二进制键、或表没有可用索引时直接跳过。

查询在独立 *sql.Conn 上执行,context.WithTimeout(2s)。超时或出错则 SetEstimate(nil),此后不显示百分比与 ETA,不重试。

路径 B 的扫描器稍后还会自己算一次 MIN/MAX(initDays)。这里接受一次重复的索引范围查询,换取 Reporter 与扫描器解耦;该查询与路径 B 首次查询量级相同,不影响正确性。

替代方案是让扫描器实现 EstimateProvider 接口,但那会把并发发布职责扩散到三个扫描器实现里。

D8:位置与百分比口径

  • 日期模式:位置取当前 chunk 尾行的 bucket(chunk.Buckets 已有),百分比 = 已完成天数 / 总天数;显示 day 37/120,estimate=day。NULL 与零日期阶段单独处理,未进入正常日期前不显示天数进度。
  • 非日期模式:位置取 chunk.LastKey[0] 的数值,百分比 = (当前键 − 最小键) / (最大键 − 最小键),estimate=key。
  • 续跑时位置来自游标,天然包含此前进度。

已知口径限制写进 Risks,不在代码里假装精确。

D9:速率与 ETA

Reporter 维护最近约 5 秒的 (时间, 进度位置) 样本环,速率用窗口内差分计算;不足两个样本时回退到累计平均。ETA = 剩余量 / 窗口速率,其中剩余量由百分比口径推导(天数或键跨度),而不是行数——因为总行数未知。ETA 与百分比一样带 ~,且只在 estimate != none 时显示。

D10:生命周期

  • execute 开始时 Start,finish 与 interrupt 结束时 Stop。
  • Stop 先停 ticker、清 live 行;正常完成再输出 done 行,中断则输出最终快照行。
  • interrupt 的执行顺序:停刷新 → 清行 → 快照 → 现有 SealCurrent → saveState,退出码不变。
  • --dry-run 不启动 Reporter(没有运行循环)。

D11:续跑基线

prepareFile 读到 state.json 后,除现有游标外记录 baseRows = st.RowsDone。Reporter 的 rows 指标显示 baseRows + 本次 RowsRead;saveState 写入 baseRows + 本次 RowsCommitted。--statistics 增加"本次 / 累计"两列。

D12:不新增依赖

TTY 判定用 os.File.Stat;时间源注入 func() time.Time;渲染目标注入 io.Writer。单测不需要伪终端,直接用 bytes.Buffer + 手动推进时钟。

Risks / Trade-offs

  • 估算查询在繁忙库上仍可能拖慢启动 → 2s 上下文超时 + 只在启动时一次 + 绝不 COUNT(*);超时后彻底放弃,不重试。
  • 键位置百分比在键有空洞或分布不均时偏差大 → 标注 estimate=key 与 ~;日期模式优先按天;任何估算都不影响归档逻辑。
  • 日期模式的百分比按天跳变 → 显示 day 37/120 原文,让操作者看到真实口径;不把天进度伪装成行进度。
  • 升级后首次续跑旧 checkpoint 时 rows_done 仍可能偏低 → 旧版本写入的值只是上次运行的行数;无法还原真实累计。文档说明该限制,不做迁移;新写入的值从此正确。
  • live 行与日志交错 → 所有 stderr 消息经 Reporter.Message;单测覆盖"消息插入后行内容完整"。
  • Windows conhost 不支持复杂控制序列 → 只使用 \r + 空格补齐;不引入颜色与光标移动。
  • 进度从 stdout 转到 stderr 会改变现有调用方 → 集成测试更新;README/spec 明确通道;脚本本来就把 stderr 重定向进日志。
  • ticker 增加少量锁竞争 → 每秒一次、临界区仅是字段复制与格式化,开销可忽略。

Migration Plan

  • 仅发布新二进制,无数据迁移;state.json 版本不变,旧文件可读。
  • 升级后第一次续跑可能沿用旧的偏低 rows_done,完成后即恢复累计语义。
  • scripts/export-all.ps1 的 -Verify 在历史 checkpoint 上可能仍报一次差异,重新完成后消失;如需日志内进度,可给 archer 加 --progress on。
  • 回滚到旧二进制不影响运行;旧二进制会按旧语义覆盖 rows_done,仅丢失累计值。