Renamed from arcdb: module path, cmd/archer, internal/archererr, docs, build scripts and ARCHER_* environment variables. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
4.9 KiB
cli-contract Specification
Purpose
定义 archer 的命令行参数、默认值、参数之间的依赖与互斥规则,以及启动校验、错误信息和 dry-run 行为。
Requirements
Requirement: 必填参数
系统 MUST 要求提供 --source 与 --where,并且 --file、--dest、--purge 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
Scenario: 缺少过滤条件
- WHEN 用户未提供
--where - THEN 系统立即报错,提示
--where必填,不建立数据库连接
Scenario: 没有任何输出目标
- WHEN 用户既未提供
--file、--dest,也未启用--purge - THEN 系统报错,提示至少需要一种输出目标
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,然后以非零退出码结束