Files
archer/openspec/changes/archive/2026-11-08-add-archive-import/proposal.md
T
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

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