Add archer import and allow date-mode bulk delete

archer import replays a sealed archive into an existing table: shard
selection (`--select`), SHA-256 pre-verification, idempotent modes
(`ignore`/`insert`/`replace`), and both LOAD DATA and batched-INSERT
engines. It reads manifest.jsonl strictly so corruption is reported
instead of skipped, and supports --dry-run, --allow-partial, and
per-shard workers.

--bulk-delete no longer rejects --shard-by date. Range deletion now
derives its bounds from the chunk's actual keys (date scanners rewrite
LastKey into a resumption cursor) and keeps safe-auto-increment
semantics by excluding the current max key. A startup warning documents
the monotonic-shard-column assumption.

Also splits CLI/format/sharding/progress/safety reference docs out of
the README, and adds the corresponding OpenSpec change artifacts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 21:14:23 +08:00
1 parent bc4a6b504f
commit 366d61ca25
49 files changed
+5099 -342

No files matched your search

+29 -324
View File
@@ -7,33 +7,23 @@
导出的分片沿扫描顺序连续、有序、无重叠:可以按主键或时间戳范围并行导入,
也可以按日期目录分批处理。
## 要求
## 特性
- Go 1.24+(构建)
- MySQL 5.7+ / 8.0 或 MariaDB 10.x(运行)
- 源表必须有主键或唯一索引;日期分片还需要分片列上的索引(见下文)
- 三种输出目标:文件分片、目标表、归档后删除源表行,可任意组合。
- 按唯一索引 seek 分块扫描,不依赖 `OFFSET`;日期模式按索引能力自动选择路径。
- 分片按扫描顺序编号,相邻分片主键范围连续、不重叠。
- `dump` / `csv` / `jsonl` 三种格式,`gzip` / `zstd` / `xz` 独立压缩。
- 原子封片、`manifest.jsonl` 清单、`state.json` 断点,支持中断续跑。
- `archer import` 按清单把归档重放进已存在的表:分片选择、SHA-256 预校验、幂等模式、`LOAD DATA` 与批量插入两种引擎。
- 实时进度、副本延迟等待、chunk 级重试。
## 构建
## 快速开始
需要 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 \
@@ -42,313 +32,28 @@ archer \
--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
archer import \
--file ./export \
--dest 'user:pass@tcp(10.0.0.6:3306)/app' \
--dest-table orders \
--dry-run
```
只删除(危险,需确认):
更多示例、构建脚本与前置条件见[快速开始](docs/getting-started.md)。
```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`。
| [快速开始](docs/getting-started.md) | 环境要求、构建、最小示例 |
| [分片模式](docs/sharding.md) | `none`/`count`/`date`、日期分片、索引路径 A/B |
| [输出格式与导入](docs/output-formats.md) | `dump`/`csv`/`jsonl`、压缩、各数据库导入 |
| [导入归档](docs/import.md) | `archer import`:选片、完整性校验、两种引擎、列映射与幂等 |
| [清单、断点与一致性](docs/checkpoint-and-resume.md) | `manifest`、`state`、续跑、at-least-once |
| [进度显示](docs/progress.md) | 进度模式、阶段、总量估算口径 |
| [安全说明](docs/safety.md) | `--purge`、`--bulk-delete`、副本延迟等注意事项 |
| [CLI 参考](docs/cli-reference.md) | 全部参数、退出码、pt-archiver 对照 |
| [开发](docs/development.md) | 单元测试与集成测试 |