Files
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

244 lines
12 KiB
Markdown
Raw Permalink 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.
# archive-import Specification
## Purpose
定义如何把一次归档产出(分片文件 + `manifest.jsonl` + `state.json`)按需、可校验、可重复地重放进 MySQL 目标表,供冷数据查询与恢复使用。
## 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