# 导入归档 `archer import` 把一次归档产出(分片文件 + `manifest.jsonl` + `state.json`)按需重放进一个**已存在**的 MySQL/MariaDB 表。它不创建表、不修改表结构,也不改变导出端的文件或清单格式。 ```bash 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` 确认选片。 ```bash 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_` 丢弃变量,由目标表重新计算。启动时打印位置映射警告。 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 接口、队列或定时任务。