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

146 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 导入归档
`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_<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 接口、队列或定时任务。