Files
archer/docs/cli-reference.md
T
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

141 lines
7.8 KiB
Markdown
Raw 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 参考
## 参数参考
按功能分组。“默认”是未显式传参时的值;标注“必填”的参数缺失时以退出码 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 扩展 |