## 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 ()
AND (shard_col, pk) > (?, ?)
ORDER BY shard_col, pk
LIMIT ?
```
路径 B 每天一条查询,用 `rows.Next()` 流式读完:
```sql
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`。回滚即停止使用新二进制;已产生的导出文件不受影响。