Files
archer/docs/import.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

8.2 KiB
Raw Blame History

导入归档

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

完整性检查

导入前依次检查:

  1. state.json 存在且 complete 为 true;不满足时拒绝导入,--allow-partial 可显式导入已封分片。
  2. 清单中所有选中分片的文件存在。
  3. 选中分片的格式与压缩方式一致,且格式为 dump(v1 不支持 csv/jsonl)。
  4. 每个分片的格式、压缩、目标列映射就绪。

默认 --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 不可用时语义不变。两种引擎对同一归档、同一目标表的结果一致。

列映射

文件本身没有列名,因此映射以列名为准:

  1. 归档记录了列清单(导出时使用了 --columns):按记录顺序生成装载列清单,逐个校验目标列存在;记录中包含生成列时直接报错。此时不能再指定 --columns 或 --assume-all-columns。
  2. --columns:按文件字段顺序给出目标列名,做同样的名校验。
  3. --assume-all-columns:接受位置映射。按目标表全部列的 ordinal 顺序生成列清单;生成列替换为 @_archer_skip_<n> 丢弃变量,由目标表重新计算。启动时打印位置映射警告。
  4. 都没有时拒绝导入,提示提供 --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 接口、队列或定时任务。