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

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