Files
archer/README.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

355 lines
15 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.
# archer
`archer` 是一个 Go 原生的 MySQL/MariaDB 大表归档工具。它复用了 `pt-archiver`
的核心语义(按唯一索引 seek 分块、file + dest + purge 三件套),并补齐了
**可有序分片、可分段导入** 的导出能力。
导出的分片沿扫描顺序连续、有序、无重叠:可以按主键或时间戳范围并行导入,
也可以按日期目录分批处理。
## 要求
- Go 1.24+(构建)
- MySQL 5.7+ / 8.0 或 MariaDB 10.x(运行)
- 源表必须有主键或唯一索引;日期分片还需要分片列上的索引(见下文)
## 构建
```bash
go build -o archer ./cmd/archer
```
或使用打包脚本(Windows PowerShell / Linux shell):
```powershell
./scripts/build.ps1
```
```bash
./scripts/build.sh
```
产物在 `dist/` 下,版本信息通过 `-ldflags -X` 注入,`archer --version` 可查看。
## 最小示例
```bash
archer \
--source 'user:pass@tcp(10.0.0.5:3306)/app' \
--table orders \
--where "created_at < '2025-01-01'" \
--file ./export \
--format dump
```
结果:`./export/000001.<首主键>-<尾主键>.dump`、`manifest.jsonl`、`state.json`。
只写目标表:
```bash
archer --source '...' --table orders --where "id < 100000" \
--dest 'user:pass@tcp(10.0.0.9:3306)/archive' --dest-table orders
```
只删除(危险,需确认):
```bash
archer --source '...' --table orders --where "created_at < '2024-01-01'" --purge
```
先看计划,不落盘:
```bash
archer --source '...' --table orders --where "1=1" --file /tmp/out --dry-run
```
## 分片模式
| `--shard-by` | 行为 | 文件 |
|---|---|---|
| `none`(默认) | 单文件 | `<seq>.<lo>-<hi>.<format>` |
| `count` | 每 `--shard-rows` 行封片,流式滚动 | 同上,序号递增 |
| `date` | 每个日期一个目录;同一天内可再按 `--shard-rows` 切分 | `date=YYYY-MM-DD/<seq>.<lo>-<hi>.<format>` |
三种模式都保证:
- 分片按扫描顺序编号;
- 相邻分片的主键范围连续、不重叠;
- 分片合并等于本次扫描读取到的全部行;
- 文件名中的 `lo`/`hi` 是该分片实际首尾键;
- 同一时刻只有一个活跃分片文件(因此没有 fd 上限问题)。
`--chunk-size`(每次 SELECT 的行数、事务大小、checkpoint 粒度)与
`--shard-rows` 相互独立,一个 chunk 可以跨多个分片。
分片先写 `<seq>.partial`,`flush + fsync` 后原子重命名为最终文件名。
### 日期分片
必须显式指定 `--shard-column`,即使表中只有一个日期列:
```bash
archer --source '...' --table orders --where "1=1" \
--file ./export --shard-by date --shard-column created_at
```
启动时探测索引并选择路径:
| 索引 | 路径 | 读事务 / 删除 |
|---|---|---|
| `(created_at, id)` 联合索引 | A:`(created_at, id)` keyset 分块 | 每 chunk 一个短查询;dest 写入与 purge 可放同一事务 |
| 只有 `created_at` 单列索引 | B:逐日枚举 + 长游标流式读取 | 读取是一个长查询、占用独立连接;写入/删除仍按 chunk 提交,purge 使用第二条连接 |
| 都没有 | 报错退出;`--allow-full-scan` 可覆盖 | — |
### 为什么分两条路径
分界不是实现偏好,而是索引能力决定了两件事:**能否精确 seek**,以及**读取能否短事务化**。
- **路径 A**:联合索引 `(created_at, id)` 让 `(created_at, id) > (?, ?)` 成为一次精确的索引范围定位。
每个 chunk 都是 O(chunk) 的短查询,游标就是一个元组,天然可以按 chunk 续跑;
dest 写入和 purge 删除还能放进同一个事务,跨 chunk 之间不持有任何长事务。
- **路径 B**:只有 `created_at` 单列索引。InnoDB 二级索引的物理顺序仍然是 `(created_at, id)`
(主键会隐式追加到索引末尾),所以 `ORDER BY created_at, id` 的输出依然有序,分片不变量成立。
但 `id` 不是显式索引列,`(created_at, id) > (?, ?)` 无法作为精确索引范围下推。
如果仍按 chunk 反复查询,每次都得从当天起点重新扫描再过滤已读行,单日内会退化为
O(天行数 × chunk 数)。所以改为“每天一条查询 + 长游标流式读完”:只扫一遍,
代价是这条读查询长时间占用一条连接(同连接不能再发删除语句),删除必须换第二条连接,
且长读快照会延长 undo 保留时间。
因此:**A 是推荐路径;B 是“不改表结构也能用”的兼容路径**。启动时探测索引,就是为了让
有联合索引的用户拿到逐 chunk 短事务与精确续跑,让只有单列索引的用户不必在生产大表上
新建索引也能完成归档;两者都没有时默认 fail-fast,而不是静默退化成全表扫描。
`path A` 的游标比较是行构造器:
```sql
WHERE (<where>)
AND (created_at, id) > (?, ?)
ORDER BY created_at, id
LIMIT ?
```
这里的 `id` 不是特指名为 `id` 的列,而是**所选唯一键**(优先主键,没有主键时用第一个唯一索引)。
日期分片本身只要求“同一天的行落在同一个文件”,并不要求按主键排序,但游标仍然需要这个唯一键:
1. **`created_at` 不唯一**:同一秒可能有大量行。只比较 `created_at` 时,`>` 会跳过同秒的其余行,
`>=` 会反复重读同一批行(只能靠 `OFFSET` 跳过,深分页会退化)。加上唯一键构成全序,
游标 `(created_at, id) > (?, ?)` 才能既不重不漏地向前推进。
2. **断点续跑必须能唯一定位一行**:`state.json` 里的游标就是这个元组;只有时间戳无法区分
同秒的行,重启后会重复或跳过。
3. **归档语义本身也需要主键**:文件名里的 `pk_lo`/`pk_hi`、IN 列表删除、
`--safe-auto-increment` 保护最大自增行,都按唯一键工作。
所以准确说法是:**日期决定文件归属,唯一键只在日期内部提供全序和可恢复的游标**。
如果业务上日期列本身唯一(一行一个时间点),理论上不需要 tie-breaker,但本工具仍要求
表有唯一键,因为删除和清单语义都依赖它。
NULL 日期行先单独扫描(`created_at IS NULL`),再扫描非 NULL 行,保持有序。
**零日期**:默认报错并输出行主键;`--zero-date bucket` 将其放入
`date=0000-00-00` 分片。
**整数 epoch 列**:必须声明单位,否则会采样 min/max 并展示三种解释,绝不自动选择:
```bash
--shard-column ts --shard-column-type epoch-seconds
# 可选:epoch-seconds / epoch-milliseconds / epoch-microseconds
```
**时区**:
| 列类型 | 日期归属 |
|---|---|
| `DATE` / `DATETIME` | 原值,不做换算 |
| `TIMESTAMP` | 连接会话 `time_zone` |
| epoch 整数 | `--shard-time-zone`(默认 UTC) |
`--shard-time-zone` 与 DSN 中的 `time_zone` 都计入配置指纹;续跑时不一致会拒绝。
## 输出格式
| `--format` | 说明 |
|---|---|
| `dump`(默认) | MySQL `LOAD DATA` 兼容的 TSV:TAB 分隔、`\N` 表示 NULL、MySQL 转义表、无表头 |
| `csv` | RFC4180:逗号分隔、表头、双引号转义、CRLF;`--csv-null` 覆盖 NULL 标记 |
| `jsonl` | 每行一个 JSON 对象;DECIMAL 为字符串、BLOB 为 base64、时间列为 RFC3339、NULL 为 `null` |
`--compress none|gzip|zstd|xz`,默认 `none`。每个分片独立压缩,扩展名分别为 `.gz` / `.zst` / `.xz`。压缩文件可单独解压后导入。
`--compress-level 1..9`,默认 `3`。1–9 是跨压缩器的统一档位:数值越大压缩率越高、吞吐越低,`9` 表示该压缩器的最强档位。各格式的映射:
| 档位 | gzip | zstd | xz 字典 |
|---|---|---|---|
| 1 | 1 | fastest | 1 MiB |
| 2 | 2 | fastest | 2 MiB |
| 3(默认) | 3 | default | 4 MiB |
| 4 | 4 | default | 4 MiB |
| 5 | 5 | default | 8 MiB |
| 6 | 6 | better | 8 MiB |
| 7 | 7 | better | 16 MiB |
| 8 | 8 | better | 32 MiB |
| 9 | 9 | best | 64 MiB |
默认档位与引入该参数前的版本保持一致,存量任务可直接续跑;非默认档位会计入配置指纹,续跑时不一致会被拒绝。`--compress none` 不能搭配非默认档位。
xz 由纯 Go 库实现,产物是标准 xz 流,`xz -dc` 可直接解码。其压缩吞吐明显低于 gzip/zstd,适合长期归档、写入速度不敏感的场景;zstd 则在吞吐与压缩率之间更均衡。
### 导入
```bash
# dump -> MySQL(列顺序一致时)
zcat 000001.1-1000000.dump.gz | mysql -e "LOAD DATA LOCAL INFILE '/dev/stdin' INTO TABLE orders"
# xz -> MySQL
xz -dc 000001.1-1000000.dump.xz | mysql -e "LOAD DATA LOCAL INFILE '/dev/stdin' INTO TABLE orders"
# csv -> PostgreSQL
gunzip -c 000001.1-1000.csv.gz | psql -c "\copy orders FROM STDIN WITH (FORMAT csv, HEADER true)"
# csv -> ClickHouse
clickhouse-client --query "INSERT INTO orders FORMAT CSVWithNames" < 000001.csv
# jsonl -> ClickHouse
clickhouse-client --query "INSERT INTO orders FORMAT JSONEachRow" < 000001.jsonl
```
## 进度显示
默认 `--progress auto`:stderr 是终端时在最后一行原地刷新,重定向到文件或管道时不输出进度。
进度与警告统一写 stderr;`--dry-run` 与 `--statistics` 仍写 stdout,因此
`archer ... > result.txt` 不会把进度混进结果。
| 取值 | 行为 |
|---|---|
| `auto`(默认) | stderr 是终端时显示实时进度,否则静默 |
| `on` | 始终显示;非终端时每个间隔输出一行完整 `key=value` |
| `off` / `0` | 关闭 |
| `N>0` | 开启,并在每处理 N 行时额外输出一行 |
`--progress-interval`(默认 `1s`)是最小刷新间隔。终端模式用 `\r` 覆盖同一行并以空格补齐,
不使用 ANSI 清行或颜色,兼容 Windows conhost;行宽超过 100 字符时按优先级裁掉字节数、
分片序号,再缩短进度条,不换行。
进度包含:已处理行数、约 5 秒窗口速率、当前阶段与阶段耗时、本次运行 elapsed,
存在分片时包含分片序号,写文件时包含已写字节。阶段依次为
`probe → resume → estimate → scan → file → db → checkpoint → finalize`;
等待副本延迟时显示 `lag-wait` 与等待原因,而不是一条孤立的 `waiting:` 消息。
单日长查询、fsync 与 lag 等待期间进度仍按间隔刷新。
总量估算只使用有界 MIN/MAX 查询(独立连接 + 2 秒超时,绝不 `COUNT(*)`):
| 场景 | 口径 | 显示 |
|---|---|---|
| `--shard-by date` | 分片列的 MIN/MAX 天范围 | `estimate=day`、`day 37/120`、`~58%`、`eta ~1m36s` |
| 非日期、单列整数唯一键 | 键的 MIN/MAX | `estimate=key`、`~58%`、`eta ~1m36s` |
| 复合键、字符串/二进制键 | 不适用 | `estimate=none`,只显示行数与速率 |
百分比与 ETA 都带 `~`;ETA 按本次运行的推进速率与剩余量计算,不使用"已用时间 ÷ 百分比"。
日期模式按天跳变、键模式在键有空洞或分布不均时偏差较大,这些值都是估算而非精确进度,
不影响归档逻辑。
续跑后进度从 `state.json` 的累计 `rows_done` 起算,不会从零重来;本次运行写回的
`rows_done` 同样是累计值(续跑前已提交 + 本次提交)。旧版本写入的 checkpoint 只记录
上次运行的行数,升级后首次续跑可能偏低,完成后即恢复累计语义。
按 Ctrl+C 时先停止刷新、清除实时行并输出最终快照,然后封存当前分片并写 checkpoint,
退出码保持 130。
## 清单与断点
每个分片关闭后向 `manifest.jsonl` 追加一行并 fsync:
```json
{"seq":1,"path":"000001.1-1000000.dump","pk_lo":"1","pk_hi":"1000000","rows":1000000,"bytes":12345678,"sha256":"...","closed_at":"2026-11-06T12:00:00Z"}
```
`state.json` 在每个 chunk 提交后原子更新(tmp + fsync + rename),记录:
- `config_hash` 与完整的配置指纹;
- 扫描游标(主键、日期键或当前日期);
- 当前日期桶与分片序号;
- 已处理行数。
续跑时使用相同输出目录与配置即可。指纹不一致会拒绝,除非显式
`--force-resume`;不一致的字段会列在错误信息里。密码不参与指纹,允许凭据轮换。
已封分片的文件如果缺少 manifest 记录(例如在 rename 与 manifest 追加之间崩溃),
续跑会自动识别并补录,不会被覆盖。带 `--purge` 时还会保留活动分片的
`.partial` 与 sidecar 元数据,续跑时截断到一致偏移并追加,避免已删除数据丢失。
## 一致性
**at-least-once**。文件写入与数据库提交不在同一个原子域内,崩溃后重跑可能重复写入
已处理的行,但不会丢失已提交的数据。导入端可用 `INSERT IGNORE` / 去重逻辑处理。
扫描期间不提供快照一致性:只保证读取到的行,并发写入可能改变行集合。
## 安全说明
- `--purge` **会删除源表数据**。先用 `--dry-run`,再只导出核对,最后才启用。
- `--bulk-delete` 改为按主键区间删除,可能删除扫描期间新插入且满足 `--where` 的行;
默认关闭,日期分片模式禁止使用。
- `--safe-auto-increment` 默认开启,purge 时不会删除当前最大自增主键行。
- 日期路径 B 会长时间持有一个只读查询与连接,可能推迟 undo 清理;用 `--max-lag`
限制主从延迟,优先为分片列建立 `(shard_column, pk)` 联合索引走路径 A。
- `--where` 原样拼入 SQL,等同于 pt-archiver 的信任模型;不要让不可信输入进入该参数。
- 配置指纹包含 DSN 中的 `time_zone`;时区漂移会导致同一行落到相邻日期,续跑会被拒绝。
## 退出码
| 码 | 含义 |
|---|---|
| 0 | 成功 |
| 2 | 配置错误 |
| 3 | 连接错误 |
| 4 | 写入/文件错误 |
| 5 | 校验失败(索引、指纹、分片列等) |
| 130 | 被 SIGINT/SIGTERM 中断(已 flush 当前分片并写 checkpoint) |
| 1 | 其他 |
## 参数对照:pt-archiver
| pt-archiver | archer | 说明 |
|---|---|---|
| `--source` | `--source` | MySQL DSN |
| `--dest` | `--dest` | MySQL DSN |
| `--file` | `--file` | archer 中为输出目录 |
| `--limit` | `--limit` / `--chunk-size` | `--limit` 为隐藏别名;语义是每次 SELECT 行数 |
| `--txn-size` | — | chunk 即事务,不提供独立事务粒度 |
| `--where` | `--where` | 必填 |
| `--columns` | `--columns` | 逗号分隔 |
| `--purge` | `--purge` | 默认不删除 |
| `--bulk-delete` | `--bulk-delete` | 依赖 `--purge` |
| `--replace` | `--replace` | |
| `--ignore` | `--insert-ignore` | |
| `--safe-auto-increment` | `--safe-auto-increment` | 默认开启 |
| `--max-lag` | `--max-lag` | |
| `--check-slave-lag` | `--check-replica-lag` | 传副本 DSN |
| `--check-interval` | `--check-interval` | |
| `--retries` | `--retries` | |
| `--dry-run` | `--dry-run` | archer 输出解析后配置、索引探测与 SQL |
| — | `--shard-by` / `--shard-rows` / `--shard-column` | archer 扩展 |
| — | `--format` / `--compress` / `--compress-level` | archer 扩展 |
| — | `--progress` / `--progress-interval` | archer 扩展;默认 `auto`,写 stderr |
| — | `--allow-full-scan` / `--force-resume` | archer 扩展 |
## 非目标(v1)
- 非 MySQL 数据源
- Parquet / Arrow 输出
- 字符串日期列分片
- 预计算边界并行导出
- 文件侧 exactly-once
- PXC Flow Control 适配
## 开发
```bash
go test ./...
# 集成测试(需要 MySQL):
ARCHER_TEST_DSN='root@tcp(127.0.0.1:3306)/archer_test' go test ./internal/app -run TestIntegration -v
```
集成测试会创建并删除 `it_*` 表;`LOAD DATA LOCAL INFILE` 相关用例需要服务器开启
`local_infile`。