## 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::'` 只查 `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` 形如 `.-.[.]`。导入从扩展名推导格式与压缩器,并要求所有选中条目一致;推导结果不是 `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---`); 2. `mysql.RegisterReaderHandler(name, func() io.Reader { ... })` 返回解压 Reader; 3. 执行 `LOAD DATA LOCAL INFILE 'Reader::' ...`; 4. `DeregisterReaderHandler(name)`。 字段规则与 `internal/row/dump.go` 的编码严格对应: ```sql LOAD DATA LOCAL INFILE 'Reader::' INTO TABLE . CHARACTER SET 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_`),由目标表重新计算;首行字段数必须等于清单长度;启动时打印位置映射警告。 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`,以支持自动建表和更强的核对。