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>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 21:14:23 +08:00
1 parent bc4a6b504f
commit 366d61ca25
49 files changed
+5099 -342

No files matched your search

+145
View File
@@ -0,0 +1,145 @@
# 导入归档
`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 接口、队列或定时任务。