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>
12 KiB
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