Files
archer/openspec/changes/archive/2026-11-06-add-archer-archiver/tasks.md
T
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-06 22:12:17 +08:00

4.9 KiB
Raw Blame History

1. 项目骨架

  • 1.1 初始化 Go module,建立 cmd/archer 与 internal/{cli,schema,scan,row,sink,shard,purge,checkpoint,lag} 目录
  • 1.2 引入 go-sql-driver/mysql 与 klauspost/compress/zstd,锁定版本
  • 1.3 定义 Chunk、Scanner、Sink 接口与共享的 Row、Key 类型
  • 1.4 建立最小 main.go 与版本号输出

2. CLI 与配置校验

  • 2.1 实现全部参数解析与默认值(--chunk-size 2000、--shard-by none、--format dump、--compress none 等)
  • 2.2 实现必填校验:--source、--where、至少一个输出目标
  • 2.3 实现依赖与互斥校验:date 必须带 --shard-column;count/none 禁止;--bulk-delete 依赖 --purge 且日期模式禁止;insert/ignore/replace 互斥
  • 2.4 实现配置标准化与 config_hash 计算(排除密码)
  • 2.5 实现 --dry-run 输出:解析后配置、索引探测结果、首条 SELECT 与写入 SQL

3. Schema 元数据与索引探测

  • 3.1 从 information_schema 读取列名、类型、可空性、列顺序
  • 3.2 实现唯一索引发现,优先主键,支持用户强制指定索引
  • 3.3 实现分片列索引探测:联合索引 / 单列索引 / 无索引三种结果
  • 3.4 实现日期列候选枚举与错误提示
  • 3.5 实现整数 epoch 列的 min/max 采样与三种单位解释提示

4. 扫描器

  • 4.1 实现主键 seek 分块扫描(key > :last ORDER BY key LIMIT :chunk_size)
  • 4.2 实现主键空洞与尾 chunk 的处理,返回准确 LastKey
  • 4.3 实现日期路径 A:(shard_col, pk) 行构造器 keyset 分块
  • 4.4 实现日期路径 B:逐日枚举 + 长游标流式读取
  • 4.5 实现 NULL 日期先扫、非 NULL 后扫的两段扫描
  • 4.6 接入 --max-lag 拉取前检查与 --check-interval 等待

5. 行编码与压缩

  • 5.1 实现 dump 编码器(TAB、\N、与 MySQL 一致的转义表)
  • 5.2 实现 CSV 编码器(RFC4180、表头、引号规则、--csv-null)
  • 5.3 实现 JSONL 编码器(时间、DECIMAL、BLOB 的类型映射)
  • 5.4 实现每分片独立的 gzip 与 zstd 压缩包装器
  • 5.5 用固定样例验证三种格式可被对应工具直接导入

6. 分片写入与清单

  • 6.1 实现 ShardWriter:单活跃分片、逐行写入、按 --shard-rows 封片
  • 6.2 实现 .partial 写入与封片时的 fsync + 原子重命名
  • 6.3 实现文件名规则:[date=<d>/]<seq>.<lo>-<hi>.<format>[.<comp>]
  • 6.4 实现日期分片的目录布局与日期切换时封片
  • 6.5 实现 manifest.jsonl 追加与 flush(seq/path/date/pk_lo/pk_hi/rows/bytes/sha256)
  • 6.6 实现崩溃后残留 .partial 的识别与清理

7. 目标表写入

  • 7.1 实现多行批量 INSERT,按 max_allowed_packet 自动拆分
  • 7.2 实现 --insert-ignore 与 --replace
  • 7.3 实现同实例单事务提交
  • 7.4 实现跨实例分别提交与 --retries 重试

8. 删除

  • 8.1 实现默认 IN 列表删除与 1000 参数分批
  • 8.2 实现 --bulk-delete 区间删除并附带 --where
  • 8.3 实现 --safe-auto-increment 保护最大主键行
  • 8.4 实现日期路径 B 的独立 purge 连接
  • 8.5 实现日期模式拒绝 --bulk-delete 的启动校验

9. Checkpoint 与续跑

  • 9.1 实现 state.json 原子写(tmp + fsync + rename)
  • 9.2 记录并校验 config_hash、游标、当前分片序号、已处理行数
  • 9.3 实现续跑:从游标恢复、跳过已封分片、清理未完成临时文件
  • 9.4 实现配置不一致时的拒绝与 --force-resume 覆盖
  • 9.5 实现信号中断时 flush 当前分片并写 checkpoint

10. 进度、统计与错误

  • 10.1 实现 --progress N 周期进度输出
  • 10.2 实现 --statistics 结束汇总
  • 10.3 统一退出码与错误分类(配置、连接、写入、校验、中断)

11. 集成测试与验收

  • 11.1 搭建 MySQL 测试环境与固定数据夹具
  • 11.2 验证分片有序连续不变量:范围无重叠、合并等于全集、文件名首尾主键正确
  • 11.3 验证 chunk 跨分片边界(chunk-size 与 shard-rows 非整除)
  • 11.4 验证日期路径 A 与路径 B 的输出一致
  • 11.5 验证 NULL、零日期、epoch 秒/毫秒/微秒的分片归属
  • 11.6 验证崩溃续跑不丢数据、manifest 与 state 一致
  • 11.7 验证 dump/csv/jsonl 分别可被 MySQL、Postgres/ClickHouse 导入
  • 11.8 验证 gzip/zstd 分片可独立解压导入
  • 11.9 验证 --dry-run、互斥校验、无索引 fail-fast 的错误信息

12. 文档与发布

  • 12.1 编写 README:安装、最小示例、分片模式、导入方法
  • 12.2 编写安全说明:--purge、--bulk-delete、at-least-once、时区
  • 12.3 编写与 pt-archiver 的参数对照表
  • 12.4 打包 Windows/Linux 二进制与版本信息