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