archer import replays a sealed archive into an existing table: shard selection (`--select`), SHA-256 pre-verification, idempotent modes (`ignore`/`insert`/`replace`), and both LOAD DATA and batched-INSERT engines. It reads manifest.jsonl strictly so corruption is reported instead of skipped, and supports --dry-run, --allow-partial, and per-shard workers. --bulk-delete no longer rejects --shard-by date. Range deletion now derives its bounds from the chunk's actual keys (date scanners rewrite LastKey into a resumption cursor) and keeps safe-auto-increment semantics by excluding the current max key. A startup warning documents the monotonic-shard-column assumption. Also splits CLI/format/sharding/progress/safety reference docs out of the README, and adds the corresponding OpenSpec change artifacts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
7.1 KiB
7.1 KiB
1. CLI 子命令与配置
- 1.1
cmd/archer/main.go:在解析参数前识别os.Args[1] == "import",分发到导入入口;其余参数保持现有行为 - 1.2 新建
internal/cli/import.go:ImportConfig、ParseImport、ValidateImport,与现有Config解耦 - 1.3 实现导入参数与默认值:
--file、--dest、--dest-table、--columns、--assume-all-columns、--select、--mode、--engine、--verify、--workers、--charset、--time-zone、--allow-partial、--allow-warnings、--dry-run、--progress、--statistics - 1.4 拒绝导出专属参数(
--source、--where、--purge等)与未知参数,退出码 2;--columns与--assume-all-columns互斥 - 1.5
archer import --help与archer import --version可用 - 1.6 单元测试:默认值、参数互斥、非法
--mode/--engine/--workers/--select、导出参数被拒绝、列映射参数冲突
2. 归档读取与选片
- 2.1 在
internal/shard新增严格只读清单加载器:解析失败即报错,不打开追加句柄、不修改归档 - 2.2 从
Entry.Path推导格式与压缩方式,并要求所有选中分片一致;非dump报错 - 2.3 实现
--select解析:all、seq:A-B、pk:LO-HI、date:D1..D2,多次取并集、按seq去重排序 - 2.4
pk:使用分片区间相交语义;date:在清单无日期桶时报错 - 2.5 使用
checkpoint.Load实现完成度门槛:默认要求complete == true,--allow-partial放开 - 2.6 校验选中分片文件存在;清单损坏、条目文件缺失时在连接数据库前报错
- 2.7 单元测试:四种选择器、并集去重、空选择、日期桶缺失、损坏清单行、缺失文件、完成度门槛
3. 目标库前置检查与列映射
- 3.1 建立目标连接,执行
SELECT @@local_infile, @@version;--engine load且关闭时给出可操作错误 - 3.2 校验目标表存在(
information_schema.tables),不存在时报错 - 3.3 加载目标列元数据(名、ordinal、是否为
VIRTUAL/STORED GENERATED) - 3.4 归档记录列清单时:按记录顺序按名校验目标列存在、拒绝包含生成列、生成
LOAD DATA列清单 - 3.5
--columns模式:解析用户提供的文件字段顺序,做与 3.4 相同的名校验 - 3.6
--assume-all-columns模式:按目标 ordinal 生成列清单,生成列替换为@_archer_skip_<i>丢弃变量,打印位置映射警告 - 3.7 无任何映射来源时拒绝导入,提示
--columns或--assume-all-columns - 3.8 读取首个选中分片首行,按未转义 TAB 统计字段数,与列清单长度比较;不一致在装载前报错
- 3.9 每个 worker 使用固定
*sql.Conn,设置character_set与可选time_zone - 3.10 单元测试:名校验、缺失列、生成列拒绝、位置映射丢弃变量、字段数不一致、映射来源缺失
4. load 引擎
- 4.1 实现单分片流式装载:注册唯一
Readerhandler → 解压 Reader → 执行LOAD DATA LOCAL INFILE 'Reader::<name>'→ 注销 - 4.2 生成与
dump编码严格对应的 SQL:FIELDS TERMINATED BY '\t' ESCAPED BY '\\' LINES TERMINATED BY '\n'、CHARACTER SET、可选列清单、IGNORE/REPLACE - 4.3 实现
--verify pre:流式计算压缩文件 SHA-256 并与清单比对;--verify off跳过 - 4.4 装载后在同一会话执行
SHOW WARNINGS;有告警且未指定--allow-warnings时失败 - 4.5 实现行数规则:
insert要求 affected == rows;ignore要求 affected <= rows 并报告差额;replace只报告 - 4.6 确保失败路径清理 handler 注册与文件句柄
- 4.7 单元测试:SQL 形状、模式映射、哈希不一致、告警失败、行数规则
5. insert 兜底引擎
- 5.1 实现最小
dump行解码器:TAB 分隔、\N→ NULL、反转义\\ \t \n \r \0 \b \Z - 5.2 复用
internal/sink.DB的分批插入逻辑,按max_allowed_packet切批 - 5.3 每个分片的所有批次包在同一个事务中,保证分片级原子
- 5.4 单元测试:解码器边界(空串、NULL、转义、中文、emoji、BLOB)、分批与事务提交/回滚
6. 运行编排
- 6.1 实现 worker 池:按连续
seq区间分配,默认 1,结果与串行一致 - 6.2 接入
internal/progress.Reporter:以清单总行数为总量,按分片与行数推进 - 6.3 实现
--statistics:选片数、成功/失败/跳过分片数、期望/实际/跳过行数、字节与耗时 - 6.4 实现
--dry-run:只读清单与首行,打印选片、总行数/字节、目标表与引擎,不连接目标库、不装载 - 6.5 失败即停:报告失败分片
seq、原因与累计行数;已成功分片保留 - 6.6 用
internal/archererr映射退出码:配置 2、连接 3、写入 4、校验 5、中断 130 - 6.7 信号中断:停止开始新分片,当前分片完成或安全失败后以非零码退出
7. 测试
- 7.1 单元测试:选片、清单、字段数、SQL、解码器、退出码
- 7.2 集成测试:导出小表 → 导入空表,比较行数与抽样内容(沿用
ARCHER_TEST_DSN门控) - 7.3 集成测试:
none/gzip/zstd/xz四种压缩的导入 - 7.4 集成测试:
ignore重复导入幂等、insert遇重复失败、replace覆盖 - 7.5 集成测试:篡改分片触发哈希失败、
complete=false默认拒绝与--allow-partial放开 - 7.6 集成测试:
--workers 1与--workers 4导入结果一致 - 7.7 集成测试:
--engine insert与--engine load结果一致 - 7.8 保真测试:NULL、TAB、换行、反斜杠、中文、emoji、BLOB 的导出→导入往返
- 7.9 列映射测试:归档列清单、
--columns、--assume-all-columns三种来源;目标表含生成列时丢弃变量生效;缺失列/字段数不一致被拒绝 - 7.10
gofmt、go build ./...、go vet ./...、go test ./...通过
8. 文档与 OpenSpec
- 8.1 新增
docs/import.md:使用示例、选片语义、完整性检查、两种引擎、local_infile与代理限制、导回原表的注意事项 - 8.2 更新
README.md的功能与文档索引 - 8.3 更新
docs/cli-reference.md的导入参数表 - 8.4 运行
openspec validate add-archive-import --strict - 8.5 在具备 MySQL 的环境中完成一次真实归档目录的按需导入,并记录结果
- 2026-11-08:临时 MySQL 8.3.0 实例(
local_infile=ON)。ARCHER_TEST_DSN门控下运行go test ./internal/importer -run Integration -v,导出→导入、四种压缩、三种模式、哈希/完成度门槛、workers 1/4、load/insert 引擎、保真往返、三种列映射全部通过。 - 2026-11-08 手工 CLI:导出一张 7 行表为 3 个 count 分片;
archer import --workers 2 --assume-all-columns --statistics导入空表,7/7 行与原表逐列一致(affected=7,skipped=0)。默认ignore重跑:affected=0,skipped=7。--dry-run未建立连接。 - 同次运行
go build ./...、go vet ./...、全量go test ./...均通过。
- 2026-11-08:临时 MySQL 8.3.0 实例(