Files
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

3.5 KiB
Raw Permalink Blame History

Why

archer 面向的是长时间运行的大表归档/导出,但当前唯一的进度输出(--progress N)只在 chunk 完整处理完后按行数阈值打印一行,既没有速率、百分比和 ETA,也不显示当前处于扫描、写文件、写库还是等待副本延迟。路径 B 的单日长查询、fsync 与 lag.Wait 期间完全没有输出,操作者无法区分"正在慢"和"已经卡死";续跑后进度与 state.json 的行数还会从零重新起算。

这次改动把进度从"稀疏日志"变成"给人看的实时显示",同时修正续跑计数语义。

What Changes

  • 新增默认 --progress auto:stderr 是终端时输出单行实时刷新(\r 覆盖、空格补齐、不使用 ANSI 清行与颜色,兼容 Windows conhost);非终端时保持静默。
  • --progress on|off|auto|N:on 强制开启(非终端时按间隔输出稳定的 key=value 行,便于 tail 日志),N>0 保留现有行阈值语义,off/0 关闭。新增 --progress-interval(默认 1s)。
  • 进度行统一写 stderr;--dry-run 与 --statistics 仍在 stdout。
  • 显示内容包含 rows、窗口速率、分片序号、已写字节、当前阶段及各阶段耗时、elapsed;在能廉价估算总量时额外显示带 ~ 的百分比与 ETA,并标注估算口径(day|key)。
  • 新增阶段模型:probe → resume → estimate → scan → file → db → checkpoint → finalize,lag-wait 作为 scan 前的独立阶段;长阻塞期间持续刷新。
  • 进度开启时,结束打印一行 done 汇总;中断时停止刷新、清除 live 行并打印最终快照后再执行现有的封片与 checkpoint。
  • BREAKING(行为):state.json 的 rows_done 改为累计值(含续跑前已处理行数)。旧 checkpoint 继续可读;语义变化会影响依赖该字段的校验脚本(修正 scripts/export-all.ps1 -Verify 的误报)。
  • --statistics 分开展示"本次运行"与"累计(含续跑)"。
  • 应用内所有面向人的警告与 lag 提示收口到进度 reporter,避免与 live 行交错。

非目标:JSONL/机器可读进度、彩色输出、多行 TUI、精确 COUNT(*)、后台异步计数、export-all 脚本自身的多表进度条(脚本可通过 --progress on 获得日志行)。

Capabilities

New Capabilities

  • progress-reporting: 进度输出的模式与降级、显示指标与格式、廉价总量估算与回退、阶段模型、中断与完成时的最终快照、续跑基线语义。

Modified Capabilities

  • cli-contract: --progress 的取值与默认值、新增 --progress-interval、进度输出通道(stderr)及 TTY/非 TTY 行为。
  • archive-core: 运行循环的阶段标记、lag 等待期间的进度、中断时的最终快照,以及 state.json 中 rows_done 的累计语义与 --statistics 口径。

Impact

  • 代码:新增 internal/progress;修改 internal/app/app.go(阶段标记、消息收口、续跑基线、done/中断快照)、internal/app/probe.go 或扫描器(暴露日期/键边界供估算)、internal/cli/{parse,config,validate}.go、internal/checkpoint 使用方、internal/lag 的等待回调。
  • 输出契约:进度从 stdout 移到 stderr;集成测试中按 stdout 抓 progress: 的用例需要更新。
  • 脚本:scripts/export-all.ps1 的 -Verify 恢复正确;可选加 --progress on 让日志可 tail -f。
  • 依赖:不新增第三方库(TTY 判定使用标准库;不使用 ANSI 清行)。