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>
9.6 KiB
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,仅丢失累计值。