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>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 21:14:23 +08:00
1 parent bc4a6b504f
commit 366d61ca25
49 files changed
+5099 -342

No files matched your search

+140
View File
@@ -0,0 +1,140 @@
# CLI 参考
## 参数参考
按功能分组。“默认”是未显式传参时的值;标注“必填”的参数缺失时以退出码 2 退出。
### 连接与目标
| 参数 | 默认 | 说明 |
|---|---|---|
| `--source` | 必填 | 源 MySQL DSN。`parseTime` 被强制关闭,列值按原始字节读取。 |
| `--table` | 必填 | 源表名。 |
| `--where` | 必填 | 源表过滤条件,原样拼入 SQL;空白字符串视为未提供。 |
| `--dest` | 空 | 目标 MySQL DSN。`--file`、`--dest`、`--purge` 至少要有一个。与源同实例(`host:port` 相同)时,dest 插入与 purge 删除共用一个事务。 |
| `--dest-table` | 同 `--table` | 目标表名,仅 `--dest` 生效。 |
| `--columns` | 全部列 | 逗号分隔的输出/插入列。扫描键与分片列总会读取,但只有列在此列表中才会写出。 |
| `--file` | 空 | 输出目录;设置后生成分片文件、`manifest.jsonl` 与 `state.json`。 |
| `--insert-ignore` | 关闭 | dest 写入使用 `INSERT IGNORE`。与 `--replace` 互斥。 |
| `--replace` | 关闭 | dest 写入使用 `REPLACE`。与 `--insert-ignore` 互斥。 |
| `--purge` | 关闭 | 归档后删除源表行。没有其他输出目标时,单独使用即为“只删除”。 |
### 扫描与事务
| 参数 | 默认 | 说明 |
|---|---|---|
| `--chunk-size` | `2000` | 每条 SELECT 的行数,同时是事务大小与 checkpoint 粒度。 |
| `--limit` | — | `--chunk-size` 的隐藏别名(已弃用),只能与 `--chunk-size` 二选一。 |
| `--index` | 自动选择 | 强制用指定索引作为扫描键。必须是唯一索引且各列 `NOT NULL`;未指定时优先主键,否则取第一个满足条件的唯一索引。 |
| `--safe-auto-increment` | 开启 | purge 时跳过当前最大自增键所在行,避免删掉写入端刚分配的最大 id。 |
### 分片
| 参数 | 默认 | 说明 |
|---|---|---|
| `--shard-by` | `none` | `none`:单文件;`count`:每 `--shard-rows` 行封片;`date`:按分片列的日期分目录。 |
| `--shard-rows` | `0` | `none` 时必须为 0;`count` 时必须大于 0;`date` 时为 0 表示每天一个文件,大于 0 表示同一天内再按行切片。 |
| `--shard-column` | — | 仅 `date` 且必填;日期、`DATETIME`/`TIMESTAMP` 或整数 epoch 列。 |
| `--shard-column-type` | — | 仅 `date` 且分片列为整数时必填:`epoch-seconds` / `epoch-milliseconds` / `epoch-microseconds`。 |
| `--shard-time-zone` | `UTC` | 仅用于解释整数 epoch 的日归属;与 DSN 的 `time_zone` 一起计入配置指纹。 |
| `--zero-date` | 报错 | 空:遇到 `0000-00-00` 报错并输出行键;`bucket`:放入 `date=0000-00-00`。仅 `date`。 |
| `--allow-full-scan` | 关闭 | `date` 模式下没有可用索引时,允许退化为路径 B 的全表扫描,而不是 fail-fast。 |
### 输出格式
| 参数 | 默认 | 说明 |
|---|---|---|
| `--format` | `dump` | `dump` / `csv` / `jsonl`。 |
| `--compress` | `none` | `none` / `gzip` / `zstd` / `xz`;每个分片独立压缩。 |
| `--compress-level` | `3` | 1–9 的统一档位;`--compress none` 时只接受默认值 3。 |
| `--csv-null` | `\N` | `csv` 中 NULL 的文本表示,仅 `--format csv` 生效。 |
### 副本延迟
| 参数 | 默认 | 说明 |
|---|---|---|
| `--check-replica-lag` | 空 | 副本 DSN。设置后每个 chunk 读取前执行 `SHOW REPLICA STATUS`(回退 `SHOW SLAVE STATUS`),延迟超标或复制线程未运行就等待。 |
| `--max-lag` | `1s` | 允许的最大副本延迟;只有设置了 `--check-replica-lag` 才生效。 |
| `--check-interval` | `1s` | 两次延迟检查之间的等待间隔。 |
### 重试与恢复
| 参数 | 默认 | 说明 |
|---|---|---|
| `--retries` | `1` | chunk 的数据库事务失败后的重试次数。总尝试次数为 `1 + retries`,第 n 次重试前等待 n 秒。 |
| `--force-resume` | 关闭 | 配置指纹不一致时仍从 `state.json` 续跑。 |
| `--dry-run` | 关闭 | 输出解析后的配置、索引探测结果与将要执行的 SQL;不写文件、不写目标表、不删除数据。 |
### 进度与统计
| 参数 | 默认 | 说明 |
|---|---|---|
| `--progress` | `auto` | `auto`:stderr 是终端才显示;`on`:始终显示;`off`/`0`:关闭;`N>0`:开启并每 N 行额外输出一行。 |
| `--progress-interval` | `1s` | 两次进度刷新之间的最小间隔。 |
| `--statistics` | 关闭 | 结束后向 stdout 打印汇总。 |
| `--version` | — | 打印版本并退出,不执行配置校验。 |
## 导入模式(`archer import`)
`archer import --file <归档目录> --dest <DSN> [flags]` 把归档重放进已存在的目标表。导入模式只接受下列参数;`--source`、`--table`、`--where`、`--purge`、`--format`、`--compress` 等导出参数会被拒绝(退出码 2)。
| 参数 | 默认 | 说明 |
|---|---|---|
| `--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`(`LOAD DATA LOCAL INFILE`)/ `insert`(批量参数化插入) |
| `--verify` | `pre` | `pre`:装载前校验压缩文件 SHA-256;`off`:跳过 |
| `--workers` | `1` | 并行分片数,必须大于 0;按连续 `seq` 区间分配 |
| `--charset` | `utf8mb4` | 装载字符集 |
| `--time-zone` | 空 | 设置目标会话时区;空表示服务端默认 |
| `--allow-partial` | 关闭 | 允许导入 `state.json` 中 `complete` 为 false 或缺失的归档 |
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
| `--dry-run` | 关闭 | 只打印选片与配置,不连接目标库、不写入 |
| `--progress` | `auto` | 进度输出,语义同导出模式 |
| `--statistics` | 关闭 | 结束汇总 |
| `--version` | — | 打印版本并退出 |
行为细节见[导入归档](import.md)。
## 退出码
| 码 | 含义 |
|---|---|
| 0 | 成功 |
| 2 | 配置错误 |
| 3 | 连接错误 |
| 4 | 写入/文件错误 |
| 5 | 校验失败(索引、指纹、分片列等) |
| 130 | 被 SIGINT/SIGTERM 中断(已 flush 当前分片并写 checkpoint) |
| 1 | 其他 |
## 参数对照:pt-archiver
| pt-archiver | archer | 说明 |
|---|---|---|
| `--source` | `--source` | MySQL DSN |
| `--dest` | `--dest` | MySQL DSN |
| `--file` | `--file` | archer 中为输出目录 |
| `--limit` | `--limit` / `--chunk-size` | `--limit` 为隐藏别名;语义是每次 SELECT 行数 |
| `--txn-size` | — | chunk 即事务,不提供独立事务粒度 |
| `--where` | `--where` | 必填 |
| `--columns` | `--columns` | 逗号分隔 |
| `--purge` | `--purge` | 默认不删除 |
| `--bulk-delete` | `--bulk-delete` | 依赖 `--purge` |
| `--replace` | `--replace` | |
| `--ignore` | `--insert-ignore` | |
| `--safe-auto-increment` | `--safe-auto-increment` | 默认开启 |
| `--max-lag` | `--max-lag` | |
| `--check-slave-lag` | `--check-replica-lag` | 传副本 DSN |
| `--check-interval` | `--check-interval` | |
| `--retries` | `--retries` | |
| `--dry-run` | `--dry-run` | archer 输出解析后配置、索引探测与 SQL |
| — | `--shard-by` / `--shard-rows` / `--shard-column` | archer 扩展 |
| — | `--format` / `--compress` / `--compress-level` | archer 扩展 |
| — | `--progress` / `--progress-interval` | archer 扩展;默认 `auto`,写 stderr |
| — | `--allow-full-scan` / `--force-resume` | archer 扩展 |