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>
This commit is contained in:
1 parent
bc4a6b504f
commit
366d61ca25
49 files changed
+5099
-342
No files matched your search
@@ -0,0 +1,241 @@
|
||||
## 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
|
||||
Reference in new issue
Block a user