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:
voidandClaude Sonnet 4.6 committed 2026-11-06 22:12:17 +08:00
commit bc4a6b504f
99 files changed
+12752

No files matched your search

@@ -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 二进制与版本信息