Files
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

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

97 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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 二进制与版本信息