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>
9.4 KiB
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。回滚即停止使用新二进制;已产生的导出文件不受影响。