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>
4.7 KiB
4.7 KiB
MODIFIED 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 系统在解析阶段报错,说明该参数仅用于归档模式
ADDED Requirements
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 结束,不建立数据库连接