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>
3.7 KiB
3.7 KiB
Why
归档把冷数据移出了热表,但“冷”不等于“永不查询”。目前把归档文件装回 MySQL 只能按 docs/output-formats.md 手工 zcat | mysql:没有范围选择、没有完整性校验、没有幂等保证,导错或导到一半都会污染原表,而且失败后无法判断哪些分片已经落入。
What Changes
- 新增
archer import子命令,与导出共用同一个二进制;导入逻辑独立成internal/importer包。 - 以归档目录中的
manifest.jsonl为唯一权威:只导入清单中登记、文件存在且校验通过的分片;目录里游离的文件不导入。 - 分片选择支持整表、分片序号区间、主键区间、日期桶区间,多次
--select取并集;选择粒度为整个分片(LOAD DATA不支持行级过滤)。 - 列映射支持三种来源:归档记录的列清单、导入时
--columns指定的文件字段顺序、--assume-all-columns的位置映射(会警告)。 - 默认要求
state.json.complete == true,避免静默导入半张表;--allow-partial显式放开。 - 默认对每个压缩分片做 SHA-256 预校验,失败即中止;
--verify off可关闭。 - 默认
--mode ignore(INSERT IGNORE),利用归档中的主键实现重复导入幂等;可选insert/replace。 - 默认
--engine load:通过mysql.RegisterReaderHandler把解压流直接交给LOAD DATA LOCAL INFILE,不落临时文件;启动时探测@@local_infile,关闭则 fail-fast 并提示--engine insert。--engine insert复用现有批量参数化插入作为受限环境兜底。 - 目标表必须预先存在。列映射以列名为准:归档记录了列清单时按名校验;默认全列归档必须显式提供
--columns,或显式接受--assume-all-columns的位置映射。文件字段数只作为前置检查,不得作为“映射正确”的证明。 - 提供
--dry-run(打印选中分片、总行数/字节)、--workers、--progress、--statistics。 - v1 只支持
dump格式;csv/jsonl明确报错并说明原因。 - 新增
docs/import.md,并在 README 与 CLI 参考中登记导入入口。
Non-goals:
- 不做常驻服务、HTTP 接口、队列或定时任务。
- 不引入第二个二进制或独立仓库。
- 不支持 MySQL 以外的目标库。
- 不做导入台账或断点续导;幂等由
IGNORE与分片级原子装载保证。 - 不做行级过滤,选择粒度只到分片边界。
- 不自动建表、不生成 DDL、不修改表结构。
- 不改变导出端的文件格式与清单格式。
Capabilities
New Capabilities
archive-import: 从归档目录按清单重放分片到 MySQL,覆盖分片选择、完整性校验、幂等模式、装载引擎、目标前置检查、进度与失败语义。
Modified Capabilities
cli-contract: 增加import子命令的参数、默认值与校验规则;明确原有“必填参数”仅作用于归档(导出)模式。
Impact
- 代码:
cmd/archer/main.go(子命令分发)、internal/cli/import.go(新增)、internal/importer/(新增);复用internal/shard(清单)、internal/sink(插入兜底)、internal/progress、internal/archererr、internal/atomicfile。 - 依赖:无新增外部依赖;
github.com/go-sql-driver/mysql已支持Reader::形式的LOAD DATA LOCAL INFILE,且不需要allowAllFiles。 - 测试:新增
internal/importer单元测试;新增导入集成测试,沿用ARCHER_TEST_DSN门控。 - 文档:
docs/import.md、README.md、docs/cli-reference.md。 - 运维:目标库需要启用
local_infile(MySQL 8.0.3+ 默认关闭);不满足时使用--engine insert,吞吐下降但语义不变。