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

7.8 KiB
Raw Permalink Blame History

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