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>
8.2 KiB
导入归档
archer import 把一次归档产出(分片文件 + manifest.jsonl + state.json)按需重放进一个已存在的 MySQL/MariaDB 表。它不创建表、不修改表结构,也不改变导出端的文件或清单格式。
archer import \
--file ./export/orders \
--dest 'user:pass@tcp(db.example:3306)/app' \
--dest-table orders
导入的权威来源是归档目录中的 manifest.jsonl:
- 只导入清单里登记、文件存在且校验通过的分片;
- 目录里游离的分片文件不会导入,
--statistics会把它们计为 ignored files; - 清单行无法解析时直接报错,不会把损坏行当成“没有这个分片”;
- 未提供
--dest-table时使用state.json记录的源表名。
必填参数与默认值
| 参数 | 默认 | 说明 |
|---|---|---|
--file |
必填 | 归档目录,必须包含 manifest.jsonl |
--dest |
必填 | 目标 MySQL DSN,必须包含数据库名 |
--dest-table |
归档记录的源表名 | 目标表名 |
--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 / insert |
--verify |
pre |
pre / off |
--workers |
1 |
并行分片数,必须大于 0 |
--charset |
utf8mb4 |
装载时使用的字符集 |
--time-zone |
空 | 目标会话时区;空表示使用服务端默认 |
--allow-partial |
关闭 | 允许导入未完成归档的已封分片 |
--allow-warnings |
关闭 | 服务端告警不视为失败 |
--dry-run |
关闭 | 只打印选片与配置 |
--progress |
auto |
进度输出 |
--statistics |
关闭 | 结束汇总 |
导入模式拒绝导出专属参数(--source、--where、--purge、--format 等),未知参数同样报错,退出码为 2。
分片选择
选择粒度是整个分片:LOAD DATA 不做行级过滤。
| 语法 | 语义 |
|---|---|
all |
清单中的全部分片 |
seq:A-B |
分片序号闭区间 |
pk:LO-HI |
分片主键区间与 [LO,HI] 相交即入选 |
date:D1..D2 |
日期桶闭区间 |
多个 --select 取并集,并按归档顺序(日期桶、再按 seq)去重排序。date: 只能用于按日期分片的归档;count/none 归档使用会直接报错。
pk: 的边界分片会带入请求范围之外的行。例如请求 pk:150000-250000,而分片 1 覆盖 1-200000,则分片 1 会整片导入。启动时会打印相应警告,建议先用 --dry-run 确认选片。
archer import --file ./export/orders --dest '...' \
--dest-table orders --select seq:1-10 --select pk:500000-600000 --dry-run
完整性检查
导入前依次检查:
state.json存在且complete为true;不满足时拒绝导入,--allow-partial可显式导入已封分片。- 清单中所有选中分片的文件存在。
- 选中分片的格式与压缩方式一致,且格式为
dump(v1 不支持 csv/jsonl)。 - 每个分片的格式、压缩、目标列映射就绪。
默认 --verify pre 会在装载每个分片前流式计算压缩文件的 SHA-256,并与清单比对;不一致立即中止,不会发送任何该分片数据。--verify off 关闭预校验。
每个分片装载后核对行数:
insert:实际写入必须等于清单rows;ignore:实际写入不得大于rows,差额报告为跳过;replace:只报告受影响行数(覆盖通常按删除 + 插入计数)。
两种引擎
load(默认)
通过 mysql.RegisterReaderHandler 把解压流直接交给 LOAD DATA LOCAL INFILE 'Reader::...',不落临时文件,也不要求驱动开启任意本地文件读取。
目标服务器必须启用 local_infile(MySQL 8.0.3+ 默认关闭;MariaDB 默认开启;托管库通常在参数组中控制)。启动时执行 SELECT @@local_infile, @@version,关闭时在装载前失败,并提示两条出路:
- 在服务端/代理启用
local_infile,或 - 使用
--engine insert。
经过连接池或代理时,本地文件请求可能不被转发;必要时直连目标实例。
insert(兜底)
使用参数化批量 INSERT,按 max_allowed_packet 切批,每个分片的所有批次包在同一个事务中,保证分片级原子。吞吐低于 LOAD DATA,但在 local_infile 不可用时语义不变。两种引擎对同一归档、同一目标表的结果一致。
列映射
文件本身没有列名,因此映射以列名为准:
- 归档记录了列清单(导出时使用了
--columns):按记录顺序生成装载列清单,逐个校验目标列存在;记录中包含生成列时直接报错。此时不能再指定--columns或--assume-all-columns。 --columns:按文件字段顺序给出目标列名,做同样的名校验。--assume-all-columns:接受位置映射。按目标表全部列的 ordinal 顺序生成列清单;生成列替换为@_archer_skip_<n>丢弃变量,由目标表重新计算。启动时打印位置映射警告。- 都没有时拒绝导入,提示提供
--columns或显式接受--assume-all-columns。
文件字段数只是前置检查:与列清单长度不一致会在装载前报错,但字段数相同不能证明列名和顺序正确。--assume-all-columns 无法发现“同数换列/改名”,严格场景请使用归档列清单或显式 --columns。
目标表必须预先存在。需要装到全新实例时,先建同构表(列名、顺序、类型一致),再导入。
模式与幂等
--mode |
语句 | 重复导入 |
|---|---|---|
ignore(默认) |
LOAD DATA ... IGNORE / INSERT IGNORE |
跳过冲突行,可安全重跑 |
insert |
LOAD DATA ... / INSERT |
遇重复键失败 |
replace |
LOAD DATA ... REPLACE / REPLACE |
用归档内容覆盖冲突行 |
默认 ignore 让“失败后修复再重跑”成为安全操作。ignore 模式下,唯一键冲突被跳过的行计入跳过行数,对应的重复键告警不视为失败;其他服务端告警默认失败,--allow-warnings 可改为记录并继续。insert/replace 重跑可能失败或覆盖,需自行确认。
进度、统计与 dry-run
--progress语义与导出一致,总量是选中分片的清单一共行数。--statistics输出选片数、成功/失败/未选分片数、期望/实际/跳过行数、字节、ignored files 与耗时。--dry-run只读清单与首个分片首行,打印配置、选片、总行数/字节;不连接目标库,也不写入。
--workers N 把选中分片按连续 seq 区间分给 N 个 worker。并行结果与串行一致;默认 1,导回线上表时建议低峰执行并监控锁等待和主从延迟。
失败语义与退出码
- 每个分片原子:
LOAD DATA单语句在 InnoDB 下原子;insert引擎每分片一个事务。 - 首个分片失败即停止开始新分片,报告失败
seq、原因与失败前累计行数;已完成分片保留。 - 成功返回 0;参数/配置错误返回 2;连接错误 3;写入/装载错误 4;校验失败(哈希、行数、列映射、完成度)5;被信号中断 130。
导回原表的注意事项
- 归档边界与下一次归档的
--where范围可能重叠。导回原表的行若仍落在归档条件内,会被再次归档;归档条件应覆盖“纯冷时间段”。 TIMESTAMP的时区解释取决于导出与会话设置。归档未记录导出会话时区,必要时用--time-zone显式设置目标会话时区,并在导入后核对样本。- 非 ASCII、emoji、BLOB 建议使用
--charset utf8mb4;二进制列可试用--charset binary并按业务核对。 - 导入不会自动建表或迁移 schema;归档与目标表的列名、顺序和类型需要人工保持一致。
限制
- v1 只支持
dump格式;csv/jsonl会明确报错。 - 选择粒度只到分片,不支持行级过滤,也没有导入台账或断点续导。
- 不做常驻服务、HTTP 接口、队列或定时任务。