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

3.7 KiB
Raw Blame History

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,吞吐下降但语义不变。