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

200 lines
9.0 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.
# cli-contract Specification
## Purpose
定义 archer 的命令行参数、默认值、参数之间的依赖与互斥规则,以及启动校验、错误信息和 dry-run 行为。
## Requirements
### Requirement: 必填参数
归档(导出)模式下,系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
导入模式(`archer import`)MUST 要求提供 `--file` 与 `--dest`;`--source`、`--where`、`--purge` 在导入模式下 MUST 被拒绝。缺少必需参数时,系统 MUST 在连接目标数据库前报错退出。
#### Scenario: 缺少过滤条件
- **WHEN** 归档模式未提供 `--where`
- **THEN** 系统立即报错,提示 `--where` 必填,不建立数据库连接
#### Scenario: 没有任何输出目标
- **WHEN** 归档模式既未提供 `--file`、`--dest`,也未启用 `--purge`
- **THEN** 系统报错,提示至少需要一种输出目标
#### Scenario: 导入模式缺少目标
- **WHEN** `archer import` 未提供 `--dest`
- **THEN** 系统立即报错,提示 `--dest` 必填,不建立数据库连接
#### Scenario: 导入模式误用导出参数
- **WHEN** `archer import` 带上 `--source` 或 `--where`
- **THEN** 系统在解析阶段报错,说明该参数仅用于归档模式
### Requirement: 导入子命令
系统 MUST 提供 `archer import` 子命令,语法为 `archer import --file <dir> --dest <dsn> [flags]`。未知参数 MUST 报错。`archer import --help` MUST 打印导入模式的参数说明;`archer --version` 与 `archer import --version` MUST 均可打印版本并退出。
导入模式的参数与默认值:
| 参数 | 默认 | 说明 |
|---|---|---|
| `--file` | 必填 | 归档目录,必须存在且包含 `manifest.jsonl` |
| `--dest` | 必填 | 目标 MySQL DSN |
| `--dest-table` | 归档记录的源表名 | 目标表名;归档未记录表名时必须显式提供 |
| `--columns` | 空 | 按文件字段顺序给出目标列名;与 `--assume-all-columns` 互斥 |
| `--assume-all-columns` | 关闭 | 接受与目标表 ordinal 顺序一致的位置映射,并打印警告 |
| `--select` | `all` | 可重复;`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2` |
| `--mode` | `ignore` | `ignore` / `insert` / `replace` |
| `--engine` | `load` | `load` / `insert` |
| `--verify` | `pre` | `pre` / `off` |
| `--workers` | `1` | 并行分片数,必须大于 0 |
| `--charset` | `utf8mb4` | 装载时使用的字符集 |
| `--time-zone` | 空 | 设置目标会话时区;空表示使用服务端默认 |
| `--allow-partial` | 关闭 | 允许导入未完成归档的已封分片 |
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
| `--dry-run` | 关闭 | 只打印选片与配置 |
| `--progress` | `auto` | 进度输出 |
| `--statistics` | 关闭 | 结束汇总 |
#### Scenario: 最小导入命令
- **WHEN** 用户执行 `archer import --file ./export/orders --dest 'user:pass@tcp(host:3306)/db'`
- **THEN** 系统按默认值解析为 `all` / `ignore` / `load` / `pre` / 1 个 worker
#### Scenario: 未知参数
- **WHEN** 用户给 `archer import` 传入未定义的参数
- **THEN** 系统报错并以退出码 2 结束
#### Scenario: 非法 worker 数
- **WHEN** 用户指定 `--workers 0`
- **THEN** 系统在连接数据库前报错,说明必须大于 0
#### Scenario: 非法模式
- **WHEN** 用户指定 `--mode merge` 或 `--engine bulk`
- **THEN** 系统在解析阶段报错,列出允许的取值
#### Scenario: 列映射参数互斥
- **WHEN** 用户同时指定 `--columns` 与 `--assume-all-columns`
- **THEN** 系统在连接数据库前报错,说明二者只能选一个
#### Scenario: 归档已记录列清单又显式指定映射
- **WHEN** `state.json` 的 `columns` 非空,且用户仍指定 `--columns` 或 `--assume-all-columns`
- **THEN** 系统报错,避免两套映射来源冲突
### Requirement: 导入模式的 dry-run、进度与退出码
`--dry-run` 时,系统 MUST 打印解析后的导入配置、选中分片与汇总,MUST NOT 执行装载或写入。`--progress` 与 `--statistics` 在导入模式下的语义 SHALL 与归档模式一致,分别输出分片进度与结束汇总。
成功完成 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片并返回非零退出码。
#### Scenario: dry-run
- **WHEN** 用户执行 `archer import ... --dry-run`
- **THEN** 标准输出包含选中分片、总行数与总字节数,目标库没有数据变化
#### Scenario: 结束统计
- **WHEN** 用户执行 `archer import ... --statistics`
- **THEN** 进程退出前输出成功/跳过/失败分片数、行数与耗时
#### Scenario: 配置错误退出码
- **WHEN** `--select` 语法非法
- **THEN** 进程以退出码 2 结束,不建立数据库连接
### Requirement: 默认值
系统 SHALL 采用以下默认值:`--chunk-size 2000`、`--shard-by none`、`--shard-rows 0`、`--format dump`、`--compress none`、`--compress-level 3`、`--max-lag 1s`、`--check-interval 1s`、`--retries 1`、`--safe-auto-increment true`、`--progress 0`。
#### Scenario: 最小可运行配置
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
### Requirement: 参数依赖与互斥
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge`;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误。违反时 MUST 在启动阶段报错。
#### Scenario: 数量模式误传日期列
- **WHEN** `--shard-by count` 同时带上 `--shard-column`
- **THEN** 系统报错,说明该参数仅在日期模式下有效
#### Scenario: 未启用 purge 却要求 bulk-delete
- **WHEN** 用户指定 `--bulk-delete` 但未指定 `--purge`
- **THEN** 系统报错,说明 bulk-delete 必须配合 purge
#### Scenario: 插入模式互斥
- **WHEN** 用户同时指定 `--insert-ignore` 与 `--replace`
- **THEN** 系统报错,要求只能选择一种插入模式
#### Scenario: 压缩档位越界
- **WHEN** 用户指定 `--compress-level 0` 或 `--compress-level 10`
- **THEN** 系统在启动阶段报错,说明档位必须在 1–9 之间
#### Scenario: 不压缩却指定非默认档位
- **WHEN** 用户指定 `--compress none` 与 `--compress-level 5`
- **THEN** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
### Requirement: 日期列探测与错误提示
启动时,系统 SHALL 读取表元数据并判断 `--shard-column` 是否存在、类型是否受支持、是否可为 NULL。缺少 `--shard-column` 时 MUST 列出所有候选日期/时间列及其类型。整数列缺少单位声明时 MUST 采样最小/最大值,并展示按秒、毫秒、微秒解释后的日期范围。
#### Scenario: 列出候选列
- **WHEN** 用户指定 `--shard-by date` 但未给 `--shard-column`
- **THEN** 错误信息包含表内所有 DATE/DATETIME/TIMESTAMP 列的列名、类型与可空性
#### Scenario: epoch 单位提示
- **WHEN** 分片列为 BIGINT 且未声明单位
- **THEN** 错误信息展示采样范围以及三种单位解释下的日期范围,不自动选择
### Requirement: dry-run
`--dry-run` 时,系统 MUST 打印解析后的配置、索引探测结果、最终生效的分片与格式参数,以及第一条将要执行的 SELECT 和每类写入语句,然后退出。系统 MUST NOT 建立写入连接、创建目录或写文件。
#### Scenario: dry-run 输出 SQL
- **WHEN** 用户传入 `--dry-run`
- **THEN** 标准输出包含解析后的配置和将要执行的 SQL,进程以 0 退出
### Requirement: 进度与统计
当 `--progress N` 大于 0 时,系统 SHALL 每处理 N 行输出一次进度,包含已处理行数、当前分片序号与耗时。启用 `--statistics` 时,系统 MUST 在结束时输出读取行数、写入行数、删除行数、分片数与各阶段耗时。
#### Scenario: 周期进度
- **WHEN** `--progress 100000`
- **THEN** 每处理 100000 行打印一行进度信息
#### Scenario: 结束统计
- **WHEN** 启用 `--statistics`
- **THEN** 进程退出前输出汇总统计
### Requirement: 退出码
系统 SHALL 在成功完成时返回 0;配置错误、连接错误、写入错误或校验失败时返回非零退出码。被信号中断时 MUST 完成当前 chunk 的清理并返回非零退出码。
#### Scenario: 配置错误
- **WHEN** 参数校验失败
- **THEN** 进程以非零退出码结束,且不产生部分输出文件
#### Scenario: 信号中断
- **WHEN** 进程收到 SIGINT
- **THEN** 系统停止拉取新 chunk,关闭并 flush 当前分片,写入 checkpoint,然后以非零退出码结束