Files
archer/openspec/changes/archive/2026-11-06-add-archer-archiver/design.md
T
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

188 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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 的续点条件是行构造器比较:
```sql
WHERE (<base where>)
AND (shard_col, pk) > (?, ?)
ORDER BY shard_col, pk
LIMIT ?
```
路径 B 每天一条查询,用 `rows.Next()` 流式读完:
```sql
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/ 复制延迟监控
```
核心接口:
```go
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`。回滚即停止使用新二进制;已产生的导出文件不受影响。