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

9.0 KiB
Raw Permalink Blame History

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,然后以非零退出码结束