# 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 [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 扩展 |