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,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
|
||||
Reference in new issue
Block a user