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>
154 lines
12 KiB
Markdown
154 lines
12 KiB
Markdown
## Context
|
||
|
||
动机见 `proposal.md`。与本设计直接相关的现状:
|
||
|
||
- 归档目录由 `manifest.jsonl`(`internal/shard/manifest.go` 的 `Entry`:`seq`、`path`、`date`、`pk_lo`、`pk_hi`、`rows`、`bytes`、`sha256`)与 `state.json`(`internal/checkpoint.State`:`config`、`complete`)描述。
|
||
- 全列导出取 `information_schema.COLUMNS` 的全部列并按 ordinal 排序(`probe.go:81-85`、`schema.go:241-247`),包含生成列与不可见列;文件没有列名,`state.json` 只保存原始 `--columns` 字符串,不保存解析后的列名与顺序。
|
||
- 每个分片独立压缩,`internal/shard/compress.go` 的 `Compressor.Reader` 已能把 gzip/zstd/xz 包装成 `io.ReadCloser`。
|
||
- 当前 `cmd/archer/main.go` 直接把所有参数交给单一 `flag.FlagSet`;`cli.Config.Validate` 强制要求 `--source`/`--table`/`--where`,导入不能复用这套校验。
|
||
- `internal/sink.DB` 已实现按 `max_allowed_packet` 分批的参数化多行 `INSERT`,可直接作为插入引擎。
|
||
- 驱动 `go-sql-driver/mysql` 在握手中无条件发送 `clientLocalFiles`(`packets.go:288`);`LOAD DATA LOCAL INFILE 'Reader::<name>'` 只查 `RegisterReaderHandler` 注册表(`infile.go:105`),不要求 `allowAllFiles`,也不暴露任意文件读取。
|
||
- MySQL 8.0.3+ 的 `local_infile` 默认关闭;MariaDB 默认开启;托管库由参数组控制。代理/连接池可能不转发本地文件请求。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- 按清单安全、可重复、可选择范围地把归档重放进 MySQL。
|
||
- 复用现有分片、压缩、错误分类与进度基础设施,不改变导出端格式。
|
||
- 在受限环境(`local_infile` 关闭、经过代理)仍提供可用的兜底路径。
|
||
|
||
**Non-Goals:**
|
||
|
||
- 不做行级过滤、断点续导台账或导入状态持久化。
|
||
- 不自动建表、不推导/迁移表结构。
|
||
- 不引入服务化入口或第二个二进制。
|
||
- 不在 v1 支持 csv/jsonl 导入。
|
||
|
||
## Decisions
|
||
|
||
### D1:同一二进制内的 `import` 子命令
|
||
|
||
`main.go` 在解析参数前检查 `os.Args[1] == "import"`,命中则交给 `internal/importer` 的独立解析与运行路径;其余参数仍走现有 `cli.Parse`。这样对现有导出调用完全向后兼容,也不需要拆分仓库或构建两套产物。
|
||
|
||
替代方案是新增 `cmd/archer-import` 二进制,但导入要复用清单解析、压缩、错误码、进度与插入实现,独立二进制只会增加发布与版本对齐成本,收益接近于零。
|
||
|
||
### D2:清单使用严格只读加载器
|
||
|
||
现有 `Manifest.readExisting` 会静默跳过无法解析的行,这对导出续跑是合理的容错,但导入不能把损坏行当成“分片不存在”。新增只读加载函数(例如 `shard.LoadManifest(root)`):逐行解析,遇到非法 JSON 立即报错;不打开 `O_APPEND` 句柄,不修改归档目录。`Entry` 结构保持不变。
|
||
|
||
### D3:完成度以 `state.json` 为准,默认拒绝部分归档
|
||
|
||
导入前调用 `checkpoint.Load`。默认要求 `complete == true`;`state.json` 缺失或 `complete == false` 时,只有在 `--allow-partial` 下才继续。理由:分片清单只能证明“这些分片已封”,不能证明“导出已覆盖全表”。
|
||
|
||
### D4:选择粒度到分片,主键区间按相交语义
|
||
|
||
`--select` 可重复,解析为选择器集合,按 `seq` 去重排序:
|
||
|
||
- `all`:全部清单条目;
|
||
- `seq:A-B`:`A <= seq <= B`;
|
||
- `pk:LO-HI`:分片的 `[pk_lo, pk_hi]` 与 `[LO, HI]` 相交即入选;
|
||
- `date:D1..D2`:`Entry.Date` 落入闭区间。`count` 分片的 `Date` 为空(`writer.go:357` 只在日期模式下写 bucket),因此对非日期归档按日期选择必须报错。
|
||
|
||
`LOAD DATA` 不能过滤行,所以 `pk:`/`date:` 的边界分片会带入范围外的行。`--dry-run` 与启动摘要必须显式提示这一点,避免用户误以为“只导入这个主键段”。
|
||
|
||
替代方案是把边界分片解压后逐行过滤再装载,但那样既要写解码器又要丢弃 `LOAD DATA` 的性能优势,v1 不值得。
|
||
|
||
### D5:格式与压缩从清单路径推导,v1 只接受 dump
|
||
|
||
`Entry.Path` 形如 `<seq>.<lo>-<hi>.<format>[.<comp>]`。导入从扩展名推导格式与压缩器,并要求所有选中条目一致;推导结果不是 `dump` 时报错。这样无需修改归档格式,也对 `none/gzip/zstd/xz` 全部生效。
|
||
|
||
### D6:SHA-256 预校验,而不是边导边校验
|
||
|
||
`--verify pre`(默认)先以流式读取压缩文件计算 SHA-256,与清单比对,通过后再打开一次用于解压装载。
|
||
|
||
替代方案是边装载边计算哈希,末尾不一致时回滚该分片。它省一次顺序读,但要求把整个分片放进一个大事务,且 `LOAD DATA` 在事务中的回滚代价与内存行为不易预测。压缩分片通常是几 MB 到几 GB,额外的顺序读是磁盘带宽级别,远比事务风险便宜。
|
||
|
||
### D7:`load` 引擎用注册的流式 Reader,不落临时文件
|
||
|
||
每个 worker 持有自己的 `*sql.Conn`,装载单个分片时:
|
||
|
||
1. 为分片生成唯一 handler 名(如 `archer-import-<pid>-<seq>-<nonce>`);
|
||
2. `mysql.RegisterReaderHandler(name, func() io.Reader { ... })` 返回解压 Reader;
|
||
3. 执行 `LOAD DATA LOCAL INFILE 'Reader::<name>' ...`;
|
||
4. `DeregisterReaderHandler(name)`。
|
||
|
||
字段规则与 `internal/row/dump.go` 的编码严格对应:
|
||
|
||
```sql
|
||
LOAD DATA LOCAL INFILE 'Reader::<name>'
|
||
INTO TABLE <db>.<table>
|
||
CHARACTER SET <charset>
|
||
FIELDS TERMINATED BY '\t' ESCAPED BY '\\'
|
||
LINES TERMINATED BY '\n'
|
||
-- 可选: (col1, col2, ...)
|
||
```
|
||
|
||
模式映射为语句中的 `IGNORE` / `REPLACE` 关键字;`insert` 模式不带关键字。会话级 `time_zone` 在连接建立后设置。
|
||
|
||
### D8:`insert` 引擎复用 `sink.DB`,每个分片一个事务
|
||
|
||
`--engine insert` 使用 `internal/sink.DB.InsertChunk` 的同一套分批逻辑,但输入来自解压后的行解码,而不是扫描结果。为保持“分片失败不留半截数据”,每个分片的所有批次 MUST 包在同一个事务中;这比 `LOAD DATA` 的单语句事务粒度更粗,但只作为兜底路径。
|
||
|
||
v1 的 `insert` 引擎同样只支持 `dump`:按行 Split 后把字段转成 `row.Value`(`\N` → NULL,反转义表与 `dumpEncoder` 对称)。这需要一个最小的 dump 解码器;csv/jsonl 的解码各自有歧义或类型依赖,留待后续。
|
||
|
||
### D9:启动探测 `local_infile`,失败即停,不静默降级
|
||
|
||
在建立目标连接后、装载任何分片前,执行 `SELECT @@local_infile, @@version`。`--engine load` 且值为 0 时返回配置类错误,错误信息同时给出“启用 local_infile”和“改用 `--engine insert`”两条出路。
|
||
|
||
静默回退会让几十 GB 的导入从分钟级变成小时级且用户毫无察觉,违背本仓库既有的 fail-fast 风格。
|
||
|
||
### D10:列映射按列名,字段数只做前置检查
|
||
|
||
先明确归档里到底有什么:全列导出取的是 `information_schema.COLUMNS` 的全部列、按 `ORDINAL_POSITION` 排序(`probe.go:81-85`、`schema.go:241-247`),包含生成列与不可见列;文件本身没有列名。`state.json` 只记录原始 `--columns` 字符串,为空表示“导出时全部列”,**不记录解析后的列名与顺序**。
|
||
|
||
因此“文件字段数 == 目标表列数”既不是充分条件(同数换列、改名、交换顺序都能通过),也不应作为映射依据。字段数只用于在装载前给出更早、更清晰的错误。
|
||
|
||
列映射按以下优先级确定:
|
||
|
||
1. **归档记录了列清单**(`state.json` 的 `columns` 非空):按记录顺序生成 `LOAD DATA` 列清单;逐个校验列名存在于目标表;若记录中包含目标表的生成列,直接报错(生成列不能从归档写入)。
|
||
2. **`--columns`**:用户按文件字段顺序给出目标列名,做与上一条相同的名校验。它与归档记录的列清单互斥,避免两套来源冲突。
|
||
3. **`--assume-all-columns`**:接受位置映射。按目标表全部列的 ordinal 顺序生成列清单;生成列替换为丢弃用的用户变量(`@_archer_skip_<i>`),由目标表重新计算;首行字段数必须等于清单长度;启动时打印位置映射警告。
|
||
4. 以上都不可用时拒绝导入,提示用户提供 `--columns` 或显式接受 `--assume-all-columns`。
|
||
|
||
使用显式列清单还能消除 `LOAD DATA` 对不可见列是否计入“全部列”的歧义,因为不可见列可以被显式命名并写入。
|
||
|
||
不做自动建表:归档没有记录 DDL,猜测 schema 的风险远大于收益。需要“装到全新实例”时,用户应先建同构表。把有序列名、类型与 `SHOW CREATE TABLE` 写进归档,是让默认全列导出也能严格校验的根治方案,作为后续独立的导出侧改动。
|
||
|
||
### D11:告警与行数核对依赖同一会话
|
||
|
||
驱动的 `Result` 只暴露 affected rows,不能读取 LOAD DATA 的 `Records/Skipped/Warnings` 信息串。因此每个 worker 必须用固定 `*sql.Conn`(而不是连接池),在装载后立即执行 `SHOW WARNINGS`:
|
||
|
||
- 有告警且未指定 `--allow-warnings`:该分片失败;例外是 `ignore` 模式下唯一键冲突产生的告警(错误码 1062),它们是“跳过”而非数据缺陷,已被行数规则计入跳过行数,否则默认 `ignore` 无法做到重复导入幂等;
|
||
- 行数规则:`insert` 模式要求 affected == 清单 `rows`;`ignore` 模式要求 affected <= `rows`,差额报告为跳过;`replace` 模式的 affected 可能大于 `rows`(覆盖计为删除+插入),只报告不强制相等。
|
||
|
||
这比“解析 OK 包信息串”更依赖会话,但驱动没有暴露后者;使用固定连接也顺带保证 `time_zone`/`character_set` 等会话设置不被连接池复用破坏。
|
||
|
||
### D12:进度与统计复用现有组件
|
||
|
||
`internal/progress.Reporter` 以清单总行数为总量,按分片完成/行数推进;`--statistics` 输出选片数、成功/失败/跳过分片数、期望/实际/跳过行数、字节与耗时。`--dry-run` 只读清单与首行(用于字段数),不连接目标库,也不装载。
|
||
|
||
### D13:失败即停,分片原子
|
||
|
||
默认在首个失败分片处终止,并报告该分片 `seq`、失败原因与失败前的累计行数。`load` 引擎的单条 `LOAD DATA` 在 InnoDB 下是原子的;`insert` 引擎用每分片一个事务保证同样的可见性。已完成分片不回滚,重跑依赖 `--mode ignore` 的幂等性。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **`local_infile` 被安全基线关闭** → 提供 `--engine insert`;启动时明确报错而不是降级。走代理/连接池时需实测,必要时直连目标实例。
|
||
- **字符集导致非 ASCII/BLOB 失真** → 默认 `--charset utf8mb4`,提供 `--charset binary`;集成测试覆盖中文、emoji、BLOB、TAB/换行/反斜杠/NULL。
|
||
- **`TIMESTAMP` 时区漂移** → 归档未记录导出会话时区;提供 `--time-zone` 显式设置目标会话时区,文档说明风险,测试覆盖显式设置与默认两种情况。
|
||
- **导回线上表造成锁等待/主从延迟** → 默认 `--workers 1`,文档建议低峰执行并监控;`LOAD DATA` 的行锁范围取决于目标表索引。
|
||
- **部分导入给出不完整查询结果** → 启动与结束摘要显式列出导入范围与行数;`--dry-run` 强制先看选片。
|
||
- **再次归档边界** → 导回原表的行可能落在下一次归档的 `--where` 范围内;文档提醒归档条件应覆盖“纯冷时间段”。
|
||
- **位置映射无法发现“同数换列/改名”** → `--assume-all-columns` 只保证字段数一致并打印警告,不具备名校验能力;严格场景要求归档列清单或显式 `--columns`。根治方案是后续让导出端记录有序列名。
|
||
- **生成列与不可见列** → `--assume-all-columns` 下生成列映射为丢弃变量、由目标表重算;记录列清单包含生成列时直接报错;不可见列通过显式列清单写入。
|
||
- **没有导入台账** → 依赖 `ignore` 幂等;`insert`/`replace` 重跑可能失败或覆盖,文档明确这一点。
|
||
- **`SHOW WARNINGS` 需要同会话** → 强制使用 `*sql.Conn`,并在测试中覆盖连接复用场景。
|
||
|
||
## Migration Plan
|
||
|
||
- 纯增量:现有导出行为、文件格式、清单与 `state.json` 均不变。
|
||
- 发布:与现有二进制一同构建;`archer import` 对新旧归档都可用。
|
||
- 回滚:不调用 `import` 子命令即可;已导入的数据需要按业务自行清理。
|
||
- 后续独立改动(不在本 change 内):归档记录 `format`/`columns`/`charset`/`time_zone` 与 `SHOW CREATE TABLE`,以支持自动建表和更强的核对。
|