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>
This commit is contained in:
commit
bc4a6b504f
99 files changed
+12752
No files matched your search
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-06
|
||||
@@ -0,0 +1,136 @@
|
||||
## 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`,仅丢失累计值。
|
||||
@@ -0,0 +1,37 @@
|
||||
## 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 清行)。
|
||||
@@ -0,0 +1,71 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 断点续跑
|
||||
|
||||
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。`state.json` 中记录的源连接与目标连接 MUST 采用标准 MySQL DSN 形式(去除密码),例如 `user@tcp(host:3306)/db?charset=utf8mb4`。续跑时 MUST 校验源、表、过滤条件、列、分片参数、时区、输出格式、压缩设置,以及源/目标连接的全部规范化参数(含字符集与排序规则)的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。密码 MUST NOT 计入指纹,也 MUST NOT 写入 `state.json`。压缩档位仅在启用压缩且档位不是默认值 3 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。`rows_done` MUST 表示该输出目录累计已提交的行数(含续跑前已提交的部分),MUST NOT 在续跑后被重置为本次运行的行数。
|
||||
|
||||
#### Scenario: 配置一致时续跑
|
||||
|
||||
- **WHEN** 上次运行在 chunk 中途退出,且本次配置指纹一致
|
||||
- **THEN** 系统从 `state.json` 记录的游标位置继续,不重复处理已提交的 chunk
|
||||
|
||||
#### Scenario: 配置被修改
|
||||
|
||||
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出不一致的字段,拒绝开始扫描
|
||||
|
||||
#### Scenario: 压缩档位被修改
|
||||
|
||||
- **WHEN** 续跑时 `--compress-level` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出 `compress_level` 字段的变化,拒绝开始扫描
|
||||
|
||||
#### Scenario: 默认档位兼容存量任务
|
||||
|
||||
- **WHEN** `state.json` 由引入压缩档位之前的版本写入,且本次使用默认档位 3
|
||||
- **THEN** 指纹一致,系统正常续跑
|
||||
|
||||
#### Scenario: 连接字符集被修改
|
||||
|
||||
- **WHEN** 续跑时 `--source` 的 `charset` 或 `collation` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出 `source` 字段的变化,拒绝开始扫描
|
||||
|
||||
#### Scenario: 密码轮换
|
||||
|
||||
- **WHEN** 续跑时仅 `--source` 或 `--dest` 的密码与上次运行不同
|
||||
- **THEN** 指纹一致,系统正常续跑
|
||||
|
||||
#### Scenario: 连接信息的存储形态
|
||||
|
||||
- **WHEN** 查看任意一次运行生成的 `state.json`
|
||||
- **THEN** `config.source` 与 `config.dest` 为标准 MySQL DSN,且不包含密码明文
|
||||
|
||||
#### Scenario: 续跑后累计行数
|
||||
|
||||
- **WHEN** 首次运行提交 10000 行后中断,随后续跑提交剩余 40000 行
|
||||
- **THEN** 完成后的 `state.json` 中 `rows_done` 为 50000,而不是 40000
|
||||
|
||||
#### Scenario: 校验脚本读取累计值
|
||||
|
||||
- **WHEN** 一次经过续跑的导出完成后,外部脚本读取 `state.json` 的 `rows_done` 并与源表匹配行数比较
|
||||
- **THEN** 两者一致,不产生误报
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 运行阶段顺序
|
||||
|
||||
系统 SHALL 在运行中维护以下阶段:`probe`、`resume`、`estimate`、`scan`、`file`、`db`、`checkpoint`、`finalize`。启用复制延迟保护时,每个 chunk 拉取前 MUST 进入 `lag-wait` 阶段。单个 chunk 的处理顺序 MUST 为 `lag-wait → scan → file → db → checkpoint`。阶段切换 MUST 对进度输出可见,且任一阶段持续期间 MUST NOT 阻断周期性进度刷新。
|
||||
|
||||
#### Scenario: 等待副本延迟
|
||||
|
||||
- **WHEN** 副本延迟超过 `--max-lag`
|
||||
- **THEN** 系统进入 `lag-wait` 阶段并持续输出进度,直到延迟恢复
|
||||
|
||||
#### Scenario: 恢复后进入扫描
|
||||
|
||||
- **WHEN** 延迟恢复到 `--max-lag` 以下
|
||||
- **THEN** 系统离开 `lag-wait`,按 `scan → file → db → checkpoint` 处理下一个 chunk
|
||||
|
||||
#### Scenario: 长时间扫描
|
||||
|
||||
- **WHEN** 路径 B 的单日查询长时间未返回首个 chunk
|
||||
- **THEN** 阶段保持 `scan`,进度刷新不中断,操作者可观察到阶段耗时增长
|
||||
@@ -0,0 +1,68 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 默认值
|
||||
|
||||
系统 SHALL 采用以下默认值:`--chunk-size 2000`、`--shard-by none`、`--shard-rows 0`、`--format dump`、`--compress none`、`--compress-level 3`、`--max-lag 1s`、`--check-interval 1s`、`--retries 1`、`--safe-auto-increment true`、`--progress auto`、`--progress-interval 1s`。
|
||||
|
||||
#### Scenario: 最小可运行配置
|
||||
|
||||
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
|
||||
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
|
||||
|
||||
#### Scenario: 默认进度模式
|
||||
|
||||
- **WHEN** 用户未显式指定 `--progress`
|
||||
- **THEN** stderr 是终端时显示实时进度,否则不输出进度行
|
||||
|
||||
### Requirement: 参数依赖与互斥
|
||||
|
||||
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge` 且在日期模式下禁止;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误;`--progress` MUST 取值 `auto`、`on`、`off` 或非负整数;`--progress-interval` MUST 为正时长。违反时 MUST 在启动阶段报错。
|
||||
|
||||
#### Scenario: 数量模式误传日期列
|
||||
|
||||
- **WHEN** `--shard-by count` 同时带上 `--shard-column`
|
||||
- **THEN** 系统报错,说明该参数仅在日期模式下有效
|
||||
|
||||
#### Scenario: 未启用 purge 却要求 bulk-delete
|
||||
|
||||
- **WHEN** 用户指定 `--bulk-delete` 但未指定 `--purge`
|
||||
- **THEN** 系统报错,说明 bulk-delete 必须配合 purge
|
||||
|
||||
#### Scenario: 插入模式互斥
|
||||
|
||||
- **WHEN** 用户同时指定 `--insert-ignore` 与 `--replace`
|
||||
- **THEN** 系统报错,要求只能选择一种插入模式
|
||||
|
||||
#### Scenario: 压缩档位越界
|
||||
|
||||
- **WHEN** 用户指定 `--compress-level 0` 或 `--compress-level 10`
|
||||
- **THEN** 系统在启动阶段报错,说明档位必须在 1–9 之间
|
||||
|
||||
#### Scenario: 不压缩却指定非默认档位
|
||||
|
||||
- **WHEN** 用户指定 `--compress none` 与 `--compress-level 5`
|
||||
- **THEN** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
|
||||
|
||||
#### Scenario: 非法进度参数
|
||||
|
||||
- **WHEN** 用户指定 `--progress abc`、`--progress -1` 或 `--progress-interval 0s`
|
||||
- **THEN** 系统在启动阶段报错,说明取值要求
|
||||
|
||||
### Requirement: 进度与统计
|
||||
|
||||
`--progress` SHALL 接受 `auto`、`on`、`off` 或非负整数,默认 `auto`。`auto` 时,stderr 是终端则启用实时进度,否则不输出进度行;`on` MUST 始终启用;`off` 与 `0` MUST 关闭;正整数 MUST 额外作为每处理 N 行触发一次的行阈值。`--progress-interval` MUST 控制最小输出间隔,默认 `1s`。所有进度输出 MUST 写入 stderr;`--dry-run` 与 `--statistics` 的输出 MUST 保持在 stdout。启用 `--statistics` 时,系统 MUST 在结束时分别输出本次运行与含续跑的累计读取行数、写入行数、删除行数、分片数与各阶段耗时。
|
||||
|
||||
#### Scenario: 周期进度
|
||||
|
||||
- **WHEN** `--progress 100000`
|
||||
- **THEN** 系统至少每 `--progress-interval` 输出一次进度,并在每处理 100000 行时额外输出一次
|
||||
|
||||
#### Scenario: 终端实时进度
|
||||
|
||||
- **WHEN** stderr 是终端且进度启用
|
||||
- **THEN** 系统在同一行内刷新进度,并输出到 stderr
|
||||
|
||||
#### Scenario: 结束统计
|
||||
|
||||
- **WHEN** 启用 `--statistics`
|
||||
- **THEN** 进程退出前输出汇总统计,并区分本次运行与含续跑的累计值
|
||||
@@ -0,0 +1,138 @@
|
||||
## Purpose
|
||||
|
||||
定义 archer 面向操作者的实时进度显示:何时显示、显示什么、百分比与 ETA 如何估算与降级,以及完成和中断时的最终反馈,使长时间归档任务的运行状态可被直接观察。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 进度模式与输出通道
|
||||
|
||||
`--progress` SHALL 接受 `auto`、`on`、`off` 或正整数,默认 `auto`。`auto` 时,当 stderr 是终端则启用实时进度,否则 MUST 不输出任何进度行。`on` MUST 始终启用进度。`off` 或 `0` MUST 关闭进度。正整数 MUST 在按间隔输出之外,额外作为"每处理 N 行至少触发一次"的行阈值。
|
||||
|
||||
所有进度输出 MUST 写入 stderr。`--dry-run` 与 `--statistics` 的输出 MUST 保持在 stdout。启用 `--progress-interval` 且值为非正数时 MUST 视为配置错误。
|
||||
|
||||
#### Scenario: 终端下的默认模式
|
||||
|
||||
- **WHEN** 用户未传 `--progress`,且 stderr 是终端
|
||||
- **THEN** 系统显示实时进度
|
||||
|
||||
#### Scenario: 重定向时的默认模式
|
||||
|
||||
- **WHEN** 用户未传 `--progress`,且 stderr 被重定向到文件或管道
|
||||
- **THEN** 系统不输出进度行,只有警告与错误信息
|
||||
|
||||
#### Scenario: 强制开启写入日志
|
||||
|
||||
- **WHEN** 用户传 `--progress on`,且 stderr 被重定向
|
||||
- **THEN** 系统按 `--progress-interval` 向 stderr 输出进度行,每行是一条完整的 key=value 记录
|
||||
|
||||
#### Scenario: 关闭进度
|
||||
|
||||
- **WHEN** 用户传 `--progress off` 或 `--progress 0`
|
||||
- **THEN** 系统不输出任何进度行
|
||||
|
||||
#### Scenario: 非法进度参数
|
||||
|
||||
- **WHEN** 用户传 `--progress abc` 或 `--progress-interval 0s`
|
||||
- **THEN** 系统在连接数据库前以配置错误退出
|
||||
|
||||
### Requirement: 刷新节奏
|
||||
|
||||
系统 MUST 至少每隔 `--progress-interval`(默认 `1s`)输出一次进度,并在启用行阈值时于跨过阈值的 chunk 边界额外输出。无论是否到达间隔或阈值,完成与中断时 MUST 输出一次最终快照。
|
||||
|
||||
#### Scenario: 慢 chunk 仍在刷新
|
||||
|
||||
- **WHEN** 单个 chunk 的扫描或写库耗时超过 `--progress-interval`
|
||||
- **THEN** 系统在该 chunk 处理期间仍按间隔输出进度,不出现长时间静默
|
||||
|
||||
#### Scenario: 行阈值提前触发
|
||||
|
||||
- **WHEN** `--progress 100000`,且两个间隔之间处理行数超过 100000
|
||||
- **THEN** 系统在跨过阈值时额外输出一次进度
|
||||
|
||||
### Requirement: 显示指标
|
||||
|
||||
终端模式下,进度 MUST 以单行原地刷新(使用回车覆盖并以空格补齐,不依赖 ANSI 清行或颜色)。进度行 MUST 包含:已处理行数、当前速率、当前阶段及阶段内耗时、本次运行已用时间。当当前分片存在时 MUST 包含分片序号;写入文件时 MUST 包含已写字节数。存在总量估算时 MUST 额外包含百分比与 ETA,并以 `~` 标注为估算值。
|
||||
|
||||
非终端模式下,每行 MUST 是一条独立、完整、稳定的 key=value 记录,至少包含 `rows`、`rate`、`phase`、`elapsed`;存在估算时包含 `pct`、`estimate` 与 `eta`。记录 MUST NOT 使用回车覆盖。
|
||||
|
||||
#### Scenario: 终端单行刷新
|
||||
|
||||
- **WHEN** stderr 是终端且进度启用
|
||||
- **THEN** 每秒在同一行内更新进度,不向终端累积刷屏
|
||||
|
||||
#### Scenario: 重定向下的一行一记录
|
||||
|
||||
- **WHEN** stderr 被重定向且通过 `--progress on` 启用进度
|
||||
- **THEN** 每行是一条完整记录,不含回车控制字符,可直接 `tail` 或按行解析
|
||||
|
||||
### Requirement: 廉价总量估算与降级
|
||||
|
||||
系统 MUST 只使用有界成本的估算方式,MUST NOT 默认执行 `COUNT(*)`。日期分片模式 SHALL 使用分片列的 `MIN`/`MAX` 得到天数进度,并标注估算口径为 `day`;非日期模式仅在扫描键是单列整数唯一键时使用键的 `MIN`/`MAX` 做位置比例,并标注为 `key`。估算查询 MUST 在独立连接上执行并设有超时上限;超时、失败或口径不适用时,系统 MUST 静默降级为不显示百分比与 ETA,并标注 `estimate=none`。
|
||||
|
||||
百分比与 ETA MUST 带 `~` 前缀。ETA MUST 基于本次运行的推进速率与剩余量计算,MUST NOT 使用"已用时间 ÷ 百分比"。
|
||||
|
||||
#### Scenario: 日期模式按天估算
|
||||
|
||||
- **WHEN** `--shard-by date` 且存在可用的分片列索引
|
||||
- **THEN** 进度显示形如 `day 37/120` 的百分比与 ETA,并标注 `estimate=day`
|
||||
|
||||
#### Scenario: 单列整数键估算
|
||||
|
||||
- **WHEN** 非日期模式,扫描键是单列整数唯一键
|
||||
- **THEN** 进度显示基于键位置的百分比与 ETA,并标注 `estimate=key`
|
||||
|
||||
#### Scenario: 复合键或字符串键
|
||||
|
||||
- **WHEN** 扫描键为复合键或非整数类型
|
||||
- **THEN** 进度不显示百分比与 ETA,并标注 `estimate=none`
|
||||
|
||||
#### Scenario: 估算超时
|
||||
|
||||
- **WHEN** 估算查询在超时上限内未返回
|
||||
- **THEN** 系统放弃本次估算,进度降级为仅显示行数与速率,归档继续执行
|
||||
|
||||
### Requirement: 阶段可见性
|
||||
|
||||
系统 MUST 在进度中显示当前阶段,阶段集合为:`probe`、`resume`、`estimate`、`scan`、`file`、`db`、`checkpoint`、`finalize`、`lag-wait`。阶段内耗时 MUST 随时间递增,使操作者可以区分"正在慢"与"已经卡死"。`lag-wait` 阶段 MUST 显示等待原因。
|
||||
|
||||
#### Scenario: 等待副本延迟
|
||||
|
||||
- **WHEN** 副本延迟超过 `--max-lag`
|
||||
- **THEN** 进度显示 `lag-wait` 阶段与等待原因,而不是只输出一条 `waiting:` 消息
|
||||
|
||||
#### Scenario: 长扫描期间保持刷新
|
||||
|
||||
- **WHEN** 路径 B 的单日查询长时间未返回首个 chunk
|
||||
- **THEN** 阶段保持 `scan`,进度继续按间隔刷新,阶段内耗时持续增长
|
||||
|
||||
### Requirement: 消息与实时行互斥
|
||||
|
||||
在实时进度启用时,任何警告、提示或 lag 等待消息 MUST NOT 与实时行交错。系统 MUST 在输出消息前清除当前实时行,并在下一个刷新周期重新绘制。
|
||||
|
||||
#### Scenario: 警告出现在实时行之后
|
||||
|
||||
- **WHEN** 实时进度运行期间产生一条警告
|
||||
- **THEN** 警告单独占一行,实时行不在同一行上被截断或拼接
|
||||
|
||||
### Requirement: 完成与中断反馈
|
||||
|
||||
进度启用时,正常完成 MUST 输出一行最终汇总,包含累计行数、耗时、分片数与已写字节(存在文件输出时)。收到中断信号时,系统 MUST 先停止刷新、清除实时行并输出最终快照,然后执行现有的封片与 checkpoint 写入,退出码保持现有语义(130)。
|
||||
|
||||
#### Scenario: 正常完成
|
||||
|
||||
- **WHEN** 扫描自然结束且进度启用
|
||||
- **THEN** 在退出前输出一行 `done` 汇总
|
||||
|
||||
#### Scenario: 中断时保留现场
|
||||
|
||||
- **WHEN** 运行期间收到 SIGINT
|
||||
- **THEN** 进度停止并输出最终快照,随后当前分片被封存、checkpoint 被写入,进程以 130 退出
|
||||
|
||||
### Requirement: 续跑基线
|
||||
|
||||
进度中的已处理行数 MUST 包含当前输出目录在续跑前已提交的行数,即 `已处理 = 续跑前累计 + 本次运行读取行数`。续跑后进度 MUST NOT 从零重新起算。
|
||||
|
||||
#### Scenario: 续跑后继续累计
|
||||
|
||||
- **WHEN** 上次运行处理 10000 行后中断,本次续跑处理 40000 行
|
||||
- **THEN** 进度显示已处理行数为 50000,而不是 40000
|
||||
@@ -0,0 +1,52 @@
|
||||
## 1. CLI 参数与校验
|
||||
|
||||
- [x] 1.1 把 `--progress` 从 int 改为自定义 `flag.Value`,支持 `auto|on|off|N`,默认 `auto`
|
||||
- [x] 1.2 新增 `--progress-interval`(默认 `1s`),并接入 `cli.Config`
|
||||
- [x] 1.3 在 `validate.go` 中校验 `--progress` 取值与 `--progress-interval > 0`,错误走 KindConfig
|
||||
- [x] 1.4 更新 `--help` 文案与 `cli_test.go`,覆盖 `auto`、`on`、`off`、`0`、正整数、非法值
|
||||
|
||||
## 2. internal/progress 模块
|
||||
|
||||
- [x] 2.1 定义 `Reporter` 与内部快照结构,用互斥量保护计数、阶段、估算、位置与消息
|
||||
- [x] 2.2 实现 `Start/Stop` 与 ticker 生命周期,支持注入时钟与 `io.Writer`
|
||||
- [x] 2.3 实现 TTY 判定(`os.File.Stat` 的 `ModeCharDevice`)与 live/line 渲染器选择
|
||||
- [x] 2.4 实现 live 单行渲染:`\r` 覆盖、空格补齐、宽度上限与字段优先级裁剪
|
||||
- [x] 2.5 实现非 TTY 的稳定 key=value 行渲染
|
||||
- [x] 2.6 实现 5 秒窗口速率与 ETA(基于本次运行的推进速率,不使用 elapsed/pct)
|
||||
- [x] 2.7 实现 `Message`:清 live 行、整行输出、下一拍重绘
|
||||
- [x] 2.8 实现 `done` 汇总行与中断时的最终快照行
|
||||
- [x] 2.9 单元测试:live/line 输出、间隔节流、行阈值触发、清行补齐、消息不撕裂、速率窗口、ETA 降级
|
||||
|
||||
## 3. 廉价总量估算
|
||||
|
||||
- [x] 3.1 实现有界估算查询:独立连接、`context.WithTimeout(2s)`、失败/超时静默返回无估算
|
||||
- [x] 3.2 日期模式:`MIN/MAX(shard_column)` 得到天范围,发布 `estimate=day`
|
||||
- [x] 3.3 非日期模式:仅单列整数唯一键时用 `MIN/MAX(key)`,发布 `estimate=key`
|
||||
- [x] 3.4 复合键、字符串/二进制键、无索引时跳过并保持 `estimate=none`
|
||||
- [x] 3.5 单测覆盖估算可用、超时降级、口径不适用;集成测试覆盖日期与主键两种口径
|
||||
|
||||
## 4. 运行循环接入
|
||||
|
||||
- [x] 4.1 在 `execute` 启动 Reporter,在 `finish`/`interrupt` 停止
|
||||
- [x] 4.2 推送阶段:`probe`、`resume`(`Manifest.Adopt`)、`estimate`、`scan`、`file`、`db`、`checkpoint`、`finalize`
|
||||
- [x] 4.3 每个 chunk 完成后发布 RowsRead/committed、分片序号、已写字节与当前键位置
|
||||
- [x] 4.4 把 `lag.OnWait` 改为 `lag-wait` 阶段并携带原因,移除裸 `waiting:` 输出
|
||||
- [x] 4.5 把 `app.go` 中直接写 `os.Stderr` 的警告与提示改为 `Reporter.Message`
|
||||
- [x] 4.6 读取 `state.json` 时记录 `baseRows`,进度显示 `base + 本次 RowsRead`
|
||||
- [x] 4.7 `saveState` 写入 `baseRows + 本次 RowsCommitted`,修复续跑后 `rows_done` 重置
|
||||
- [x] 4.8 `--statistics` 分开展示本次运行与含续跑的累计值
|
||||
- [x] 4.9 中断顺序:停刷新 → 清行 → 最终快照 → `SealCurrent` → `saveState`,退出码保持 130
|
||||
|
||||
## 5. 测试与验证
|
||||
|
||||
- [x] 5.1 更新 `internal/app/integration_test.go` 中从 stdout 抓 `progress:` 的用例,改为 stderr 与新模式
|
||||
- [x] 5.2 新增集成测试:续跑后 `state.json` 的 `rows_done` 为累计值
|
||||
- [x] 5.3 新增集成测试:`--progress off` 与默认非 TTY 时 stderr 无进度行
|
||||
- [ ] 5.4 手动验证 Windows conhost 的 live 刷新、重定向日志的 `--progress on` 输出、SIGINT 快照
|
||||
- [ ] 5.5 运行 `go test ./...` 与 `go vet ./...`,确认无 data race(`go test -race` 覆盖 progress 单测)
|
||||
|
||||
## 6. 文档与收尾
|
||||
|
||||
- [x] 6.1 README 增加进度章节:模式、默认行为、通道、估算口径与限制
|
||||
- [x] 6.2 说明 `scripts/export-all.ps1` 可用 `--progress on` 让日志可 tail,并说明 `-Verify` 的续跑语义变化
|
||||
- [x] 6.3 运行 `openspec validate add-realtime-progress --strict` 并修复所有告警
|
||||
Reference in new issue
Block a user