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:
1 parent
bc4a6b504f
commit
366d61ca25
49 files changed
+5099
-342
No files matched your search
+145
@@ -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 接口、队列或定时任务。
|
||||
Reference in new issue
Block a user