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 |
— |
打印版本并退出 |
行为细节见导入归档。
退出码
| 码 |
含义 |
| 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 扩展 |