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

12 KiB
Raw Blame History

Purpose

定义如何把一次归档产出(分片文件 + manifest.jsonl + state.json)按需、可校验、可重复地重放进 MySQL 目标表,供冷数据查询与恢复使用。

ADDED Requirements

Requirement: 归档目录与清单权威性

一次导入 MUST 以一个包含 manifest.jsonl 的归档目录为单元。系统 MUST 以清单记录为唯一权威:只考虑清单中登记的分片,并按 seq 升序处理;清单之外的文件 MUST NOT 导入。清单条目指向的文件缺失时,系统 MUST 报错并终止,不得跳过该条目继续导入。

Scenario: 目录中存在未登记文件

  • WHEN 归档目录中有一个已封分片文件,但 manifest.jsonl 没有对应记录
  • THEN 系统不导入该文件,并在统计中报告其被忽略

Scenario: 清单条目对应文件缺失

  • WHEN 清单登记了 000003.*,但该文件已被删除
  • THEN 系统在开始装载前报错,指出缺失的分片序号与路径

Scenario: 清单包含损坏行

  • WHEN manifest.jsonl 中某行不是合法 JSON
  • THEN 系统报错并终止,不得把损坏行当作“没有该分片”处理

Requirement: 归档完成度门槛

默认情况下,系统 MUST 要求 state.json 存在且 complete 为 true;不满足时 MUST 在导入任何分片前报错,并提示可使用 --allow-partial 显式导入已封分片。启用 --allow-partial 时,系统 SHALL 忽略完成度标记,只导入清单中已封的分片。

Scenario: 未完成的归档

  • WHEN state.json 中 complete 为 false,且未指定 --allow-partial
  • THEN 系统拒绝导入,说明该归档可能只包含部分数据

Scenario: 显式导入部分归档

  • WHEN complete 为 false,且指定 --allow-partial
  • THEN 系统导入清单中所有已封分片,并在结束统计中标注“部分归档”

Scenario: 缺少 state.json

  • WHEN 归档目录没有 state.json,且未指定 --allow-partial
  • THEN 系统拒绝导入,说明无法确认导出是否完成

Requirement: 分片选择

系统 MUST 支持通过可重复的 --select 选择分片,多个选择条件取并集并按 seq 去重。支持的语法为:all、seq:A-B(闭区间)、pk:LO-HI、date:D1..D2(闭区间)。未提供 --select 时等价于 all。

pk:LO-HI MUST 选择主键范围与闭区间 [LO,HI] 相交的分片;由于装载不支持行级过滤,边界分片可能包含请求范围之外的行,系统 MUST 在选择结果中明示这一点。date:D1..D2 MUST 只匹配清单中带日期桶的分片;归档不含日期信息时,系统 MUST 报错并说明该归档不是按日期分片导出的。

Scenario: 按序号选择

  • WHEN --select seq:3-9
  • THEN 系统只导入 seq 在 3 到 9(含)之间的分片

Scenario: 主键区间命中边界分片

  • WHEN 请求 --select pk:150000-250000,而分片 1 的范围是 1-200000、分片 2 是 200001-400000
  • THEN 系统选择分片 1 和 2,并提示分片 1 会带入 1-149999 的行

Scenario: 多次选择取并集

  • WHEN 同时给出 --select seq:1-2 与 --select seq:2-3
  • THEN 系统导入分片 1、2、3,不重复处理分片 2

Scenario: 对非日期分片按日期选择

  • WHEN 归档为 --shard-by count 导出(清单无日期桶),用户指定 --select date:2025-01-01..2025-01-31
  • THEN 系统报错,说明该归档无法按日期选择,只能按序号或主键范围选择

Scenario: 选择结果为空

  • WHEN 选择条件没有命中任何分片
  • THEN 系统报错并以非零退出码结束,不连接目标库执行装载

Requirement: 完整性校验

默认情况下,系统 MUST 在装载每个分片前计算其压缩文件的 SHA-256,并与清单记录比对;不一致时 MUST 中止该分片并终止本次导入。--verify off 可关闭预校验。

每个分片装载完成后,系统 MUST 核对实际写入行数:insert 模式下 MUST 等于清单 rows;ignore 模式下 MUST NOT 大于 rows,差额 SHALL 报告为跳过行数;replace 模式 SHALL 只报告受影响行数。不满足对应规则时 MUST 视为失败并终止。

Scenario: 分片内容损坏

  • WHEN 某分片的 SHA-256 与清单不一致
  • THEN 系统在发送任何该分片数据前失败,指出分片序号与期望/实际哈希

Scenario: 严格插入的行数不足

  • WHEN --mode insert 装载一个清单记录 200000 行的分片,但实际写入 199999 行
  • THEN 系统报错并终止,指出分片序号与行数差异

Scenario: 重复导入产生的跳过

  • WHEN 使用默认 --mode ignore 重复导入同一分片
  • THEN 实际写入为 0、跳过为清单行数,导入继续并最终成功

Requirement: 插入模式与幂等

系统 MUST 提供 --mode ignore|insert|replace,默认 ignore。三种模式互斥。ignore MUST 跳过与目标表现有唯一键冲突的行且不修改既有行;insert MUST 在遇到重复键时失败;replace MUST 用归档内容覆盖冲突行。

系统 MUST NOT 在分片内部按行过滤;选择只决定导入哪些分片。

Scenario: 重复导入原表

  • WHEN 目标表已包含归档中的全部行,且使用默认 --mode ignore
  • THEN 导入成功,所有冲突行被跳过,目标表数据不变

Scenario: 严格插入遇到重复键

  • WHEN 使用 --mode insert,目标表已存在相同主键
  • THEN 该分片装载失败,系统报告重复键错误并终止

Scenario: 覆盖模式

  • WHEN 使用 --mode replace,目标表存在相同主键但列值不同
  • THEN 目标行被归档内容覆盖

Requirement: 装载引擎与 local_infile

系统 MUST 提供 --engine load|insert,默认 load。

load 引擎 MUST 通过客户端流式读取解压后的数据并执行 LOAD DATA LOCAL INFILE,MUST NOT 依赖将完整分片写入临时文件,也 MUST NOT 要求驱动开启任意本地文件读取。其字段与行分隔规则 MUST 与 dump 格式的产出完全对应。

启动时,系统 MUST 查询目标会话的 local_infile 状态。load 引擎在 local_infile 关闭时 MUST 在导入任何分片前失败,并在错误信息中给出两条出路:启用 local_infile,或改用 --engine insert。系统 MUST NOT 静默回退到 insert。

insert 引擎 MUST 使用参数化批量插入,并遵守目标的 max_allowed_packet。两种引擎对同一归档、同一目标表的行结果 MUST 一致。

服务端报告告警时,系统 MUST 默认视为失败;--allow-warnings 可改为记录告警并继续。ignore 模式下因唯一键冲突被跳过的行 SHALL 计入跳过行数,其重复键告警 MUST NOT 单独导致分片失败,否则默认重跑无法幂等。

Scenario: local_infile 已关闭

  • WHEN SELECT @@local_infile 返回 0,且使用默认 --engine load
  • THEN 系统在装载任何分片前失败,并提示启用该变量或改用 --engine insert

Scenario: 显式使用插入兜底

  • WHEN local_infile 关闭,且指定 --engine insert
  • THEN 系统通过批量参数化插入完成导入,行为与 load 引擎一致

Scenario: 装载产生告警

  • WHEN 服务端返回至少一条告警,且未指定 --allow-warnings
  • THEN 系统把该分片视为失败并终止

Requirement: 目标表与列映射

目标表 MUST 预先存在;不存在时系统 MUST 在装载前报错,不尝试创建表。

列映射 MUST 以列名而不是文件位置为准。当归档记录了列清单时(state.json 的 columns 非空):

  • 每个记录的列名 MUST 在目标表中存在,否则 MUST 报错;
  • 装载列清单 MUST 按记录顺序生成;
  • 记录中包含目标表的生成列时,系统 MUST 报错,不得静默丢弃该字段或写入生成列。

当归档为默认全列导出、未记录列名时,系统 MUST NOT 仅凭“文件字段数等于目标表列数”认为映射正确。此时用户 MUST 显式提供以下之一:

  • --columns:按文件字段顺序给出目标列名,系统按名校验并生成装载列清单;
  • --assume-all-columns:接受位置映射,系统按目标表全部列的 ordinal 顺序生成装载列清单,把生成列映射为丢弃用的用户变量,并 MUST 打印位置映射警告。

文件字段数与装载列清单长度不一致时,系统 MUST 在装载前报错。字段数核对只是前置检查,列名与顺序的正确性由记录列清单或显式 --columns 保证。

Scenario: 目标表不存在

  • WHEN --dest 指向的库中没有目标表
  • THEN 系统报错,提示需要先创建表

Scenario: 归档记录了列清单且目标缺列

  • WHEN 归档记录列 id,created_at,title,目标表只有 id,created_at
  • THEN 系统在装载前报错,指出缺失的列名

Scenario: 归档列清单包含生成列

  • WHEN 归档记录的列清单包含目标表的生成列 full_name
  • THEN 系统报错,说明生成列不能从归档写入

Scenario: 全列归档未提供映射

  • WHEN 归档未记录列名,且既未提供 --columns 也未指定 --assume-all-columns
  • THEN 系统拒绝导入,并说明两种显式映射方式

Scenario: 位置映射遇到生成列

  • WHEN 使用 --assume-all-columns,目标表含一个生成列,且文件字段数与全部列数一致
  • THEN 系统把生成列位置映射为丢弃变量,装载成功,并打印位置映射警告

Scenario: 字段数不一致

  • WHEN 文件首行有 10 个字段,装载列清单长度为 11
  • THEN 系统在装载前报错,指出字段数与列清单长度

Requirement: 进度、统计与 dry-run

启用 --dry-run 时,系统 MUST 打印解析后的配置、选中的分片列表(序号、路径、行数、字节数、日期桶)、总行数与总字节数,并 MUST NOT 执行任何装载或写入。启用 --progress 时,系统 SHALL 按分片完成情况输出已导入行数与分片进度。启用 --statistics 时,系统 MUST 在结束时输出选片数、成功/失败/跳过分片数、期望/实际/跳过的行数、字节数与耗时。

--workers N 默认 1(N 必须大于 0)。并行时系统 MUST 以连续 seq 区间分配分片,且最终数据结果 MUST 与串行导入一致。

Scenario: dry-run 不写数据

  • WHEN 用户传入 --dry-run
  • THEN 标准输出包含选中分片与汇总信息,目标表不发生任何写入

Scenario: 并行导入结果一致

  • WHEN 同一归档分别以 --workers 1 与 --workers 4 导入空表
  • THEN 两次导入后的目标表行集合相同

Requirement: 失败语义与退出码

每个分片的装载 MUST 是原子的:分片失败时,系统 MUST NOT 在该分片留下部分行;此前已成功的分片 SHALL 保持已导入状态。系统 MUST 在首个分片失败时终止,并报告失败分片序号与失败前的累计导入行数。使用 --mode ignore 时,修复问题后重跑 MUST 安全。

成功完成时系统 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片,并返回非零退出码。

Scenario: 分片装载中断

  • WHEN 第 3 个分片在装载过程中失败
  • THEN 分片 3 不留下部分行,分片 1、2 保持已导入,进程以非零退出码结束

Scenario: 修复后重跑

  • WHEN 上次导入在第 3 个分片失败,修复原因后使用默认 --mode ignore 重跑
  • THEN 已导入的分片被跳过,导入从失败处继续完成

Scenario: 参数错误

  • WHEN --workers 0 或未知 --select 语法
  • THEN 系统在连接数据库前报错,退出码为 2

Requirement: 格式支持范围

v1 的导入 MUST 只支持 dump 格式。归档为 csv 或 jsonl 时,系统 MUST 报错并说明当前仅支持 dump,不得尝试按 dump 规则解析。

Scenario: csv 归档

  • WHEN 选中的分片扩展名为 .csv 或 .csv.gz
  • THEN 系统报错,说明导入功能暂不支持 csv

Scenario: jsonl 归档

  • WHEN 选中的分片扩展名为 .jsonl
  • THEN 系统报错,说明导入功能暂不支持 jsonl