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>
12 KiB
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,装载单个分片时:
- 为分片生成唯一 handler 名(如
archer-import-<pid>-<seq>-<nonce>); mysql.RegisterReaderHandler(name, func() io.Reader { ... })返回解压 Reader;- 执行
LOAD DATA LOCAL INFILE 'Reader::<name>' ...; DeregisterReaderHandler(name)。
字段规则与 internal/row/dump.go 的编码严格对应:
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 字符串,为空表示“导出时全部列”,不记录解析后的列名与顺序。
因此“文件字段数 == 目标表列数”既不是充分条件(同数换列、改名、交换顺序都能通过),也不应作为映射依据。字段数只用于在装载前给出更早、更清晰的错误。
列映射按以下优先级确定:
- 归档记录了列清单(
state.json的columns非空):按记录顺序生成LOAD DATA列清单;逐个校验列名存在于目标表;若记录中包含目标表的生成列,直接报错(生成列不能从归档写入)。 --columns:用户按文件字段顺序给出目标列名,做与上一条相同的名校验。它与归档记录的列清单互斥,避免两套来源冲突。--assume-all-columns:接受位置映射。按目标表全部列的 ordinal 顺序生成列清单;生成列替换为丢弃用的用户变量(@_archer_skip_<i>),由目标表重新计算;首行字段数必须等于清单长度;启动时打印位置映射警告。- 以上都不可用时拒绝导入,提示用户提供
--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,以支持自动建表和更强的核对。