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