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

137 lines
9.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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`,仅丢失累计值。