Files
voidandClaude Sonnet 4.6 366d61ca25 Add archer import and allow date-mode bulk delete
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>
2026-11-08 21:14:23 +08:00

7.1 KiB
Raw Permalink Blame History

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 实现单分片流式装载:注册唯一 Reader handler → 解压 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 ./... 均通过。