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>
47 lines
3.7 KiB
Markdown
47 lines
3.7 KiB
Markdown
## 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`,吞吐下降但语义不变。
|