Files
voidandClaude Sonnet 4.6 366d61ca25 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>
2026-11-08 21:14:23 +08:00

12 KiB
Raw Permalink Blame History

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 的编码严格对应:

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,以支持自动建表和更强的核对。