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>
3.5 KiB
3.5 KiB
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 清行)。