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:
1 parent
bc4a6b504f
commit
366d61ca25
49 files changed
+5099
-342
No files matched your search
@@ -0,0 +1,30 @@
|
||||
# 清单、断点与一致性
|
||||
|
||||
## 清单与断点
|
||||
|
||||
每个分片关闭后向 `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` / 去重逻辑处理。
|
||||
|
||||
扫描期间不提供快照一致性:只保证读取到的行,并发写入可能改变行集合。
|
||||
@@ -0,0 +1,140 @@
|
||||
# CLI 参考
|
||||
|
||||
## 参数参考
|
||||
|
||||
按功能分组。“默认”是未显式传参时的值;标注“必填”的参数缺失时以退出码 2 退出。
|
||||
|
||||
### 连接与目标
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--source` | 必填 | 源 MySQL DSN。`parseTime` 被强制关闭,列值按原始字节读取。 |
|
||||
| `--table` | 必填 | 源表名。 |
|
||||
| `--where` | 必填 | 源表过滤条件,原样拼入 SQL;空白字符串视为未提供。 |
|
||||
| `--dest` | 空 | 目标 MySQL DSN。`--file`、`--dest`、`--purge` 至少要有一个。与源同实例(`host:port` 相同)时,dest 插入与 purge 删除共用一个事务。 |
|
||||
| `--dest-table` | 同 `--table` | 目标表名,仅 `--dest` 生效。 |
|
||||
| `--columns` | 全部列 | 逗号分隔的输出/插入列。扫描键与分片列总会读取,但只有列在此列表中才会写出。 |
|
||||
| `--file` | 空 | 输出目录;设置后生成分片文件、`manifest.jsonl` 与 `state.json`。 |
|
||||
| `--insert-ignore` | 关闭 | dest 写入使用 `INSERT IGNORE`。与 `--replace` 互斥。 |
|
||||
| `--replace` | 关闭 | dest 写入使用 `REPLACE`。与 `--insert-ignore` 互斥。 |
|
||||
| `--purge` | 关闭 | 归档后删除源表行。没有其他输出目标时,单独使用即为“只删除”。 |
|
||||
|
||||
### 扫描与事务
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--chunk-size` | `2000` | 每条 SELECT 的行数,同时是事务大小与 checkpoint 粒度。 |
|
||||
| `--limit` | — | `--chunk-size` 的隐藏别名(已弃用),只能与 `--chunk-size` 二选一。 |
|
||||
| `--index` | 自动选择 | 强制用指定索引作为扫描键。必须是唯一索引且各列 `NOT NULL`;未指定时优先主键,否则取第一个满足条件的唯一索引。 |
|
||||
| `--safe-auto-increment` | 开启 | purge 时跳过当前最大自增键所在行,避免删掉写入端刚分配的最大 id。 |
|
||||
|
||||
### 分片
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--shard-by` | `none` | `none`:单文件;`count`:每 `--shard-rows` 行封片;`date`:按分片列的日期分目录。 |
|
||||
| `--shard-rows` | `0` | `none` 时必须为 0;`count` 时必须大于 0;`date` 时为 0 表示每天一个文件,大于 0 表示同一天内再按行切片。 |
|
||||
| `--shard-column` | — | 仅 `date` 且必填;日期、`DATETIME`/`TIMESTAMP` 或整数 epoch 列。 |
|
||||
| `--shard-column-type` | — | 仅 `date` 且分片列为整数时必填:`epoch-seconds` / `epoch-milliseconds` / `epoch-microseconds`。 |
|
||||
| `--shard-time-zone` | `UTC` | 仅用于解释整数 epoch 的日归属;与 DSN 的 `time_zone` 一起计入配置指纹。 |
|
||||
| `--zero-date` | 报错 | 空:遇到 `0000-00-00` 报错并输出行键;`bucket`:放入 `date=0000-00-00`。仅 `date`。 |
|
||||
| `--allow-full-scan` | 关闭 | `date` 模式下没有可用索引时,允许退化为路径 B 的全表扫描,而不是 fail-fast。 |
|
||||
|
||||
### 输出格式
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--format` | `dump` | `dump` / `csv` / `jsonl`。 |
|
||||
| `--compress` | `none` | `none` / `gzip` / `zstd` / `xz`;每个分片独立压缩。 |
|
||||
| `--compress-level` | `3` | 1–9 的统一档位;`--compress none` 时只接受默认值 3。 |
|
||||
| `--csv-null` | `\N` | `csv` 中 NULL 的文本表示,仅 `--format csv` 生效。 |
|
||||
|
||||
### 副本延迟
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--check-replica-lag` | 空 | 副本 DSN。设置后每个 chunk 读取前执行 `SHOW REPLICA STATUS`(回退 `SHOW SLAVE STATUS`),延迟超标或复制线程未运行就等待。 |
|
||||
| `--max-lag` | `1s` | 允许的最大副本延迟;只有设置了 `--check-replica-lag` 才生效。 |
|
||||
| `--check-interval` | `1s` | 两次延迟检查之间的等待间隔。 |
|
||||
|
||||
### 重试与恢复
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--retries` | `1` | chunk 的数据库事务失败后的重试次数。总尝试次数为 `1 + retries`,第 n 次重试前等待 n 秒。 |
|
||||
| `--force-resume` | 关闭 | 配置指纹不一致时仍从 `state.json` 续跑。 |
|
||||
| `--dry-run` | 关闭 | 输出解析后的配置、索引探测结果与将要执行的 SQL;不写文件、不写目标表、不删除数据。 |
|
||||
|
||||
### 进度与统计
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--progress` | `auto` | `auto`:stderr 是终端才显示;`on`:始终显示;`off`/`0`:关闭;`N>0`:开启并每 N 行额外输出一行。 |
|
||||
| `--progress-interval` | `1s` | 两次进度刷新之间的最小间隔。 |
|
||||
| `--statistics` | 关闭 | 结束后向 stdout 打印汇总。 |
|
||||
| `--version` | — | 打印版本并退出,不执行配置校验。 |
|
||||
|
||||
## 导入模式(`archer import`)
|
||||
|
||||
`archer import --file <归档目录> --dest <DSN> [flags]` 把归档重放进已存在的目标表。导入模式只接受下列参数;`--source`、`--table`、`--where`、`--purge`、`--format`、`--compress` 等导出参数会被拒绝(退出码 2)。
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--file` | 必填 | 归档目录,必须存在且包含 `manifest.jsonl` |
|
||||
| `--dest` | 必填 | 目标 MySQL DSN,必须包含数据库名 |
|
||||
| `--dest-table` | 归档记录的源表名 | 目标表名;归档未记录表名时必须显式提供 |
|
||||
| `--columns` | 空 | 按文件字段顺序给出目标列名;与 `--assume-all-columns` 互斥 |
|
||||
| `--assume-all-columns` | 关闭 | 接受与目标表 ordinal 顺序一致的位置映射,并打印警告 |
|
||||
| `--select` | `all` | 可重复:`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2`,多次取并集 |
|
||||
| `--mode` | `ignore` | `ignore` / `insert` / `replace` |
|
||||
| `--engine` | `load` | `load`(`LOAD DATA LOCAL INFILE`)/ `insert`(批量参数化插入) |
|
||||
| `--verify` | `pre` | `pre`:装载前校验压缩文件 SHA-256;`off`:跳过 |
|
||||
| `--workers` | `1` | 并行分片数,必须大于 0;按连续 `seq` 区间分配 |
|
||||
| `--charset` | `utf8mb4` | 装载字符集 |
|
||||
| `--time-zone` | 空 | 设置目标会话时区;空表示服务端默认 |
|
||||
| `--allow-partial` | 关闭 | 允许导入 `state.json` 中 `complete` 为 false 或缺失的归档 |
|
||||
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
|
||||
| `--dry-run` | 关闭 | 只打印选片与配置,不连接目标库、不写入 |
|
||||
| `--progress` | `auto` | 进度输出,语义同导出模式 |
|
||||
| `--statistics` | 关闭 | 结束汇总 |
|
||||
| `--version` | — | 打印版本并退出 |
|
||||
|
||||
行为细节见[导入归档](import.md)。
|
||||
|
||||
## 退出码
|
||||
|
||||
| 码 | 含义 |
|
||||
|---|---|
|
||||
| 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 扩展 |
|
||||
@@ -0,0 +1,10 @@
|
||||
# 开发
|
||||
|
||||
```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`。
|
||||
@@ -0,0 +1,66 @@
|
||||
# 快速开始
|
||||
|
||||
## 要求
|
||||
|
||||
- Go 1.24+(构建)
|
||||
- MySQL 5.7+ / 8.0 或 MariaDB 10.x(运行)
|
||||
- 源表必须有主键或唯一索引;日期分片还需要分片列上的索引(见[分片模式](sharding.md))
|
||||
|
||||
## 构建
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [分片模式](sharding.md)
|
||||
- [输出格式与导入](output-formats.md)
|
||||
- [清单与断点](checkpoint-and-resume.md)
|
||||
- [进度显示](progress.md)
|
||||
- [安全说明](safety.md)
|
||||
- [参数参考](cli-reference.md)
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
# 导入归档
|
||||
|
||||
`archer import` 把一次归档产出(分片文件 + `manifest.jsonl` + `state.json`)按需重放进一个**已存在**的 MySQL/MariaDB 表。它不创建表、不修改表结构,也不改变导出端的文件或清单格式。
|
||||
|
||||
```bash
|
||||
archer import \
|
||||
--file ./export/orders \
|
||||
--dest 'user:pass@tcp(db.example:3306)/app' \
|
||||
--dest-table orders
|
||||
```
|
||||
|
||||
导入的权威来源是归档目录中的 `manifest.jsonl`:
|
||||
|
||||
- 只导入清单里登记、文件存在且校验通过的分片;
|
||||
- 目录里游离的分片文件不会导入,`--statistics` 会把它们计为 ignored files;
|
||||
- 清单行无法解析时直接报错,不会把损坏行当成“没有这个分片”;
|
||||
- 未提供 `--dest-table` 时使用 `state.json` 记录的源表名。
|
||||
|
||||
## 必填参数与默认值
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--file` | 必填 | 归档目录,必须包含 `manifest.jsonl` |
|
||||
| `--dest` | 必填 | 目标 MySQL DSN,必须包含数据库名 |
|
||||
| `--dest-table` | 归档记录的源表名 | 目标表名 |
|
||||
| `--columns` | 空 | 按文件字段顺序给出目标列名 |
|
||||
| `--assume-all-columns` | 关闭 | 接受与目标表 ordinal 顺序一致的位置映射,并打印警告 |
|
||||
| `--select` | `all` | 可重复;`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2` |
|
||||
| `--mode` | `ignore` | `ignore` / `insert` / `replace` |
|
||||
| `--engine` | `load` | `load` / `insert` |
|
||||
| `--verify` | `pre` | `pre` / `off` |
|
||||
| `--workers` | `1` | 并行分片数,必须大于 0 |
|
||||
| `--charset` | `utf8mb4` | 装载时使用的字符集 |
|
||||
| `--time-zone` | 空 | 目标会话时区;空表示使用服务端默认 |
|
||||
| `--allow-partial` | 关闭 | 允许导入未完成归档的已封分片 |
|
||||
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
|
||||
| `--dry-run` | 关闭 | 只打印选片与配置 |
|
||||
| `--progress` | `auto` | 进度输出 |
|
||||
| `--statistics` | 关闭 | 结束汇总 |
|
||||
|
||||
导入模式拒绝导出专属参数(`--source`、`--where`、`--purge`、`--format` 等),未知参数同样报错,退出码为 2。
|
||||
|
||||
## 分片选择
|
||||
|
||||
选择粒度是**整个分片**:`LOAD DATA` 不做行级过滤。
|
||||
|
||||
| 语法 | 语义 |
|
||||
|---|---|
|
||||
| `all` | 清单中的全部分片 |
|
||||
| `seq:A-B` | 分片序号闭区间 |
|
||||
| `pk:LO-HI` | 分片主键区间与 `[LO,HI]` **相交**即入选 |
|
||||
| `date:D1..D2` | 日期桶闭区间 |
|
||||
|
||||
多个 `--select` 取并集,并按归档顺序(日期桶、再按 `seq`)去重排序。`date:` 只能用于按日期分片的归档;`count`/`none` 归档使用会直接报错。
|
||||
|
||||
`pk:` 的边界分片会带入请求范围之外的行。例如请求 `pk:150000-250000`,而分片 1 覆盖 `1-200000`,则分片 1 会整片导入。启动时会打印相应警告,建议先用 `--dry-run` 确认选片。
|
||||
|
||||
```bash
|
||||
archer import --file ./export/orders --dest '...' \
|
||||
--dest-table orders --select seq:1-10 --select pk:500000-600000 --dry-run
|
||||
```
|
||||
|
||||
## 完整性检查
|
||||
|
||||
导入前依次检查:
|
||||
|
||||
1. `state.json` 存在且 `complete` 为 `true`;不满足时拒绝导入,`--allow-partial` 可显式导入已封分片。
|
||||
2. 清单中所有选中分片的文件存在。
|
||||
3. 选中分片的格式与压缩方式一致,且格式为 `dump`(v1 不支持 csv/jsonl)。
|
||||
4. 每个分片的格式、压缩、目标列映射就绪。
|
||||
|
||||
默认 `--verify pre` 会在装载每个分片前流式计算压缩文件的 SHA-256,并与清单比对;不一致立即中止,不会发送任何该分片数据。`--verify off` 关闭预校验。
|
||||
|
||||
每个分片装载后核对行数:
|
||||
|
||||
- `insert`:实际写入必须等于清单 `rows`;
|
||||
- `ignore`:实际写入不得大于 `rows`,差额报告为跳过;
|
||||
- `replace`:只报告受影响行数(覆盖通常按删除 + 插入计数)。
|
||||
|
||||
## 两种引擎
|
||||
|
||||
### `load`(默认)
|
||||
|
||||
通过 `mysql.RegisterReaderHandler` 把解压流直接交给 `LOAD DATA LOCAL INFILE 'Reader::...'`,不落临时文件,也不要求驱动开启任意本地文件读取。
|
||||
|
||||
目标服务器必须启用 `local_infile`(MySQL 8.0.3+ 默认关闭;MariaDB 默认开启;托管库通常在参数组中控制)。启动时执行 `SELECT @@local_infile, @@version`,关闭时在装载前失败,并提示两条出路:
|
||||
|
||||
- 在服务端/代理启用 `local_infile`,或
|
||||
- 使用 `--engine insert`。
|
||||
|
||||
经过连接池或代理时,本地文件请求可能不被转发;必要时直连目标实例。
|
||||
|
||||
### `insert`(兜底)
|
||||
|
||||
使用参数化批量 `INSERT`,按 `max_allowed_packet` 切批,每个分片的所有批次包在同一个事务中,保证分片级原子。吞吐低于 `LOAD DATA`,但在 `local_infile` 不可用时语义不变。两种引擎对同一归档、同一目标表的结果一致。
|
||||
|
||||
## 列映射
|
||||
|
||||
文件本身没有列名,因此映射以**列名**为准:
|
||||
|
||||
1. **归档记录了列清单**(导出时使用了 `--columns`):按记录顺序生成装载列清单,逐个校验目标列存在;记录中包含生成列时直接报错。此时不能再指定 `--columns` 或 `--assume-all-columns`。
|
||||
2. **`--columns`**:按文件字段顺序给出目标列名,做同样的名校验。
|
||||
3. **`--assume-all-columns`**:接受位置映射。按目标表全部列的 ordinal 顺序生成列清单;生成列替换为 `@_archer_skip_<n>` 丢弃变量,由目标表重新计算。启动时打印位置映射警告。
|
||||
4. 都没有时拒绝导入,提示提供 `--columns` 或显式接受 `--assume-all-columns`。
|
||||
|
||||
文件字段数只是前置检查:与列清单长度不一致会在装载前报错,但字段数相同**不能**证明列名和顺序正确。`--assume-all-columns` 无法发现“同数换列/改名”,严格场景请使用归档列清单或显式 `--columns`。
|
||||
|
||||
目标表必须预先存在。需要装到全新实例时,先建同构表(列名、顺序、类型一致),再导入。
|
||||
|
||||
## 模式与幂等
|
||||
|
||||
| `--mode` | 语句 | 重复导入 |
|
||||
|---|---|---|
|
||||
| `ignore`(默认) | `LOAD DATA ... IGNORE` / `INSERT IGNORE` | 跳过冲突行,可安全重跑 |
|
||||
| `insert` | `LOAD DATA ...` / `INSERT` | 遇重复键失败 |
|
||||
| `replace` | `LOAD DATA ... REPLACE` / `REPLACE` | 用归档内容覆盖冲突行 |
|
||||
|
||||
默认 `ignore` 让“失败后修复再重跑”成为安全操作。`ignore` 模式下,唯一键冲突被跳过的行计入跳过行数,对应的重复键告警不视为失败;其他服务端告警默认失败,`--allow-warnings` 可改为记录并继续。`insert`/`replace` 重跑可能失败或覆盖,需自行确认。
|
||||
|
||||
## 进度、统计与 dry-run
|
||||
|
||||
- `--progress` 语义与导出一致,总量是选中分片的清单一共行数。
|
||||
- `--statistics` 输出选片数、成功/失败/未选分片数、期望/实际/跳过行数、字节、ignored files 与耗时。
|
||||
- `--dry-run` 只读清单与首个分片首行,打印配置、选片、总行数/字节;不连接目标库,也不写入。
|
||||
|
||||
`--workers N` 把选中分片按连续 `seq` 区间分给 N 个 worker。并行结果与串行一致;默认 1,导回线上表时建议低峰执行并监控锁等待和主从延迟。
|
||||
|
||||
## 失败语义与退出码
|
||||
|
||||
- 每个分片原子:`LOAD DATA` 单语句在 InnoDB 下原子;`insert` 引擎每分片一个事务。
|
||||
- 首个分片失败即停止开始新分片,报告失败 `seq`、原因与失败前累计行数;已完成分片保留。
|
||||
- 成功返回 0;参数/配置错误返回 2;连接错误 3;写入/装载错误 4;校验失败(哈希、行数、列映射、完成度)5;被信号中断 130。
|
||||
|
||||
## 导回原表的注意事项
|
||||
|
||||
- 归档边界与下一次归档的 `--where` 范围可能重叠。导回原表的行若仍落在归档条件内,会被再次归档;归档条件应覆盖“纯冷时间段”。
|
||||
- `TIMESTAMP` 的时区解释取决于导出与会话设置。归档未记录导出会话时区,必要时用 `--time-zone` 显式设置目标会话时区,并在导入后核对样本。
|
||||
- 非 ASCII、emoji、BLOB 建议使用 `--charset utf8mb4`;二进制列可试用 `--charset binary` 并按业务核对。
|
||||
- 导入不会自动建表或迁移 schema;归档与目标表的列名、顺序和类型需要人工保持一致。
|
||||
|
||||
## 限制
|
||||
|
||||
- v1 只支持 `dump` 格式;`csv`/`jsonl` 会明确报错。
|
||||
- 选择粒度只到分片,不支持行级过滤,也没有导入台账或断点续导。
|
||||
- 不做常驻服务、HTTP 接口、队列或定时任务。
|
||||
@@ -0,0 +1,50 @@
|
||||
# 输出格式与导入
|
||||
|
||||
## 输出格式
|
||||
|
||||
| `--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
|
||||
```
|
||||
@@ -0,0 +1,41 @@
|
||||
# 进度显示
|
||||
|
||||
默认 `--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。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 安全说明
|
||||
|
||||
- `--purge` **会删除源表数据**。先用 `--dry-run`,再只导出核对,最后才启用。
|
||||
- `--bulk-delete` 改为按 chunk 实际读取行的主键区间删除,可能删除扫描期间新插入且满足 `--where` 的行;
|
||||
默认关闭。日期分片模式下也可用,但要求**分片列相对扫描键单调、无回填**(即日期随主键递增、
|
||||
没有迟到数据),否则迟到行可能让区间跨日期,把尚未归档的数据提前删掉。
|
||||
- `--safe-auto-increment` 默认开启,purge 时不会删除当前最大自增主键行。
|
||||
- 日期路径 B 会长时间持有一个只读查询与连接,可能推迟 undo 清理;用 `--max-lag`
|
||||
限制主从延迟,优先为分片列建立 `(shard_column, pk)` 联合索引走路径 A。
|
||||
- `--where` 原样拼入 SQL,等同于 pt-archiver 的信任模型;不要让不可信输入进入该参数。
|
||||
- 配置指纹包含 DSN 中的 `time_zone`;时区漂移会导致同一行落到相邻日期,续跑会被拒绝。
|
||||
@@ -0,0 +1,109 @@
|
||||
# 分片模式
|
||||
|
||||
| `--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, <主键>)`
|
||||
(主键会隐式追加到索引末尾),所以当游标键恰好是主键时,`ORDER BY created_at, id` 的输出依然有序,
|
||||
分片不变量成立;若所选唯一键不是主键,日内顺序不再由索引保证,需要 filesort(结果仍正确,只是更慢)。
|
||||
但 `id` 不是显式索引列,`(created_at, id) > (?, ?)` 无法作为精确索引范围下推。
|
||||
如果仍按 chunk 反复查询,每次都得从当天起点重新扫描再过滤已读行,单日内会退化为
|
||||
O(天行数 × chunk 数)。所以改为“每天一条查询 + 长游标流式读完”:只扫一遍,
|
||||
代价是这条读查询长时间占用一条连接(同连接不能再发删除语句),删除必须换第二条连接,
|
||||
且长读快照会延长 undo 保留时间。
|
||||
|
||||
因此:**A 是推荐路径;B 是“不改表结构也能用”的兼容路径**。启动时探测索引,就是为了让
|
||||
有联合索引的用户拿到逐 chunk 短事务与精确续跑,让只有单列索引的用户不必在生产大表上
|
||||
新建索引也能完成归档;两者都没有时默认 fail-fast,而不是静默退化成全表扫描。
|
||||
|
||||
需要区分两件事:**索引决定的是执行方式,不是结果正确性**。`(created_at, id) > (?, ?)` 在没有
|
||||
联合索引时依旧按“先 `created_at`、相等再比 `id`”的字典序正确求值,只是优化器不能把它变成精确的
|
||||
索引起点;缺索引的后果是重复扫描与耗时(即路径 B 要规避的单日 O(天行数 × chunk 数) 退化),
|
||||
而不是多读、漏读或删错行。两条路径产出的行集相同,区别只在能否逐 chunk 精确 seek、
|
||||
以及读取能否短事务化。
|
||||
|
||||
`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` 都计入配置指纹;续跑时不一致会拒绝。
|
||||
Reference in new issue
Block a user