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` 并修复所有告警
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-06
|
||||
@@ -0,0 +1,3 @@
|
||||
# add-archer-archiver
|
||||
|
||||
Go implementation of pt-archiver with ordered count-based and date-based file sharding, file+dest+purge, dump/csv/jsonl + gzip/zstd
|
||||
@@ -0,0 +1,187 @@
|
||||
## Context
|
||||
|
||||
这是一个全新的 Go 项目,没有既有代码需要兼容。需求见 `proposal.md`,行为契约见 `specs/`。
|
||||
|
||||
关键约束来自目标环境:MySQL/MariaDB、可能是有活跃写入的生产大表、单次导出规模从百万到数十亿行。因此设计围绕三件事展开:**内存恒定**(不能把结果集读进内存)、**扫描不退化**(不能出现 O(n²))、**产物可分段导入**(分片连续有序)。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 单趟、流式、内存恒定的扫描与导出。
|
||||
- 分片在扫描顺序上连续、有序、无重叠,文件名反映真实主键范围。
|
||||
- 同一套提交流水线同时支持 file、dest、purge。
|
||||
- 崩溃后可从 checkpoint 续跑,语义明确为 at-least-once。
|
||||
- 无合适索引时快速失败,而不是静默变慢。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 并行导出(多 worker)。
|
||||
- 文件侧 exactly-once。
|
||||
- Parquet / Arrow 输出。
|
||||
- 非 MySQL 数据源。
|
||||
- PXC Flow Control 与插件机制。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1:seek 分块,chunk 即事务
|
||||
|
||||
每个 chunk 用 `key > :last ORDER BY key LIMIT :chunk_size` 向前 seek,不使用 `OFFSET`。`--chunk-size` 同时是 SELECT 批量、事务大小和 checkpoint 粒度,**不引入 `--txn-size`**。
|
||||
|
||||
理由:pt-archiver 把 fetch 和 transaction 解耦后,出现“一个事务跨多个 chunk / 一个 chunk 拆多个事务”的组合复杂度;而 `OFFSET` 在 InnoDB 上是线性扫描,深分页会退化。统一粒度后,续跑、lag 检查、崩溃语义都只有一个边界。
|
||||
|
||||
**备选**:保留 `--txn-size` 做 parity — 放弃,收益不足以抵消复杂度。
|
||||
|
||||
### 决策 2:分片是 file sink 内部的行级路由,不是独立 sink
|
||||
|
||||
```
|
||||
Scanner ──chunk──▶ FileSink ──row──▶ ShardWriter ──▶ .partial ──seal──▶ final + manifest
|
||||
│
|
||||
├──▶ DBSink
|
||||
└──▶ Purger
|
||||
```
|
||||
|
||||
`FileSink.WriteChunk` 逐行交给 `ShardWriter`,由它判断是否封片。因为 `--chunk-size` 与 `--shard-rows` 正交,一个 chunk 可以跨多个分片;这是正常路径,不是特例。
|
||||
|
||||
**关键推论**:三种分片模式都保证扫描顺序等于分片顺序,因此**同一时刻只需要一个打开的分片文件**。不需要 LRU 句柄池,也没有 fd 上限风险。这是选择“有序扫描”换来的最大简化。
|
||||
|
||||
### 决策 3:按数量分片采用流式滚动
|
||||
|
||||
`--shard-by count` 每写满 `--shard-rows` 行封片,分片边界由扫描顺序自然产生。**不预计算边界**。
|
||||
|
||||
理由:预计算需要额外一趟扫描或 `OFFSET` 采样,边界状态还要按分片存进 checkpoint;流式滚动只需一个游标,且边界天然连续。代价是文件名在封片前未知,用 `.partial` + 封片时重命名解决。
|
||||
|
||||
**备选**:预计算边界以支持并行 — 留给 v2。
|
||||
|
||||
### 决策 4:日期分片的双扫描路径
|
||||
|
||||
启动时探测索引,按能力选择:
|
||||
|
||||
| 探测结果 | 路径 | 事务 | purge 连接 |
|
||||
|---|---|---|---|
|
||||
| `(shard_column, pk)` 联合索引 | A:keyset 分块 | 每 chunk 短事务 | 同连接 |
|
||||
| 仅 `shard_column` 单列索引 | B:逐日流式 | 长游标,无 chunk 事务 | 第二连接 |
|
||||
| 都没有 | fail fast(`--allow-full-scan` 可覆盖) | — | — |
|
||||
|
||||
路径 A 的续点条件是行构造器比较:
|
||||
|
||||
```sql
|
||||
WHERE (<base where>)
|
||||
AND (shard_col, pk) > (?, ?)
|
||||
ORDER BY shard_col, pk
|
||||
LIMIT ?
|
||||
```
|
||||
|
||||
路径 B 每天一条查询,用 `rows.Next()` 流式读完:
|
||||
|
||||
```sql
|
||||
WHERE (<base where>)
|
||||
AND shard_col >= ? AND shard_col < ?
|
||||
ORDER BY shard_col, pk
|
||||
```
|
||||
|
||||
选择依据:单列索引的物理顺序已经是 `(shard_col, pk)`,所以路径 B 的**输出有序**;但它的续点无法 seek,只能整日流式读。反过来,路径 A 能用联合索引精确 seek,但要求用户多建一个索引。检测驱动让两种用户都能运行,而不是硬性要求联合索引。
|
||||
|
||||
**NULL 处理**:行构造器比较遇到 NULL 结果恒为 NULL,无法推进游标。因此当存在 `date=_null` 桶时,先单独扫描 `shard_col IS NULL` 的行,再扫描非 NULL 行;两段都保持有序。
|
||||
|
||||
### 决策 5:日期列必须显式指定,类型白名单
|
||||
|
||||
`--shard-by date` 必须给 `--shard-column`,即使表中只有一个日期列。类型仅允许 `DATE`、`DATETIME`、`TIMESTAMP`,以及显式声明单位的整数 epoch。整数列缺单位时采样 min/max,展示三种解释下的日期范围,但**绝不自动选择**。
|
||||
|
||||
理由:同一张表常有多个日期列;`BIGINT` 列可能是 ID、金额或时间戳,秒与毫秒相差 1000 倍且转换后仍落在合法日期区间。静默猜错的代价是整批分片归属错误,且很难事后发现。
|
||||
|
||||
### 决策 6:时区模型显式化
|
||||
|
||||
| 列类型 | 日期归属 |
|
||||
|---|---|
|
||||
| `DATE` / `DATETIME` | 原值,不做换算 |
|
||||
| `TIMESTAMP` | 连接会话 `time_zone` |
|
||||
| epoch 整数 | `--shard-time-zone`,默认 UTC |
|
||||
|
||||
`--shard-time-zone` 与 DSN 的 `time_zone` 都计入配置指纹。续跑时不一致直接拒绝,因为同一行可能落到相邻日期分片,拼出的文件内部不一致。
|
||||
|
||||
### 决策 7:driver 使用 `parseTime=false`
|
||||
|
||||
所有列先按原始字节取回。dump/CSV 需要的就是 MySQL 原始文本;`parseTime=true` 会让 `0000-00-00` 直接报错,也会引入 `time.Time` 往返的格式漂移。分片时只对 `shard_column` 单独解析日期部分,JSONL 的类型化在编码层按列元数据完成。
|
||||
|
||||
### 决策 8:提交顺序与崩溃语义
|
||||
|
||||
```
|
||||
chunk:
|
||||
① FileSink 写行(缓冲)
|
||||
② DBSink 插入
|
||||
③ Purger 删除
|
||||
④ 提交(同实例单事务 / 跨实例分别提交)
|
||||
⑤ flush 文件 → seal 分片 → 追加 manifest
|
||||
⑥ 原子更新 state.json
|
||||
```
|
||||
|
||||
同实例时 ③④ 与 ② 在同一个事务里;跨实例时分别提交并重试。任一步失败都不推进 checkpoint。
|
||||
|
||||
一致性等级为 **at-least-once**:文件写入与数据库提交不在同一个原子域内,崩溃重跑可能重复追加。这是与 pt-archiver 对齐的取舍;文件侧 exactly-once 需要 pending journal,属于 v2。
|
||||
|
||||
**备选**:pending journal — 每 chunk 多一次 fsync,吞吐下降明显,当前需求不要求。
|
||||
|
||||
### 决策 9:删除策略
|
||||
|
||||
默认 IN 列表,按 1000 个参数分批。`--bulk-delete` 改为区间删除,并显式附上 `--where`;仅允许在 `none`/`count` 模式下使用。日期模式下 chunk 的主键不连续(迟到数据会让区间跨日期),区间删除会误伤其他分片的数据,因此直接拒绝。
|
||||
|
||||
**备选**:始终区间删除 — 性能收益在大 chunk 时才明显,但引入并发写入误删风险,不作为默认。
|
||||
|
||||
### 决策 10:checkpoint 与配置指纹
|
||||
|
||||
`state.json` 原子写(tmp + fsync + rename),记录 `version`、`run_id`、`config_hash`、模式、`last_key`、`last_date`、`last_shard_seq`、`rows_done`。
|
||||
|
||||
指纹输入:source 的 host/port/db/user、table、where、columns、shard 参数、时区、format、compress、dest、purge、bulk-delete。**排除密码**,允许凭据轮换。
|
||||
|
||||
### 决策 11:包结构
|
||||
|
||||
```
|
||||
cmd/archer/main.go
|
||||
internal/
|
||||
cli/ 参数解析、校验、互斥规则
|
||||
schema/ 表元数据、索引探测、列类型
|
||||
scan/ seek 分块迭代器(路径 A / B / 主键)
|
||||
row/ 行值、编码器(dump/csv/jsonl)
|
||||
sink/ FileSink、DBSink
|
||||
shard/ ShardWriter、命名、manifest
|
||||
purge/ IN 列表 / 区间删除
|
||||
checkpoint/ state.json
|
||||
lag/ 复制延迟监控
|
||||
```
|
||||
|
||||
核心接口:
|
||||
|
||||
```go
|
||||
type Chunk struct {
|
||||
Rows []Row
|
||||
LastKey Key
|
||||
}
|
||||
|
||||
type Scanner interface {
|
||||
Next(ctx context.Context) (Chunk, error)
|
||||
}
|
||||
|
||||
type Sink interface {
|
||||
WriteChunk(ctx context.Context, c Chunk) error
|
||||
Flush(ctx context.Context) error
|
||||
Close() error
|
||||
}
|
||||
```
|
||||
|
||||
依赖:`github.com/go-sql-driver/mysql`、`github.com/klauspost/compress/zstd`,gzip 用标准库。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **日期模式 B 持有长读快照** → 大表上 undo 可能膨胀,且无法在扫描期间用同连接删除。缓解:路径 A 优先;提供 `--max-lag`;文档说明长事务影响。
|
||||
- **at-least-once 会产生重复行** → 重跑后文件可能重复。缓解:manifest 记录已封分片;文档明确;导入端可用 `INSERT IGNORE` 去重。
|
||||
- **`--bulk-delete` 并发误删** → 扫描期间落在区间内且满足 `--where` 的新行会被删。缓解:默认关闭;启用时打印警告;日期模式禁止。
|
||||
- **分片文件名延迟确定** → 长时间运行的大分片在封片前没有最终文件名。缓解:`state.json` 记录当前 seq 与起始主键;`.partial` 可识别。
|
||||
- **时区配置漂移** → 同一表在不同机器分片结果不同。缓解:时区进入指纹;续跑时不一致即拒绝。
|
||||
- **无索引时误开全表扫描** → 缓解:默认 fail fast,`--allow-full-scan` 必须显式开启。
|
||||
- **单条 INSERT/DELETE 超过 `max_allowed_packet`** → 缓解:按字节预算自动拆分为多条语句。
|
||||
- **并发写入导致扫描期间的行集合漂移** → 与本工具语义一致(只保证读到的行),文档说明不提供快照一致性。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
全新项目,无数据迁移。首个版本只读能力(`--file` / `--dest`)可安全试跑;`--purge` 需显式开启。建议上线流程:先 `--dry-run`,再只导出核对文件,最后再启用 `--purge`。回滚即停止使用新二进制;已产生的导出文件不受影响。
|
||||
@@ -0,0 +1,41 @@
|
||||
## Why
|
||||
|
||||
`pt-archiver` 是归档大表的可靠方案,但它的文件导出只在启动时计算一次文件名,无法把一次归档拆成多个可独立导入的文件;它也不支持按数据自身的日期或行数做有序分片。同时它是 Perl 工具,部署和二次开发成本较高。
|
||||
|
||||
需要一个 Go 原生的归档工具:复用 pt-archiver 的 seek 式分块扫描与 file + dest + purge 语义,并补齐“导出文件可有序分片”这一能力,让大表导出结果能按日期或按行数切成连续、无重叠、可并行导入的文件。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增 Go CLI `archer`,对齐 pt-archiver 的核心归档语义:按唯一索引 seek 分块,支持 file、dest 表、purge 三件套。
|
||||
- 新增导出分片能力:
|
||||
- `--shard-by count`:按固定行数流式封片,分片沿扫描顺序连续、有序、主键范围不重叠。
|
||||
- `--shard-by date`:按用户显式指定的日期/时间列分片,每个文件只含一个日期。
|
||||
- `--shard-by none`:不分片,输出单文件。
|
||||
- 新增日期分片的两种扫描路径:存在 `(shard_column, pk)` 联合索引时走 keyset 分块(短事务);仅存在 `shard_column` 单列索引时走逐日流式(长游标 + 第二连接删除)。
|
||||
- 新增输出格式 `dump`(TSV,NULL=`\N`)、`csv`(RFC4180 + 表头)、`jsonl`(类型化 JSON),支持每分片独立 `gzip` 或 `zstd` 压缩。
|
||||
- 新增 `manifest.jsonl` 与 `state.json`:记录分片边界、行数、校验和与断点,支持崩溃续跑;一致性等级为 at-least-once。
|
||||
- 新增安全控制:`--dry-run`、`--max-lag` 复制延迟等待、`--safe-auto-increment`、`--bulk-delete` 的适用性限制、续跑时配置指纹校验。
|
||||
- **BREAKING**: 新项目,无既有接口需要兼容。`--chunk-size` 取代 pt-archiver 的 `--limit`,语义为“每次 SELECT 的行数”;`--limit` 仅作为隐藏别名。
|
||||
|
||||
**非目标(v1 不做)**:PostgreSQL 等非 MySQL 数据源、Parquet 输出、字符串日期列分片、按预计算边界并行导出、文件侧 exactly-once、PXC Flow Control 适配。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `archive-core`: 扫描与归档执行——按唯一索引 seek 分块、file/dest/purge 三件套提交顺序、事务边界、复制延迟等待、安全护栏与断点续跑。
|
||||
- `file-sharding`: 分片路由与产物管理——`none`/`count`/`date` 三种分片模式、有序连续不变量、文件命名、句柄管理、`manifest.jsonl` 与 `state.json`。
|
||||
- `output-formats`: 行编码与压缩——dump/csv/jsonl 的精确格式规则、NULL 与类型处理、每分片独立 gzip/zstd。
|
||||
- `cli-contract`: 命令行契约——参数集合与默认值、互斥与依赖校验、日期列类型与索引探测、错误信息与 `--dry-run` 输出。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无。这是新项目,`openspec/specs/` 下没有既有能力。
|
||||
|
||||
## Impact
|
||||
|
||||
- **代码**:新建 Go module 与目录结构(`cmd/archer`、`internal/{cli,schema,scan,row,sink,shard,purge,checkpoint}`)。
|
||||
- **依赖**:`github.com/go-sql-driver/mysql`;`github.com/klauspost/compress`(zstd)。其余用标准库。
|
||||
- **运行环境**:MySQL 5.7+/8.0 与 MariaDB 10.x;不引入服务端组件。
|
||||
- **输出**:新增用户指定目录下的分片文件、`manifest.jsonl`、`state.json`。
|
||||
- **数据安全**:启用 `--purge` 会删除源表数据,需要显式确认;`--bulk-delete` 在日期模式或被拒绝。
|
||||
@@ -0,0 +1,150 @@
|
||||
## Purpose
|
||||
|
||||
定义 archer 如何按唯一索引分块读取源表,并以固定顺序完成文件写入、目标表写入与源行删除,同时提供复制延迟保护、安全护栏和可中断续跑能力。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 唯一索引 seek 分块扫描
|
||||
|
||||
系统 SHALL 以源表的一个唯一索引(优先主键)作为扫描游标。每个 chunk 的查询 MUST 使用“索引键大于上一次尾值”的条件、按索引列 `ORDER BY`、并带 `LIMIT chunk-size`;系统 MUST NOT 使用 `OFFSET` 翻页。返回行数小于 `chunk-size` 时,系统 SHALL 结束扫描。
|
||||
|
||||
#### Scenario: 主键连续
|
||||
|
||||
- **WHEN** 源表主键为连续的 1..N,且 `--chunk-size 2000`
|
||||
- **THEN** 系统按 2000 行一个 chunk 依次读取,直到最后一个不足 2000 行的 chunk
|
||||
|
||||
#### Scenario: 主键存在空洞
|
||||
|
||||
- **WHEN** 主键序列为 1,2,100,101,且 `--chunk-size 2`
|
||||
- **THEN** 第一个 chunk 返回 1,2,第二个 chunk 从 `id > 2` 继续并返回 100,101,不会跳过或重复
|
||||
|
||||
#### Scenario: 无可用唯一索引
|
||||
|
||||
- **WHEN** 源表既没有主键也没有唯一索引,且用户未指定索引
|
||||
- **THEN** 系统在开始扫描前报错退出,并提示需要唯一索引
|
||||
|
||||
### Requirement: chunk 即事务
|
||||
|
||||
每个 chunk SHALL 构成唯一的事务边界,`--chunk-size` 同时决定 SELECT 批量、事务大小和 checkpoint 粒度。系统 SHALL NOT 提供跨 chunk 的事务,也 SHALL NOT 提供独立的 `--txn-size` 参数。
|
||||
|
||||
#### Scenario: 源表与目标表在同一实例
|
||||
|
||||
- **WHEN** `--source` 与 `--dest` 指向同一 MySQL 实例,且同时启用 dest 与 purge
|
||||
- **THEN** 目标表写入与源行删除在同一个事务中提交,二者要么同时生效要么同时回滚
|
||||
|
||||
#### Scenario: 源表与目标表在不同实例
|
||||
|
||||
- **WHEN** `--source` 与 `--dest` 指向不同实例
|
||||
- **THEN** 系统使用两个连接分别提交,并在任一步失败时按 `--retries` 重试;已提交的目标表写入可能在重跑时重复,行为为 at-least-once
|
||||
|
||||
### Requirement: 三件套提交顺序
|
||||
|
||||
当 file、dest、purge 中任意多项同时启用时,系统 MUST 对每个 chunk 按固定顺序执行:写文件、写目标表、删除源行、提交事务并更新 checkpoint。任何前置步骤失败时,系统 MUST NOT 执行后续步骤,也 MUST NOT 推进 checkpoint。
|
||||
|
||||
#### Scenario: 文件写入失败
|
||||
|
||||
- **WHEN** 写文件返回错误
|
||||
- **THEN** 系统不写目标表、不删除源行、不推进 checkpoint,并以非零码退出
|
||||
|
||||
#### Scenario: 目标表写入失败
|
||||
|
||||
- **WHEN** 文件写入成功但目标表插入失败
|
||||
- **THEN** 系统删除源行,回滚本次事务,不推进 checkpoint,并以非零码退出
|
||||
|
||||
### Requirement: 输出目标约束
|
||||
|
||||
系统 SHALL 要求 `--file`、`--dest`、`--purge` 至少启用一个,并且 `--where` 必填。三者可以任意组合,包括只导出文件、只删除、或文件与目标表同时输出。
|
||||
|
||||
#### Scenario: 只删不写
|
||||
|
||||
- **WHEN** 用户只指定 `--purge` 和 `--where`
|
||||
- **THEN** 系统仅按 chunk 删除匹配行,不生成任何文件
|
||||
|
||||
#### Scenario: 文件与目标表同时输出
|
||||
|
||||
- **WHEN** 用户同时指定 `--file` 与 `--dest`
|
||||
- **THEN** 同一批行既写入分片文件,也写入目标表
|
||||
|
||||
### Requirement: 目标表写入模式
|
||||
|
||||
目标表写入 SHALL 支持普通插入、`INSERT IGNORE` 与 `REPLACE` 三种模式,三者互斥。系统 MUST 使用多行批量插入,并在单条语句可能超过 `max_allowed_packet` 时自动拆分为多条语句。
|
||||
|
||||
#### Scenario: 默认插入遇到重复主键
|
||||
|
||||
- **WHEN** 使用默认插入模式,且目标表已存在相同主键
|
||||
- **THEN** 该 chunk 失败并回滚,系统报告重复键错误
|
||||
|
||||
#### Scenario: ignore 模式遇到重复主键
|
||||
|
||||
- **WHEN** 使用 `--insert-ignore`
|
||||
- **THEN** 重复行被跳过,其余行写入成功,chunk 正常提交
|
||||
|
||||
### Requirement: 删除语义
|
||||
|
||||
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`,且在日期分片模式下 MUST 被拒绝。
|
||||
|
||||
#### Scenario: 默认 IN 列表删除
|
||||
|
||||
- **WHEN** 一个 chunk 读取到主键 1001..3000,且 `--where "created_at < '2026-01-01'"`
|
||||
- **THEN** 系统生成 `DELETE ... WHERE id IN (1001,...,3000)`,不删除未被读取的行
|
||||
|
||||
#### Scenario: 区间删除附带回填条件
|
||||
|
||||
- **WHEN** 启用 `--bulk-delete`,chunk 首尾主键为 1001 与 3000
|
||||
- **THEN** 系统生成 `DELETE ... WHERE id BETWEEN 1001 AND 3000 AND (<where>)`
|
||||
|
||||
#### Scenario: 日期模式启用区间删除
|
||||
|
||||
- **WHEN** `--shard-by date` 与 `--bulk-delete` 同时出现
|
||||
- **THEN** 系统在启动校验阶段报错退出,不执行任何查询
|
||||
|
||||
### Requirement: 复制延迟保护
|
||||
|
||||
当指定 `--check-replica-lag` 时,系统 SHALL 在每次拉取前检查该副本的延迟;延迟超过 `--max-lag` 或复制未运行时,系统 MUST 暂停并在 `--check-interval` 后重试。
|
||||
|
||||
#### Scenario: 延迟超限
|
||||
|
||||
- **WHEN** `--max-lag 1s`,副本延迟为 5s
|
||||
- **THEN** 系统暂停拉取,直到延迟降到 1s 以下
|
||||
|
||||
#### Scenario: 副本复制中断
|
||||
|
||||
- **WHEN** 被检查的副本复制线程未运行
|
||||
- **THEN** 系统持续等待并周期性重试,不继续归档
|
||||
|
||||
### Requirement: 安全护栏
|
||||
|
||||
系统 SHALL 默认启用 `--safe-auto-increment`,禁止通过 purge 删除当前最大自增主键行。`--dry-run` 时系统 MUST 只打印将要执行的 SQL 与实际生效配置,不连接写入、不创建或修改任何文件。
|
||||
|
||||
#### Scenario: 保护最大自增行
|
||||
|
||||
- **WHEN** purge 范围包含源表当前 `MAX(pk)`,且 `--safe-auto-increment` 为默认值
|
||||
- **THEN** 该行不被删除,系统记录一条警告
|
||||
|
||||
#### Scenario: dry-run 无副作用
|
||||
|
||||
- **WHEN** 用户指定 `--dry-run`
|
||||
- **THEN** 系统打印每条 SQL 与解析后的配置后退出,输出目录不产生任何文件
|
||||
|
||||
### Requirement: 断点续跑
|
||||
|
||||
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。续跑时 MUST 校验源、表、过滤条件、列、分片参数与时区的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。
|
||||
|
||||
#### Scenario: 配置一致时续跑
|
||||
|
||||
- **WHEN** 上次运行在 chunk 中途退出,且本次配置指纹一致
|
||||
- **THEN** 系统从 `state.json` 记录的游标位置继续,不重复处理已提交的 chunk
|
||||
|
||||
#### Scenario: 配置被修改
|
||||
|
||||
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出不一致的字段,拒绝开始扫描
|
||||
|
||||
### Requirement: 一致性等级
|
||||
|
||||
文件输出的一致性等级 SHALL 为 at-least-once:崩溃后重跑可能向分片文件重复追加已处理的行,系统 MUST 在文档与启动输出中明确该行为。
|
||||
|
||||
#### Scenario: 崩溃后重跑
|
||||
|
||||
- **WHEN** 文件已写入但 checkpoint 尚未更新时进程崩溃,随后以相同配置重跑
|
||||
- **THEN** 系统从上一个已提交游标继续,文件可能出现重复行,数据不丢失
|
||||
@@ -0,0 +1,98 @@
|
||||
## Purpose
|
||||
|
||||
定义 archer 的命令行参数、默认值、参数之间的依赖与互斥规则,以及启动校验、错误信息和 dry-run 行为。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 必填参数
|
||||
|
||||
系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
|
||||
|
||||
#### Scenario: 缺少过滤条件
|
||||
|
||||
- **WHEN** 用户未提供 `--where`
|
||||
- **THEN** 系统立即报错,提示 `--where` 必填,不建立数据库连接
|
||||
|
||||
#### Scenario: 没有任何输出目标
|
||||
|
||||
- **WHEN** 用户既未提供 `--file`、`--dest`,也未启用 `--purge`
|
||||
- **THEN** 系统报错,提示至少需要一种输出目标
|
||||
|
||||
### Requirement: 默认值
|
||||
|
||||
系统 SHALL 采用以下默认值:`--chunk-size 2000`、`--shard-by none`、`--shard-rows 0`、`--format dump`、`--compress none`、`--max-lag 1s`、`--check-interval 1s`、`--retries 1`、`--safe-auto-increment true`、`--progress 0`。
|
||||
|
||||
#### Scenario: 最小可运行配置
|
||||
|
||||
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
|
||||
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
|
||||
|
||||
### 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` 三者互斥。违反时 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** 系统报错,要求只能选择一种插入模式
|
||||
|
||||
### Requirement: 日期列探测与错误提示
|
||||
|
||||
启动时,系统 SHALL 读取表元数据并判断 `--shard-column` 是否存在、类型是否受支持、是否可为 NULL。缺少 `--shard-column` 时 MUST 列出所有候选日期/时间列及其类型。整数列缺少单位声明时 MUST 采样最小/最大值,并展示按秒、毫秒、微秒解释后的日期范围。
|
||||
|
||||
#### Scenario: 列出候选列
|
||||
|
||||
- **WHEN** 用户指定 `--shard-by date` 但未给 `--shard-column`
|
||||
- **THEN** 错误信息包含表内所有 DATE/DATETIME/TIMESTAMP 列的列名、类型与可空性
|
||||
|
||||
#### Scenario: epoch 单位提示
|
||||
|
||||
- **WHEN** 分片列为 BIGINT 且未声明单位
|
||||
- **THEN** 错误信息展示采样范围以及三种单位解释下的日期范围,不自动选择
|
||||
|
||||
### Requirement: dry-run
|
||||
|
||||
`--dry-run` 时,系统 MUST 打印解析后的配置、索引探测结果、最终生效的分片与格式参数,以及第一条将要执行的 SELECT 和每类写入语句,然后退出。系统 MUST NOT 建立写入连接、创建目录或写文件。
|
||||
|
||||
#### Scenario: dry-run 输出 SQL
|
||||
|
||||
- **WHEN** 用户传入 `--dry-run`
|
||||
- **THEN** 标准输出包含解析后的配置和将要执行的 SQL,进程以 0 退出
|
||||
|
||||
### Requirement: 进度与统计
|
||||
|
||||
当 `--progress N` 大于 0 时,系统 SHALL 每处理 N 行输出一次进度,包含已处理行数、当前分片序号与耗时。启用 `--statistics` 时,系统 MUST 在结束时输出读取行数、写入行数、删除行数、分片数与各阶段耗时。
|
||||
|
||||
#### Scenario: 周期进度
|
||||
|
||||
- **WHEN** `--progress 100000`
|
||||
- **THEN** 每处理 100000 行打印一行进度信息
|
||||
|
||||
#### Scenario: 结束统计
|
||||
|
||||
- **WHEN** 启用 `--statistics`
|
||||
- **THEN** 进程退出前输出汇总统计
|
||||
|
||||
### Requirement: 退出码
|
||||
|
||||
系统 SHALL 在成功完成时返回 0;配置错误、连接错误、写入错误或校验失败时返回非零退出码。被信号中断时 MUST 完成当前 chunk 的清理并返回非零退出码。
|
||||
|
||||
#### Scenario: 配置错误
|
||||
|
||||
- **WHEN** 参数校验失败
|
||||
- **THEN** 进程以非零退出码结束,且不产生部分输出文件
|
||||
|
||||
#### Scenario: 信号中断
|
||||
|
||||
- **WHEN** 进程收到 SIGINT
|
||||
- **THEN** 系统停止拉取新 chunk,关闭并 flush 当前分片,写入 checkpoint,然后以非零退出码结束
|
||||
@@ -0,0 +1,151 @@
|
||||
## Purpose
|
||||
|
||||
定义导出文件的分片模式、顺序不变量、命名规则、句柄管理与分片清单,确保大规模导出的结果可被分段、有序、独立地导入。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 分片模式
|
||||
|
||||
系统 SHALL 支持三种分片模式:`none`(不分片,单文件)、`count`(按固定行数封片)、`date`(按用户指定的日期或时间列封片)。分片模式 SHALL 由 `--shard-by` 选择,默认 `none`。
|
||||
|
||||
#### Scenario: 不分片
|
||||
|
||||
- **WHEN** `--shard-by none`
|
||||
- **THEN** 本次扫描的全部行写入同一个文件
|
||||
|
||||
#### Scenario: 按数量分片
|
||||
|
||||
- **WHEN** `--shard-by count --shard-rows 5000000`
|
||||
- **THEN** 每写满 500 万行封一个文件,最后一个文件可少于 500 万行
|
||||
|
||||
#### Scenario: 按日期分片
|
||||
|
||||
- **WHEN** `--shard-by date --shard-column created_at`
|
||||
- **THEN** 每个文件只包含 `created_at` 落在同一个日期的行
|
||||
|
||||
### Requirement: 有序连续不变量
|
||||
|
||||
对于任何分片模式,系统 MUST 保证:分片按扫描顺序编号;相邻分片的主键范围连续且不重叠;所有分片合并后等于本次扫描读取的全部行;每个分片内部的行顺序与扫描顺序一致;文件名中的首尾主键为该分片实际写入的第一行与最后一行主键。
|
||||
|
||||
#### Scenario: 分片边界连续
|
||||
|
||||
- **WHEN** 一次扫描读取主键 1..2500,且 `--shard-rows 1000`
|
||||
- **THEN** 生成三个分片,主键范围分别为 1-1000、1001-2000、2001-2500,无重叠也无空洞
|
||||
|
||||
#### Scenario: 主键存在空洞时仍连续
|
||||
|
||||
- **WHEN** 扫描读取到主键 1,2,100,101,且 `--shard-rows 2`
|
||||
- **THEN** 分片范围分别为 1-2 与 100-101,文件名反映实际首尾主键
|
||||
|
||||
### Requirement: 按行数流式封片
|
||||
|
||||
在 `count` 模式下,系统 SHALL 在写入过程中逐行判断当前分片是否已满,写满 `--shard-rows` 行后立即封片。`--chunk-size` 与 `--shard-rows` SHALL 相互独立,系统 MUST 支持一个 chunk 跨越多个分片,且不要求两者存在整除关系。
|
||||
|
||||
#### Scenario: chunk 跨越分片边界
|
||||
|
||||
- **WHEN** `--chunk-size 2000` 且 `--shard-rows 2500`
|
||||
- **THEN** 第二个 chunk 的前 1500 行写入第一个分片,后 500 行写入第二个分片
|
||||
|
||||
#### Scenario: 文件在关闭时才确定名称
|
||||
|
||||
- **WHEN** 一个分片正在写入
|
||||
- **THEN** 该文件在关闭前以 `.partial` 形式存在,关闭并 flush 后重命名为包含实际首尾主键的最终文件名
|
||||
|
||||
### Requirement: 日期分片的列契约
|
||||
|
||||
`--shard-by date` 时,系统 MUST 要求显式提供 `--shard-column`;即使表中只有一个日期列也不得自动选择。该列类型 MUST 属于 `DATE`、`DATETIME`、`TIMESTAMP` 或整数类型(epoch,需显式声明单位)。其他类型 MUST 被拒绝。
|
||||
|
||||
#### Scenario: 缺少分片列
|
||||
|
||||
- **WHEN** `--shard-by date` 但未提供 `--shard-column`
|
||||
- **THEN** 系统报错,并列出表中所有候选的日期/时间列及其类型与可空性
|
||||
|
||||
#### Scenario: 多个日期列
|
||||
|
||||
- **WHEN** 表中有 `created_at`、`updated_at`、`paid_at` 三个日期列,用户指定 `--shard-column created_at`
|
||||
- **THEN** 系统只按 `created_at` 分片,其他日期列作为普通导出列
|
||||
|
||||
#### Scenario: 整数时间戳列未声明单位
|
||||
|
||||
- **WHEN** `--shard-column created_at` 指向 `BIGINT` 列,且未提供 `--shard-column-type`
|
||||
- **THEN** 系统报错,采样该列最小/最大值,并分别展示按秒、毫秒、微秒解释后的日期范围供用户选择
|
||||
|
||||
#### Scenario: 不支持的列类型
|
||||
|
||||
- **WHEN** `--shard-column` 指向 `VARCHAR` 或 `TIME` 列
|
||||
- **THEN** 系统报错,并说明 v1 仅支持日期时间类型与显式声明的 epoch 整数
|
||||
|
||||
### Requirement: 日期值归属规则
|
||||
|
||||
系统 MUST 按列语义决定日期归属:`DATE` 与 `DATETIME` 使用原值,不做时区换算;`TIMESTAMP` 按连接会话时区换算;epoch 整数按 `--shard-time-zone`(默认 UTC)换算。NULL 值默认落入 `date=_null` 分片;零日期默认报错并给出行主键,可通过 `--zero-date bucket` 改为落入 `date=0000-00-00` 分片。`--shard-time-zone` MUST 计入配置指纹。
|
||||
|
||||
#### Scenario: NULL 日期值
|
||||
|
||||
- **WHEN** 某行的 `created_at` 为 NULL,且使用默认配置
|
||||
- **THEN** 该行写入 `date=_null` 分片,扫描顺序与分片顺序仍保持一致
|
||||
|
||||
#### Scenario: 零日期值
|
||||
|
||||
- **WHEN** 某行的 `created_at` 为 `0000-00-00 00:00:00`,且未指定 `--zero-date`
|
||||
- **THEN** 系统报错并输出该行主键,不生成静默的错误分片
|
||||
|
||||
#### Scenario: 时区改变后续跑
|
||||
|
||||
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致
|
||||
- **THEN** 系统拒绝续跑,除非显式传入 `--force-resume`
|
||||
|
||||
### Requirement: 日期扫描路径选择
|
||||
|
||||
系统 SHALL 在启动时探测分片列的索引,并据此选择扫描路径:存在 `(shard_column, pk)` 联合索引时使用 keyset 分块(短事务);仅存在 `shard_column` 单列索引时使用逐日流式读取(长游标,purge 使用独立连接);两者都不存在时 MUST fail fast,除非显式传入 `--allow-full-scan`。
|
||||
|
||||
#### Scenario: 存在联合索引
|
||||
|
||||
- **WHEN** 表上存在 `(created_at, id)` 联合索引
|
||||
- **THEN** 系统按 `(created_at, id)` 做 keyset 分块,每个 chunk 独立提交
|
||||
|
||||
#### Scenario: 仅存在单列索引
|
||||
|
||||
- **WHEN** 表上只有 `created_at` 单列索引
|
||||
- **THEN** 系统按日期逐日发出查询并流式读取,日期内按 `created_at, id` 排序;删除操作使用第二条源连接
|
||||
|
||||
#### Scenario: 没有任何相关索引
|
||||
|
||||
- **WHEN** 分片列上既无联合索引也无单列索引
|
||||
- **THEN** 系统报错并提示创建索引,或由用户显式传入 `--allow-full-scan` 以接受全表扫描
|
||||
|
||||
### Requirement: 文件命名与目录布局
|
||||
|
||||
分片文件 MUST 按 `<输出目录>/[date=<YYYY-MM-DD>/]<seq>.<pk_lo>-<pk_hi>.<format>[.<compress>]` 命名,`seq` 为从 1 开始的六位零填充序号。日期模式 MUST 按日期建立子目录。输出目录下同时生成 `manifest.jsonl` 与 `state.json`。
|
||||
|
||||
#### Scenario: 数量分片命名
|
||||
|
||||
- **WHEN** 第一个分片主键范围为 1..5000000,格式为 dump,压缩为 zstd
|
||||
- **THEN** 文件名为 `000001.1-5000000.dump.zst`
|
||||
|
||||
#### Scenario: 日期分片布局
|
||||
|
||||
- **WHEN** `--shard-by date` 导出的首个日期为 2025-06-01
|
||||
- **THEN** 文件位于 `date=2025-06-01/` 子目录下,序号在该日期内从 000001 开始
|
||||
|
||||
### Requirement: 分片清单
|
||||
|
||||
系统 SHALL 在每次分片关闭后向 `manifest.jsonl` 追加一行并 flush,记录序号、相对路径、日期(如适用)、首尾主键、行数、字节数与 SHA-256。清单 MUST 在进程崩溃后仍可用于识别已完成的分片。
|
||||
|
||||
#### Scenario: 分片关闭后写入清单
|
||||
|
||||
- **WHEN** 一个分片完成 flush 并重命名
|
||||
- **THEN** `manifest.jsonl` 追加一条包含 seq、path、pk_lo、pk_hi、rows、bytes、sha256、closed_at 的记录
|
||||
|
||||
#### Scenario: 崩溃后识别已完成分片
|
||||
|
||||
- **WHEN** 进程在写完两个分片后崩溃
|
||||
- **THEN** `manifest.jsonl` 中保留这两条完整记录,残留的 `.partial` 文件不进入清单
|
||||
|
||||
### Requirement: 分片文件原子性
|
||||
|
||||
每个分片 MUST 先写入同目录下的 `.partial` 临时文件,成功 flush 后原子重命名为最终文件名。每个分片 MUST 独立压缩,使单个文件可以脱离其他分片单独导入。
|
||||
|
||||
#### Scenario: 崩溃留下临时文件
|
||||
|
||||
- **WHEN** 进程在分片写入过程中崩溃
|
||||
- **THEN** 目录中留下 `.partial` 文件,最终文件名对应的文件不存在,续跑时系统忽略或清理该临时文件
|
||||
@@ -0,0 +1,75 @@
|
||||
## Purpose
|
||||
|
||||
定义行数据到文件的编码规则与压缩方式,确保导出产物可以被 MySQL、PostgreSQL、ClickHouse、Spark 等常见工具直接导入。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: dump 格式
|
||||
|
||||
`--format dump` 时,系统 MUST 以制表符分隔字段、换行符结束行、`\N` 表示 NULL、反斜杠转义特殊字符,并且不写表头。转义规则 MUST 与 MySQL `SELECT ... INTO OUTFILE` 一致:反斜杠、制表符、换行、回车、NUL、退格、Ctrl-Z 均需转义。
|
||||
|
||||
#### Scenario: 默认 dump 输出
|
||||
|
||||
- **WHEN** 一行包含 `a\tb` 与 NULL
|
||||
- **THEN** 输出为 `a\\tb\t\\N\n`,可被 `LOAD DATA INFILE` 以默认参数读回
|
||||
|
||||
#### Scenario: 数值与日期列
|
||||
|
||||
- **WHEN** 列类型为 DECIMAL、DATETIME
|
||||
- **THEN** 直接输出 MySQL 返回的文本表示,不做重格式化
|
||||
|
||||
### Requirement: CSV 格式
|
||||
|
||||
`--format csv` 时,系统 MUST 输出 RFC4180 兼容内容:逗号分隔、首行为列名表头、含逗号/引号/CR/LF 的字段用双引号包裹、字段内双引号写为两个双引号、行尾为 CRLF。NULL 默认输出 `\N`,可通过 `--csv-null` 覆盖;空字符串输出为空字段。
|
||||
|
||||
#### Scenario: 字段包含逗号与引号
|
||||
|
||||
- **WHEN** 字段值为 `a,"b"`
|
||||
- **THEN** 输出为 `"a,""b"""`
|
||||
|
||||
#### Scenario: 表头
|
||||
|
||||
- **WHEN** 生成任意 CSV 分片
|
||||
- **THEN** 每个文件首行都是列名列表,顺序与 `--columns` 一致
|
||||
|
||||
### Requirement: JSONL 格式
|
||||
|
||||
`--format jsonl` 时,系统 MUST 每行输出一个 JSON 对象,键为列名。类型映射 MUST 为:DATETIME/TIMESTAMP 输出 RFC3339 字符串;DECIMAL 输出字符串以保留精度;BLOB/BINARY 输出 base64 字符串;NULL 输出 JSON `null`;整数与浮点输出 JSON 数字。
|
||||
|
||||
#### Scenario: 类型映射
|
||||
|
||||
- **WHEN** 一行包含 DECIMAL(10,2)=12.30、DATETIME、NULL
|
||||
- **THEN** 对应字段分别为 `"12.30"`、RFC3339 时间字符串、`null`
|
||||
|
||||
#### Scenario: 每行独立可解析
|
||||
|
||||
- **WHEN** 读取 JSONL 分片的任意一行
|
||||
- **THEN** 该行可以被标准 JSON 解析器独立解析,不依赖前后行
|
||||
|
||||
### Requirement: 压缩
|
||||
|
||||
系统 SHALL 支持 `--compress none|gzip|zstd`,默认 `none`。每个分片 MUST 独立压缩,压缩后的文件扩展名分别为 `.gz` 与 `.zst`。gzip 与 zstd 的默认压缩级别 MUST 为 3(吞吐优先)。
|
||||
|
||||
#### Scenario: gzip 分片
|
||||
|
||||
- **WHEN** `--compress gzip`
|
||||
- **THEN** 每个分片是一个独立的 gzip 流,文件名为 `*.gz`
|
||||
|
||||
#### Scenario: zstd 分片
|
||||
|
||||
- **WHEN** `--compress zstd`
|
||||
- **THEN** 每个分片是一个独立的 zstd 帧,文件名为 `*.zst`
|
||||
|
||||
### Requirement: 可导入性
|
||||
|
||||
系统 MUST 保证每种格式的产物可被至少一种常见工具直接导入:dump 可被 MySQL `LOAD DATA INFILE` 默认参数导入;csv 可被 PostgreSQL `COPY ... CSV HEADER`、ClickHouse `CSVWithNames`、Pandas/Spark 默认 CSV 读取器导入;jsonl 可被 ClickHouse `JSONEachRow` 及常见流式 JSON 工具导入。
|
||||
|
||||
#### Scenario: 压缩文件导入
|
||||
|
||||
- **WHEN** 产物为 `000001.1-1000.csv.gz`
|
||||
- **THEN** 可以通过 `gunzip -c` 或 `zcat` 管道交给目标数据库导入,无需改写文件内容
|
||||
|
||||
#### Scenario: dump 直接导入 MySQL
|
||||
|
||||
- **WHEN** 使用 dump 格式且不压缩
|
||||
- **THEN** `LOAD DATA INFILE '000001.1-1000.dump' INTO TABLE t` 在列顺序一致时可成功执行
|
||||
@@ -0,0 +1,96 @@
|
||||
## 1. 项目骨架
|
||||
|
||||
- [x] 1.1 初始化 Go module,建立 `cmd/archer` 与 `internal/{cli,schema,scan,row,sink,shard,purge,checkpoint,lag}` 目录
|
||||
- [x] 1.2 引入 `go-sql-driver/mysql` 与 `klauspost/compress/zstd`,锁定版本
|
||||
- [x] 1.3 定义 `Chunk`、`Scanner`、`Sink` 接口与共享的 `Row`、`Key` 类型
|
||||
- [x] 1.4 建立最小 `main.go` 与版本号输出
|
||||
|
||||
## 2. CLI 与配置校验
|
||||
|
||||
- [x] 2.1 实现全部参数解析与默认值(`--chunk-size 2000`、`--shard-by none`、`--format dump`、`--compress none` 等)
|
||||
- [x] 2.2 实现必填校验:`--source`、`--where`、至少一个输出目标
|
||||
- [x] 2.3 实现依赖与互斥校验:date 必须带 `--shard-column`;count/none 禁止;`--bulk-delete` 依赖 `--purge` 且日期模式禁止;insert/ignore/replace 互斥
|
||||
- [x] 2.4 实现配置标准化与 `config_hash` 计算(排除密码)
|
||||
- [x] 2.5 实现 `--dry-run` 输出:解析后配置、索引探测结果、首条 SELECT 与写入 SQL
|
||||
|
||||
## 3. Schema 元数据与索引探测
|
||||
|
||||
- [x] 3.1 从 `information_schema` 读取列名、类型、可空性、列顺序
|
||||
- [x] 3.2 实现唯一索引发现,优先主键,支持用户强制指定索引
|
||||
- [x] 3.3 实现分片列索引探测:联合索引 / 单列索引 / 无索引三种结果
|
||||
- [x] 3.4 实现日期列候选枚举与错误提示
|
||||
- [x] 3.5 实现整数 epoch 列的 min/max 采样与三种单位解释提示
|
||||
|
||||
## 4. 扫描器
|
||||
|
||||
- [x] 4.1 实现主键 seek 分块扫描(`key > :last ORDER BY key LIMIT :chunk_size`)
|
||||
- [x] 4.2 实现主键空洞与尾 chunk 的处理,返回准确 `LastKey`
|
||||
- [x] 4.3 实现日期路径 A:`(shard_col, pk)` 行构造器 keyset 分块
|
||||
- [x] 4.4 实现日期路径 B:逐日枚举 + 长游标流式读取
|
||||
- [x] 4.5 实现 NULL 日期先扫、非 NULL 后扫的两段扫描
|
||||
- [x] 4.6 接入 `--max-lag` 拉取前检查与 `--check-interval` 等待
|
||||
|
||||
## 5. 行编码与压缩
|
||||
|
||||
- [x] 5.1 实现 dump 编码器(TAB、`\N`、与 MySQL 一致的转义表)
|
||||
- [x] 5.2 实现 CSV 编码器(RFC4180、表头、引号规则、`--csv-null`)
|
||||
- [x] 5.3 实现 JSONL 编码器(时间、DECIMAL、BLOB 的类型映射)
|
||||
- [x] 5.4 实现每分片独立的 gzip 与 zstd 压缩包装器
|
||||
- [x] 5.5 用固定样例验证三种格式可被对应工具直接导入
|
||||
|
||||
## 6. 分片写入与清单
|
||||
|
||||
- [x] 6.1 实现 `ShardWriter`:单活跃分片、逐行写入、按 `--shard-rows` 封片
|
||||
- [x] 6.2 实现 `.partial` 写入与封片时的 fsync + 原子重命名
|
||||
- [x] 6.3 实现文件名规则:`[date=<d>/]<seq>.<lo>-<hi>.<format>[.<comp>]`
|
||||
- [x] 6.4 实现日期分片的目录布局与日期切换时封片
|
||||
- [x] 6.5 实现 `manifest.jsonl` 追加与 flush(seq/path/date/pk_lo/pk_hi/rows/bytes/sha256)
|
||||
- [x] 6.6 实现崩溃后残留 `.partial` 的识别与清理
|
||||
|
||||
## 7. 目标表写入
|
||||
|
||||
- [x] 7.1 实现多行批量 INSERT,按 `max_allowed_packet` 自动拆分
|
||||
- [x] 7.2 实现 `--insert-ignore` 与 `--replace`
|
||||
- [x] 7.3 实现同实例单事务提交
|
||||
- [x] 7.4 实现跨实例分别提交与 `--retries` 重试
|
||||
|
||||
## 8. 删除
|
||||
|
||||
- [x] 8.1 实现默认 IN 列表删除与 1000 参数分批
|
||||
- [x] 8.2 实现 `--bulk-delete` 区间删除并附带 `--where`
|
||||
- [x] 8.3 实现 `--safe-auto-increment` 保护最大主键行
|
||||
- [x] 8.4 实现日期路径 B 的独立 purge 连接
|
||||
- [x] 8.5 实现日期模式拒绝 `--bulk-delete` 的启动校验
|
||||
|
||||
## 9. Checkpoint 与续跑
|
||||
|
||||
- [x] 9.1 实现 `state.json` 原子写(tmp + fsync + rename)
|
||||
- [x] 9.2 记录并校验 `config_hash`、游标、当前分片序号、已处理行数
|
||||
- [x] 9.3 实现续跑:从游标恢复、跳过已封分片、清理未完成临时文件
|
||||
- [x] 9.4 实现配置不一致时的拒绝与 `--force-resume` 覆盖
|
||||
- [x] 9.5 实现信号中断时 flush 当前分片并写 checkpoint
|
||||
|
||||
## 10. 进度、统计与错误
|
||||
|
||||
- [x] 10.1 实现 `--progress N` 周期进度输出
|
||||
- [x] 10.2 实现 `--statistics` 结束汇总
|
||||
- [x] 10.3 统一退出码与错误分类(配置、连接、写入、校验、中断)
|
||||
|
||||
## 11. 集成测试与验收
|
||||
|
||||
- [x] 11.1 搭建 MySQL 测试环境与固定数据夹具
|
||||
- [x] 11.2 验证分片有序连续不变量:范围无重叠、合并等于全集、文件名首尾主键正确
|
||||
- [x] 11.3 验证 chunk 跨分片边界(`chunk-size` 与 `shard-rows` 非整除)
|
||||
- [x] 11.4 验证日期路径 A 与路径 B 的输出一致
|
||||
- [x] 11.5 验证 NULL、零日期、epoch 秒/毫秒/微秒的分片归属
|
||||
- [x] 11.6 验证崩溃续跑不丢数据、manifest 与 state 一致
|
||||
- [x] 11.7 验证 dump/csv/jsonl 分别可被 MySQL、Postgres/ClickHouse 导入
|
||||
- [x] 11.8 验证 gzip/zstd 分片可独立解压导入
|
||||
- [x] 11.9 验证 `--dry-run`、互斥校验、无索引 fail-fast 的错误信息
|
||||
|
||||
## 12. 文档与发布
|
||||
|
||||
- [x] 12.1 编写 README:安装、最小示例、分片模式、导入方法
|
||||
- [x] 12.2 编写安全说明:`--purge`、`--bulk-delete`、at-least-once、时区
|
||||
- [x] 12.3 编写与 pt-archiver 的参数对照表
|
||||
- [x] 12.4 打包 Windows/Linux 二进制与版本信息
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-06
|
||||
@@ -0,0 +1,3 @@
|
||||
# add-compress-level-and-xz
|
||||
|
||||
新增 xz 压缩格式,并引入统一 1-9 压缩档位 --compress-level
|
||||
@@ -0,0 +1,85 @@
|
||||
# 设计:xz 压缩与统一压缩档位
|
||||
|
||||
## 依赖选择
|
||||
|
||||
采用 `github.com/ulikunitz/xz`(纯 Go、BSD-3、读写齐全)。
|
||||
|
||||
| 方案 | 结论 |
|
||||
|---|---|
|
||||
| `klauspost/compress` | 不支持 xz |
|
||||
| cgo 绑定 liblzma | 破坏交叉编译与"纯 Go 构建"约束 |
|
||||
| 外部 `xz` 进程 | 额外运行时依赖、错误处理与安全面变大 |
|
||||
| `ulikunitz/xz` | 唯一可行,本机 module cache 已有 v0.5.17 |
|
||||
|
||||
## 档位模型:1–9 是语义档位,不是原生级别
|
||||
|
||||
zstd 库没有连续 1–22 级别,只有 4 个 `EncoderLevel`;xz 库没有 preset 参数。因此 1–9 被定义为**跨格式语义档位**,各格式显式映射,9 表示该格式最强:
|
||||
|
||||
| level | gzip (flate) | zstd | xz 字典 |
|
||||
|---|---|---|---|
|
||||
| 1 | 1 | SpeedFastest | 1 MiB |
|
||||
| 2 | 2 | SpeedFastest | 2 MiB |
|
||||
| 3 | 3 | SpeedDefault | 4 MiB |
|
||||
| 4 | 4 | SpeedDefault | 4 MiB |
|
||||
| 5 | 5 | SpeedDefault | 8 MiB |
|
||||
| 6 | 6 | SpeedBetterCompression | 8 MiB |
|
||||
| 7 | 7 | SpeedBetterCompression | 16 MiB |
|
||||
| 8 | 8 | SpeedBetterCompression | 32 MiB |
|
||||
| 9 | 9 | SpeedBestCompression | 64 MiB |
|
||||
|
||||
默认 3:gzip 与现行 `NewWriterLevel(3)` 一致;zstd 的 `SpeedDefault` 与现行代码一致;xz 无历史行为。
|
||||
|
||||
xz 映射只设置 `WriterConfig.DictCap`,其余使用库默认(CRC64、hash-table matcher)。这与 `xz -N` 的字典表一致,但不比特级复刻 xz-utils 的 preset(matcher 不同,压缩率略低),文档需说明产物仍是标准 xz。
|
||||
|
||||
## xz 读取的字典上限
|
||||
|
||||
`ulikunitz/xz` 的 reader 默认 `DictCap = 8 MiB`;读取 level 9(64 MiB 字典)的流会失败。
|
||||
|
||||
**决定:xz reader 固定使用 64 MiB 上限,而不是按当前 level 推导。**
|
||||
|
||||
原因:
|
||||
|
||||
1. 本工具可能产出的最大字典就是 64 MiB;
|
||||
2. `--force-resume` 允许改配置续跑。若按当前 level 推导,从 9 降到 1 后读取旧分片会因上限不足而失败;
|
||||
3. 读侧只出现在续跑与清单补录路径,不在主写入热路径,一次 64 MiB 缓冲可接受。
|
||||
|
||||
## checkpoint 会产生多 stream
|
||||
|
||||
`Writer.Checkpoint()` 关闭当前压缩流、记录偏移,再在偏移处开启新流。gzip 多 member、zstd 多 frame、xz 多 stream 都是合法拼接;`ulikunitz/xz` 的 `SingleStream` 默认 `false`,会解码全部 stream,`xz -dc` 同样如此。
|
||||
|
||||
**要求:必须有测试覆盖"checkpoint 后的 xz 分片能被完整读回",防止 `--purge` 场景下静默丢行。**
|
||||
|
||||
## 指纹兼容性
|
||||
|
||||
现有 `state.json` 的指纹里没有 `compress_level`。无条件加字段会让本功能上线前启动的任务全部续跑失败。
|
||||
|
||||
**决定:仅当 `compress != none && level != 3` 时把 `compress_level` 加入指纹。**
|
||||
|
||||
- 老任务(无键)+ 新进程默认 3 → 哈希输入逐字节不变,无缝续跑;
|
||||
- 非默认档位才出现新键,`DiffFields` 会显示 `compress_level: "5" -> (absent)` 并拒绝;
|
||||
- 从 5 改回 3 也因键消失被识别。
|
||||
|
||||
`compress == none` 时档位不参与哈希,因为不影响产物。
|
||||
|
||||
## none 与 level 的组合
|
||||
|
||||
`compress == none && level != 3` → 配置错误;`level == 3`(默认值)静默接受。这样既能拒绝无意义组合,又不会惩罚"只是没传"的用户。
|
||||
|
||||
## 崩溃恢复识别 `.xz`
|
||||
|
||||
`manifest.go` 的 `shardNameRE` 目前只列 `\.gz|\.zst`,且 `Adopt` 用 `mt[3] != comp.Ext` 过滤。不加 `\.xz` 时,崩溃在 rename 与 manifest 追加之间的 xz 分片不会被计入 `maxSeq`,续跑会重算序号并覆盖已封分片。
|
||||
|
||||
**决定:正则与扩展名判断都识别 `.xz`,并补一条针对性测试。**
|
||||
|
||||
## Compressor 结构与扩展名收敛
|
||||
|
||||
`Compressor` 从 `{Name, Ext}` 扩展为 `{Name, Ext, Level}`,构造签名改为 `NewCompressor(name string, level int)`。gzip/zstd/xz 都从同一个对象取 `Ext`。
|
||||
|
||||
`app/dryrun.go` 的 `compressExt()` 是第二份扩展名表,改成复用 `Compressor.Ext`,避免新增格式时漏改一处。
|
||||
|
||||
## 被否决的方案
|
||||
|
||||
- **把 zstd 暴露为 1–22**:与 gzip/xz 的 1–9 不一致,校验和文档复杂度上升;zstd `best` 已足够,空间优先交给 xz。
|
||||
- **按当前 level 推导 reader 字典**:与 `--force-resume` 降级续跑冲突。
|
||||
- **xz 使用默认 8 MiB 字典**:level 3 与 xz preset 3 不一致,且高档位无法表达。
|
||||
- **无条件把档位写入指纹**:打断存量任务续跑。
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
当前只支持 `none|gzip|zstd`,且压缩级别写死为 3,用户无法在"吞吐优先"与"空间优先"之间取舍。xz 能显著降低长期归档的存储成本,但压缩吞吐远低于 gzip/zstd;把它作为一个显式选项,同时把级别做成统一档位,才能让三种压缩器在同一语义下被选择。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增 `--compress xz`,每个分片是一个独立 xz 流,扩展名为 `.xz`。
|
||||
- 新增 `--compress-level 1..9`,默认 3;1–9 是跨格式统一档位,按格式映射到各自的压缩参数,9 表示该格式最强。默认档位 3 与现有行为一致。
|
||||
- `--compress none` 与非默认 `--compress-level` 同时出现时视为配置错误。
|
||||
- 配置指纹:仅当 `compress != none` 且 `level != 3` 时把 `compress_level` 纳入指纹,保证本功能之前启动的任务仍能无缝续跑;非默认档位变化仍会被识别并拒绝。
|
||||
- 崩溃恢复扫描必须识别 `.xz` 分片,避免重算序号覆盖已封分片。
|
||||
- 收敛扩展名逻辑:dry-run 复用 `Compressor.Ext`,删除重复的 `compressExt` 表。
|
||||
- 引入纯 Go 依赖 `github.com/ulikunitz/xz`。
|
||||
- **BREAKING**: 无。未设置 `--compress-level` 时,gzip/zstd 的产物与当前版本一致。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(无)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `output-formats`: 压缩 Requirement 从 3 种压缩器扩展为 4 种,并定义 1–9 档位到各格式的映射与 xz 场景。
|
||||
- `cli-contract`: 默认值中加入 `--compress-level 3`,参数依赖规则加入 `none` 与非默认档位的冲突校验。
|
||||
- `archive-core`: 断点续跑指纹纳入非默认压缩档位,并明确档位变化时的拒绝行为。
|
||||
- `file-sharding`: 文件命名与分片清单覆盖 `.xz`,并明确崩溃后按压缩扩展名识别已封分片。
|
||||
|
||||
## Impact
|
||||
|
||||
- 代码:`internal/cli/{config,parse,validate,hash}.go`、`internal/shard/{compress,manifest}.go`、`internal/app/{app,dryrun}.go`
|
||||
- 依赖:`go.mod` / `go.sum` 新增 `github.com/ulikunitz/xz`
|
||||
- 文档:`README.md` 压缩章节、档位表与 xz 导入示例
|
||||
- 测试:`internal/shard/writer_test.go`、`internal/app/integration_test.go`、`internal/cli` 校验与指纹测试
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 断点续跑
|
||||
|
||||
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。续跑时 MUST 校验源、表、过滤条件、列、分片参数、时区、输出格式与压缩设置的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。压缩档位仅在启用压缩且档位不是默认值 3 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。
|
||||
|
||||
#### 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** 指纹一致,系统正常续跑
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
## 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 0`。
|
||||
|
||||
#### Scenario: 最小可运行配置
|
||||
|
||||
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
|
||||
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
|
||||
|
||||
### 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 视为配置错误。违反时 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** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 文件命名与目录布局
|
||||
|
||||
分片文件 MUST 按 `<输出目录>/[date=<YYYY-MM-DD>/]<seq>.<pk_lo>-<pk_hi>.<format>[.<compress>]` 命名,`seq` 为从 1 开始的六位零填充序号。日期模式 MUST 按日期建立子目录。输出目录下同时生成 `manifest.jsonl` 与 `state.json`。
|
||||
|
||||
#### Scenario: 数量分片命名
|
||||
|
||||
- **WHEN** 第一个分片主键范围为 1..5000000,格式为 dump,压缩为 zstd
|
||||
- **THEN** 文件名为 `000001.1-5000000.dump.zst`
|
||||
|
||||
#### Scenario: xz 分片命名
|
||||
|
||||
- **WHEN** 第一个分片主键范围为 1..5000000,格式为 dump,压缩为 xz
|
||||
- **THEN** 文件名为 `000001.1-5000000.dump.xz`
|
||||
|
||||
#### Scenario: 日期分片布局
|
||||
|
||||
- **WHEN** `--shard-by date` 导出的首个日期为 2025-06-01
|
||||
- **THEN** 文件位于 `date=2025-06-01/` 子目录下,序号在该日期内从 000001 开始
|
||||
|
||||
### Requirement: 分片清单
|
||||
|
||||
系统 SHALL 在每次分片关闭后向 `manifest.jsonl` 追加一行并 flush,记录序号、相对路径、日期(如适用)、首尾主键、行数、字节数与 SHA-256。清单 MUST 在进程崩溃后仍可用于识别已完成的分片。对于已重命名但尚无清单记录的分片,续跑 MUST 按当前输出格式与压缩扩展名识别、补录并计入序号,不得覆盖。
|
||||
|
||||
#### Scenario: 分片关闭后写入清单
|
||||
|
||||
- **WHEN** 一个分片完成 flush 并重命名
|
||||
- **THEN** `manifest.jsonl` 追加一条包含 seq、path、pk_lo、pk_hi、rows、bytes、sha256、closed_at 的记录
|
||||
|
||||
#### Scenario: 崩溃后识别已完成分片
|
||||
|
||||
- **WHEN** 进程在写完两个分片后崩溃
|
||||
- **THEN** `manifest.jsonl` 中保留这两条完整记录,残留的 `.partial` 文件不进入清单
|
||||
|
||||
#### Scenario: xz 分片在清单追加前崩溃
|
||||
|
||||
- **WHEN** 一个 `.xz` 分片完成重命名后、写 `manifest.jsonl` 前进程崩溃
|
||||
- **THEN** 续跑扫描识别该分片,补录清单,后续序号从其后继续,不覆盖该文件
|
||||
+35
@@ -0,0 +1,35 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 压缩
|
||||
|
||||
系统 SHALL 支持 `--compress none|gzip|zstd|xz`,默认 `none`。每个分片 MUST 独立压缩,压缩后的文件扩展名分别为 `.gz`、`.zst` 与 `.xz`。系统 SHALL 支持 `--compress-level 1..9`,默认 3;档位是跨格式统一语义,数值越大压缩率越高、吞吐越低,9 表示该压缩器的最强档位。gzip 与 zstd 在默认档位下的字节输出 MUST 与引入档位前保持一致。xz 分片 MUST 是标准 xz 流,可被通用 xz 工具解码。
|
||||
|
||||
#### Scenario: gzip 分片
|
||||
|
||||
- **WHEN** `--compress gzip`
|
||||
- **THEN** 每个分片是一个独立的 gzip 流,文件名为 `*.gz`
|
||||
|
||||
#### Scenario: zstd 分片
|
||||
|
||||
- **WHEN** `--compress zstd`
|
||||
- **THEN** 每个分片是一个独立的 zstd 帧,文件名为 `*.zst`
|
||||
|
||||
#### Scenario: xz 分片
|
||||
|
||||
- **WHEN** `--compress xz`
|
||||
- **THEN** 每个分片是一个独立的 xz 流,文件名为 `*.xz`
|
||||
|
||||
#### Scenario: xz 分片可被标准工具解码
|
||||
|
||||
- **WHEN** 产物为 `000001.1-1000.dump.xz`
|
||||
- **THEN** `xz -dc` 可将其还原为与该次扫描行内容一致的 dump 文本
|
||||
|
||||
#### Scenario: 默认档位保持既有产物
|
||||
|
||||
- **WHEN** 用户未指定 `--compress-level`
|
||||
- **THEN** gzip 与 zstd 使用档位 3,产物与引入该参数前的版本一致
|
||||
|
||||
#### Scenario: 各档位对三种压缩器均可用
|
||||
|
||||
- **WHEN** 用户指定 `--compress gzip|zstd|xz` 与任意 `--compress-level 1..9`
|
||||
- **THEN** 系统接受配置并产出对应扩展名的独立压缩分片
|
||||
@@ -0,0 +1,42 @@
|
||||
## 1. 依赖与压缩器
|
||||
|
||||
- [x] 1.1 `go get github.com/ulikunitz/xz@v0.5.17`,更新 `go.mod` / `go.sum`
|
||||
- [x] 1.2 `Compressor` 增加 `Level` 字段;`NewCompressor(name string, level int)` 接受档位
|
||||
- [x] 1.3 实现档位映射:gzip 直传 1–9;zstd 按 1-2 fastest / 3-5 default / 6-8 better / 9 best;xz 按字典表 1/2/4/4/8/8/16/32/64 MiB
|
||||
- [x] 1.4 xz writer 使用 `xz.WriterConfig{DictCap: ...}`;reader 固定 `DictCap 64 MiB` 并保留多 stream 解码
|
||||
|
||||
## 2. CLI
|
||||
|
||||
- [x] 2.1 `cli/config.go`:`CompressLevel int`,默认 3
|
||||
- [x] 2.2 `cli/parse.go`:注册 `--compress-level`,help 标注 1–9
|
||||
- [x] 2.3 `cli/validate.go`:档位必须在 1–9;`--compress none` 且档位非 3 时报配置错误
|
||||
- [x] 2.4 `cli/hash.go`:仅当 `compress != none && level != 3` 时加入 `compress_level`
|
||||
|
||||
## 3. 装配与扩展名收敛
|
||||
|
||||
- [x] 3.1 `app/app.go`:用 `NewCompressor(cfg.Compress, cfg.CompressLevel)` 构造
|
||||
- [x] 3.2 `app/dryrun.go`:输出压缩档位;删除 `compressExt()`,改用 `Compressor.Ext`
|
||||
|
||||
## 4. 崩溃恢复
|
||||
|
||||
- [x] 4.1 `shard/manifest.go`:`shardNameRE` 增加 `\.xz`,`Adopt` 能识别 xz 分片并计入序号
|
||||
|
||||
## 5. 测试
|
||||
|
||||
- [x] 5.1 档位映射边界单测(含 gzip/zstd/xz 与非法档位)
|
||||
- [x] 5.2 `shard/writer_test.go` 的压缩往返循环加入 `xz`
|
||||
- [x] 5.3 新增:`Checkpoint()` 后多 stream xz 分片能被完整读回
|
||||
- [x] 5.4 新增:无 manifest 记录的 `.xz` 分片可被 `Adopt` 补录且不影响序号
|
||||
- [x] 5.5 CLI 测试:非法档位、`none` + 非默认档位、默认档位的指纹向后兼容、非默认档位变化被拒绝
|
||||
- [x] 5.6 `app/integration_test.go`:压缩循环加入 `xz`,`decompressFile` 增加 xz 分支
|
||||
|
||||
## 6. 文档
|
||||
|
||||
- [x] 6.1 `README.md`:压缩选项加入 xz 与 `--compress-level`,补档位表、xz 导入示例(`xz -dc`)与 xz 吞吐/空间定位说明
|
||||
|
||||
## 7. 验证
|
||||
|
||||
- [x] 7.1 `go test ./...`
|
||||
- [x] 7.2 `go vet ./...`
|
||||
- [x] 7.3 `openspec validate add-compress-level-and-xz --strict`
|
||||
- [ ] 7.4 如有 MySQL 环境,跑一次 `ARCHER_TEST_DSN=... go test ./internal/app -run TestIntegration -v`
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-06
|
||||
@@ -0,0 +1,3 @@
|
||||
# normalize-state-config
|
||||
|
||||
state.json 的 config.source/dest 改用标准 MySQL DSN(去密码),并修复 charset 等参数未纳入指纹的问题
|
||||
@@ -0,0 +1,75 @@
|
||||
## Context
|
||||
|
||||
当前实现(见 proposal.md - Why):
|
||||
|
||||
- `cli.Config.Fingerprint()`(internal/cli/hash.go:17)把 `dsnFingerprint(src)` 与 `dsnFingerprint(dst)` 的结果放进 `fields` map,该 map 既用于计算 `config_hash`,也原样写入 `state.json` 的 `config`(internal/app/app.go:492)。
|
||||
- `dsnFingerprint`(internal/cli/hash.go:69)手工拼接 `Net|Addr|DBName|User` 和 `Params`。
|
||||
- `normalize()`(internal/cli/config.go:86)统一设置 `ParseTime=false`,`Loc` 为空时置为 UTC。
|
||||
- `redactDSN`(internal/app/dryrun.go:155)已经采用"复制配置、清空密码、`FormatDSN()`"的做法。
|
||||
|
||||
约束:指纹必须保持可复现;密码不得落盘;旧 `state.json` 必须仍能读取(版本号不变)。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- `config.source` / `config.dest` 使用可逆、可转义、生态通用的标准 DSN。
|
||||
- 指纹覆盖所有可能改变导出结果的连接参数,尤其是 `charset` 与 `collation`。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不拆分"哈希输入"与"展示快照";两者继续共用同一份 `fields` map。
|
||||
- 不改变 `state.json` 的 schema 版本,不做旧指纹的兼容计算。
|
||||
- 不改变 `--source` / `--dest` 的输入语法(仍然是 MySQL DSN)。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 用 `FormatDSN()` 生成指纹片段
|
||||
|
||||
```go
|
||||
func dsnFingerprint(c *mysql.Config) string {
|
||||
if c == nil {
|
||||
return ""
|
||||
}
|
||||
redacted := *c // 值拷贝,保留未导出字段(charsets 等)
|
||||
redacted.Passwd = ""
|
||||
return redacted.FormatDSN()
|
||||
}
|
||||
```
|
||||
|
||||
理由:
|
||||
|
||||
- `charset`、`collation`、`compress`、`timeTruncate` 是驱动的未导出字段,**只有 `FormatDSN` 能序列化它们**(dsn.go:318、322 等),手工枚举字段必然继续漏检。
|
||||
- `FormatDSN` 对库名做 `PathEscape`、对参数做 `QueryEscape`、对参数 key 排序(dsn.go:379-396),输出确定且无歧义。
|
||||
- 与 `redactDSN` 共用同一套序列化逻辑,`--dry-run` 与 `state.json` 的写法一致。
|
||||
|
||||
备选方案:
|
||||
|
||||
- 继续竖线格式、补上 `charset`:仍是非标准写法,未导出字段没有稳定的读取入口。
|
||||
- 嵌套 JSON 对象:需要改 `State.Config` 类型与 `DiffFields`,收益是更精确的 diff;本次不取,记录为后续方向。
|
||||
|
||||
### 2. 用值拷贝而不是原地清空密码
|
||||
|
||||
`mysql.Config` 含未导出字段,值拷贝会一起带上,`FormatDSN` 因而仍能输出 `charset`。原地清空 `Passwd` 会污染调用方的配置,直接排除。
|
||||
|
||||
### 3. 保持 `state.json` `Version = 1`
|
||||
|
||||
指纹变化会让旧任务一次性失配。不升版本的理由:`checkpoint.Load` 对未知版本直接报错,会让已 `complete` 的目录也无法重入;而保持版本 1 时,`DiffFields` 会把 `source` 的旧竖线串与新 DSN 并列展示,用户能直观看懂差异,必要时加 `--force-resume` 即可。
|
||||
|
||||
### 4. 密码继续排除在指纹之外
|
||||
|
||||
`Passwd` 清空后再序列化。口令轮换不应使续跑失效,这是现有契约。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- `FormatDSN` 会连带覆盖 `tls`、`timeout` 等不影响产物字节的参数,这类修改也会触发续跑失配 → 方向是"宁可多报";确实需要时用 `--force-resume`。若未来噪声过大,再改为语义白名单。
|
||||
- 旧 `state.json` 需要一次性 `--force-resume` → 在变更说明中标注为 BREAKING,且错误信息本身会展示新旧写法。
|
||||
- `Params` 中若有自定义敏感参数会被写入 `state.json` → 与现状相同(原实现同样写入 `Params`),本次不扩大范围。
|
||||
- 哈希输入与展示快照仍然耦合,未来再改 state 展示格式仍会触发失配 → 接受为已知债务,不在本次处理。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 修改 `dsnFingerprint` 并补充单元测试。
|
||||
2. 验证新 `state.json` 中 `config.source` 为标准 DSN 且不含密码。
|
||||
3. 对存量任务:首轮续跑加 `--force-resume`;已完成任务不受影响。
|
||||
4. 回滚:还原 `dsnFingerprint` 即可;已写入的新格式 `config` 只是普通字符串,仍可读取,但指纹会再次失配,需要 `--force-resume`。
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
`state.json` 的 `config.source` / `config.dest` 目前由 `dsnFingerprint`(internal/cli/hash.go)用竖线拼成 `tcp|host:3306|db|user`。这既不是 MySQL 生态的标准写法,也无法转义;更严重的是它只读取 `Net/Addr/DBName/User/Params`,导致 `charset`、`collation` 等被驱动收进结构体字段的参数**完全不参与指纹校验**——续跑时把 `charset=utf8mb4` 改成其他编码不会被发现,同一份导出会出现混合编码的分片。
|
||||
|
||||
## What Changes
|
||||
|
||||
- `state.json` 中的 `config.source` / `config.dest` 改为标准 MySQL DSN(去掉密码),例如 `root@tcp(s1.void01.com:3306)/lexis?charset=utf8mb4`。
|
||||
- 配置指纹改用同一份规范化 DSN 计算,覆盖驱动解析出的全部连接参数(密码除外),从而把 `charset`、`collation`、`loc` 等纳入续跑校验。
|
||||
- 与 `--dry-run` 的展示格式(`redactDSN`,internal/app/dryrun.go)保持一致,工具的"用户可见连接串"只有一种写法。
|
||||
- **BREAKING**:指纹取值变化,旧版本写入的 `state.json` 会被判定为配置不同。续跑旧任务需要一次性传入 `--force-resume`;`state.json` 版本号不变(仍为 1),旧文件仍可读取并展示差异。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(无)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `archive-core`: 断点续跑要求中,明确配置指纹必须覆盖源/目标连接的规范化参数(含字符集与排序规则),并规定 `state.json` 中连接信息的存储形态为标准 DSN。
|
||||
|
||||
## Impact
|
||||
|
||||
- 代码:`internal/cli/hash.go`(`dsnFingerprint` 改为复制配置、清空 `Passwd`、调用 `FormatDSN`)。
|
||||
- 测试:`internal/cli/cli_test.go` 增加 charset/参数变化的指纹断言与 `state.json` 快照断言。
|
||||
- 数据:`state.json` 的 `config` 内容形态变化,触发一次性续跑校验失败。
|
||||
- 文档:README 中关于 `state.json` 记录的描述无需改动;`--dry-run` 输出不变。
|
||||
@@ -0,0 +1,40 @@
|
||||
## 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 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。
|
||||
|
||||
#### 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,且不包含密码明文
|
||||
@@ -0,0 +1,17 @@
|
||||
## 1. 指纹生成
|
||||
|
||||
- [x] 1.1 将 `internal/cli/hash.go` 的 `dsnFingerprint` 改为:`nil` 返回空串;否则值拷贝 `mysql.Config`、清空 `Passwd`、返回 `FormatDSN()`
|
||||
- [x] 1.2 更新 `Fingerprint` 与 `dsnFingerprint` 的注释,说明输出为标准 DSN、覆盖驱动全部已解析参数、密码除外
|
||||
|
||||
## 2. 测试
|
||||
|
||||
- [x] 2.1 新增单元测试:`charset` 或 `collation` 不同时指纹不同
|
||||
- [x] 2.2 新增单元测试:仅密码不同时指纹相同
|
||||
- [x] 2.3 新增单元测试:指纹中不含密码明文,`dest` 为空时片段为空串
|
||||
- [x] 2.4 新增断言:`state.json` 的 `config.source` 等于 `redactDSN` 输出的标准 DSN(可复用现有 app 测试夹具)
|
||||
|
||||
## 3. 验证
|
||||
|
||||
- [x] 3.1 运行 `go test ./...`(无数据库环境下跳过集成测试)
|
||||
- [ ] 3.2 用同一 `--source` 分别以不同密码、不同 `charset` 运行 `--dry-run` 与续跑,确认前者指纹一致、后者报错并展示 `source` 差异
|
||||
- [ ] 3.3 用旧版 `state.json` 续跑一次,确认报错信息可读,且 `--force-resume` 后正常继续并改写为新格式
|
||||
Reference in new issue
Block a user