Files
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-06 22:12:17 +08:00

9.4 KiB
Raw Permalink Blame History

Context

这是一个全新的 Go 项目,没有既有代码需要兼容。需求见 proposal.md,行为契约见 specs/。

关键约束来自目标环境:MySQL/MariaDB、可能是有活跃写入的生产大表、单次导出规模从百万到数十亿行。因此设计围绕三件事展开:内存恒定(不能把结果集读进内存)、扫描不退化(不能出现 O(n²))、产物可分段导入(分片连续有序)。

Goals / Non-Goals

Goals:

  • 单趟、流式、内存恒定的扫描与导出。
  • 分片在扫描顺序上连续、有序、无重叠,文件名反映真实主键范围。
  • 同一套提交流水线同时支持 file、dest、purge。
  • 崩溃后可从 checkpoint 续跑,语义明确为 at-least-once。
  • 无合适索引时快速失败,而不是静默变慢。

Non-Goals:

  • 并行导出(多 worker)。
  • 文件侧 exactly-once。
  • Parquet / Arrow 输出。
  • 非 MySQL 数据源。
  • PXC Flow Control 与插件机制。

Decisions

决策 1:seek 分块,chunk 即事务

每个 chunk 用 key > :last ORDER BY key LIMIT :chunk_size 向前 seek,不使用 OFFSET。--chunk-size 同时是 SELECT 批量、事务大小和 checkpoint 粒度,不引入 --txn-size。

理由:pt-archiver 把 fetch 和 transaction 解耦后,出现“一个事务跨多个 chunk / 一个 chunk 拆多个事务”的组合复杂度;而 OFFSET 在 InnoDB 上是线性扫描,深分页会退化。统一粒度后,续跑、lag 检查、崩溃语义都只有一个边界。

备选:保留 --txn-size 做 parity — 放弃,收益不足以抵消复杂度。

决策 2:分片是 file sink 内部的行级路由,不是独立 sink

Scanner ──chunk──▶ FileSink ──row──▶ ShardWriter ──▶ .partial ──seal──▶ final + manifest
                      │
                      ├──▶ DBSink
                      └──▶ Purger

FileSink.WriteChunk 逐行交给 ShardWriter,由它判断是否封片。因为 --chunk-size 与 --shard-rows 正交,一个 chunk 可以跨多个分片;这是正常路径,不是特例。

关键推论:三种分片模式都保证扫描顺序等于分片顺序,因此同一时刻只需要一个打开的分片文件。不需要 LRU 句柄池,也没有 fd 上限风险。这是选择“有序扫描”换来的最大简化。

决策 3:按数量分片采用流式滚动

--shard-by count 每写满 --shard-rows 行封片,分片边界由扫描顺序自然产生。不预计算边界。

理由:预计算需要额外一趟扫描或 OFFSET 采样,边界状态还要按分片存进 checkpoint;流式滚动只需一个游标,且边界天然连续。代价是文件名在封片前未知,用 .partial + 封片时重命名解决。

备选:预计算边界以支持并行 — 留给 v2。

决策 4:日期分片的双扫描路径

启动时探测索引,按能力选择:

探测结果 路径 事务 purge 连接
(shard_column, pk) 联合索引 A:keyset 分块 每 chunk 短事务 同连接
仅 shard_column 单列索引 B:逐日流式 长游标,无 chunk 事务 第二连接
都没有 fail fast(--allow-full-scan 可覆盖) — —

路径 A 的续点条件是行构造器比较:

WHERE (<base where>)
  AND (shard_col, pk) > (?, ?)
ORDER BY shard_col, pk
LIMIT ?

路径 B 每天一条查询,用 rows.Next() 流式读完:

WHERE (<base where>)
  AND shard_col >= ? AND shard_col < ?
ORDER BY shard_col, pk

选择依据:单列索引的物理顺序已经是 (shard_col, pk),所以路径 B 的输出有序;但它的续点无法 seek,只能整日流式读。反过来,路径 A 能用联合索引精确 seek,但要求用户多建一个索引。检测驱动让两种用户都能运行,而不是硬性要求联合索引。

NULL 处理:行构造器比较遇到 NULL 结果恒为 NULL,无法推进游标。因此当存在 date=_null 桶时,先单独扫描 shard_col IS NULL 的行,再扫描非 NULL 行;两段都保持有序。

决策 5:日期列必须显式指定,类型白名单

--shard-by date 必须给 --shard-column,即使表中只有一个日期列。类型仅允许 DATE、DATETIME、TIMESTAMP,以及显式声明单位的整数 epoch。整数列缺单位时采样 min/max,展示三种解释下的日期范围,但绝不自动选择。

理由:同一张表常有多个日期列;BIGINT 列可能是 ID、金额或时间戳,秒与毫秒相差 1000 倍且转换后仍落在合法日期区间。静默猜错的代价是整批分片归属错误,且很难事后发现。

决策 6:时区模型显式化

列类型 日期归属
DATE / DATETIME 原值,不做换算
TIMESTAMP 连接会话 time_zone
epoch 整数 --shard-time-zone,默认 UTC

--shard-time-zone 与 DSN 的 time_zone 都计入配置指纹。续跑时不一致直接拒绝,因为同一行可能落到相邻日期分片,拼出的文件内部不一致。

决策 7:driver 使用 parseTime=false

所有列先按原始字节取回。dump/CSV 需要的就是 MySQL 原始文本;parseTime=true 会让 0000-00-00 直接报错,也会引入 time.Time 往返的格式漂移。分片时只对 shard_column 单独解析日期部分,JSONL 的类型化在编码层按列元数据完成。

决策 8:提交顺序与崩溃语义

chunk:
  ① FileSink 写行(缓冲)
  ② DBSink 插入
  ③ Purger 删除
  ④ 提交(同实例单事务 / 跨实例分别提交)
  ⑤ flush 文件 → seal 分片 → 追加 manifest
  ⑥ 原子更新 state.json

同实例时 ③④ 与 ② 在同一个事务里;跨实例时分别提交并重试。任一步失败都不推进 checkpoint。

一致性等级为 at-least-once:文件写入与数据库提交不在同一个原子域内,崩溃重跑可能重复追加。这是与 pt-archiver 对齐的取舍;文件侧 exactly-once 需要 pending journal,属于 v2。

备选:pending journal — 每 chunk 多一次 fsync,吞吐下降明显,当前需求不要求。

决策 9:删除策略

默认 IN 列表,按 1000 个参数分批。--bulk-delete 改为区间删除,并显式附上 --where;仅允许在 none/count 模式下使用。日期模式下 chunk 的主键不连续(迟到数据会让区间跨日期),区间删除会误伤其他分片的数据,因此直接拒绝。

备选:始终区间删除 — 性能收益在大 chunk 时才明显,但引入并发写入误删风险,不作为默认。

决策 10:checkpoint 与配置指纹

state.json 原子写(tmp + fsync + rename),记录 version、run_id、config_hash、模式、last_key、last_date、last_shard_seq、rows_done。

指纹输入:source 的 host/port/db/user、table、where、columns、shard 参数、时区、format、compress、dest、purge、bulk-delete。排除密码,允许凭据轮换。

决策 11:包结构

cmd/archer/main.go
internal/
  cli/        参数解析、校验、互斥规则
  schema/     表元数据、索引探测、列类型
  scan/       seek 分块迭代器(路径 A / B / 主键)
  row/        行值、编码器(dump/csv/jsonl)
  sink/       FileSink、DBSink
  shard/      ShardWriter、命名、manifest
  purge/      IN 列表 / 区间删除
  checkpoint/ state.json
  lag/        复制延迟监控

核心接口:

type Chunk struct {
    Rows    []Row
    LastKey Key
}

type Scanner interface {
    Next(ctx context.Context) (Chunk, error)
}

type Sink interface {
    WriteChunk(ctx context.Context, c Chunk) error
    Flush(ctx context.Context) error
    Close() error
}

依赖:github.com/go-sql-driver/mysql、github.com/klauspost/compress/zstd,gzip 用标准库。

Risks / Trade-offs

  • 日期模式 B 持有长读快照 → 大表上 undo 可能膨胀,且无法在扫描期间用同连接删除。缓解:路径 A 优先;提供 --max-lag;文档说明长事务影响。
  • at-least-once 会产生重复行 → 重跑后文件可能重复。缓解:manifest 记录已封分片;文档明确;导入端可用 INSERT IGNORE 去重。
  • --bulk-delete 并发误删 → 扫描期间落在区间内且满足 --where 的新行会被删。缓解:默认关闭;启用时打印警告;日期模式禁止。
  • 分片文件名延迟确定 → 长时间运行的大分片在封片前没有最终文件名。缓解:state.json 记录当前 seq 与起始主键;.partial 可识别。
  • 时区配置漂移 → 同一表在不同机器分片结果不同。缓解:时区进入指纹;续跑时不一致即拒绝。
  • 无索引时误开全表扫描 → 缓解:默认 fail fast,--allow-full-scan 必须显式开启。
  • 单条 INSERT/DELETE 超过 max_allowed_packet → 缓解:按字节预算自动拆分为多条语句。
  • 并发写入导致扫描期间的行集合漂移 → 与本工具语义一致(只保证读到的行),文档说明不提供快照一致性。

Migration Plan

全新项目,无数据迁移。首个版本只读能力(--file / --dest)可安全试跑;--purge 需显式开启。建议上线流程:先 --dry-run,再只导出核对文件,最后再启用 --purge。回滚即停止使用新二进制;已产生的导出文件不受影响。