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
+5097
-340
No files matched your search
@@ -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) | 单元测试与集成测试 |
|
||||
@@ -12,10 +12,15 @@ import (
|
||||
"archer/internal/app"
|
||||
"archer/internal/archererr"
|
||||
"archer/internal/cli"
|
||||
"archer/internal/importer"
|
||||
"archer/internal/version"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if len(os.Args) > 1 && os.Args[1] == "import" {
|
||||
runImport(os.Args[2:])
|
||||
return
|
||||
}
|
||||
cfg, err := cli.Parse(os.Args[1:], os.Stderr)
|
||||
if err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
@@ -37,3 +42,26 @@ func main() {
|
||||
os.Exit(archererr.ExitCode(err))
|
||||
}
|
||||
}
|
||||
|
||||
func runImport(args []string) {
|
||||
cfg, err := cli.ParseImport(args, os.Stderr)
|
||||
if err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
return
|
||||
}
|
||||
fmt.Fprintln(os.Stderr, "archer import:", err)
|
||||
os.Exit(2)
|
||||
}
|
||||
if cfg.Version {
|
||||
fmt.Println(version.String())
|
||||
return
|
||||
}
|
||||
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
|
||||
if err := importer.Run(ctx, cfg); err != nil {
|
||||
fmt.Fprintln(os.Stderr, "archer import:", err)
|
||||
os.Exit(archererr.ExitCode(err))
|
||||
}
|
||||
}
|
||||
@@ -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` 都计入配置指纹;续跑时不一致会拒绝。
|
||||
@@ -366,6 +366,9 @@ func (a *App) execute(ctx context.Context) error {
|
||||
if a.cfg.BulkDelete {
|
||||
a.message("warning: --bulk-delete removes all rows in the scanned key range that match --where, including concurrent inserts")
|
||||
}
|
||||
if a.cfg.BulkDelete && a.cfg.IsDateShard() {
|
||||
a.message("warning: date mode --bulk-delete assumes the shard column never moves backwards relative to the scan key; a late or backfilled row can be deleted before it is archived")
|
||||
}
|
||||
|
||||
for {
|
||||
if err := ctx.Err(); err != nil {
|
||||
|
||||
@@ -882,6 +882,57 @@ func TestIntegrationPurgeAndDest(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationDateBulkDelete(t *testing.T) {
|
||||
dsn := testDSN(t)
|
||||
db := openRoot(t, dsn)
|
||||
defer db.Close()
|
||||
|
||||
seed := func(table string) {
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS "+table)
|
||||
execSQL(t, db, `CREATE TABLE `+table+` (
|
||||
id BIGINT NOT NULL AUTO_INCREMENT,
|
||||
v VARCHAR(32),
|
||||
created_at DATETIME NOT NULL,
|
||||
PRIMARY KEY (id),
|
||||
KEY d (created_at, id))`)
|
||||
execSQL(t, db, `INSERT INTO `+table+` (id, v, created_at) VALUES
|
||||
(1,'a','2025-01-01 00:00:00'),
|
||||
(2,'b','2025-01-02 00:00:00'),
|
||||
(3,'c','2025-01-03 00:00:00'),
|
||||
(4,'d','2025-01-04 00:00:00')`)
|
||||
}
|
||||
|
||||
seed("it_date_bulk")
|
||||
out := t.TempDir()
|
||||
if _, err := runCLI(t, context.Background(), baseCLI(dsn, "it_date_bulk", out,
|
||||
"--shard-by", "date", "--shard-column", "created_at",
|
||||
"--purge", "--bulk-delete", "--safe-auto-increment=false", "--chunk-size", "2")...); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var count int
|
||||
db.QueryRow("SELECT COUNT(*) FROM it_date_bulk").Scan(&count)
|
||||
if count != 0 {
|
||||
t.Fatalf("safe off: %d rows left", count)
|
||||
}
|
||||
if got := len(readTree(t, out)); got != 4 {
|
||||
t.Fatalf("expected 4 shards, got %d", got)
|
||||
}
|
||||
|
||||
seed("it_date_bulk_safe")
|
||||
out = t.TempDir()
|
||||
if _, err := runCLI(t, context.Background(), baseCLI(dsn, "it_date_bulk_safe", out,
|
||||
"--shard-by", "date", "--shard-column", "created_at",
|
||||
"--purge", "--bulk-delete", "--chunk-size", "2")...); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
db.QueryRow("SELECT COUNT(*) FROM it_date_bulk_safe").Scan(&count)
|
||||
var maxID int64
|
||||
db.QueryRow("SELECT MAX(id) FROM it_date_bulk_safe").Scan(&maxID)
|
||||
if count != 1 || maxID != 4 {
|
||||
t.Fatalf("safe on: count=%d max=%d", count, maxID)
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationCheckpointConfigMismatch(t *testing.T) {
|
||||
dsn := testDSN(t)
|
||||
db := openRoot(t, dsn)
|
||||
|
||||
@@ -87,8 +87,8 @@ func TestValidateShardRules(t *testing.T) {
|
||||
|
||||
args = append(baseArgs(), "--shard-by", "date", "--shard-column", "c", "--bulk-delete", "--purge")
|
||||
c, _ = Parse(args, &bytes.Buffer{})
|
||||
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "bulk-delete") {
|
||||
t.Fatalf("got %v", err)
|
||||
if err := c.Validate(); err != nil {
|
||||
t.Fatalf("date mode bulk delete should be allowed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,219 @@
|
||||
package cli
|
||||
|
||||
import (
|
||||
"flag"
|
||||
"fmt"
|
||||
"io"
|
||||
"regexp"
|
||||
"strings"
|
||||
|
||||
"github.com/go-sql-driver/mysql"
|
||||
|
||||
"archer/internal/shard"
|
||||
)
|
||||
|
||||
// ImportConfig is the resolved configuration of `archer import`. It is kept
|
||||
// separate from Config so archive (export) validation rules never leak into
|
||||
// replay and vice versa.
|
||||
type ImportConfig struct {
|
||||
FileDir string
|
||||
DestDSN string
|
||||
DestTable string
|
||||
Columns []string
|
||||
AssumeAll bool
|
||||
Selects []string
|
||||
Selectors []shard.Selector
|
||||
Mode string // ignore|insert|replace
|
||||
Engine string // load|insert
|
||||
Verify string // pre|off
|
||||
Workers int
|
||||
Charset string
|
||||
TimeZone string
|
||||
AllowPartial bool
|
||||
AllowWarnings bool
|
||||
DryRun bool
|
||||
Progress ProgressValue
|
||||
Statistics bool
|
||||
Version bool
|
||||
}
|
||||
|
||||
// ImportDefaults returns the documented defaults for `archer import`.
|
||||
func ImportDefaults() *ImportConfig {
|
||||
return &ImportConfig{
|
||||
Mode: "ignore",
|
||||
Engine: "load",
|
||||
Verify: "pre",
|
||||
Workers: 1,
|
||||
Charset: "utf8mb4",
|
||||
Progress: ProgressValue{Mode: ProgressAuto},
|
||||
}
|
||||
}
|
||||
|
||||
// exportOnlyFlags lists archive-mode flags. They are intentionally absent from
|
||||
// the import flag set, but a dedicated message is friendlier than the flag
|
||||
// package's generic "flag provided but not defined".
|
||||
var exportOnlyFlags = []string{
|
||||
"source", "table", "where", "purge", "bulk-delete", "insert-ignore",
|
||||
"replace", "chunk-size", "limit", "shard-by", "shard-rows", "shard-column",
|
||||
"shard-column-type", "shard-time-zone", "zero-date", "format", "compress",
|
||||
"compress-level", "csv-null", "max-lag", "check-interval",
|
||||
"check-replica-lag", "retries", "safe-auto-increment", "progress-interval",
|
||||
"allow-full-scan", "force-resume", "index",
|
||||
}
|
||||
|
||||
var charsetRE = regexp.MustCompile(`^[A-Za-z0-9_]+$`)
|
||||
|
||||
type stringList []string
|
||||
|
||||
func (s *stringList) String() string { return strings.Join(*s, ",") }
|
||||
func (s *stringList) Set(v string) error {
|
||||
*s = append(*s, v)
|
||||
return nil
|
||||
}
|
||||
|
||||
// ParseImport parses args (without the "import" subcommand) into an
|
||||
// ImportConfig. Validation is separate.
|
||||
func ParseImport(args []string, errOut io.Writer) (*ImportConfig, error) {
|
||||
if err := rejectExportFlags(args); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
c := ImportDefaults()
|
||||
var (
|
||||
columnsArg string
|
||||
selects stringList
|
||||
)
|
||||
fs := flag.NewFlagSet("archer import", flag.ContinueOnError)
|
||||
fs.SetOutput(errOut)
|
||||
fs.Usage = func() {
|
||||
fmt.Fprintln(errOut, "usage: archer import --file <archive-dir> --dest <dsn> [flags]")
|
||||
fmt.Fprintln(errOut, "")
|
||||
fmt.Fprintln(errOut, "Replay a dump archive into an existing MySQL table.")
|
||||
fmt.Fprintln(errOut, "")
|
||||
fmt.Fprintln(errOut, "flags:")
|
||||
fs.PrintDefaults()
|
||||
}
|
||||
|
||||
fs.StringVar(&c.FileDir, "file", "", "archive directory containing manifest.jsonl (required)")
|
||||
fs.StringVar(&c.DestDSN, "dest", "", "target MySQL DSN (required, must include a database)")
|
||||
fs.StringVar(&c.DestTable, "dest-table", "", "target table (defaults to the archived source table)")
|
||||
fs.StringVar(&columnsArg, "columns", "", "comma separated target columns in file field order")
|
||||
fs.BoolVar(&c.AssumeAll, "assume-all-columns", false, "accept positional mapping to all target columns, in ordinal order")
|
||||
fs.Var(&selects, "select", "shard selector (repeatable): all, seq:A-B, pk:LO-HI, date:D1..D2")
|
||||
fs.StringVar(&c.Mode, "mode", c.Mode, "insert mode: ignore|insert|replace")
|
||||
fs.StringVar(&c.Engine, "engine", c.Engine, "load engine: load|insert")
|
||||
fs.StringVar(&c.Verify, "verify", c.Verify, "integrity check: pre|off")
|
||||
fs.IntVar(&c.Workers, "workers", c.Workers, "parallel shard workers (must be greater than 0)")
|
||||
fs.StringVar(&c.Charset, "charset", c.Charset, "character set used for loading")
|
||||
fs.StringVar(&c.TimeZone, "time-zone", "", "target session time zone (empty: server default)")
|
||||
fs.BoolVar(&c.AllowPartial, "allow-partial", false, "import sealed shards from an archive whose state.json is incomplete")
|
||||
fs.BoolVar(&c.AllowWarnings, "allow-warnings", false, "do not treat server warnings as failures")
|
||||
fs.BoolVar(&c.DryRun, "dry-run", false, "print selected shards and configuration without connecting or writing")
|
||||
fs.Var(&c.Progress, "progress", "progress output: auto|on|off|N")
|
||||
fs.BoolVar(&c.Statistics, "statistics", false, "print a summary when finished")
|
||||
fs.BoolVar(&c.Version, "version", false, "print version and exit")
|
||||
|
||||
if err := fs.Parse(args); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if fs.NArg() > 0 {
|
||||
return nil, fmt.Errorf("unexpected argument %q", fs.Arg(0))
|
||||
}
|
||||
if c.Version {
|
||||
return c, nil
|
||||
}
|
||||
if columnsArg != "" {
|
||||
for _, part := range strings.Split(columnsArg, ",") {
|
||||
part = strings.TrimSpace(part)
|
||||
if part != "" {
|
||||
c.Columns = append(c.Columns, part)
|
||||
}
|
||||
}
|
||||
}
|
||||
c.Selects = append([]string(nil), selects...)
|
||||
return c, nil
|
||||
}
|
||||
|
||||
func rejectExportFlags(args []string) error {
|
||||
exportOnly := make(map[string]bool, len(exportOnlyFlags))
|
||||
for _, name := range exportOnlyFlags {
|
||||
exportOnly[name] = true
|
||||
}
|
||||
for _, a := range args {
|
||||
if a == "--" {
|
||||
break
|
||||
}
|
||||
if !strings.HasPrefix(a, "--") {
|
||||
continue
|
||||
}
|
||||
name := strings.TrimPrefix(a, "--")
|
||||
if i := strings.IndexByte(name, '='); i >= 0 {
|
||||
name = name[:i]
|
||||
}
|
||||
if exportOnly[name] {
|
||||
return cfgErr("--%s is only valid in archive (export) mode", name)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// Validate checks required flags and the import-only dependency rules. Archive
|
||||
// contents (completion, recorded columns, selectors against entries) are
|
||||
// checked by the importer before any database connection is opened.
|
||||
func (c *ImportConfig) Validate() error {
|
||||
if c.FileDir == "" {
|
||||
return cfgErr("--file is required")
|
||||
}
|
||||
if c.DestDSN == "" {
|
||||
return cfgErr("--dest is required")
|
||||
}
|
||||
dest, err := normalize(c.DestDSN)
|
||||
if err != nil {
|
||||
return cfgErr("--dest: %v", err)
|
||||
}
|
||||
if dest.DBName == "" {
|
||||
return cfgErr("--dest must include a database name")
|
||||
}
|
||||
switch c.Mode {
|
||||
case "ignore", "insert", "replace":
|
||||
default:
|
||||
return cfgErr("--mode must be one of ignore, insert, replace")
|
||||
}
|
||||
switch c.Engine {
|
||||
case "load", "insert":
|
||||
default:
|
||||
return cfgErr("--engine must be one of load, insert")
|
||||
}
|
||||
switch c.Verify {
|
||||
case "pre", "off":
|
||||
default:
|
||||
return cfgErr("--verify must be pre or off")
|
||||
}
|
||||
if c.Workers <= 0 {
|
||||
return cfgErr("--workers must be greater than 0")
|
||||
}
|
||||
if !charsetRE.MatchString(c.Charset) {
|
||||
return cfgErr("--charset %q is not a valid character set name", c.Charset)
|
||||
}
|
||||
if len(c.Columns) > 0 && c.AssumeAll {
|
||||
return cfgErr("--columns and --assume-all-columns are mutually exclusive")
|
||||
}
|
||||
if err := c.Progress.resolve(); err != nil {
|
||||
return cfgErr("%v", err)
|
||||
}
|
||||
sels, err := shard.ParseSelection(c.Selects)
|
||||
if err != nil {
|
||||
return cfgErr("%v", err)
|
||||
}
|
||||
for _, s := range sels {
|
||||
if s.Kind == "all" && len(sels) > 1 {
|
||||
return cfgErr("--select all cannot be combined with other selectors")
|
||||
}
|
||||
}
|
||||
c.Selectors = sels
|
||||
return nil
|
||||
}
|
||||
|
||||
// DestConfig parses the target DSN, forcing parseTime off like the export path.
|
||||
func (c *ImportConfig) DestConfig() (*mysql.Config, error) {
|
||||
return normalize(c.DestDSN)
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
package cli
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func importArgs(extra ...string) []string {
|
||||
args := []string{"--file", "archive", "--dest", "u:p@tcp(127.0.0.1:3306)/db"}
|
||||
return append(args, extra...)
|
||||
}
|
||||
|
||||
func parseImport(t *testing.T, args ...string) *ImportConfig {
|
||||
t.Helper()
|
||||
c, err := ParseImport(args, &bytes.Buffer{})
|
||||
if err != nil {
|
||||
t.Fatalf("parse %v: %v", args, err)
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
func TestImportDefaults(t *testing.T) {
|
||||
c := parseImport(t, importArgs()...)
|
||||
if err := c.Validate(); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if c.Mode != "ignore" || c.Engine != "load" || c.Verify != "pre" || c.Workers != 1 {
|
||||
t.Fatalf("bad defaults: %+v", c)
|
||||
}
|
||||
if c.Charset != "utf8mb4" || c.Progress.Mode != ProgressAuto {
|
||||
t.Fatalf("bad defaults: %+v", c)
|
||||
}
|
||||
if len(c.Selectors) != 1 || c.Selectors[0].Kind != "all" {
|
||||
t.Fatalf("default selector = %+v", c.Selectors)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportRequired(t *testing.T) {
|
||||
c := parseImport(t, "--dest", "u:p@tcp(h:3306)/db")
|
||||
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "--file") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
c = parseImport(t, "--file", "archive")
|
||||
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "--dest") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
c = parseImport(t, "--file", "archive", "--dest", "u:p@tcp(h:3306)/")
|
||||
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "database name") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportRejectsExportFlags(t *testing.T) {
|
||||
for _, arg := range []string{"--source", "--where", "--purge", "--table", "--format", "--replace"} {
|
||||
_, err := ParseImport(append(importArgs(), arg, "x"), &bytes.Buffer{})
|
||||
if err == nil {
|
||||
t.Fatalf("%s: expected an error", arg)
|
||||
}
|
||||
if !strings.Contains(err.Error(), "archive (export) mode") {
|
||||
t.Fatalf("%s: got %v", arg, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportRejectsUnknownFlag(t *testing.T) {
|
||||
if _, err := ParseImport(append(importArgs(), "--bogus", "1"), &bytes.Buffer{}); err == nil {
|
||||
t.Fatal("expected unknown flag error")
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportInvalidValues(t *testing.T) {
|
||||
cases := []struct {
|
||||
extra []string
|
||||
want string
|
||||
}{
|
||||
{[]string{"--mode", "merge"}, "--mode"},
|
||||
{[]string{"--engine", "bulk"}, "--engine"},
|
||||
{[]string{"--verify", "after"}, "--verify"},
|
||||
{[]string{"--workers", "0"}, "--workers"},
|
||||
{[]string{"--charset", "utf8; drop"}, "--charset"},
|
||||
{[]string{"--select", "seq:5-2"}, "--select"},
|
||||
{[]string{"--select", "date:2025-01-31..2025-01-01"}, "--select"},
|
||||
{[]string{"--select", "bogus:1"}, "--select"},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
c := parseImport(t, importArgs(tc.extra...)...)
|
||||
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), tc.want) {
|
||||
t.Fatalf("%v: got %v", tc.extra, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportMappingConflict(t *testing.T) {
|
||||
c := parseImport(t, importArgs("--columns", "id,title", "--assume-all-columns")...)
|
||||
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportSelectAllCannotCombine(t *testing.T) {
|
||||
c := parseImport(t, importArgs("--select", "all", "--select", "seq:1-2")...)
|
||||
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "cannot be combined") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportRepeatedSelect(t *testing.T) {
|
||||
c := parseImport(t, importArgs("--select", "seq:1-2", "--select", "pk:10-20", "--select", "date:2025-01-01..2025-01-02")...)
|
||||
if err := c.Validate(); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(c.Selectors) != 3 || c.Selectors[0].Kind != "seq" || c.Selectors[1].Kind != "pk" || c.Selectors[2].Kind != "date" {
|
||||
t.Fatalf("selectors = %+v", c.Selectors)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImportUnexpectedPositional(t *testing.T) {
|
||||
if _, err := ParseImport(append(importArgs(), "stray"), &bytes.Buffer{}); err == nil {
|
||||
t.Fatal("expected an error for a positional argument")
|
||||
}
|
||||
}
|
||||
@@ -67,9 +67,6 @@ func (c *Config) Validate() error {
|
||||
if c.BulkDelete && !c.Purge {
|
||||
return cfgErr("--bulk-delete requires --purge")
|
||||
}
|
||||
if c.BulkDelete && c.ShardBy == "date" {
|
||||
return cfgErr("--bulk-delete cannot be used with --shard-by date; delete by IN list instead")
|
||||
}
|
||||
|
||||
switch c.Format {
|
||||
case "dump", "csv", "jsonl":
|
||||
|
||||
@@ -0,0 +1,214 @@
|
||||
// Package importer replays a dump archive into an existing MySQL table.
|
||||
//
|
||||
// The archive's manifest.jsonl is the only authority: files on disk that are
|
||||
// not registered are never imported, and unparseable manifest lines abort the
|
||||
// run before a database connection is opened. Each shard is a complete,
|
||||
// independently loadable file, so shards are the unit of selection, atomicity
|
||||
// and failure reporting.
|
||||
package importer
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"strings"
|
||||
|
||||
"archer/internal/archererr"
|
||||
"archer/internal/checkpoint"
|
||||
"archer/internal/shard"
|
||||
)
|
||||
|
||||
// Archive is a loaded, validated-by-reading view of an export directory.
|
||||
type Archive struct {
|
||||
Root string
|
||||
Entries []shard.Entry
|
||||
State *checkpoint.State
|
||||
Complete bool
|
||||
SourceTable string
|
||||
ArchivedColumns []string
|
||||
Format string
|
||||
Compress string
|
||||
Compressor *shard.Compressor
|
||||
}
|
||||
|
||||
// LoadArchive reads manifest.jsonl strictly and state.json when present. It
|
||||
// never writes to the archive directory.
|
||||
func LoadArchive(root string) (*Archive, error) {
|
||||
st, err := os.Stat(root)
|
||||
if err != nil {
|
||||
return nil, archererr.Newf(archererr.KindConfig, "--file %s: %v", root, err)
|
||||
}
|
||||
if !st.IsDir() {
|
||||
return nil, archererr.Newf(archererr.KindConfig, "--file %s is not a directory", root)
|
||||
}
|
||||
entries, err := shard.LoadManifest(root)
|
||||
if err != nil {
|
||||
return nil, archererr.Wrap(archererr.KindValidation, err)
|
||||
}
|
||||
state, err := checkpoint.Load(root)
|
||||
if err != nil {
|
||||
return nil, archererr.Wrap(archererr.KindValidation, err)
|
||||
}
|
||||
a := &Archive{Root: root, Entries: entries, State: state}
|
||||
if state != nil {
|
||||
a.Complete = state.Complete
|
||||
a.SourceTable = strings.TrimSpace(state.Config["table"])
|
||||
if cols := strings.TrimSpace(state.Config["columns"]); cols != "" {
|
||||
for _, part := range strings.Split(cols, ",") {
|
||||
if part = strings.TrimSpace(part); part != "" {
|
||||
a.ArchivedColumns = append(a.ArchivedColumns, part)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return a, nil
|
||||
}
|
||||
|
||||
// CheckComplete enforces the completion gate. A manifest only proves which
|
||||
// shards are sealed, not that the export covered the whole table, so an
|
||||
// incomplete archive is refused unless the operator opts in explicitly.
|
||||
func (a *Archive) CheckComplete(allowPartial bool) error {
|
||||
if allowPartial {
|
||||
return nil
|
||||
}
|
||||
if a.State == nil {
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"archive %s has no state.json; cannot confirm the export finished (pass --allow-partial to import its sealed shards)", a.Root)
|
||||
}
|
||||
if !a.State.Complete {
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"archive %s is incomplete; it may contain only part of the table (pass --allow-partial to import its sealed shards)", a.Root)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// CheckMappingChoice rejects an explicit mapping when the archive already
|
||||
// recorded its own column list: two sources of truth would silently disagree.
|
||||
func (a *Archive) CheckMappingChoice(columns []string, assumeAll bool) error {
|
||||
if len(a.ArchivedColumns) == 0 {
|
||||
return nil
|
||||
}
|
||||
if len(columns) > 0 {
|
||||
return archererr.Newf(archererr.KindConfig,
|
||||
"archive records its own column list (%s); --columns cannot be combined with it", strings.Join(a.ArchivedColumns, ", "))
|
||||
}
|
||||
if assumeAll {
|
||||
return archererr.Newf(archererr.KindConfig,
|
||||
"archive records its own column list (%s); --assume-all-columns cannot be combined with it", strings.Join(a.ArchivedColumns, ", "))
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
var shardFileRE = regexp.MustCompile(`^\d+\..*\.(dump|csv|jsonl)(\.gz|\.zst|\.xz)?$`)
|
||||
|
||||
// UnregisteredFiles counts shard-looking files that the manifest does not
|
||||
// list. They are ignored by design; the count is surfaced in --statistics so
|
||||
// they are not mistaken for imported data.
|
||||
func UnregisteredFiles(root string, entries []shard.Entry) int {
|
||||
registered := make(map[string]bool, len(entries))
|
||||
for _, e := range entries {
|
||||
registered[filepath.ToSlash(e.Path)] = true
|
||||
}
|
||||
n := 0
|
||||
_ = filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
|
||||
if err != nil || d.IsDir() {
|
||||
return nil
|
||||
}
|
||||
name := d.Name()
|
||||
if name == "manifest.jsonl" || name == "state.json" || strings.HasSuffix(name, ".partial") ||
|
||||
strings.HasSuffix(name, ".partial.meta") || !shardFileRE.MatchString(name) {
|
||||
return nil
|
||||
}
|
||||
rel, err := filepath.Rel(root, path)
|
||||
if err != nil {
|
||||
return nil
|
||||
}
|
||||
if !registered[filepath.ToSlash(rel)] {
|
||||
n++
|
||||
}
|
||||
return nil
|
||||
})
|
||||
return n
|
||||
}
|
||||
|
||||
// ShardFormat derives the output format and compression from a manifest path
|
||||
// such as 000003.100-200.dump.gz.
|
||||
func ShardFormat(p string) (format, compress string, err error) {
|
||||
name := filepath.Base(p)
|
||||
switch {
|
||||
case strings.HasSuffix(name, ".gz"):
|
||||
compress, name = "gzip", strings.TrimSuffix(name, ".gz")
|
||||
case strings.HasSuffix(name, ".zst"):
|
||||
compress, name = "zstd", strings.TrimSuffix(name, ".zst")
|
||||
case strings.HasSuffix(name, ".xz"):
|
||||
compress, name = "xz", strings.TrimSuffix(name, ".xz")
|
||||
default:
|
||||
compress = "none"
|
||||
}
|
||||
ext := strings.ToLower(filepath.Ext(name))
|
||||
if ext == "" {
|
||||
return "", "", fmt.Errorf("shard %s has no format extension", p)
|
||||
}
|
||||
format = strings.TrimPrefix(ext, ".")
|
||||
switch format {
|
||||
case "dump", "csv", "jsonl":
|
||||
return format, compress, nil
|
||||
default:
|
||||
return "", "", fmt.Errorf("shard %s has unknown format %q", p, format)
|
||||
}
|
||||
}
|
||||
|
||||
// ResolveFormat checks that every selected shard agrees on format and
|
||||
// compression, and that the format is dump (the only one v1 can replay).
|
||||
func ResolveFormat(entries []shard.Entry) (format, compress string, comp *shard.Compressor, err error) {
|
||||
for i, e := range entries {
|
||||
f, c, ferr := ShardFormat(e.Path)
|
||||
if ferr != nil {
|
||||
return "", "", nil, archererr.Wrap(archererr.KindValidation, ferr)
|
||||
}
|
||||
if i == 0 {
|
||||
format, compress = f, c
|
||||
continue
|
||||
}
|
||||
if f != format {
|
||||
return "", "", nil, archererr.Newf(archererr.KindValidation,
|
||||
"selected shards mix formats: %s is %s but %s is %s", entries[0].Path, format, e.Path, f)
|
||||
}
|
||||
if c != compress {
|
||||
return "", "", nil, archererr.Newf(archererr.KindValidation,
|
||||
"selected shards mix compression: %s is %s but %s is %s", entries[0].Path, compress, e.Path, c)
|
||||
}
|
||||
}
|
||||
if format != "dump" {
|
||||
return "", "", nil, archererr.Newf(archererr.KindValidation,
|
||||
"import supports only dump archives; the selected shards are %s", format)
|
||||
}
|
||||
comp, err = shard.NewCompressor(compress, shard.DefaultLevel)
|
||||
if err != nil {
|
||||
return "", "", nil, archererr.Wrap(archererr.KindValidation, err)
|
||||
}
|
||||
return format, compress, comp, nil
|
||||
}
|
||||
|
||||
// CheckShardFiles verifies every selected manifest entry has a readable file
|
||||
// before any connection is opened.
|
||||
func CheckShardFiles(root string, entries []shard.Entry) error {
|
||||
for _, e := range entries {
|
||||
path := filepath.Join(root, filepath.FromSlash(e.Path))
|
||||
st, err := os.Stat(path)
|
||||
if err != nil {
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"manifest entry seq %d points to missing shard %s: %v", e.Seq, e.Path, err)
|
||||
}
|
||||
if st.IsDir() {
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"manifest entry seq %d points to a directory, not a shard: %s", e.Seq, e.Path)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func shardPath(root string, e shard.Entry) string {
|
||||
return filepath.Join(root, filepath.FromSlash(e.Path))
|
||||
}
|
||||
@@ -0,0 +1,211 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"archer/internal/checkpoint"
|
||||
"archer/internal/shard"
|
||||
)
|
||||
|
||||
func writeManifest(t *testing.T, root string, entries []shard.Entry) {
|
||||
t.Helper()
|
||||
var b strings.Builder
|
||||
for _, e := range entries {
|
||||
j, err := json.Marshal(e)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
b.Write(j)
|
||||
b.WriteByte('\n')
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(root, "manifest.jsonl"), []byte(b.String()), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func writeShard(t *testing.T, root, rel, body string) {
|
||||
t.Helper()
|
||||
path := filepath.Join(root, filepath.FromSlash(rel))
|
||||
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func saveState(t *testing.T, root string, complete bool, config map[string]string) {
|
||||
t.Helper()
|
||||
if err := checkpoint.Save(root, &checkpoint.State{Complete: complete, Config: config}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadArchiveReadsStateAndRecords(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
entries := []shard.Entry{{Seq: 1, Path: "000001.1-1.dump", PKLo: "1", PKHi: "1", Rows: 1, Bytes: 3, SHA256: "aa"}}
|
||||
writeManifest(t, root, entries)
|
||||
writeShard(t, root, entries[0].Path, "1\tx\n")
|
||||
saveState(t, root, true, map[string]string{"table": "orders", "columns": "id,title"})
|
||||
|
||||
a, err := LoadArchive(root)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !a.Complete || a.SourceTable != "orders" {
|
||||
t.Fatalf("archive = %+v", a)
|
||||
}
|
||||
if strings.Join(a.ArchivedColumns, ",") != "id,title" {
|
||||
t.Fatalf("columns = %v", a.ArchivedColumns)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadArchiveRejectsCorruptManifest(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
if err := os.WriteFile(filepath.Join(root, "manifest.jsonl"), []byte("{not json\n"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
_, err := LoadArchive(root)
|
||||
if err == nil || !strings.Contains(err.Error(), "line 1") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadArchiveMissingManifest(t *testing.T) {
|
||||
_, err := LoadArchive(t.TempDir())
|
||||
if err == nil || !strings.Contains(err.Error(), "manifest") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadArchiveNotADirectory(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "file")
|
||||
if err := os.WriteFile(path, []byte("x"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := LoadArchive(path); err == nil {
|
||||
t.Fatal("expected an error")
|
||||
}
|
||||
}
|
||||
|
||||
func TestCompletionGate(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeManifest(t, root, []shard.Entry{{Seq: 1, Path: "000001.1-1.dump"}})
|
||||
|
||||
a, err := LoadArchive(root)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := a.CheckComplete(false); err == nil || !strings.Contains(err.Error(), "state.json") {
|
||||
t.Fatalf("missing state: %v", err)
|
||||
}
|
||||
if err := a.CheckComplete(true); err != nil {
|
||||
t.Fatalf("--allow-partial: %v", err)
|
||||
}
|
||||
|
||||
saveState(t, root, false, nil)
|
||||
a, _ = LoadArchive(root)
|
||||
if err := a.CheckComplete(false); err == nil || !strings.Contains(err.Error(), "incomplete") {
|
||||
t.Fatalf("incomplete: %v", err)
|
||||
}
|
||||
if err := a.CheckComplete(true); err != nil {
|
||||
t.Fatalf("--allow-partial: %v", err)
|
||||
}
|
||||
|
||||
saveState(t, root, true, nil)
|
||||
a, _ = LoadArchive(root)
|
||||
if err := a.CheckComplete(false); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingChoiceConflict(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeManifest(t, root, []shard.Entry{{Seq: 1, Path: "000001.1-1.dump"}})
|
||||
saveState(t, root, true, map[string]string{"columns": "id,title"})
|
||||
a, _ := LoadArchive(root)
|
||||
if err := a.CheckMappingChoice([]string{"id"}, false); err == nil || !strings.Contains(err.Error(), "--columns") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
if err := a.CheckMappingChoice(nil, true); err == nil || !strings.Contains(err.Error(), "--assume-all-columns") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
if err := a.CheckMappingChoice(nil, false); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCheckShardFiles(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeShard(t, root, "a/000001.1-1.dump", "1\n")
|
||||
ok := []shard.Entry{{Seq: 1, Path: "a/000001.1-1.dump"}}
|
||||
if err := CheckShardFiles(root, ok); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
missing := []shard.Entry{{Seq: 7, Path: "a/000007.1-1.dump"}}
|
||||
if err := CheckShardFiles(root, missing); err == nil || !strings.Contains(err.Error(), "seq 7") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveFormat(t *testing.T) {
|
||||
dump := []shard.Entry{{Seq: 1, Path: "000001.1-1.dump"}, {Seq: 2, Path: "000002.2-2.dump.gz"}}
|
||||
if _, _, _, err := ResolveFormat(dump); err == nil || !strings.Contains(err.Error(), "mix compression") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
|
||||
gz := []shard.Entry{{Seq: 1, Path: "000001.1-1.dump.gz"}, {Seq: 2, Path: "000002.2-2.dump.gz"}}
|
||||
format, compress, comp, err := ResolveFormat(gz)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if format != "dump" || compress != "gzip" || comp.Name != "gzip" {
|
||||
t.Fatalf("format=%s compress=%s comp=%+v", format, compress, comp)
|
||||
}
|
||||
|
||||
for _, bad := range []string{"000001.1-1.csv", "000001.1-1.jsonl", "000001.1-1.csv.gz"} {
|
||||
_, _, _, err := ResolveFormat([]shard.Entry{{Seq: 1, Path: bad}})
|
||||
if err == nil || !strings.Contains(err.Error(), "only dump") {
|
||||
t.Fatalf("%s: got %v", bad, err)
|
||||
}
|
||||
}
|
||||
|
||||
mixed := []shard.Entry{{Seq: 1, Path: "a/000001.1-1.dump"}, {Seq: 2, Path: "b/000002.2-2.csv"}}
|
||||
if _, _, _, err := ResolveFormat(mixed); err == nil || !strings.Contains(err.Error(), "mix formats") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestShardFormat(t *testing.T) {
|
||||
for _, tc := range []struct{ path, format, compress string }{
|
||||
{"000001.1-2.dump", "dump", "none"},
|
||||
{"000001.1-2.dump.gz", "dump", "gzip"},
|
||||
{"000001.1-2.dump.zst", "dump", "zstd"},
|
||||
{"000001.1-2.dump.xz", "dump", "xz"},
|
||||
{"date=2025-01-01/000001.1-2.jsonl", "jsonl", "none"},
|
||||
} {
|
||||
f, c, err := ShardFormat(tc.path)
|
||||
if err != nil || f != tc.format || c != tc.compress {
|
||||
t.Fatalf("%s: f=%s c=%s err=%v", tc.path, f, c, err)
|
||||
}
|
||||
}
|
||||
if _, _, err := ShardFormat("000001.1-2"); err == nil {
|
||||
t.Fatal("expected an error for a missing extension")
|
||||
}
|
||||
}
|
||||
|
||||
func TestUnregisteredFiles(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
entries := []shard.Entry{{Seq: 1, Path: "000001.1-1.dump"}}
|
||||
writeManifest(t, root, entries)
|
||||
writeShard(t, root, "000001.1-1.dump", "1\n")
|
||||
writeShard(t, root, "000002.2-2.dump", "2\n")
|
||||
writeShard(t, root, "notes.txt", "ignored")
|
||||
if got := UnregisteredFiles(root, entries); got != 1 {
|
||||
t.Fatalf("got %d", got)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,163 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"bytes"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"strings"
|
||||
|
||||
"archer/internal/archererr"
|
||||
"archer/internal/schema"
|
||||
"archer/internal/shard"
|
||||
"archer/internal/sqlutil"
|
||||
)
|
||||
|
||||
// Mapping translates file fields to target columns. It is the single place
|
||||
// that decides whether a field is loaded into a named column or discarded into
|
||||
// a user variable (generated columns under positional mapping).
|
||||
type Mapping struct {
|
||||
// FileColumns has one entry per file field: the canonical target column
|
||||
// name, or "" when the field is intentionally discarded.
|
||||
FileColumns []string
|
||||
// InsertColumns and InsertFieldIdx describe the parameterized INSERT used
|
||||
// by the insert engine. InsertFieldIdx points into FileColumns.
|
||||
InsertColumns []string
|
||||
InsertFieldIdx []int
|
||||
// LoadList is the LOAD DATA column list: quoted identifiers and
|
||||
// @_archer_skip_N variables.
|
||||
LoadList []string
|
||||
// Positional is true for --assume-all-columns; callers must warn.
|
||||
Positional bool
|
||||
}
|
||||
|
||||
// BuildMapping resolves the three permitted mapping sources. Columns recorded
|
||||
// in the archive win over an explicit --columns by construction (the conflict
|
||||
// is rejected earlier); assumeAll is only consulted when neither list exists.
|
||||
func BuildMapping(table *schema.Table, archived, explicit []string, assumeAll bool) (*Mapping, error) {
|
||||
return buildMapping(table.Name, table.Columns, archived, explicit, assumeAll)
|
||||
}
|
||||
|
||||
func buildMapping(tableName string, columns []schema.Column, archived, explicit []string, assumeAll bool) (*Mapping, error) {
|
||||
names := archived
|
||||
if len(names) == 0 {
|
||||
names = explicit
|
||||
}
|
||||
switch {
|
||||
case len(names) > 0:
|
||||
return mappingByName(tableName, columns, names)
|
||||
case assumeAll:
|
||||
return mappingPositional(tableName, columns)
|
||||
default:
|
||||
return nil, archererr.Newf(archererr.KindConfig,
|
||||
"the archive did not record a column list; provide --columns in file field order or accept positional mapping with --assume-all-columns")
|
||||
}
|
||||
}
|
||||
|
||||
func mappingByName(tableName string, columns []schema.Column, names []string) (*Mapping, error) {
|
||||
byName := make(map[string]schema.Column, len(columns))
|
||||
for _, c := range columns {
|
||||
byName[strings.ToLower(c.Name)] = c
|
||||
}
|
||||
m := &Mapping{}
|
||||
seen := map[string]bool{}
|
||||
for _, requested := range names {
|
||||
col, ok := byName[strings.ToLower(requested)]
|
||||
if !ok {
|
||||
return nil, archererr.Newf(archererr.KindValidation,
|
||||
"column %q from the file field mapping does not exist in target table %s", requested, tableName)
|
||||
}
|
||||
if isGenerated(col) {
|
||||
return nil, archererr.Newf(archererr.KindValidation,
|
||||
"column %q is a generated column and cannot be written from an archive", col.Name)
|
||||
}
|
||||
if seen[col.Name] {
|
||||
return nil, archererr.Newf(archererr.KindValidation,
|
||||
"column %q appears more than once in the file field mapping", col.Name)
|
||||
}
|
||||
seen[col.Name] = true
|
||||
idx := len(m.FileColumns)
|
||||
m.FileColumns = append(m.FileColumns, col.Name)
|
||||
m.InsertColumns = append(m.InsertColumns, col.Name)
|
||||
m.InsertFieldIdx = append(m.InsertFieldIdx, idx)
|
||||
m.LoadList = append(m.LoadList, sqlutil.Ident(col.Name))
|
||||
}
|
||||
return m, nil
|
||||
}
|
||||
|
||||
func mappingPositional(tableName string, columns []schema.Column) (*Mapping, error) {
|
||||
m := &Mapping{Positional: true}
|
||||
for i, col := range columns {
|
||||
if isGenerated(col) {
|
||||
// The file still contains this field, so keep a placeholder and
|
||||
// discard the value; the target table recomputes it.
|
||||
m.FileColumns = append(m.FileColumns, "")
|
||||
m.LoadList = append(m.LoadList, fmt.Sprintf("@_archer_skip_%d", col.Ordinal))
|
||||
continue
|
||||
}
|
||||
m.FileColumns = append(m.FileColumns, col.Name)
|
||||
m.InsertColumns = append(m.InsertColumns, col.Name)
|
||||
m.InsertFieldIdx = append(m.InsertFieldIdx, i)
|
||||
m.LoadList = append(m.LoadList, sqlutil.Ident(col.Name))
|
||||
}
|
||||
if len(m.InsertColumns) == 0 {
|
||||
return nil, archererr.Newf(archererr.KindValidation,
|
||||
"target table %s has no writable columns", tableName)
|
||||
}
|
||||
return m, nil
|
||||
}
|
||||
|
||||
func isGenerated(c schema.Column) bool {
|
||||
return strings.Contains(strings.ToLower(c.Extra), "generated")
|
||||
}
|
||||
|
||||
// CountFields counts dump fields in one raw line. Literal tabs are escaped by
|
||||
// the dump encoder, so every 0x09 byte is a separator. An empty line is a
|
||||
// single empty, non-NULL field.
|
||||
func CountFields(line []byte) int {
|
||||
return strings.Count(string(line), "\t") + 1
|
||||
}
|
||||
|
||||
// FirstLineFieldCount reads the first decompressed line of a shard.
|
||||
func FirstLineFieldCount(path string, comp *shard.Compressor) (fields int, hasRow bool, err error) {
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return 0, false, err
|
||||
}
|
||||
defer f.Close()
|
||||
r, err := comp.Reader(f)
|
||||
if err != nil {
|
||||
return 0, false, err
|
||||
}
|
||||
defer r.Close()
|
||||
br := bufio.NewReaderSize(r, 64*1024)
|
||||
line, err := br.ReadBytes('\n')
|
||||
if err == io.EOF {
|
||||
if len(line) == 0 {
|
||||
return 0, false, nil
|
||||
}
|
||||
} else if err != nil {
|
||||
return 0, false, err
|
||||
}
|
||||
line = bytes.TrimSuffix(line, []byte{'\n'})
|
||||
return CountFields(line), true, nil
|
||||
}
|
||||
|
||||
// CheckFieldCount compares the first row's field count with the load list
|
||||
// length. It is a sanity check only: it cannot prove that same-width columns
|
||||
// are in the right order.
|
||||
func CheckFieldCount(path string, comp *shard.Compressor, want int) error {
|
||||
got, hasRow, err := FirstLineFieldCount(path, comp)
|
||||
if err != nil {
|
||||
return archererr.Wrap(archererr.KindValidation, fmt.Errorf("read first row of %s: %w", path, err))
|
||||
}
|
||||
if !hasRow {
|
||||
return nil
|
||||
}
|
||||
if got != want {
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"first row of %s has %d fields, but the load column list has %d; refusing to load", path, got, want)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,151 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"archer/internal/schema"
|
||||
"archer/internal/shard"
|
||||
)
|
||||
|
||||
func targetColumns() []schema.Column {
|
||||
return []schema.Column{
|
||||
{Name: "id", Ordinal: 1},
|
||||
{Name: "title", Ordinal: 2},
|
||||
{Name: "full_name", Ordinal: 3, Extra: "STORED GENERATED"},
|
||||
{Name: "created_at", Ordinal: 4},
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingByNamePreservesOrder(t *testing.T) {
|
||||
m, err := buildMapping("orders", targetColumns(), []string{"title", "ID"}, nil, false)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if strings.Join(m.FileColumns, ",") != "title,id" {
|
||||
t.Fatalf("file columns = %v", m.FileColumns)
|
||||
}
|
||||
if strings.Join(m.InsertColumns, ",") != "title,id" {
|
||||
t.Fatalf("insert columns = %v", m.InsertColumns)
|
||||
}
|
||||
if strings.Join(m.LoadList, ",") != "`title`,`id`" {
|
||||
t.Fatalf("load list = %v", m.LoadList)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingByNameMissingColumn(t *testing.T) {
|
||||
_, err := buildMapping("orders", targetColumns(), []string{"id", "missing"}, nil, false)
|
||||
if err == nil || !strings.Contains(err.Error(), "missing") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingByNameRejectsGenerated(t *testing.T) {
|
||||
_, err := buildMapping("orders", targetColumns(), []string{"id", "full_name"}, nil, false)
|
||||
if err == nil || !strings.Contains(err.Error(), "generated") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingByNameRejectsDuplicate(t *testing.T) {
|
||||
_, err := buildMapping("orders", targetColumns(), []string{"id", "Id"}, nil, false)
|
||||
if err == nil || !strings.Contains(err.Error(), "more than once") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingPositionalDropsGenerated(t *testing.T) {
|
||||
m, err := buildMapping("orders", targetColumns(), nil, nil, true)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !m.Positional {
|
||||
t.Fatal("expected positional mapping")
|
||||
}
|
||||
if len(m.FileColumns) != 4 {
|
||||
t.Fatalf("file fields = %v", m.FileColumns)
|
||||
}
|
||||
if m.FileColumns[2] != "" {
|
||||
t.Fatalf("generated field should be empty, got %q", m.FileColumns[2])
|
||||
}
|
||||
if strings.Join(m.InsertColumns, ",") != "id,title,created_at" {
|
||||
t.Fatalf("insert columns = %v", m.InsertColumns)
|
||||
}
|
||||
if len(m.InsertFieldIdx) != 3 || m.InsertFieldIdx[2] != 3 {
|
||||
t.Fatalf("insert indices = %v", m.InsertFieldIdx)
|
||||
}
|
||||
if m.LoadList[2] != "@_archer_skip_3" {
|
||||
t.Fatalf("skip variable = %q", m.LoadList[2])
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingRequiresSource(t *testing.T) {
|
||||
_, err := buildMapping("orders", targetColumns(), nil, nil, false)
|
||||
if err == nil || !strings.Contains(err.Error(), "--assume-all-columns") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMappingExplicitColumns(t *testing.T) {
|
||||
m, err := buildMapping("orders", targetColumns(), nil, []string{"id", "title"}, false)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(m.FileColumns) != 2 || m.FileColumns[1] != "title" {
|
||||
t.Fatalf("file columns = %v", m.FileColumns)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCountFields(t *testing.T) {
|
||||
cases := []struct {
|
||||
line string
|
||||
want int
|
||||
}{
|
||||
{"", 1},
|
||||
{"a", 1},
|
||||
{"a\tb", 2},
|
||||
{"a\tb\tc\t", 4},
|
||||
{`a\tb`, 1}, // escaped tab is not a separator
|
||||
}
|
||||
for _, tc := range cases {
|
||||
if got := CountFields([]byte(tc.line)); got != tc.want {
|
||||
t.Fatalf("%q: got %d want %d", tc.line, got, tc.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestFirstLineFieldCount(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
path := filepath.Join(root, "x.dump")
|
||||
if err := os.WriteFile(path, []byte("a\tb\tc\n1\t2\t3\n"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
comp, _ := shard.NewCompressor("none", shard.DefaultLevel)
|
||||
n, ok, err := FirstLineFieldCount(path, comp)
|
||||
if err != nil || !ok || n != 3 {
|
||||
t.Fatalf("n=%d ok=%t err=%v", n, ok, err)
|
||||
}
|
||||
if err := CheckFieldCount(path, comp, 3); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := CheckFieldCount(path, comp, 4); err == nil || !strings.Contains(err.Error(), "3 fields") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFirstLineFieldCountEmptyFile(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "empty.dump")
|
||||
if err := os.WriteFile(path, nil, 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
comp, _ := shard.NewCompressor("none", shard.DefaultLevel)
|
||||
_, ok, err := FirstLineFieldCount(path, comp)
|
||||
if err != nil || ok {
|
||||
t.Fatalf("ok=%t err=%v", ok, err)
|
||||
}
|
||||
if err := CheckFieldCount(path, comp, 9); err != nil {
|
||||
t.Fatalf("empty shard must not fail the field check: %v", err)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"bytes"
|
||||
"io"
|
||||
|
||||
"archer/internal/row"
|
||||
)
|
||||
|
||||
// DumpReader decodes the dump format produced by internal/row.dumpEncoder:
|
||||
// TAB-separated fields, LF-terminated rows, \N for NULL and the MySQL escape
|
||||
// table. It exists for the insert fallback engine; the load engine hands the
|
||||
// bytes to the server unchanged.
|
||||
type DumpReader struct {
|
||||
br *bufio.Reader
|
||||
}
|
||||
|
||||
func NewDumpReader(r io.Reader) *DumpReader {
|
||||
return &DumpReader{br: bufio.NewReaderSize(r, 256*1024)}
|
||||
}
|
||||
|
||||
// ReadRow returns the next row. It returns io.EOF exactly when the stream ends.
|
||||
func (d *DumpReader) ReadRow() (row.Row, error) {
|
||||
line, err := d.br.ReadBytes('\n')
|
||||
if len(line) == 0 && err == io.EOF {
|
||||
return row.Row{}, io.EOF
|
||||
}
|
||||
if err != nil && err != io.EOF {
|
||||
return row.Row{}, err
|
||||
}
|
||||
line = bytes.TrimSuffix(line, []byte{'\n'})
|
||||
fields := bytes.Split(line, []byte{'\t'})
|
||||
out := row.Row{Values: make([]row.Value, len(fields))}
|
||||
for i, f := range fields {
|
||||
out.Values[i] = unescapeField(f)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// unescapeField mirrors MySQL's LOAD DATA escape handling. A field is NULL only
|
||||
// when it is exactly \N; unknown escapes yield the escaped character, matching
|
||||
// the server's default FIELDS ESCAPED BY '\\' behavior.
|
||||
func unescapeField(f []byte) row.Value {
|
||||
if len(f) == 2 && f[0] == '\\' && f[1] == 'N' {
|
||||
return row.Value{}
|
||||
}
|
||||
if bytes.IndexByte(f, '\\') < 0 {
|
||||
return row.Value{Raw: append([]byte{}, f...)}
|
||||
}
|
||||
out := make([]byte, 0, len(f))
|
||||
for i := 0; i < len(f); i++ {
|
||||
if f[i] != '\\' {
|
||||
out = append(out, f[i])
|
||||
continue
|
||||
}
|
||||
if i+1 >= len(f) {
|
||||
out = append(out, '\\')
|
||||
break
|
||||
}
|
||||
i++
|
||||
switch f[i] {
|
||||
case '\\':
|
||||
out = append(out, '\\')
|
||||
case 't':
|
||||
out = append(out, '\t')
|
||||
case 'n':
|
||||
out = append(out, '\n')
|
||||
case 'r':
|
||||
out = append(out, '\r')
|
||||
case '0':
|
||||
out = append(out, 0)
|
||||
case 'b':
|
||||
out = append(out, '\b')
|
||||
case 'Z':
|
||||
out = append(out, 0x1a)
|
||||
default:
|
||||
// Includes \N in a mixed field: only a whole-field \N is NULL.
|
||||
out = append(out, f[i])
|
||||
}
|
||||
}
|
||||
return row.Value{Raw: out}
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"io"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"archer/internal/row"
|
||||
)
|
||||
|
||||
func TestDumpReaderEmptyFieldAndNull(t *testing.T) {
|
||||
input := "a\t\\N\t\tx\\Ny\n"
|
||||
dr := NewDumpReader(strings.NewReader(input))
|
||||
got, err := dr.ReadRow()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(got.Values) != 4 {
|
||||
t.Fatalf("got %d fields", len(got.Values))
|
||||
}
|
||||
if got.Values[0].IsNull() || got.Values[0].String() != "a" {
|
||||
t.Fatalf("field 0 = %+v", got.Values[0])
|
||||
}
|
||||
if !got.Values[1].IsNull() {
|
||||
t.Fatalf("field 1 should be NULL")
|
||||
}
|
||||
if got.Values[2].IsNull() || len(got.Values[2].Raw) != 0 {
|
||||
t.Fatalf("field 2 should be an empty string, got %+v", got.Values[2])
|
||||
}
|
||||
if got.Values[3].String() != "xNy" {
|
||||
t.Fatalf("\\N inside a field should yield N, got %q", got.Values[3].String())
|
||||
}
|
||||
if _, err := dr.ReadRow(); err != io.EOF {
|
||||
t.Fatalf("expected EOF, got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDumpReaderEscapeTable(t *testing.T) {
|
||||
input := "a\t\\N\t\t\\t\\n\\r\\0\\b\\Z\\\\\t中文😀\n"
|
||||
dr := NewDumpReader(strings.NewReader(input))
|
||||
got, err := dr.ReadRow()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(got.Values) != 5 {
|
||||
t.Fatalf("got %d fields: %+v", len(got.Values), got.Values)
|
||||
}
|
||||
want := []byte{'\t', '\n', '\r', 0, '\b', 0x1a, '\\'}
|
||||
if !bytes.Equal(got.Values[3].Raw, want) {
|
||||
t.Fatalf("escapes = %q, want %q", got.Values[3].Raw, want)
|
||||
}
|
||||
if got.Values[4].String() != "中文😀" {
|
||||
t.Fatalf("unicode = %q", got.Values[4].String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestDumpReaderRoundTripWithEncoder(t *testing.T) {
|
||||
cols := []row.Column{{Name: "a"}, {Name: "b"}, {Name: "c"}}
|
||||
enc, err := row.NewEncoder("dump", cols, []int{0, 1, 2}, row.Options{})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
rows := []row.Row{
|
||||
{Values: []row.Value{{Raw: []byte("")}, {}, {Raw: []byte{0, 1, 2, 255}}}},
|
||||
{Values: []row.Value{{Raw: []byte("tab\there")}, {Raw: []byte("line\nbreak")}, {Raw: []byte("back\\slash")}}},
|
||||
{Values: []row.Value{{Raw: []byte("中文")}, {Raw: []byte("😀")}, {Raw: []byte("")}}},
|
||||
}
|
||||
var buf bytes.Buffer
|
||||
for _, r := range rows {
|
||||
b, err := enc.Encode(nil, r)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
buf.Write(b)
|
||||
}
|
||||
dr := NewDumpReader(&buf)
|
||||
for i, want := range rows {
|
||||
got, err := dr.ReadRow()
|
||||
if err != nil {
|
||||
t.Fatalf("row %d: %v", i, err)
|
||||
}
|
||||
if len(got.Values) != len(want.Values) {
|
||||
t.Fatalf("row %d: %d fields", i, len(got.Values))
|
||||
}
|
||||
for j := range want.Values {
|
||||
w, g := want.Values[j], got.Values[j]
|
||||
if w.IsNull() != g.IsNull() || !bytes.Equal(w.Raw, g.Raw) {
|
||||
t.Fatalf("row %d field %d: got %+v want %+v", i, j, g, w)
|
||||
}
|
||||
}
|
||||
}
|
||||
if _, err := dr.ReadRow(); err != io.EOF {
|
||||
t.Fatalf("expected EOF, got %v", err)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,214 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"sync/atomic"
|
||||
|
||||
"github.com/go-sql-driver/mysql"
|
||||
|
||||
"archer/internal/archererr"
|
||||
"archer/internal/cli"
|
||||
"archer/internal/row"
|
||||
"archer/internal/shard"
|
||||
"archer/internal/sink"
|
||||
)
|
||||
|
||||
// insertBatchRows bounds the decoder's memory independently of
|
||||
// max_allowed_packet; sink.DB still splits each batch by packet size.
|
||||
const insertBatchRows = 1000
|
||||
|
||||
type worker struct {
|
||||
conn *sql.Conn
|
||||
sink *sink.DB
|
||||
cfg *cli.ImportConfig
|
||||
archive *Archive
|
||||
mapping *Mapping
|
||||
dbName string
|
||||
}
|
||||
|
||||
func newWorker(ctx context.Context, db *sql.DB, cfg *cli.ImportConfig, archive *Archive, mapping *Mapping, dbName string) (*worker, error) {
|
||||
conn, err := db.Conn(ctx)
|
||||
if err != nil {
|
||||
return nil, archererr.Wrap(archererr.KindConnection, fmt.Errorf("acquire connection: %w", err))
|
||||
}
|
||||
if err := SetSession(ctx, conn, cfg.Charset, cfg.TimeZone); err != nil {
|
||||
conn.Close()
|
||||
return nil, err
|
||||
}
|
||||
w := &worker{conn: conn, cfg: cfg, archive: archive, mapping: mapping, dbName: dbName}
|
||||
if cfg.Engine == "insert" {
|
||||
s, err := sink.NewDB(ctx, db, dbName, cfg.DestTable, mapping.InsertColumns, cfg.Mode, mapping.InsertFieldIdx)
|
||||
if err != nil {
|
||||
conn.Close()
|
||||
return nil, archererr.Wrap(archererr.KindValidation, err)
|
||||
}
|
||||
w.sink = s
|
||||
}
|
||||
return w, nil
|
||||
}
|
||||
|
||||
func (w *worker) close() {
|
||||
if w.conn != nil {
|
||||
_ = w.conn.Close()
|
||||
}
|
||||
}
|
||||
|
||||
// importShard loads one shard and returns affected rows plus, for ignore mode,
|
||||
// the number of rows the server skipped.
|
||||
func (w *worker) importShard(ctx context.Context, e shard.Entry) (affected, skipped int64, err error) {
|
||||
path := shardPath(w.archive.Root, e)
|
||||
if w.cfg.Verify == "pre" {
|
||||
if err := VerifyShard(path, e); err != nil {
|
||||
return 0, 0, err
|
||||
}
|
||||
}
|
||||
if w.cfg.Engine == "insert" {
|
||||
return w.insertShard(ctx, e, path)
|
||||
}
|
||||
return w.loadShard(ctx, e, path)
|
||||
}
|
||||
|
||||
func (w *worker) loadShard(ctx context.Context, e shard.Entry, path string) (int64, int64, error) {
|
||||
name := newReaderName(e.Seq)
|
||||
mysql.RegisterReaderHandler(name, func() io.Reader {
|
||||
return openShardReader(path, w.archive.Compressor)
|
||||
})
|
||||
defer mysql.DeregisterReaderHandler(name)
|
||||
|
||||
q := BuildLoadSQL(w.dbName, w.cfg.DestTable, w.cfg.Charset, w.mapping, w.cfg.Mode, name)
|
||||
res, err := w.conn.ExecContext(ctx, q)
|
||||
if err != nil {
|
||||
return 0, 0, archererr.Wrap(archererr.KindWrite, fmt.Errorf("shard %d: LOAD DATA: %w", e.Seq, err))
|
||||
}
|
||||
affected, _ := res.RowsAffected()
|
||||
if err := w.checkWarnings(ctx, e.Seq); err != nil {
|
||||
return affected, 0, err
|
||||
}
|
||||
skipped, err := CheckRowRule(w.cfg.Mode, e.Rows, affected)
|
||||
if err != nil {
|
||||
return affected, 0, fmt.Errorf("shard %d: %w", e.Seq, err)
|
||||
}
|
||||
return affected, skipped, nil
|
||||
}
|
||||
|
||||
func (w *worker) insertShard(ctx context.Context, e shard.Entry, path string) (int64, int64, error) {
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return 0, 0, archererr.Wrap(archererr.KindValidation, fmt.Errorf("shard %d: open: %w", e.Seq, err))
|
||||
}
|
||||
defer f.Close()
|
||||
r, err := w.archive.Compressor.Reader(f)
|
||||
if err != nil {
|
||||
return 0, 0, archererr.Wrap(archererr.KindValidation, fmt.Errorf("shard %d: decompress: %w", e.Seq, err))
|
||||
}
|
||||
defer r.Close()
|
||||
|
||||
tx, err := w.conn.BeginTx(ctx, nil)
|
||||
if err != nil {
|
||||
return 0, 0, archererr.Wrap(archererr.KindWrite, fmt.Errorf("shard %d: begin transaction: %w", e.Seq, err))
|
||||
}
|
||||
committed := false
|
||||
defer func() {
|
||||
if !committed {
|
||||
_ = tx.Rollback()
|
||||
}
|
||||
}()
|
||||
|
||||
dr := NewDumpReader(r)
|
||||
chunk := &row.Chunk{}
|
||||
var affected int64
|
||||
flush := func() error {
|
||||
if len(chunk.Rows) == 0 {
|
||||
return nil
|
||||
}
|
||||
n, err := w.sink.InsertChunk(ctx, tx, chunk)
|
||||
if err != nil {
|
||||
return archererr.Wrap(archererr.KindWrite, fmt.Errorf("shard %d: %w", e.Seq, err))
|
||||
}
|
||||
affected += n
|
||||
chunk = &row.Chunk{}
|
||||
return w.checkWarnings(ctx, e.Seq)
|
||||
}
|
||||
|
||||
for {
|
||||
rw, err := dr.ReadRow()
|
||||
if err == io.EOF {
|
||||
break
|
||||
}
|
||||
if err != nil {
|
||||
return affected, 0, archererr.Wrap(archererr.KindValidation, fmt.Errorf("shard %d: decode: %w", e.Seq, err))
|
||||
}
|
||||
if len(rw.Values) != len(w.mapping.FileColumns) {
|
||||
return affected, 0, archererr.Newf(archererr.KindValidation,
|
||||
"shard %d: row has %d fields but the mapping expects %d", e.Seq, len(rw.Values), len(w.mapping.FileColumns))
|
||||
}
|
||||
chunk.Rows = append(chunk.Rows, rw)
|
||||
if len(chunk.Rows) >= insertBatchRows {
|
||||
if err := flush(); err != nil {
|
||||
return affected, 0, err
|
||||
}
|
||||
}
|
||||
}
|
||||
if err := flush(); err != nil {
|
||||
return affected, 0, err
|
||||
}
|
||||
skipped, err := CheckRowRule(w.cfg.Mode, e.Rows, affected)
|
||||
if err != nil {
|
||||
return affected, 0, fmt.Errorf("shard %d: %w", e.Seq, err)
|
||||
}
|
||||
if err := tx.Commit(); err != nil {
|
||||
return affected, 0, archererr.Wrap(archererr.KindWrite, fmt.Errorf("shard %d: commit: %w", e.Seq, err))
|
||||
}
|
||||
committed = true
|
||||
return affected, skipped, nil
|
||||
}
|
||||
|
||||
func (w *worker) checkWarnings(ctx context.Context, seq int64) error {
|
||||
warnings, err := ShowWarnings(ctx, w.conn)
|
||||
if err != nil {
|
||||
return archererr.Wrap(archererr.KindWrite, fmt.Errorf("shard %d: SHOW WARNINGS: %w", seq, err))
|
||||
}
|
||||
return CheckWarnings(warnings, w.cfg.AllowWarnings, w.cfg.Mode, seq)
|
||||
}
|
||||
|
||||
var readerCounter atomic.Uint64
|
||||
|
||||
func newReaderName(seq int64) string {
|
||||
return fmt.Sprintf("archer-import-%d-%d-%d", os.Getpid(), seq, readerCounter.Add(1))
|
||||
}
|
||||
|
||||
type errReader struct{ err error }
|
||||
|
||||
func (e errReader) Read([]byte) (int, error) { return 0, e.err }
|
||||
|
||||
type readCloserPair struct {
|
||||
r io.ReadCloser
|
||||
f *os.File
|
||||
}
|
||||
|
||||
func (p *readCloserPair) Read(b []byte) (int, error) { return p.r.Read(b) }
|
||||
|
||||
func (p *readCloserPair) Close() error {
|
||||
err := p.r.Close()
|
||||
if ferr := p.f.Close(); err == nil {
|
||||
err = ferr
|
||||
}
|
||||
return err
|
||||
}
|
||||
|
||||
func openShardReader(path string, comp *shard.Compressor) io.Reader {
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return errReader{err}
|
||||
}
|
||||
r, err := comp.Reader(f)
|
||||
if err != nil {
|
||||
_ = f.Close()
|
||||
return errReader{err}
|
||||
}
|
||||
return &readCloserPair{r: r, f: f}
|
||||
}
|
||||
@@ -0,0 +1,429 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/go-sql-driver/mysql"
|
||||
|
||||
"archer/internal/app"
|
||||
"archer/internal/cli"
|
||||
)
|
||||
|
||||
func TestMain(m *testing.M) {
|
||||
if dsn := os.Getenv("ARCHER_TEST_DSN"); dsn != "" {
|
||||
if cfg, err := mysql.ParseDSN(dsn); err == nil && cfg.DBName != "" {
|
||||
dbName := cfg.DBName
|
||||
cfg.DBName = ""
|
||||
if db, err := sql.Open("mysql", cfg.FormatDSN()); err == nil {
|
||||
_, _ = db.Exec("CREATE DATABASE IF NOT EXISTS `" + dbName + "`")
|
||||
_, _ = db.Exec("SET GLOBAL local_infile=ON")
|
||||
_, _ = db.Exec("SET GLOBAL sql_mode=''")
|
||||
db.Close()
|
||||
}
|
||||
}
|
||||
}
|
||||
os.Exit(m.Run())
|
||||
}
|
||||
|
||||
func testDSN(t *testing.T) string {
|
||||
t.Helper()
|
||||
d := os.Getenv("ARCHER_TEST_DSN")
|
||||
if d == "" {
|
||||
t.Skip("ARCHER_TEST_DSN is not set; skipping MySQL integration test")
|
||||
}
|
||||
return d
|
||||
}
|
||||
|
||||
func charsetDSN(t *testing.T, dsn string) string {
|
||||
t.Helper()
|
||||
cfg, err := mysql.ParseDSN(dsn)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if cfg.Params == nil {
|
||||
cfg.Params = map[string]string{}
|
||||
}
|
||||
cfg.Params["charset"] = "utf8mb4"
|
||||
return cfg.FormatDSN()
|
||||
}
|
||||
|
||||
func openDB(t *testing.T, dsn string) *sql.DB {
|
||||
t.Helper()
|
||||
db, err := sql.Open("mysql", dsn)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := db.Ping(); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return db
|
||||
}
|
||||
|
||||
func execSQL(t *testing.T, db *sql.DB, q string, args ...any) {
|
||||
t.Helper()
|
||||
if _, err := db.Exec(q, args...); err != nil {
|
||||
t.Fatalf("exec %q: %v", q, err)
|
||||
}
|
||||
}
|
||||
|
||||
func exportTable(t *testing.T, dsn, table, dir string, extra ...string) {
|
||||
t.Helper()
|
||||
args := []string{"--source", dsn, "--table", table, "--where", "1=1", "--file", dir, "--progress", "off"}
|
||||
args = append(args, extra...)
|
||||
cfg, err := cli.Parse(args, io.Discard)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := app.Run(context.Background(), cfg); err != nil {
|
||||
t.Fatalf("export %s: %v", table, err)
|
||||
}
|
||||
}
|
||||
|
||||
func importArchive(t *testing.T, dsn, dir string, extra ...string) error {
|
||||
t.Helper()
|
||||
args := []string{"--file", dir, "--dest", dsn, "--progress", "off"}
|
||||
args = append(args, extra...)
|
||||
cfg, err := cli.ParseImport(args, io.Discard)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return Run(context.Background(), cfg)
|
||||
}
|
||||
|
||||
func countRows(t *testing.T, db *sql.DB, table string) int {
|
||||
t.Helper()
|
||||
var n int
|
||||
if err := db.QueryRow("SELECT COUNT(*) FROM `" + table + "`").Scan(&n); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return n
|
||||
}
|
||||
|
||||
// fingerprint renders an ordered result set byte-for-byte, using hex so NULL,
|
||||
// tabs, newlines and binary values are all distinguishable.
|
||||
func fingerprint(t *testing.T, db *sql.DB, q string) string {
|
||||
t.Helper()
|
||||
rows, err := db.Query(q)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defer rows.Close()
|
||||
cols, err := rows.Columns()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var b strings.Builder
|
||||
for rows.Next() {
|
||||
raw := make([]sql.RawBytes, len(cols))
|
||||
ptrs := make([]any, len(cols))
|
||||
for i := range raw {
|
||||
ptrs[i] = &raw[i]
|
||||
}
|
||||
if err := rows.Scan(ptrs...); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for i, v := range raw {
|
||||
if i > 0 {
|
||||
b.WriteByte('|')
|
||||
}
|
||||
if v == nil {
|
||||
b.WriteString("<NULL>")
|
||||
} else {
|
||||
fmt.Fprintf(&b, "%x", []byte(v))
|
||||
}
|
||||
}
|
||||
b.WriteByte('\n')
|
||||
}
|
||||
if err := rows.Err(); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func seedSimple(t *testing.T, db *sql.DB, table string) {
|
||||
t.Helper()
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS `"+table+"`")
|
||||
execSQL(t, db, "CREATE TABLE `"+table+"` (id BIGINT NOT NULL, v VARCHAR(64) NULL, PRIMARY KEY (id)) DEFAULT CHARSET=utf8mb4")
|
||||
execSQL(t, db, "INSERT INTO `"+table+"` (id, v) VALUES (1,'a'),(2,'b'),(3,'c'),(4,'tab\\there'),(5,NULL)")
|
||||
}
|
||||
|
||||
func freshTable(t *testing.T, db *sql.DB, table string) {
|
||||
t.Helper()
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS `"+table+"`")
|
||||
execSQL(t, db, "CREATE TABLE `"+table+"` (id BIGINT NOT NULL, v VARCHAR(64) NULL, PRIMARY KEY (id)) DEFAULT CHARSET=utf8mb4")
|
||||
}
|
||||
|
||||
func TestIntegrationExportImport(t *testing.T) {
|
||||
dsn := testDSN(t)
|
||||
db := openDB(t, dsn)
|
||||
defer db.Close()
|
||||
seedSimple(t, db, "it_imp_src")
|
||||
dir := t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_src", dir)
|
||||
|
||||
freshTable(t, db, "it_imp_dst")
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_dst", "--assume-all-columns"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if n := countRows(t, db, "it_imp_dst"); n != 5 {
|
||||
t.Fatalf("imported %d rows", n)
|
||||
}
|
||||
if got, want := fingerprint(t, db, "SELECT id, v FROM it_imp_dst ORDER BY id"),
|
||||
fingerprint(t, db, "SELECT id, v FROM it_imp_src ORDER BY id"); got != want {
|
||||
t.Fatalf("rows differ:\n%s\nwant:\n%s", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationCompression(t *testing.T) {
|
||||
dsn := testDSN(t)
|
||||
db := openDB(t, dsn)
|
||||
defer db.Close()
|
||||
seedSimple(t, db, "it_imp_comp_src")
|
||||
for _, comp := range []string{"none", "gzip", "zstd", "xz"} {
|
||||
dir := t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_comp_src", dir, "--compress", comp)
|
||||
if files, _ := filepath.Glob(filepath.Join(dir, "*.dump*")); len(files) != 1 {
|
||||
t.Fatalf("%s: shard files %v", comp, files)
|
||||
}
|
||||
dst := "it_imp_comp_" + comp
|
||||
freshTable(t, db, dst)
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", dst, "--assume-all-columns"); err != nil {
|
||||
t.Fatalf("%s: %v", comp, err)
|
||||
}
|
||||
if n := countRows(t, db, dst); n != 5 {
|
||||
t.Fatalf("%s: %d rows", comp, n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationModes(t *testing.T) {
|
||||
dsn := testDSN(t)
|
||||
db := openDB(t, dsn)
|
||||
defer db.Close()
|
||||
seedSimple(t, db, "it_imp_modes_src")
|
||||
dir := t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_modes_src", dir)
|
||||
|
||||
freshTable(t, db, "it_imp_modes_dst")
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_modes_dst", "--assume-all-columns"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_modes_dst", "--assume-all-columns"); err != nil {
|
||||
t.Fatalf("ignore re-import must be idempotent: %v", err)
|
||||
}
|
||||
if n := countRows(t, db, "it_imp_modes_dst"); n != 5 {
|
||||
t.Fatalf("ignore re-import changed row count: %d", n)
|
||||
}
|
||||
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_modes_dst", "--assume-all-columns", "--mode", "insert"); err == nil {
|
||||
t.Fatal("insert mode must fail on duplicate keys")
|
||||
}
|
||||
|
||||
execSQL(t, db, "UPDATE it_imp_modes_dst SET v='changed' WHERE id=2")
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_modes_dst", "--assume-all-columns", "--mode", "replace"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var v string
|
||||
if err := db.QueryRow("SELECT v FROM it_imp_modes_dst WHERE id=2").Scan(&v); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if v != "b" {
|
||||
t.Fatalf("replace did not restore value: %q", v)
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationVerifyAndPartial(t *testing.T) {
|
||||
dsn := testDSN(t)
|
||||
db := openDB(t, dsn)
|
||||
defer db.Close()
|
||||
seedSimple(t, db, "it_imp_verify_src")
|
||||
dir := t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_verify_src", dir)
|
||||
|
||||
files, err := filepath.Glob(filepath.Join(dir, "*.dump"))
|
||||
if err != nil || len(files) != 1 {
|
||||
t.Fatalf("files %v err %v", files, err)
|
||||
}
|
||||
f, err := os.OpenFile(files[0], os.O_APPEND|os.O_WRONLY, 0o644)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := f.WriteString("tampered\n"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
f.Close()
|
||||
freshTable(t, db, "it_imp_verify_dst")
|
||||
err = importArchive(t, dsn, dir, "--dest-table", "it_imp_verify_dst", "--assume-all-columns")
|
||||
if err == nil || !strings.Contains(err.Error(), "failed verification") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
|
||||
// Re-export a pristine archive for the completion-gate half.
|
||||
dir = t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_verify_src", dir)
|
||||
statePath := filepath.Join(dir, "state.json")
|
||||
body, err := os.ReadFile(statePath)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
body = []byte(strings.Replace(string(body), `"complete": true`, `"complete": false`, 1))
|
||||
if err := os.WriteFile(statePath, body, 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
freshTable(t, db, "it_imp_partial_dst")
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_partial_dst", "--assume-all-columns"); err == nil || !strings.Contains(err.Error(), "incomplete") {
|
||||
t.Fatalf("incomplete archive must be refused, got %v", err)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_partial_dst", "--assume-all-columns", "--allow-partial"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if n := countRows(t, db, "it_imp_partial_dst"); n != 5 {
|
||||
t.Fatalf("partial import: %d rows", n)
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationWorkersAndEnginesAgree(t *testing.T) {
|
||||
dsn := testDSN(t)
|
||||
db := openDB(t, dsn)
|
||||
defer db.Close()
|
||||
seedSimple(t, db, "it_imp_par_src")
|
||||
for i := 6; i <= 20; i++ {
|
||||
execSQL(t, db, "INSERT INTO it_imp_par_src (id, v) VALUES (?, ?)", i, fmt.Sprintf("v%d", i))
|
||||
}
|
||||
dir := t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_par_src", dir, "--shard-by", "count", "--shard-rows", "4", "--chunk-size", "3")
|
||||
|
||||
for _, dst := range []string{"it_imp_par_1", "it_imp_par_4", "it_imp_par_ins"} {
|
||||
freshTable(t, db, dst)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_par_1", "--workers", "1", "--assume-all-columns"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_par_4", "--workers", "4", "--assume-all-columns"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_par_ins", "--engine", "insert", "--assume-all-columns"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
want := fingerprint(t, db, "SELECT id, v FROM it_imp_par_1 ORDER BY id")
|
||||
for _, dst := range []string{"it_imp_par_4", "it_imp_par_ins"} {
|
||||
if got := fingerprint(t, db, "SELECT id, v FROM `"+dst+"` ORDER BY id"); got != want {
|
||||
t.Fatalf("%s differs from serial load", dst)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationFidelity(t *testing.T) {
|
||||
dsn := charsetDSN(t, testDSN(t))
|
||||
db := openDB(t, dsn)
|
||||
defer db.Close()
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_fid_src")
|
||||
execSQL(t, db, `CREATE TABLE it_imp_fid_src (
|
||||
id BIGINT NOT NULL PRIMARY KEY,
|
||||
s VARCHAR(128) NULL,
|
||||
b BLOB NULL,
|
||||
n INT NULL) DEFAULT CHARSET=utf8mb4`)
|
||||
execSQL(t, db, "INSERT INTO it_imp_fid_src (id, s, b, n) VALUES (?,?,?,?)", 1, nil, nil, nil)
|
||||
execSQL(t, db, "INSERT INTO it_imp_fid_src (id, s, b, n) VALUES (?,?,?,?)", 2, "tab\there\nnewline\\back", []byte{0x00, 0x01, 0x02, 0x03, 0xff}, 0)
|
||||
execSQL(t, db, "INSERT INTO it_imp_fid_src (id, s, b, n) VALUES (?,?,?,?)", 3, "中文😀", []byte("hi"), 42)
|
||||
|
||||
dir := t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_fid_src", dir)
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_fid_dst")
|
||||
execSQL(t, db, `CREATE TABLE it_imp_fid_dst (
|
||||
id BIGINT NOT NULL PRIMARY KEY,
|
||||
s VARCHAR(128) NULL,
|
||||
b BLOB NULL,
|
||||
n INT NULL) DEFAULT CHARSET=utf8mb4`)
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_fid_dst", "--assume-all-columns", "--charset", "binary"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
q := "SELECT id, s, HEX(b), n FROM %s ORDER BY id"
|
||||
got := fingerprint(t, db, fmt.Sprintf(q, "it_imp_fid_dst"))
|
||||
want := fingerprint(t, db, fmt.Sprintf(q, "it_imp_fid_src"))
|
||||
if got != want {
|
||||
t.Fatalf("fidelity mismatch:\n got: %s\nwant: %s", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
func TestIntegrationColumnMappings(t *testing.T) {
|
||||
dsn := charsetDSN(t, testDSN(t))
|
||||
db := openDB(t, dsn)
|
||||
defer db.Close()
|
||||
|
||||
// (a) archive-recorded column list
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_cols_src")
|
||||
execSQL(t, db, "CREATE TABLE it_imp_cols_src (id BIGINT NOT NULL, a VARCHAR(32), b VARCHAR(32), PRIMARY KEY (id))")
|
||||
execSQL(t, db, "INSERT INTO it_imp_cols_src (id, a, b) VALUES (1,'a1','b1'),(2,'a2','b2')")
|
||||
dir := t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_cols_src", dir, "--columns", "id,a")
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_cols_dst")
|
||||
execSQL(t, db, "CREATE TABLE it_imp_cols_dst (id BIGINT NOT NULL, a VARCHAR(32), b VARCHAR(32), PRIMARY KEY (id))")
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_cols_dst"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got := fingerprint(t, db, "SELECT id, a, b FROM it_imp_cols_dst ORDER BY id"); got != "31|6131|<NULL>\n32|6132|<NULL>\n" {
|
||||
t.Fatalf("archive-recorded mapping: %q", got)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_cols_dst", "--columns", "id,a"); err == nil {
|
||||
t.Fatal("archive column list plus --columns must be rejected")
|
||||
}
|
||||
|
||||
// (b) explicit --columns on a default (all-columns) archive
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_all_src")
|
||||
execSQL(t, db, "CREATE TABLE it_imp_all_src (id BIGINT NOT NULL, a VARCHAR(32), b VARCHAR(32), PRIMARY KEY (id))")
|
||||
execSQL(t, db, "INSERT INTO it_imp_all_src (id, a, b) VALUES (1,'a1','b1')")
|
||||
dir = t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_all_src", dir)
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_all_dst")
|
||||
execSQL(t, db, "CREATE TABLE it_imp_all_dst (id BIGINT NOT NULL, a VARCHAR(32), b VARCHAR(32), PRIMARY KEY (id))")
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_all_dst"); err == nil {
|
||||
t.Fatal("default all-columns archive without a mapping must be refused")
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_all_dst", "--columns", "id,a,b"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_all_dst", "--columns", "id,nope"); err == nil || !strings.Contains(err.Error(), "does not exist") {
|
||||
t.Fatalf("missing column: %v", err)
|
||||
}
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_all_dst", "--columns", "id"); err == nil || !strings.Contains(err.Error(), "fields") {
|
||||
t.Fatalf("field count mismatch: %v", err)
|
||||
}
|
||||
|
||||
// (c) positional mapping with a generated column
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_gen_src")
|
||||
execSQL(t, db, `CREATE TABLE it_imp_gen_src (
|
||||
id BIGINT NOT NULL PRIMARY KEY,
|
||||
a INT NOT NULL,
|
||||
b INT NOT NULL,
|
||||
total INT AS (a + b) STORED)`)
|
||||
execSQL(t, db, "INSERT INTO it_imp_gen_src (id, a, b) VALUES (1,2,3),(2,10,20)")
|
||||
dir = t.TempDir()
|
||||
exportTable(t, dsn, "it_imp_gen_src", dir)
|
||||
execSQL(t, db, "DROP TABLE IF EXISTS it_imp_gen_dst")
|
||||
execSQL(t, db, `CREATE TABLE it_imp_gen_dst (
|
||||
id BIGINT NOT NULL PRIMARY KEY,
|
||||
a INT NOT NULL,
|
||||
b INT NOT NULL,
|
||||
total INT AS (a + b) STORED)`)
|
||||
if err := importArchive(t, dsn, dir, "--dest-table", "it_imp_gen_dst", "--assume-all-columns"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, want := range []struct{ id, a, b, total int }{{1, 2, 3, 5}, {2, 10, 20, 30}} {
|
||||
var gotID, gotA, gotB, gotTotal int
|
||||
if err := db.QueryRow("SELECT id, a, b, total FROM it_imp_gen_dst WHERE id=?", want.id).
|
||||
Scan(&gotID, &gotA, &gotB, &gotTotal); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if gotID != want.id || gotA != want.a || gotB != want.b || gotTotal != want.total {
|
||||
t.Fatalf("row %d = (%d,%d,%d,%d), want %+v", want.id, gotID, gotA, gotB, gotTotal, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,418 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/go-sql-driver/mysql"
|
||||
|
||||
"archer/internal/archererr"
|
||||
"archer/internal/cli"
|
||||
"archer/internal/progress"
|
||||
"archer/internal/schema"
|
||||
"archer/internal/shard"
|
||||
)
|
||||
|
||||
// Stats collects the --statistics counters for one import run.
|
||||
type Stats struct {
|
||||
Started time.Time
|
||||
Elapsed time.Duration
|
||||
Selected int
|
||||
NotSelected int
|
||||
Succeeded int
|
||||
Failed int
|
||||
ExpectedRows int64
|
||||
ImportedRows int64
|
||||
SkippedRows int64
|
||||
Bytes int64
|
||||
IgnoredFiles int
|
||||
Partial bool
|
||||
}
|
||||
|
||||
// Run executes one import.
|
||||
func Run(ctx context.Context, cfg *cli.ImportConfig) error {
|
||||
if err := cfg.Validate(); err != nil {
|
||||
return err
|
||||
}
|
||||
stats := &Stats{Started: time.Now()}
|
||||
|
||||
archive, err := LoadArchive(cfg.FileDir)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if err := archive.CheckComplete(cfg.AllowPartial); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := archive.CheckMappingChoice(cfg.Columns, cfg.AssumeAll); err != nil {
|
||||
return err
|
||||
}
|
||||
stats.Partial = cfg.AllowPartial && (archive.State == nil || !archive.State.Complete)
|
||||
|
||||
selected, warnings, err := shard.ApplySelection(archive.Entries, cfg.Selectors)
|
||||
if err != nil {
|
||||
return archererr.Newf(archererr.KindConfig, "%v", err)
|
||||
}
|
||||
if err := CheckShardFiles(archive.Root, selected); err != nil {
|
||||
return err
|
||||
}
|
||||
format, compress, comp, err := ResolveFormat(selected)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
archive.Format, archive.Compress, archive.Compressor = format, compress, comp
|
||||
stats.Selected = len(selected)
|
||||
stats.NotSelected = len(archive.Entries) - len(selected)
|
||||
for _, e := range selected {
|
||||
stats.ExpectedRows += e.Rows
|
||||
stats.Bytes += e.Bytes
|
||||
}
|
||||
|
||||
if cfg.DestTable == "" {
|
||||
cfg.DestTable = archive.SourceTable
|
||||
}
|
||||
if cfg.DestTable == "" {
|
||||
return archererr.Newf(archererr.KindConfig,
|
||||
"--dest-table is required: the archive does not record the source table name")
|
||||
}
|
||||
|
||||
if cfg.DryRun {
|
||||
fields, hasRow, ferr := FirstLineFieldCount(shardPath(archive.Root, selected[0]), comp)
|
||||
if ferr != nil {
|
||||
return archererr.Wrap(archererr.KindValidation, ferr)
|
||||
}
|
||||
return PrintDryRun(os.Stdout, cfg, archive, selected, warnings, compress, fields, hasRow)
|
||||
}
|
||||
|
||||
for _, w := range warnings {
|
||||
fmt.Fprintln(os.Stderr, "warning:", w)
|
||||
}
|
||||
if len(warnings) > 0 {
|
||||
fmt.Fprintln(os.Stderr, "warning: shard selection is whole-shard; rows outside the requested key range may be imported")
|
||||
}
|
||||
|
||||
destCfg, err := cfg.DestConfig()
|
||||
if err != nil {
|
||||
return archererr.Wrap(archererr.KindConfig, err)
|
||||
}
|
||||
db, err := openDest(destCfg, cfg.Workers)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer db.Close()
|
||||
|
||||
if err := checkTarget(ctx, db, cfg.Engine); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := checkTableExists(ctx, db, destCfg.DBName, cfg.DestTable); err != nil {
|
||||
return err
|
||||
}
|
||||
table, err := schema.Load(ctx, db, destCfg.DBName, cfg.DestTable)
|
||||
if err != nil {
|
||||
return archererr.Wrap(archererr.KindValidation, err)
|
||||
}
|
||||
mapping, err := BuildMapping(table, archive.ArchivedColumns, cfg.Columns, cfg.AssumeAll)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if mapping.Positional {
|
||||
fmt.Fprintln(os.Stderr, "warning: --assume-all-columns accepts positional mapping; only the field count is checked, not column names or order")
|
||||
}
|
||||
if err := CheckFieldCount(shardPath(archive.Root, selected[0]), comp, len(mapping.FileColumns)); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
rep := startReporter(cfg, stats.ExpectedRows)
|
||||
if rep != nil {
|
||||
defer rep.Stop()
|
||||
}
|
||||
if err := runWorkers(ctx, db, destCfg.DBName, cfg, archive, mapping, selected, stats, rep); err != nil {
|
||||
if archererr.KindOf(err) == archererr.KindInterrupted && rep != nil {
|
||||
rep.Interrupted()
|
||||
}
|
||||
return err
|
||||
}
|
||||
stats.Elapsed = time.Since(stats.Started)
|
||||
stats.IgnoredFiles = UnregisteredFiles(archive.Root, archive.Entries)
|
||||
if rep != nil {
|
||||
rep.SetShards(int64(len(selected)))
|
||||
rep.SetBytes(stats.Bytes)
|
||||
rep.Done()
|
||||
}
|
||||
if cfg.Statistics {
|
||||
PrintStats(os.Stdout, archive, stats)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func openDest(cfg *mysql.Config, workers int) (*sql.DB, error) {
|
||||
db, err := sql.Open("mysql", cfg.FormatDSN())
|
||||
if err != nil {
|
||||
return nil, archererr.Wrap(archererr.KindConnection, err)
|
||||
}
|
||||
db.SetMaxOpenConns(workers + 2)
|
||||
db.SetMaxIdleConns(workers + 1)
|
||||
db.SetConnMaxLifetime(time.Hour)
|
||||
if err := db.Ping(); err != nil {
|
||||
db.Close()
|
||||
return nil, archererr.Wrap(archererr.KindConnection, fmt.Errorf("connect %s: %w", cfg.Addr, err))
|
||||
}
|
||||
return db, nil
|
||||
}
|
||||
|
||||
func checkTarget(ctx context.Context, db *sql.DB, engine string) error {
|
||||
var localInfile int
|
||||
var version string
|
||||
if err := db.QueryRowContext(ctx, "SELECT @@local_infile, @@version").Scan(&localInfile, &version); err != nil {
|
||||
return archererr.Wrap(archererr.KindConnection, fmt.Errorf("query local_infile: %w", err))
|
||||
}
|
||||
if engine == "load" && localInfile == 0 {
|
||||
return archererr.Newf(archererr.KindConfig,
|
||||
"target server (%s) has local_infile disabled; enable it on the server/proxy, or use --engine insert", version)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func checkTableExists(ctx context.Context, db *sql.DB, dbName, table string) error {
|
||||
var n int
|
||||
err := db.QueryRowContext(ctx, `
|
||||
SELECT COUNT(*) FROM information_schema.tables
|
||||
WHERE table_schema = ? AND table_name = ?`, dbName, table).Scan(&n)
|
||||
if err != nil {
|
||||
return archererr.Wrap(archererr.KindConnection, fmt.Errorf("check target table: %w", err))
|
||||
}
|
||||
if n == 0 {
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"target table %s.%s does not exist; create it before importing (archer does not create tables)", dbName, table)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func startReporter(cfg *cli.ImportConfig, total int64) *progress.Reporter {
|
||||
tty := progress.IsTerminal(os.Stderr)
|
||||
enabled := cfg.Progress.Enabled(tty)
|
||||
r := progress.New(progress.Options{
|
||||
Out: os.Stderr,
|
||||
Enabled: enabled,
|
||||
Live: enabled && tty,
|
||||
Interval: time.Second,
|
||||
RowEvery: cfg.Progress.Rows,
|
||||
})
|
||||
r.Start()
|
||||
r.SetEstimate(&progress.Estimate{Kind: "rows", Lo: 0, Hi: float64(total)})
|
||||
r.SetPosition(0)
|
||||
return r
|
||||
}
|
||||
|
||||
func runWorkers(ctx context.Context, db *sql.DB, dbName string, cfg *cli.ImportConfig, archive *Archive, mapping *Mapping, selected []shard.Entry, stats *Stats, rep *progress.Reporter) error {
|
||||
parent := ctx
|
||||
ctx, cancel := context.WithCancel(ctx)
|
||||
defer cancel()
|
||||
|
||||
var (
|
||||
wg sync.WaitGroup
|
||||
mu sync.Mutex
|
||||
firstErr error
|
||||
failedSeq int64
|
||||
processedRows int64
|
||||
rowsAtFailure int64
|
||||
importedRows int64
|
||||
skippedRows int64
|
||||
okShards int
|
||||
)
|
||||
recordFailure := func(e shard.Entry, err error) {
|
||||
mu.Lock()
|
||||
defer mu.Unlock()
|
||||
if firstErr != nil {
|
||||
return
|
||||
}
|
||||
if parent.Err() != nil {
|
||||
firstErr = archererr.Wrap(archererr.KindInterrupted, parent.Err())
|
||||
} else {
|
||||
firstErr = err
|
||||
}
|
||||
failedSeq = e.Seq
|
||||
rowsAtFailure = processedRows
|
||||
}
|
||||
|
||||
ranges := splitRanges(len(selected), cfg.Workers)
|
||||
for _, rg := range ranges {
|
||||
if rg[0] >= rg[1] {
|
||||
continue
|
||||
}
|
||||
part := selected[rg[0]:rg[1]]
|
||||
wg.Add(1)
|
||||
go func(part []shard.Entry) {
|
||||
defer wg.Done()
|
||||
if err := ctx.Err(); err != nil {
|
||||
recordFailure(part[0], err)
|
||||
return
|
||||
}
|
||||
w, err := newWorker(ctx, db, cfg, archive, mapping, dbName)
|
||||
if err != nil {
|
||||
recordFailure(part[0], err)
|
||||
cancel()
|
||||
return
|
||||
}
|
||||
defer w.close()
|
||||
for _, e := range part {
|
||||
if err := ctx.Err(); err != nil {
|
||||
recordFailure(e, err)
|
||||
return
|
||||
}
|
||||
affected, skipped, err := w.importShard(ctx, e)
|
||||
if err != nil {
|
||||
recordFailure(e, err)
|
||||
cancel()
|
||||
return
|
||||
}
|
||||
mu.Lock()
|
||||
processedRows += e.Rows
|
||||
importedRows += affected
|
||||
skippedRows += skipped
|
||||
okShards++
|
||||
done := processedRows
|
||||
mu.Unlock()
|
||||
if rep != nil {
|
||||
rep.AddRows(e.Rows)
|
||||
rep.SetPosition(float64(done))
|
||||
}
|
||||
}
|
||||
}(part)
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
mu.Lock()
|
||||
stats.Succeeded = okShards
|
||||
stats.ImportedRows = importedRows
|
||||
stats.SkippedRows = skippedRows
|
||||
err := firstErr
|
||||
seq := failedSeq
|
||||
atFailure := rowsAtFailure
|
||||
doneRows := processedRows
|
||||
mu.Unlock()
|
||||
if err != nil {
|
||||
if archererr.KindOf(err) == archererr.KindInterrupted {
|
||||
return fmt.Errorf("interrupted after %d rows: %w", doneRows, err)
|
||||
}
|
||||
stats.Failed = 1
|
||||
return fmt.Errorf("shard %d failed after %d rows: %w", seq, atFailure, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func splitRanges(n, workers int) [][2]int {
|
||||
if n <= 0 || workers <= 0 {
|
||||
return nil
|
||||
}
|
||||
if workers > n {
|
||||
workers = n
|
||||
}
|
||||
out := make([][2]int, 0, workers)
|
||||
base, rem := n/workers, n%workers
|
||||
start := 0
|
||||
for i := 0; i < workers; i++ {
|
||||
size := base
|
||||
if i < rem {
|
||||
size++
|
||||
}
|
||||
out = append(out, [2]int{start, start + size})
|
||||
start += size
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// PrintDryRun prints the resolved configuration and selection without opening
|
||||
// a database connection.
|
||||
func PrintDryRun(w io.Writer, cfg *cli.ImportConfig, archive *Archive, selected []shard.Entry, warnings []string, compress string, fields int, hasRow bool) error {
|
||||
fmt.Fprintln(w, "== import configuration ==")
|
||||
fmt.Fprintf(w, "archive: %s\n", archive.Root)
|
||||
fmt.Fprintf(w, "dest: %s\n", redactDSN(cfg.DestDSN))
|
||||
fmt.Fprintf(w, "dest table: %s\n", cfg.DestTable)
|
||||
if len(archive.ArchivedColumns) > 0 {
|
||||
fmt.Fprintf(w, "archive columns: %s\n", join(archive.ArchivedColumns))
|
||||
} else if len(cfg.Columns) > 0 {
|
||||
fmt.Fprintf(w, "columns: %s\n", join(cfg.Columns))
|
||||
} else if cfg.AssumeAll {
|
||||
fmt.Fprintf(w, "columns: positional (--assume-all-columns)\n")
|
||||
} else {
|
||||
fmt.Fprintf(w, "columns: (unresolved; --columns or --assume-all-columns is required)\n")
|
||||
}
|
||||
fmt.Fprintf(w, "engine: %s\n", cfg.Engine)
|
||||
fmt.Fprintf(w, "mode: %s\n", cfg.Mode)
|
||||
fmt.Fprintf(w, "verify: %s\n", cfg.Verify)
|
||||
fmt.Fprintf(w, "workers: %d\n", cfg.Workers)
|
||||
fmt.Fprintf(w, "charset: %s\n", cfg.Charset)
|
||||
if cfg.TimeZone != "" {
|
||||
fmt.Fprintf(w, "time zone: %s\n", cfg.TimeZone)
|
||||
}
|
||||
fmt.Fprintf(w, "compression: %s\n", compress)
|
||||
switch {
|
||||
case archive.State == nil:
|
||||
fmt.Fprintln(w, "archive complete: unknown (state.json missing)")
|
||||
case archive.Complete:
|
||||
fmt.Fprintln(w, "archive complete: true")
|
||||
default:
|
||||
fmt.Fprintln(w, "archive complete: false (--allow-partial given)")
|
||||
}
|
||||
if hasRow {
|
||||
fmt.Fprintf(w, "first row fields: %d\n", fields)
|
||||
}
|
||||
|
||||
fmt.Fprintf(w, "\n== selected shards (%d) ==\n", len(selected))
|
||||
var rows, bytes int64
|
||||
for _, e := range selected {
|
||||
date := e.Date
|
||||
if date == "" {
|
||||
date = "-"
|
||||
}
|
||||
fmt.Fprintf(w, " seq=%-6d pk=%-24s date=%-12s rows=%-10d bytes=%-10d %s\n",
|
||||
e.Seq, e.PKLo+"-"+e.PKHi, date, e.Rows, e.Bytes, e.Path)
|
||||
rows += e.Rows
|
||||
bytes += e.Bytes
|
||||
}
|
||||
fmt.Fprintf(w, "total: %d shards, %d rows, %d bytes\n", len(selected), rows, bytes)
|
||||
fmt.Fprintln(w, "\nno database connection was made and no data was written")
|
||||
return nil
|
||||
}
|
||||
|
||||
// PrintStats prints the --statistics summary.
|
||||
func PrintStats(w io.Writer, archive *Archive, s *Stats) {
|
||||
fmt.Fprintln(w, "import summary:")
|
||||
fmt.Fprintf(w, " archive: %s\n", archive.Root)
|
||||
fmt.Fprintf(w, " partial archive: %t\n", s.Partial)
|
||||
fmt.Fprintf(w, " shards selected: %d\n", s.Selected)
|
||||
fmt.Fprintf(w, " shards succeeded: %d\n", s.Succeeded)
|
||||
fmt.Fprintf(w, " shards failed: %d\n", s.Failed)
|
||||
fmt.Fprintf(w, " shards not selected: %d\n", s.NotSelected)
|
||||
fmt.Fprintf(w, " rows expected: %d\n", s.ExpectedRows)
|
||||
fmt.Fprintf(w, " rows affected: %d\n", s.ImportedRows)
|
||||
fmt.Fprintf(w, " rows skipped: %d\n", s.SkippedRows)
|
||||
fmt.Fprintf(w, " bytes: %d\n", s.Bytes)
|
||||
fmt.Fprintf(w, " ignored files: %d (present on disk, not in manifest)\n", s.IgnoredFiles)
|
||||
fmt.Fprintf(w, " elapsed: %s\n", s.Elapsed.Round(time.Millisecond))
|
||||
}
|
||||
|
||||
func join(parts []string) string {
|
||||
out := ""
|
||||
for i, p := range parts {
|
||||
if i > 0 {
|
||||
out += ", "
|
||||
}
|
||||
out += p
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func redactDSN(dsn string) string {
|
||||
c, err := mysql.ParseDSN(dsn)
|
||||
if err != nil {
|
||||
return "<invalid dsn>"
|
||||
}
|
||||
c.Passwd = ""
|
||||
return c.FormatDSN()
|
||||
}
|
||||
@@ -0,0 +1,104 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"archer/internal/archererr"
|
||||
"archer/internal/cli"
|
||||
"archer/internal/shard"
|
||||
)
|
||||
|
||||
func TestSplitRanges(t *testing.T) {
|
||||
got := splitRanges(10, 3)
|
||||
want := [][2]int{{0, 4}, {4, 7}, {7, 10}}
|
||||
if len(got) != len(want) {
|
||||
t.Fatalf("got %v", got)
|
||||
}
|
||||
for i := range want {
|
||||
if got[i] != want[i] {
|
||||
t.Fatalf("got %v want %v", got, want)
|
||||
}
|
||||
}
|
||||
if got := splitRanges(2, 5); len(got) != 2 || got[1] != [2]int{1, 2} {
|
||||
t.Fatalf("workers beyond shards: %v", got)
|
||||
}
|
||||
if got := splitRanges(0, 3); got != nil {
|
||||
t.Fatalf("empty selection: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunConfigErrorExitCode(t *testing.T) {
|
||||
err := Run(context.Background(), cli.ImportDefaults())
|
||||
if err == nil {
|
||||
t.Fatal("expected an error")
|
||||
}
|
||||
if got := archererr.ExitCode(err); got != 2 {
|
||||
t.Fatalf("exit code = %d, want 2 (%v)", got, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunEmptySelectionIsConfigError(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeManifest(t, root, []shard.Entry{{Seq: 1, Path: "000001.1-1.dump", Rows: 1}})
|
||||
writeShard(t, root, "000001.1-1.dump", "1\n")
|
||||
saveState(t, root, true, map[string]string{"table": "src"})
|
||||
|
||||
cfg := cli.ImportDefaults()
|
||||
cfg.FileDir = root
|
||||
cfg.DestDSN = "u:p@tcp(127.0.0.1:3306)/db"
|
||||
cfg.Selects = []string{"seq:9-9"}
|
||||
|
||||
err := Run(context.Background(), cfg)
|
||||
if err == nil || !strings.Contains(err.Error(), "no shards matched") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
if got := archererr.ExitCode(err); got != 2 {
|
||||
t.Fatalf("exit code = %d, want 2", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunDryRunDoesNotConnect(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
writeManifest(t, root, []shard.Entry{{Seq: 1, Path: "000001.1-1.dump", PKLo: "1", PKHi: "1", Rows: 1, Bytes: 3}})
|
||||
writeShard(t, root, "000001.1-1.dump", "1\tx\n")
|
||||
saveState(t, root, true, map[string]string{"table": "src"})
|
||||
|
||||
cfg := cli.ImportDefaults()
|
||||
cfg.FileDir = root
|
||||
cfg.DestDSN = "u:p@tcp(127.0.0.1:1)/db" // would fail if a connection were attempted
|
||||
cfg.DryRun = true
|
||||
|
||||
// PrintDryRun goes to stdout; Run reaching it without a connection error is
|
||||
// what matters here.
|
||||
if err := Run(context.Background(), cfg); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrintDryRun(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
entries := []shard.Entry{{Seq: 1, Path: "000001.1-1.dump", PKLo: "1", PKHi: "1", Rows: 2, Bytes: 10}}
|
||||
writeManifest(t, root, entries)
|
||||
saveState(t, root, true, map[string]string{"table": "src", "columns": "id,title"})
|
||||
archive, err := LoadArchive(root)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
cfg := cli.ImportDefaults()
|
||||
cfg.FileDir = root
|
||||
cfg.DestDSN = "u:p@tcp(h:3306)/db"
|
||||
cfg.DestTable = "src"
|
||||
var buf bytes.Buffer
|
||||
if err := PrintDryRun(&buf, cfg, archive, entries, nil, "none", 2, true); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
out := buf.String()
|
||||
for _, want := range []string{"archive:", "dest table:", "selected shards (1)", "seq=1", "total: 1 shards, 2 rows, 10 bytes", "no database connection"} {
|
||||
if !strings.Contains(out, want) {
|
||||
t.Fatalf("missing %q in:\n%s", want, out)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/sha256"
|
||||
"database/sql"
|
||||
"encoding/hex"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"strings"
|
||||
|
||||
"archer/internal/archererr"
|
||||
"archer/internal/shard"
|
||||
"archer/internal/sqlutil"
|
||||
)
|
||||
|
||||
// BuildLoadSQL renders the LOAD DATA statement. Field and line rules match
|
||||
// internal/row.dumpEncoder exactly: TAB, LF, backslash escaping and \N.
|
||||
func BuildLoadSQL(dbName, table, charset string, m *Mapping, mode, readerName string) string {
|
||||
var b strings.Builder
|
||||
b.WriteString("LOAD DATA LOCAL INFILE '")
|
||||
b.WriteString(escapeSQLString("Reader::" + readerName))
|
||||
b.WriteString("'")
|
||||
switch mode {
|
||||
case "ignore":
|
||||
b.WriteString(" IGNORE")
|
||||
case "replace":
|
||||
b.WriteString(" REPLACE")
|
||||
}
|
||||
b.WriteString(" INTO TABLE ")
|
||||
b.WriteString(sqlutil.Qualified(dbName, table))
|
||||
b.WriteString(" CHARACTER SET ")
|
||||
b.WriteString(charset)
|
||||
b.WriteString(` FIELDS TERMINATED BY '\t' ESCAPED BY '\\' LINES TERMINATED BY '\n'`)
|
||||
if len(m.LoadList) > 0 {
|
||||
b.WriteString(" (")
|
||||
b.WriteString(strings.Join(m.LoadList, ", "))
|
||||
b.WriteString(")")
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func escapeSQLString(s string) string {
|
||||
s = strings.ReplaceAll(s, `\`, `\\`)
|
||||
return strings.ReplaceAll(s, `'`, `''`)
|
||||
}
|
||||
|
||||
// CheckRowRule applies the per-mode affected-row rule and returns the number
|
||||
// of rows that were skipped (only meaningful for ignore mode).
|
||||
func CheckRowRule(mode string, expected, affected int64) (int64, error) {
|
||||
switch mode {
|
||||
case "insert":
|
||||
if affected != expected {
|
||||
return 0, archererr.Newf(archererr.KindValidation,
|
||||
"insert expected %d rows but wrote %d", expected, affected)
|
||||
}
|
||||
return 0, nil
|
||||
case "ignore":
|
||||
if affected > expected {
|
||||
return 0, archererr.Newf(archererr.KindValidation,
|
||||
"ignore wrote %d rows but the manifest records only %d", affected, expected)
|
||||
}
|
||||
return expected - affected, nil
|
||||
default: // replace may delete+insert, so affected can exceed rows
|
||||
return 0, nil
|
||||
}
|
||||
}
|
||||
|
||||
// VerifyShard streams the compressed shard through SHA-256 and compares it
|
||||
// with the manifest before any bytes are sent to the server.
|
||||
func VerifyShard(path string, e shard.Entry) error {
|
||||
if e.SHA256 == "" {
|
||||
return nil
|
||||
}
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return archererr.Newf(archererr.KindValidation, "open shard %s: %v", e.Path, err)
|
||||
}
|
||||
defer f.Close()
|
||||
h := sha256.New()
|
||||
if _, err := io.Copy(h, f); err != nil {
|
||||
return archererr.Newf(archererr.KindValidation, "hash shard %s: %v", e.Path, err)
|
||||
}
|
||||
got := hex.EncodeToString(h.Sum(nil))
|
||||
if !strings.EqualFold(got, e.SHA256) {
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"shard %d (%s) failed verification: manifest sha256 %s, actual %s", e.Seq, e.Path, e.SHA256, got)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// Warning is one SHOW WARNINGS row.
|
||||
type Warning struct {
|
||||
Level string
|
||||
Code int
|
||||
Message string
|
||||
}
|
||||
|
||||
func (w Warning) String() string { return fmt.Sprintf("%s %d: %s", w.Level, w.Code, w.Message) }
|
||||
|
||||
// ShowWarnings returns the current session warnings.
|
||||
func ShowWarnings(ctx context.Context, conn *sql.Conn) ([]Warning, error) {
|
||||
rows, err := conn.QueryContext(ctx, "SHOW WARNINGS")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
var out []Warning
|
||||
for rows.Next() {
|
||||
var w Warning
|
||||
if err := rows.Scan(&w.Level, &w.Code, &w.Message); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out = append(out, w)
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
|
||||
// CheckWarnings turns server warnings into a per-shard failure unless the
|
||||
// operator explicitly allowed them. Duplicate-key warnings under ignore mode
|
||||
// are expected skips (they are the mechanism that makes re-import idempotent),
|
||||
// so they are not failures; the skipped count comes from affected rows.
|
||||
func CheckWarnings(warnings []Warning, allow bool, mode string, seq int64) error {
|
||||
if allow || len(warnings) == 0 {
|
||||
return nil
|
||||
}
|
||||
fatal := warnings[:0:0]
|
||||
for _, w := range warnings {
|
||||
if mode == "ignore" && w.Code == 1062 {
|
||||
continue
|
||||
}
|
||||
fatal = append(fatal, w)
|
||||
}
|
||||
if len(fatal) == 0 {
|
||||
return nil
|
||||
}
|
||||
const maxShown = 5
|
||||
shown := fatal
|
||||
suffix := ""
|
||||
if len(shown) > maxShown {
|
||||
suffix = fmt.Sprintf(" (and %d more)", len(shown)-maxShown)
|
||||
shown = shown[:maxShown]
|
||||
}
|
||||
parts := make([]string, len(shown))
|
||||
for i, w := range shown {
|
||||
parts[i] = w.String()
|
||||
}
|
||||
return archererr.Newf(archererr.KindValidation,
|
||||
"shard %d produced %d server warning(s); pass --allow-warnings to continue: %s%s",
|
||||
seq, len(fatal), strings.Join(parts, "; "), suffix)
|
||||
}
|
||||
|
||||
// SetSession applies the loader's character set and optional time zone to one
|
||||
// fixed connection.
|
||||
func SetSession(ctx context.Context, conn *sql.Conn, charset, timeZone string) error {
|
||||
if _, err := conn.ExecContext(ctx, "SET NAMES "+charset); err != nil {
|
||||
return archererr.Wrap(archererr.KindConnection, fmt.Errorf("set character set %s: %w", charset, err))
|
||||
}
|
||||
if timeZone != "" {
|
||||
q := "SET time_zone = '" + escapeSQLString(timeZone) + "'"
|
||||
if _, err := conn.ExecContext(ctx, q); err != nil {
|
||||
return archererr.Wrap(archererr.KindConnection, fmt.Errorf("set time_zone %q: %w", timeZone, err))
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
package importer
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"archer/internal/shard"
|
||||
)
|
||||
|
||||
func TestBuildLoadSQLShape(t *testing.T) {
|
||||
m := &Mapping{LoadList: []string{"`id`", "`title`"}}
|
||||
q := BuildLoadSQL("db", "orders", "utf8mb4", m, "ignore", "r1")
|
||||
for _, want := range []string{
|
||||
"LOAD DATA LOCAL INFILE 'Reader::r1'",
|
||||
"IGNORE INTO TABLE `db`.`orders`",
|
||||
"CHARACTER SET utf8mb4",
|
||||
`FIELDS TERMINATED BY '\t' ESCAPED BY '\\' LINES TERMINATED BY '\n'`,
|
||||
"(`id`, `title`)",
|
||||
} {
|
||||
if !strings.Contains(q, want) {
|
||||
t.Fatalf("missing %q in %s", want, q)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuildLoadSQLModes(t *testing.T) {
|
||||
m := &Mapping{}
|
||||
for _, tc := range []struct{ mode, want string }{
|
||||
{"insert", "INFILE 'Reader::r' INTO TABLE"},
|
||||
{"ignore", "INFILE 'Reader::r' IGNORE INTO TABLE"},
|
||||
{"replace", "INFILE 'Reader::r' REPLACE INTO TABLE"},
|
||||
} {
|
||||
q := BuildLoadSQL("db", "t", "binary", m, tc.mode, "r")
|
||||
if !strings.Contains(q, tc.want) {
|
||||
t.Fatalf("%s: %s", tc.mode, q)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuildLoadSQLNoColumnList(t *testing.T) {
|
||||
q := BuildLoadSQL("db", "t", "utf8mb4", &Mapping{}, "insert", "r")
|
||||
if strings.Contains(q, "(") {
|
||||
t.Fatalf("unexpected column list: %s", q)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEscapeSQLString(t *testing.T) {
|
||||
if got := escapeSQLString(`a'b\c`); got != `a''b\\c` {
|
||||
t.Fatalf("got %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCheckRowRule(t *testing.T) {
|
||||
if _, err := CheckRowRule("insert", 10, 10); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := CheckRowRule("insert", 10, 9); err == nil || !strings.Contains(err.Error(), "expected 10") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
skipped, err := CheckRowRule("ignore", 10, 7)
|
||||
if err != nil || skipped != 3 {
|
||||
t.Fatalf("skipped=%d err=%v", skipped, err)
|
||||
}
|
||||
if _, err := CheckRowRule("ignore", 10, 11); err == nil {
|
||||
t.Fatal("ignore must fail when affected exceeds rows")
|
||||
}
|
||||
if _, err := CheckRowRule("replace", 10, 15); err != nil {
|
||||
t.Fatalf("replace only reports: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestVerifyShard(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
path := filepath.Join(root, "000001.1-1.dump")
|
||||
body := []byte("1\ta\n")
|
||||
if err := os.WriteFile(path, body, 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
sum := sha256.Sum256(body)
|
||||
good := shard.Entry{Seq: 1, Path: "000001.1-1.dump", SHA256: hex.EncodeToString(sum[:])}
|
||||
if err := VerifyShard(path, good); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
bad := good
|
||||
bad.SHA256 = strings.Repeat("0", 64)
|
||||
if err := VerifyShard(path, bad); err == nil || !strings.Contains(err.Error(), "failed verification") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
if err := VerifyShard(path, shard.Entry{Seq: 1, Path: path}); err != nil {
|
||||
t.Fatalf("missing hash should be skipped: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCheckWarnings(t *testing.T) {
|
||||
if err := CheckWarnings(nil, false, "insert", 1); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
w := []Warning{{Level: "Warning", Code: 1265, Message: "data truncated"}}
|
||||
if err := CheckWarnings(w, true, "insert", 1); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := CheckWarnings(w, false, "insert", 3); err == nil || !strings.Contains(err.Error(), "shard 3") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
dup := []Warning{{Level: "Warning", Code: 1062, Message: "Duplicate entry '1'"}}
|
||||
if err := CheckWarnings(dup, false, "ignore", 1); err != nil {
|
||||
t.Fatalf("duplicate-key warnings are expected skips under ignore: %v", err)
|
||||
}
|
||||
if err := CheckWarnings(dup, false, "insert", 1); err == nil {
|
||||
t.Fatal("duplicate warnings must fail outside ignore mode")
|
||||
}
|
||||
}
|
||||
+19
-5
@@ -63,8 +63,8 @@ func (p *Purger) DeleteChunk(ctx context.Context, exec Execer, c *row.Chunk) (in
|
||||
maxKey = v
|
||||
}
|
||||
|
||||
if p.Bulk && maxKey == nil {
|
||||
return p.deleteRange(ctx, exec, c)
|
||||
if p.Bulk {
|
||||
return p.deleteRange(ctx, exec, c, maxKey)
|
||||
}
|
||||
return p.deleteInList(ctx, exec, keys, maxKey)
|
||||
}
|
||||
@@ -85,8 +85,13 @@ func (p *Purger) currentMax(ctx context.Context) (*row.KeyPart, error) {
|
||||
return &row.KeyPart{Val: v.String}, nil
|
||||
}
|
||||
|
||||
func (p *Purger) deleteRange(ctx context.Context, exec Execer, c *row.Chunk) (int64, error) {
|
||||
lo, hi := c.FirstKey, c.LastKey
|
||||
func (p *Purger) deleteRange(ctx context.Context, exec Execer, c *row.Chunk, maxKey *row.KeyPart) (int64, error) {
|
||||
// Date scanners rewrite LastKey into a (shard column, key...) cursor for
|
||||
// resumption, so the bare key range must come from Keys.
|
||||
if len(c.Keys) == 0 {
|
||||
return 0, nil
|
||||
}
|
||||
lo, hi := c.Keys[0], c.Keys[len(c.Keys)-1]
|
||||
if lo.IsZero() || hi.IsZero() {
|
||||
return 0, nil
|
||||
}
|
||||
@@ -95,9 +100,18 @@ func (p *Purger) deleteRange(ctx context.Context, exec Execer, c *row.Chunk) (in
|
||||
args []any
|
||||
)
|
||||
if len(p.KeyCols) == 1 {
|
||||
col := sqlutil.Ident(p.KeyCols[0])
|
||||
if maxKey != nil {
|
||||
// Keep safe-auto-increment semantics: the current max row is
|
||||
// excluded even when it falls inside the range.
|
||||
q = fmt.Sprintf("DELETE FROM %s WHERE %s BETWEEN ? AND ? AND %s <> ? AND (%s)",
|
||||
p.table(), col, col, p.Where)
|
||||
args = []any{lo[0].DriverValue(), hi[0].DriverValue(), maxKey.DriverValue()}
|
||||
} else {
|
||||
q = fmt.Sprintf("DELETE FROM %s WHERE %s BETWEEN ? AND ? AND (%s)",
|
||||
p.table(), sqlutil.Ident(p.KeyCols[0]), p.Where)
|
||||
p.table(), col, p.Where)
|
||||
args = []any{lo[0].DriverValue(), hi[0].DriverValue()}
|
||||
}
|
||||
} else {
|
||||
q = fmt.Sprintf("DELETE FROM %s WHERE %s >= %s AND %s <= %s AND (%s)",
|
||||
p.table(), sqlutil.RowTuple(p.KeyCols), sqlutil.ParamTuple(len(p.KeyCols)),
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
package purge
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"reflect"
|
||||
"testing"
|
||||
|
||||
"archer/internal/row"
|
||||
)
|
||||
|
||||
type recordingExecer struct {
|
||||
query string
|
||||
args []any
|
||||
}
|
||||
|
||||
func (e *recordingExecer) ExecContext(_ context.Context, query string, args ...any) (sql.Result, error) {
|
||||
e.query = query
|
||||
e.args = args
|
||||
return fakeResult(2), nil
|
||||
}
|
||||
|
||||
type fakeResult int64
|
||||
|
||||
func (r fakeResult) LastInsertId() (int64, error) { return 0, nil }
|
||||
func (r fakeResult) RowsAffected() (int64, error) { return int64(r), nil }
|
||||
|
||||
func TestDeleteRangeUsesBareKeys(t *testing.T) {
|
||||
p := New(nil, "db", "t", []string{"id"}, "v > 0", true, false, true)
|
||||
c := &row.Chunk{
|
||||
Keys: []row.Key{row.KeyOf("1001"), row.KeyOf("3000")},
|
||||
// Date scanners set LastKey to a (shard column, key...) cursor.
|
||||
LastKey: row.KeyOf("2025-01-01 00:00:00", "3000"),
|
||||
}
|
||||
exec := &recordingExecer{}
|
||||
|
||||
n, err := p.DeleteChunk(context.Background(), exec, c)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if n != 2 {
|
||||
t.Fatalf("affected = %d", n)
|
||||
}
|
||||
want := "DELETE FROM `db`.`t` WHERE `id` BETWEEN ? AND ? AND (v > 0)"
|
||||
if exec.query != want {
|
||||
t.Fatalf("query:\n got %s\nwant %s", exec.query, want)
|
||||
}
|
||||
if !reflect.DeepEqual(exec.args, []any{"1001", "3000"}) {
|
||||
t.Fatalf("args = %#v", exec.args)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeleteRangeExcludesMaxAutoIncrementKey(t *testing.T) {
|
||||
p := New(nil, "db", "t", []string{"id"}, "1=1", true, true, true)
|
||||
c := &row.Chunk{Keys: []row.Key{row.KeyOf("1001"), row.KeyOf("3000")}}
|
||||
exec := &recordingExecer{}
|
||||
|
||||
maxKey := &row.KeyPart{Val: "3000"}
|
||||
if _, err := p.deleteRange(context.Background(), exec, c, maxKey); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
want := "DELETE FROM `db`.`t` WHERE `id` BETWEEN ? AND ? AND `id` <> ? AND (1=1)"
|
||||
if exec.query != want {
|
||||
t.Fatalf("query:\n got %s\nwant %s", exec.query, want)
|
||||
}
|
||||
if !reflect.DeepEqual(exec.args, []any{"1001", "3000", "3000"}) {
|
||||
t.Fatalf("args = %#v", exec.args)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeleteRangeCompositeKeyUsesBareKeys(t *testing.T) {
|
||||
p := New(nil, "db", "t", []string{"created_at", "id"}, "1=1", true, false, false)
|
||||
c := &row.Chunk{
|
||||
Keys: []row.Key{
|
||||
row.KeyOf("2025-01-01 00:00:00", "1001"),
|
||||
row.KeyOf("2025-01-02 00:00:00", "3000"),
|
||||
},
|
||||
LastKey: row.KeyOf("2025-01-02 00:00:00", "2025-01-02 00:00:00", "3000"),
|
||||
}
|
||||
exec := &recordingExecer{}
|
||||
|
||||
if _, err := p.DeleteChunk(context.Background(), exec, c); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
want := "DELETE FROM `db`.`t` WHERE (`created_at`, `id`) >= (?, ?) AND (`created_at`, `id`) <= (?, ?) AND (1=1)"
|
||||
if exec.query != want {
|
||||
t.Fatalf("query:\n got %s\nwant %s", exec.query, want)
|
||||
}
|
||||
wantArgs := []any{"2025-01-01 00:00:00", "1001", "2025-01-02 00:00:00", "3000"}
|
||||
if !reflect.DeepEqual(exec.args, wantArgs) {
|
||||
t.Fatalf("args = %#v", exec.args)
|
||||
}
|
||||
}
|
||||
@@ -28,6 +28,43 @@ type Entry struct {
|
||||
ClosedAt string `json:"closed_at"`
|
||||
}
|
||||
|
||||
// LoadManifest reads manifest.jsonl strictly for replay. Unlike OpenManifest it
|
||||
// never creates or appends to the archive, and a malformed line is an error
|
||||
// rather than a line to skip: an importer must not mistake corruption for a
|
||||
// missing shard.
|
||||
func LoadManifest(root string) ([]Entry, error) {
|
||||
path := filepath.Join(root, manifestName)
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("open manifest: %w", err)
|
||||
}
|
||||
defer f.Close()
|
||||
|
||||
var entries []Entry
|
||||
sc := bufio.NewScanner(f)
|
||||
sc.Buffer(make([]byte, 0, 64*1024), 4*1024*1024)
|
||||
line := 0
|
||||
for sc.Scan() {
|
||||
line++
|
||||
text := strings.TrimSpace(sc.Text())
|
||||
if text == "" {
|
||||
continue
|
||||
}
|
||||
var e Entry
|
||||
if err := json.Unmarshal([]byte(text), &e); err != nil {
|
||||
return nil, fmt.Errorf("parse manifest.jsonl line %d: %w", line, err)
|
||||
}
|
||||
if e.Path == "" {
|
||||
return nil, fmt.Errorf("manifest.jsonl line %d: missing path", line)
|
||||
}
|
||||
entries = append(entries, e)
|
||||
}
|
||||
if err := sc.Err(); err != nil {
|
||||
return nil, fmt.Errorf("read manifest: %w", err)
|
||||
}
|
||||
return entries, nil
|
||||
}
|
||||
|
||||
// Manifest appends sealed-shard records to manifest.jsonl and knows which
|
||||
// shards already exist.
|
||||
type Manifest struct {
|
||||
|
||||
@@ -0,0 +1,262 @@
|
||||
package shard
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"archer/internal/schema"
|
||||
)
|
||||
|
||||
// Selector is one parsed --select condition. The zero value, Kind "all", holds
|
||||
// only the raw spelling.
|
||||
type Selector struct {
|
||||
Kind string // all|seq|pk|date
|
||||
Raw string
|
||||
|
||||
SeqLo int64
|
||||
SeqHi int64
|
||||
|
||||
Lo string
|
||||
Hi string
|
||||
|
||||
DateLo string
|
||||
DateHi string
|
||||
}
|
||||
|
||||
const dateLayout = "2006-01-02"
|
||||
|
||||
// ParseSelector parses one --select value.
|
||||
func ParseSelector(s string) (Selector, error) {
|
||||
raw := strings.TrimSpace(s)
|
||||
if raw == "" {
|
||||
return Selector{}, fmt.Errorf("--select cannot be empty")
|
||||
}
|
||||
if raw == "all" {
|
||||
return Selector{Kind: "all", Raw: raw}, nil
|
||||
}
|
||||
kind, rest, ok := strings.Cut(raw, ":")
|
||||
if !ok {
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: expected all, seq:A-B, pk:LO-HI or date:D1..D2", raw)
|
||||
}
|
||||
switch kind {
|
||||
case "seq":
|
||||
lo, hi, err := parseSeqRange(rest)
|
||||
if err != nil {
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: %v", raw, err)
|
||||
}
|
||||
return Selector{Kind: "seq", Raw: raw, SeqLo: lo, SeqHi: hi}, nil
|
||||
case "pk":
|
||||
lo, hi, ok := strings.Cut(rest, "-")
|
||||
lo = strings.TrimSpace(lo)
|
||||
hi = strings.TrimSpace(hi)
|
||||
if !ok || lo == "" || hi == "" {
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: expected pk:LO-HI", raw)
|
||||
}
|
||||
return Selector{Kind: "pk", Raw: raw, Lo: lo, Hi: hi}, nil
|
||||
case "date":
|
||||
lo, hi, ok := strings.Cut(rest, "..")
|
||||
lo, hi = strings.TrimSpace(lo), strings.TrimSpace(hi)
|
||||
if !ok || lo == "" || hi == "" {
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: expected date:D1..D2", raw)
|
||||
}
|
||||
if _, err := time.Parse(dateLayout, lo); err != nil {
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: %v", raw, err)
|
||||
}
|
||||
if _, err := time.Parse(dateLayout, hi); err != nil {
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: %v", raw, err)
|
||||
}
|
||||
if lo > hi {
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: date range is reversed", raw)
|
||||
}
|
||||
return Selector{Kind: "date", Raw: raw, DateLo: lo, DateHi: hi}, nil
|
||||
default:
|
||||
return Selector{}, fmt.Errorf("invalid --select %q: unknown selector %q", raw, kind)
|
||||
}
|
||||
}
|
||||
|
||||
func parseSeqRange(s string) (int64, int64, error) {
|
||||
lo, hi, ok := strings.Cut(s, "-")
|
||||
if !ok {
|
||||
return 0, 0, fmt.Errorf("expected A-B")
|
||||
}
|
||||
a, err := strconv.ParseInt(strings.TrimSpace(lo), 10, 64)
|
||||
if err != nil {
|
||||
return 0, 0, fmt.Errorf("bad range start %q", lo)
|
||||
}
|
||||
b, err := strconv.ParseInt(strings.TrimSpace(hi), 10, 64)
|
||||
if err != nil {
|
||||
return 0, 0, fmt.Errorf("bad range end %q", hi)
|
||||
}
|
||||
if a < 0 || b < 0 {
|
||||
return 0, 0, fmt.Errorf("shard sequence numbers cannot be negative")
|
||||
}
|
||||
if a > b {
|
||||
return 0, 0, fmt.Errorf("range is reversed")
|
||||
}
|
||||
return a, b, nil
|
||||
}
|
||||
|
||||
// ParseSelection parses every --select value. An empty list means "all".
|
||||
func ParseSelection(specs []string) ([]Selector, error) {
|
||||
if len(specs) == 0 {
|
||||
return []Selector{{Kind: "all", Raw: "all"}}, nil
|
||||
}
|
||||
out := make([]Selector, 0, len(specs))
|
||||
for _, s := range specs {
|
||||
sel, err := ParseSelector(s)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out = append(out, sel)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// ApplySelection returns the deduplicated, ordered entries matched by sels.
|
||||
// Order follows the archive: bucket order (NULL, zero dates, real dates) and
|
||||
// then ascending seq, which is also the order a serial import should use.
|
||||
// Warnings describe boundary shards whose whole contents will be imported even
|
||||
// though only part of their key range was requested.
|
||||
func ApplySelection(entries []Entry, sels []Selector) ([]Entry, []string, error) {
|
||||
if len(sels) == 0 {
|
||||
sels = []Selector{{Kind: "all", Raw: "all"}}
|
||||
}
|
||||
hasDate := false
|
||||
hasAll := false
|
||||
var pkSelectors []Selector
|
||||
for _, s := range sels {
|
||||
switch s.Kind {
|
||||
case "date":
|
||||
for _, e := range entries {
|
||||
if e.Date != "" {
|
||||
hasDate = true
|
||||
break
|
||||
}
|
||||
}
|
||||
case "all":
|
||||
hasAll = true
|
||||
case "pk":
|
||||
pkSelectors = append(pkSelectors, s)
|
||||
}
|
||||
}
|
||||
for _, s := range sels {
|
||||
if s.Kind == "date" && !hasDate {
|
||||
return nil, nil, fmt.Errorf("archive has no date buckets (it was not exported with --shard-by date); --select date:%s..%s cannot be used", s.DateLo, s.DateHi)
|
||||
}
|
||||
}
|
||||
|
||||
seen := map[string]bool{}
|
||||
var selected []Entry
|
||||
var warnings []string
|
||||
for _, e := range entries {
|
||||
matched, pkFunded := matchEntry(e, sels)
|
||||
if !matched {
|
||||
continue
|
||||
}
|
||||
key := e.Date + "\x00" + strconv.FormatInt(e.Seq, 10)
|
||||
if seen[key] {
|
||||
continue
|
||||
}
|
||||
seen[key] = true
|
||||
selected = append(selected, e)
|
||||
if pkFunded && !hasAll {
|
||||
if w, ok := pkBoundaryWarning(e, pkSelectors); ok {
|
||||
warnings = append(warnings, w)
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(selected) == 0 {
|
||||
return nil, nil, fmt.Errorf("no shards matched the given --select conditions")
|
||||
}
|
||||
sort.Slice(selected, func(i, j int) bool {
|
||||
if selected[i].Date != selected[j].Date {
|
||||
return schema.BucketLess(selected[i].Date, selected[j].Date)
|
||||
}
|
||||
if selected[i].Seq != selected[j].Seq {
|
||||
return selected[i].Seq < selected[j].Seq
|
||||
}
|
||||
return selected[i].Path < selected[j].Path
|
||||
})
|
||||
return selected, warnings, nil
|
||||
}
|
||||
|
||||
func matchEntry(e Entry, sels []Selector) (matched bool, pk bool) {
|
||||
for _, s := range sels {
|
||||
switch s.Kind {
|
||||
case "all":
|
||||
return true, false
|
||||
case "seq":
|
||||
if e.Seq >= s.SeqLo && e.Seq <= s.SeqHi {
|
||||
return true, false
|
||||
}
|
||||
case "date":
|
||||
if e.Date != "" && e.Date >= s.DateLo && e.Date <= s.DateHi {
|
||||
return true, false
|
||||
}
|
||||
case "pk":
|
||||
if pkOverlap(e, s) {
|
||||
return true, true
|
||||
}
|
||||
}
|
||||
}
|
||||
return false, false
|
||||
}
|
||||
|
||||
func pkOverlap(e Entry, s Selector) bool {
|
||||
if e.PKLo == "" || e.PKHi == "" {
|
||||
return false
|
||||
}
|
||||
return CompareKeyText(e.PKHi, s.Lo) >= 0 && CompareKeyText(e.PKLo, s.Hi) <= 0
|
||||
}
|
||||
|
||||
func containedInAnyPK(e Entry, sels []Selector) bool {
|
||||
for _, s := range sels {
|
||||
if CompareKeyText(e.PKLo, s.Lo) >= 0 && CompareKeyText(e.PKHi, s.Hi) <= 0 {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func pkBoundaryWarning(e Entry, sels []Selector) (string, bool) {
|
||||
if containedInAnyPK(e, sels) {
|
||||
return "", false
|
||||
}
|
||||
for _, s := range sels {
|
||||
if !pkOverlap(e, s) {
|
||||
continue
|
||||
}
|
||||
return fmt.Sprintf(
|
||||
"shard %d covers pk [%s, %s]; requested %s overlaps it, so rows outside the requested range will be imported too",
|
||||
e.Seq, emptyAs(e.PKLo, "?"), emptyAs(e.PKHi, "?"), s.Raw), true
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
// CompareKeyText compares two key fragments, using numeric order when both are
|
||||
// integers and lexical order otherwise.
|
||||
func CompareKeyText(a, b string) int {
|
||||
ai, aErr := strconv.ParseInt(a, 10, 64)
|
||||
bi, bErr := strconv.ParseInt(b, 10, 64)
|
||||
if aErr == nil && bErr == nil {
|
||||
switch {
|
||||
case ai < bi:
|
||||
return -1
|
||||
case ai > bi:
|
||||
return 1
|
||||
default:
|
||||
return 0
|
||||
}
|
||||
}
|
||||
return strings.Compare(a, b)
|
||||
}
|
||||
|
||||
func emptyAs(s, fallback string) string {
|
||||
if s == "" {
|
||||
return fallback
|
||||
}
|
||||
return s
|
||||
}
|
||||
@@ -0,0 +1,131 @@
|
||||
package shard
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func sampleEntries() []Entry {
|
||||
return []Entry{
|
||||
{Seq: 1, Path: "000001.1-100.dump", PKLo: "1", PKHi: "100", Rows: 100},
|
||||
{Seq: 2, Path: "000002.101-200.dump", PKLo: "101", PKHi: "200", Rows: 100},
|
||||
{Seq: 3, Path: "000003.201-300.dump", PKLo: "201", PKHi: "300", Rows: 100},
|
||||
{Seq: 4, Path: "000004.301-400.dump", PKLo: "301", PKHi: "400", Rows: 100},
|
||||
}
|
||||
}
|
||||
|
||||
func mustSelect(t *testing.T, entries []Entry, specs ...string) ([]Entry, []string) {
|
||||
t.Helper()
|
||||
sels, err := ParseSelection(specs)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
out, warnings, err := ApplySelection(entries, sels)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return out, warnings
|
||||
}
|
||||
|
||||
func seqs(entries []Entry) []int64 {
|
||||
out := make([]int64, len(entries))
|
||||
for i, e := range entries {
|
||||
out[i] = e.Seq
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func TestSelectAllByDefault(t *testing.T) {
|
||||
got, _ := mustSelect(t, sampleEntries())
|
||||
if len(got) != 4 {
|
||||
t.Fatalf("got %d", len(got))
|
||||
}
|
||||
}
|
||||
|
||||
func TestSelectSeqRange(t *testing.T) {
|
||||
got, _ := mustSelect(t, sampleEntries(), "seq:2-3")
|
||||
if len(got) != 2 || got[0].Seq != 2 || got[1].Seq != 3 {
|
||||
t.Fatalf("got %v", seqs(got))
|
||||
}
|
||||
}
|
||||
|
||||
func TestSelectPKIntersection(t *testing.T) {
|
||||
got, warnings := mustSelect(t, sampleEntries(), "pk:150-250")
|
||||
if len(got) != 2 || got[0].Seq != 2 || got[1].Seq != 3 {
|
||||
t.Fatalf("got %v", seqs(got))
|
||||
}
|
||||
if len(warnings) != 2 {
|
||||
t.Fatalf("expected boundary warnings, got %v", warnings)
|
||||
}
|
||||
if !strings.Contains(warnings[0], "150") {
|
||||
t.Fatalf("warning should name the requested bound: %v", warnings)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSelectPKContainedNoWarning(t *testing.T) {
|
||||
got, warnings := mustSelect(t, sampleEntries(), "pk:101-200")
|
||||
if len(got) != 1 || got[0].Seq != 2 {
|
||||
t.Fatalf("got %v", seqs(got))
|
||||
}
|
||||
if len(warnings) != 0 {
|
||||
t.Fatalf("unexpected warnings: %v", warnings)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSelectUnionDedupes(t *testing.T) {
|
||||
got, _ := mustSelect(t, sampleEntries(), "seq:1-2", "seq:2-3")
|
||||
if len(got) != 3 || got[0].Seq != 1 || got[1].Seq != 2 || got[2].Seq != 3 {
|
||||
t.Fatalf("got %v", seqs(got))
|
||||
}
|
||||
}
|
||||
|
||||
func TestSelectEmptyIsError(t *testing.T) {
|
||||
sels, _ := ParseSelection([]string{"seq:9-10"})
|
||||
if _, _, err := ApplySelection(sampleEntries(), sels); err == nil || !strings.Contains(err.Error(), "no shards matched") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSelectDateOnNonDateArchive(t *testing.T) {
|
||||
sels, _ := ParseSelection([]string{"date:2025-01-01..2025-01-31"})
|
||||
if _, _, err := ApplySelection(sampleEntries(), sels); err == nil || !strings.Contains(err.Error(), "not exported with --shard-by date") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSelectDateBucket(t *testing.T) {
|
||||
entries := []Entry{
|
||||
{Seq: 1, Path: "date=2025-01-01/000001.1-1.dump", Date: "2025-01-01", PKLo: "1", PKHi: "1"},
|
||||
{Seq: 1, Path: "date=2025-01-02/000001.2-2.dump", Date: "2025-01-02", PKLo: "2", PKHi: "2"},
|
||||
{Seq: 2, Path: "date=2025-01-02/000002.3-3.dump", Date: "2025-01-02", PKLo: "3", PKHi: "3"},
|
||||
{Seq: 1, Path: "date=2025-01-03/000001.4-4.dump", Date: "2025-01-03", PKLo: "4", PKHi: "4"},
|
||||
}
|
||||
got, _ := mustSelect(t, entries, "date:2025-01-02..2025-01-02")
|
||||
if len(got) != 2 {
|
||||
t.Fatalf("got %d entries", len(got))
|
||||
}
|
||||
// Seq repeats across buckets; dedupe must not collapse them.
|
||||
if got[0].Path != entries[1].Path || got[1].Path != entries[2].Path {
|
||||
t.Fatalf("wrong entries: %+v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestParseSelectorErrors(t *testing.T) {
|
||||
for _, s := range []string{"", "seq", "seq:1", "seq:a-b", "seq:3-1", "pk:1", "date:2025-01-01", "date:2025-01-02..2025-01-01", "nope:1"} {
|
||||
if _, err := ParseSelector(s); err == nil {
|
||||
t.Fatalf("%q: expected an error", s)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestCompareKeyText(t *testing.T) {
|
||||
if CompareKeyText("9", "10") >= 0 {
|
||||
t.Fatal("numeric keys must sort numerically")
|
||||
}
|
||||
if CompareKeyText("a", "b") >= 0 {
|
||||
t.Fatal("non-numeric keys must sort lexically")
|
||||
}
|
||||
if CompareKeyText("5", "5") != 0 {
|
||||
t.Fatal("equal keys must compare equal")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-08
|
||||
@@ -0,0 +1,50 @@
|
||||
## Context
|
||||
|
||||
现状与动机见 `proposal.md`。与设计直接相关的约束:
|
||||
|
||||
- 日期扫描器(路径 A/B)按 `(分片列, 唯一键)` 排序,并把 `chunk.LastKey` 改写为 `(分片列, 键...)` 的复合游标用于续跑;`chunk.FirstKey` 仍是裸键(`internal/scan/date_a.go:72-73`、`internal/scan/date_b.go:87-92`)。
|
||||
- `Purger.deleteRange` 原先直接使用 `FirstKey/LastKey`(`internal/purge/purge.go`)。放开日期模式后,单列主键会生成 `id BETWEEN <首键> AND <日期>`,复合键则因 `lo` 与 `hi` 长度不同导致参数个数不匹配。
|
||||
- `DeleteChunk` 在 `--safe-auto-increment=true`(默认)且键为单列自增列时先取 `MAX(pk)`;原逻辑只要 `maxKey != nil` 就退回 IN 列表,因此默认配置下 `--bulk-delete` 实际上从不执行区间删除。
|
||||
- “日期随主键递增、无回填、无 NULL/零日期”是业务承诺,运行期无法可靠验证:单个 chunk 内的键单调性检查无法发现“整块迟到数据自成一个 chunk”的情况。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 在业务承诺成立时,日期模式可以使用区间删除。
|
||||
- 区间删除严格对应本次 chunk 读到的裸键范围,不因续跑游标的形状而越界。
|
||||
- 保留 `--safe-auto-increment` 的语义:任何 purge 模式都不删除当前最大自增行。
|
||||
- 风险以启动警告、spec 和 README 明确表达,而不是静默承担。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 运行期校验全局单调不变量。
|
||||
- 自动检测回填、迟到数据或 NULL/零日期。
|
||||
- 改变默认删除方式(不使用 `--bulk-delete` 时仍是 IN 列表)。
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1:放开校验,用启动警告承载风险
|
||||
|
||||
删除 `validate.go` 中“日期模式禁止 `--bulk-delete`”的分支,在 `App.execute` 中新增一条仅日期模式出现的警告。替代方案是新增一个 `--allow-unsafe-date-bulk` 之类的二次开关,但那会增加一个只为绕过自身校验而存在的参数;风险提示已经足以表达“这是显式承担前提”。
|
||||
|
||||
### D2:区间边界取 `chunk.Keys` 首尾
|
||||
|
||||
`Keys` 与扫描行一一对应且始终是裸唯一键;`FirstKey/LastKey` 中的 `LastKey` 会被日期扫描器改写成复合游标。改用 `c.Keys[0]` 与 `c.Keys[len-1]` 后,非日期模式的行为完全不变(两者本就相等),日期模式则得到正确的裸键区间。`FirstKey/LastKey` 继续只承担分片与 checkpoint 职责,不改变其语义。
|
||||
|
||||
### D3:区间删除中排除当前最大键,而不是退回 IN 列表
|
||||
|
||||
当 `--safe-auto-increment` 生效时,仍先查询 `MAX(pk)`,但区间 SQL 追加 `AND pk <> ?`,参数为当前最大键。最大键不在区间内时该条件无效果;在区间内时恰好跳过该行。这样默认配置下 `--bulk-delete` 真正生效,同时保持“不删除当前最大自增行”的契约。复合键或非自增键不会设置 `maxKey`,SQL 保持原样。
|
||||
|
||||
替代方案是在区间删除时把上界改成开区间 `pk < max`,但需要比较 `hi` 与 `maxKey` 的大小并处理并发删除导致的 `hi > max` 情形;`<>` 更简单且对越界情况天然安全。
|
||||
|
||||
### D4:测试分两层
|
||||
|
||||
- 单元测试:用记录型 `Execer` 直接驱动 `deleteRange`,覆盖日期式 `LastKey`、单列/复合键、以及最大键排除三种 SQL 形状。
|
||||
- 集成测试:`TestIntegrationDateBulkDelete` 在 `(created_at, id)` 联合索引上分别验证 `--safe-auto-increment=false` 全删、默认开启时保留最大行;无 `ARCHER_TEST_DSN` 时自动跳过。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **回填/迟到数据仍会误删** → 业务承诺无法运行期验证。缓解:启动警告、spec 与 README 明确前提;建议在生产使用前先用 `--dry-run` 与只导出运行核对。出现回填时应回到默认 IN 列表删除。
|
||||
- **`--bulk-delete` 的并发窗口仍然存在** → 与既有取舍一致:区间内新插入且满足 `--where` 的行可能被删。日期模式下该风险进一步依赖“日期随主键递增”的假设。
|
||||
- **`pk <> MAX(pk)` 在并发删除时可能多保留一行** → 只影响“少删”,方向安全;与 IN 列表模式跳过最大行的行为一致。
|
||||
@@ -0,0 +1,32 @@
|
||||
## Why
|
||||
|
||||
日期分片按 `(分片列, 唯一键)` 排序,日期序与主键序可能不一致。早期设计为规避“区间跨日期误删尚未归档的数据”,直接在启动校验阶段禁止了 `--shard-by date` 与 `--bulk-delete` 的组合。
|
||||
|
||||
对于业务上能保证“日期随主键递增、无回填、无 NULL/零日期”的表,这个限制堵死了一条本可安全使用的高吞吐删除路径。本次改动按“显式承担该前提”的方式放开限制,同时修正两处在放开后会暴露的问题:区间边界取错,以及默认 `--safe-auto-increment` 会让区间删除静默退回 IN 列表。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 允许 `--shard-by date` 与 `--bulk-delete` 同时使用;启动时打印前提警告。
|
||||
- 区间删除的边界改为 chunk 实际读取行的裸唯一键首尾,不再使用日期扫描器为续跑改写的 `(分片列, 键...)` 复合游标。
|
||||
- 修正 `--safe-auto-increment` 与 `--bulk-delete` 的交互:区间删除不再退回 IN 列表,而是在 SQL 中显式排除当前最大自增键。
|
||||
- 同步 `archive-core` 与 `cli-contract` 的行为契约,以及 README 的安全说明。
|
||||
|
||||
**Non-goals:**
|
||||
|
||||
- 不在运行期验证“日期随主键递增、无回填”这一不变量。
|
||||
- 不自动识别或隔离迟到/回填数据。
|
||||
- 不改变 chunk 即事务、提交顺序、checkpoint 等既有语义。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `archive-core`:日期模式下允许区间删除,明确其安全前提;区间边界取 chunk 裸键首尾;`--safe-auto-increment` 在区间删除中以排除最大键的方式生效。
|
||||
- `cli-contract`:参数依赖与互斥规则中移除“`--bulk-delete` 在日期模式下禁止”。
|
||||
|
||||
## Impact
|
||||
|
||||
- 代码:`internal/cli/validate.go`(删除日期模式校验)、`internal/purge/purge.go`(区间边界与最大键排除)、`internal/app/app.go`(日期模式启动警告)。
|
||||
- 测试:新增 `internal/purge/purge_test.go` 单元测试;新增 `TestIntegrationDateBulkDelete` 集成测试。
|
||||
- 文档:`README.md`、`openspec/specs/{archive-core,cli-contract}/spec.md`。
|
||||
- 兼容性:此前被拒绝的配置现在可以启动;未使用 `--bulk-delete` 的任务行为不变。
|
||||
@@ -0,0 +1,30 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 删除语义
|
||||
|
||||
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按 chunk 实际读取行的首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`。日期分片模式下,区间删除仅在“分片列相对扫描键单调、无回填”的前提下安全,系统 SHALL 允许该组合并在启动时打印该前提警告。
|
||||
|
||||
#### Scenario: 默认 IN 列表删除
|
||||
|
||||
- **WHEN** 一个 chunk 读取到主键 1001..3000,且 `--where "created_at < '2026-01-01'"`
|
||||
- **THEN** 系统生成 `DELETE ... WHERE id IN (1001,...,3000)`,不删除未被读取的行
|
||||
|
||||
#### Scenario: 区间删除附带回填条件
|
||||
|
||||
- **WHEN** 启用 `--bulk-delete`,chunk 首尾主键为 1001 与 3000
|
||||
- **THEN** 系统生成 `DELETE ... WHERE id BETWEEN 1001 AND 3000 AND (<where>)`
|
||||
|
||||
#### Scenario: 日期模式启用区间删除
|
||||
|
||||
- **WHEN** `--shard-by date` 与 `--bulk-delete` 同时出现
|
||||
- **THEN** 系统允许执行,并在启动时警告:该组合要求分片列永不相对扫描键回退,否则迟到或回填的行可能在归档前被删除
|
||||
|
||||
#### Scenario: 日期模式使用裸键区间
|
||||
|
||||
- **WHEN** 日期扫描器把 chunk 的 `LastKey` 改写为 `(分片列, 键...)` 的续跑游标
|
||||
- **THEN** 区间删除仍使用 chunk 实际读取行的裸唯一键首尾,不把分片列拼入删除上界
|
||||
|
||||
#### Scenario: 区间删除保留最大自增行
|
||||
|
||||
- **WHEN** 启用 `--bulk-delete` 且 `--safe-auto-increment` 为默认值,chunk 区间包含源表当前 `MAX(pk)`
|
||||
- **THEN** 区间删除语句额外排除该最大键,最大行不被删除,其余区间内行正常删除
|
||||
@@ -0,0 +1,25 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 参数依赖与互斥
|
||||
|
||||
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge`;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误。违反时 MUST 在启动阶段报错。
|
||||
|
||||
#### Scenario: 数量模式误传日期列
|
||||
|
||||
- **WHEN** `--shard-by count` 同时带上 `--shard-column`
|
||||
- **THEN** 系统报错,说明该参数仅在日期模式下有效
|
||||
|
||||
#### Scenario: 未启用 purge 却要求 bulk-delete
|
||||
|
||||
- **WHEN** 用户指定 `--bulk-delete` 但未指定 `--purge`
|
||||
- **THEN** 系统报错,说明 bulk-delete 必须配合 purge
|
||||
|
||||
#### Scenario: 日期模式使用 bulk-delete
|
||||
|
||||
- **WHEN** 用户同时指定 `--shard-by date`、`--shard-column`、`--purge` 与 `--bulk-delete`
|
||||
- **THEN** 系统通过启动校验,并在开始扫描前打印区间删除的安全前提警告
|
||||
|
||||
#### Scenario: 插入模式互斥
|
||||
|
||||
- **WHEN** 用户同时指定普通插入、`--insert-ignore` 与 `--replace` 中的多项
|
||||
- **THEN** 系统在启动阶段报错
|
||||
@@ -0,0 +1,26 @@
|
||||
## 1. 校验与启动提示
|
||||
|
||||
- [x] 1.1 删除 `validate.go` 中“`--bulk-delete` 不能与 `--shard-by date` 同时使用”的校验
|
||||
- [x] 1.2 更新 `cli_test.go`:日期模式 + `--bulk-delete` 现在应校验通过
|
||||
- [x] 1.3 在 `App.execute` 中为日期模式 + `--bulk-delete` 增加前提警告
|
||||
|
||||
## 2. 区间删除
|
||||
|
||||
- [x] 2.1 `deleteRange` 的区间边界改为 `chunk.Keys` 首尾,避免使用被日期扫描器改写为复合游标的 `LastKey`
|
||||
- [x] 2.2 `--safe-auto-increment` 生效时,区间 SQL 追加 `AND <key> <> ?` 排除当前最大键,不再退回 IN 列表
|
||||
|
||||
## 3. 测试
|
||||
|
||||
- [x] 3.1 单元测试:日期式 chunk 下单列主键生成裸键 `BETWEEN`
|
||||
- [x] 3.2 单元测试:日期式 chunk 下复合键生成正确的元组区间与参数个数
|
||||
- [x] 3.3 单元测试:`--safe-auto-increment` 下区间删除附带最大键排除条件
|
||||
- [x] 3.4 集成测试 `TestIntegrationDateBulkDelete`:安全开关关闭时全删、默认开启时保留最大行
|
||||
- [x] 3.5 `gofmt`、`go build ./...`、`go vet ./...`、`go test ./...` 通过
|
||||
|
||||
## 4. 文档与 OpenSpec
|
||||
|
||||
- [x] 4.1 更新 `openspec/specs/archive-core/spec.md` 的删除语义与日期模式场景
|
||||
- [x] 4.2 更新 `openspec/specs/cli-contract/spec.md` 的参数依赖与互斥规则
|
||||
- [x] 4.3 更新 README 安全说明
|
||||
- [x] 4.4 运行 `openspec validate allow-date-bulk-delete --strict`
|
||||
- [ ] 4.5 在具备 MySQL 的环境中运行集成测试并完成归档
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-08
|
||||
@@ -0,0 +1,153 @@
|
||||
## Context
|
||||
|
||||
动机见 `proposal.md`。与本设计直接相关的现状:
|
||||
|
||||
- 归档目录由 `manifest.jsonl`(`internal/shard/manifest.go` 的 `Entry`:`seq`、`path`、`date`、`pk_lo`、`pk_hi`、`rows`、`bytes`、`sha256`)与 `state.json`(`internal/checkpoint.State`:`config`、`complete`)描述。
|
||||
- 全列导出取 `information_schema.COLUMNS` 的全部列并按 ordinal 排序(`probe.go:81-85`、`schema.go:241-247`),包含生成列与不可见列;文件没有列名,`state.json` 只保存原始 `--columns` 字符串,不保存解析后的列名与顺序。
|
||||
- 每个分片独立压缩,`internal/shard/compress.go` 的 `Compressor.Reader` 已能把 gzip/zstd/xz 包装成 `io.ReadCloser`。
|
||||
- 当前 `cmd/archer/main.go` 直接把所有参数交给单一 `flag.FlagSet`;`cli.Config.Validate` 强制要求 `--source`/`--table`/`--where`,导入不能复用这套校验。
|
||||
- `internal/sink.DB` 已实现按 `max_allowed_packet` 分批的参数化多行 `INSERT`,可直接作为插入引擎。
|
||||
- 驱动 `go-sql-driver/mysql` 在握手中无条件发送 `clientLocalFiles`(`packets.go:288`);`LOAD DATA LOCAL INFILE 'Reader::<name>'` 只查 `RegisterReaderHandler` 注册表(`infile.go:105`),不要求 `allowAllFiles`,也不暴露任意文件读取。
|
||||
- MySQL 8.0.3+ 的 `local_infile` 默认关闭;MariaDB 默认开启;托管库由参数组控制。代理/连接池可能不转发本地文件请求。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 按清单安全、可重复、可选择范围地把归档重放进 MySQL。
|
||||
- 复用现有分片、压缩、错误分类与进度基础设施,不改变导出端格式。
|
||||
- 在受限环境(`local_infile` 关闭、经过代理)仍提供可用的兜底路径。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不做行级过滤、断点续导台账或导入状态持久化。
|
||||
- 不自动建表、不推导/迁移表结构。
|
||||
- 不引入服务化入口或第二个二进制。
|
||||
- 不在 v1 支持 csv/jsonl 导入。
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1:同一二进制内的 `import` 子命令
|
||||
|
||||
`main.go` 在解析参数前检查 `os.Args[1] == "import"`,命中则交给 `internal/importer` 的独立解析与运行路径;其余参数仍走现有 `cli.Parse`。这样对现有导出调用完全向后兼容,也不需要拆分仓库或构建两套产物。
|
||||
|
||||
替代方案是新增 `cmd/archer-import` 二进制,但导入要复用清单解析、压缩、错误码、进度与插入实现,独立二进制只会增加发布与版本对齐成本,收益接近于零。
|
||||
|
||||
### D2:清单使用严格只读加载器
|
||||
|
||||
现有 `Manifest.readExisting` 会静默跳过无法解析的行,这对导出续跑是合理的容错,但导入不能把损坏行当成“分片不存在”。新增只读加载函数(例如 `shard.LoadManifest(root)`):逐行解析,遇到非法 JSON 立即报错;不打开 `O_APPEND` 句柄,不修改归档目录。`Entry` 结构保持不变。
|
||||
|
||||
### D3:完成度以 `state.json` 为准,默认拒绝部分归档
|
||||
|
||||
导入前调用 `checkpoint.Load`。默认要求 `complete == true`;`state.json` 缺失或 `complete == false` 时,只有在 `--allow-partial` 下才继续。理由:分片清单只能证明“这些分片已封”,不能证明“导出已覆盖全表”。
|
||||
|
||||
### D4:选择粒度到分片,主键区间按相交语义
|
||||
|
||||
`--select` 可重复,解析为选择器集合,按 `seq` 去重排序:
|
||||
|
||||
- `all`:全部清单条目;
|
||||
- `seq:A-B`:`A <= seq <= B`;
|
||||
- `pk:LO-HI`:分片的 `[pk_lo, pk_hi]` 与 `[LO, HI]` 相交即入选;
|
||||
- `date:D1..D2`:`Entry.Date` 落入闭区间。`count` 分片的 `Date` 为空(`writer.go:357` 只在日期模式下写 bucket),因此对非日期归档按日期选择必须报错。
|
||||
|
||||
`LOAD DATA` 不能过滤行,所以 `pk:`/`date:` 的边界分片会带入范围外的行。`--dry-run` 与启动摘要必须显式提示这一点,避免用户误以为“只导入这个主键段”。
|
||||
|
||||
替代方案是把边界分片解压后逐行过滤再装载,但那样既要写解码器又要丢弃 `LOAD DATA` 的性能优势,v1 不值得。
|
||||
|
||||
### D5:格式与压缩从清单路径推导,v1 只接受 dump
|
||||
|
||||
`Entry.Path` 形如 `<seq>.<lo>-<hi>.<format>[.<comp>]`。导入从扩展名推导格式与压缩器,并要求所有选中条目一致;推导结果不是 `dump` 时报错。这样无需修改归档格式,也对 `none/gzip/zstd/xz` 全部生效。
|
||||
|
||||
### D6:SHA-256 预校验,而不是边导边校验
|
||||
|
||||
`--verify pre`(默认)先以流式读取压缩文件计算 SHA-256,与清单比对,通过后再打开一次用于解压装载。
|
||||
|
||||
替代方案是边装载边计算哈希,末尾不一致时回滚该分片。它省一次顺序读,但要求把整个分片放进一个大事务,且 `LOAD DATA` 在事务中的回滚代价与内存行为不易预测。压缩分片通常是几 MB 到几 GB,额外的顺序读是磁盘带宽级别,远比事务风险便宜。
|
||||
|
||||
### D7:`load` 引擎用注册的流式 Reader,不落临时文件
|
||||
|
||||
每个 worker 持有自己的 `*sql.Conn`,装载单个分片时:
|
||||
|
||||
1. 为分片生成唯一 handler 名(如 `archer-import-<pid>-<seq>-<nonce>`);
|
||||
2. `mysql.RegisterReaderHandler(name, func() io.Reader { ... })` 返回解压 Reader;
|
||||
3. 执行 `LOAD DATA LOCAL INFILE 'Reader::<name>' ...`;
|
||||
4. `DeregisterReaderHandler(name)`。
|
||||
|
||||
字段规则与 `internal/row/dump.go` 的编码严格对应:
|
||||
|
||||
```sql
|
||||
LOAD DATA LOCAL INFILE 'Reader::<name>'
|
||||
INTO TABLE <db>.<table>
|
||||
CHARACTER SET <charset>
|
||||
FIELDS TERMINATED BY '\t' ESCAPED BY '\\'
|
||||
LINES TERMINATED BY '\n'
|
||||
-- 可选: (col1, col2, ...)
|
||||
```
|
||||
|
||||
模式映射为语句中的 `IGNORE` / `REPLACE` 关键字;`insert` 模式不带关键字。会话级 `time_zone` 在连接建立后设置。
|
||||
|
||||
### D8:`insert` 引擎复用 `sink.DB`,每个分片一个事务
|
||||
|
||||
`--engine insert` 使用 `internal/sink.DB.InsertChunk` 的同一套分批逻辑,但输入来自解压后的行解码,而不是扫描结果。为保持“分片失败不留半截数据”,每个分片的所有批次 MUST 包在同一个事务中;这比 `LOAD DATA` 的单语句事务粒度更粗,但只作为兜底路径。
|
||||
|
||||
v1 的 `insert` 引擎同样只支持 `dump`:按行 Split 后把字段转成 `row.Value`(`\N` → NULL,反转义表与 `dumpEncoder` 对称)。这需要一个最小的 dump 解码器;csv/jsonl 的解码各自有歧义或类型依赖,留待后续。
|
||||
|
||||
### D9:启动探测 `local_infile`,失败即停,不静默降级
|
||||
|
||||
在建立目标连接后、装载任何分片前,执行 `SELECT @@local_infile, @@version`。`--engine load` 且值为 0 时返回配置类错误,错误信息同时给出“启用 local_infile”和“改用 `--engine insert`”两条出路。
|
||||
|
||||
静默回退会让几十 GB 的导入从分钟级变成小时级且用户毫无察觉,违背本仓库既有的 fail-fast 风格。
|
||||
|
||||
### D10:列映射按列名,字段数只做前置检查
|
||||
|
||||
先明确归档里到底有什么:全列导出取的是 `information_schema.COLUMNS` 的全部列、按 `ORDINAL_POSITION` 排序(`probe.go:81-85`、`schema.go:241-247`),包含生成列与不可见列;文件本身没有列名。`state.json` 只记录原始 `--columns` 字符串,为空表示“导出时全部列”,**不记录解析后的列名与顺序**。
|
||||
|
||||
因此“文件字段数 == 目标表列数”既不是充分条件(同数换列、改名、交换顺序都能通过),也不应作为映射依据。字段数只用于在装载前给出更早、更清晰的错误。
|
||||
|
||||
列映射按以下优先级确定:
|
||||
|
||||
1. **归档记录了列清单**(`state.json` 的 `columns` 非空):按记录顺序生成 `LOAD DATA` 列清单;逐个校验列名存在于目标表;若记录中包含目标表的生成列,直接报错(生成列不能从归档写入)。
|
||||
2. **`--columns`**:用户按文件字段顺序给出目标列名,做与上一条相同的名校验。它与归档记录的列清单互斥,避免两套来源冲突。
|
||||
3. **`--assume-all-columns`**:接受位置映射。按目标表全部列的 ordinal 顺序生成列清单;生成列替换为丢弃用的用户变量(`@_archer_skip_<i>`),由目标表重新计算;首行字段数必须等于清单长度;启动时打印位置映射警告。
|
||||
4. 以上都不可用时拒绝导入,提示用户提供 `--columns` 或显式接受 `--assume-all-columns`。
|
||||
|
||||
使用显式列清单还能消除 `LOAD DATA` 对不可见列是否计入“全部列”的歧义,因为不可见列可以被显式命名并写入。
|
||||
|
||||
不做自动建表:归档没有记录 DDL,猜测 schema 的风险远大于收益。需要“装到全新实例”时,用户应先建同构表。把有序列名、类型与 `SHOW CREATE TABLE` 写进归档,是让默认全列导出也能严格校验的根治方案,作为后续独立的导出侧改动。
|
||||
|
||||
### D11:告警与行数核对依赖同一会话
|
||||
|
||||
驱动的 `Result` 只暴露 affected rows,不能读取 LOAD DATA 的 `Records/Skipped/Warnings` 信息串。因此每个 worker 必须用固定 `*sql.Conn`(而不是连接池),在装载后立即执行 `SHOW WARNINGS`:
|
||||
|
||||
- 有告警且未指定 `--allow-warnings`:该分片失败;例外是 `ignore` 模式下唯一键冲突产生的告警(错误码 1062),它们是“跳过”而非数据缺陷,已被行数规则计入跳过行数,否则默认 `ignore` 无法做到重复导入幂等;
|
||||
- 行数规则:`insert` 模式要求 affected == 清单 `rows`;`ignore` 模式要求 affected <= `rows`,差额报告为跳过;`replace` 模式的 affected 可能大于 `rows`(覆盖计为删除+插入),只报告不强制相等。
|
||||
|
||||
这比“解析 OK 包信息串”更依赖会话,但驱动没有暴露后者;使用固定连接也顺带保证 `time_zone`/`character_set` 等会话设置不被连接池复用破坏。
|
||||
|
||||
### D12:进度与统计复用现有组件
|
||||
|
||||
`internal/progress.Reporter` 以清单总行数为总量,按分片完成/行数推进;`--statistics` 输出选片数、成功/失败/跳过分片数、期望/实际/跳过行数、字节与耗时。`--dry-run` 只读清单与首行(用于字段数),不连接目标库,也不装载。
|
||||
|
||||
### D13:失败即停,分片原子
|
||||
|
||||
默认在首个失败分片处终止,并报告该分片 `seq`、失败原因与失败前的累计行数。`load` 引擎的单条 `LOAD DATA` 在 InnoDB 下是原子的;`insert` 引擎用每分片一个事务保证同样的可见性。已完成分片不回滚,重跑依赖 `--mode ignore` 的幂等性。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **`local_infile` 被安全基线关闭** → 提供 `--engine insert`;启动时明确报错而不是降级。走代理/连接池时需实测,必要时直连目标实例。
|
||||
- **字符集导致非 ASCII/BLOB 失真** → 默认 `--charset utf8mb4`,提供 `--charset binary`;集成测试覆盖中文、emoji、BLOB、TAB/换行/反斜杠/NULL。
|
||||
- **`TIMESTAMP` 时区漂移** → 归档未记录导出会话时区;提供 `--time-zone` 显式设置目标会话时区,文档说明风险,测试覆盖显式设置与默认两种情况。
|
||||
- **导回线上表造成锁等待/主从延迟** → 默认 `--workers 1`,文档建议低峰执行并监控;`LOAD DATA` 的行锁范围取决于目标表索引。
|
||||
- **部分导入给出不完整查询结果** → 启动与结束摘要显式列出导入范围与行数;`--dry-run` 强制先看选片。
|
||||
- **再次归档边界** → 导回原表的行可能落在下一次归档的 `--where` 范围内;文档提醒归档条件应覆盖“纯冷时间段”。
|
||||
- **位置映射无法发现“同数换列/改名”** → `--assume-all-columns` 只保证字段数一致并打印警告,不具备名校验能力;严格场景要求归档列清单或显式 `--columns`。根治方案是后续让导出端记录有序列名。
|
||||
- **生成列与不可见列** → `--assume-all-columns` 下生成列映射为丢弃变量、由目标表重算;记录列清单包含生成列时直接报错;不可见列通过显式列清单写入。
|
||||
- **没有导入台账** → 依赖 `ignore` 幂等;`insert`/`replace` 重跑可能失败或覆盖,文档明确这一点。
|
||||
- **`SHOW WARNINGS` 需要同会话** → 强制使用 `*sql.Conn`,并在测试中覆盖连接复用场景。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
- 纯增量:现有导出行为、文件格式、清单与 `state.json` 均不变。
|
||||
- 发布:与现有二进制一同构建;`archer import` 对新旧归档都可用。
|
||||
- 回滚:不调用 `import` 子命令即可;已导入的数据需要按业务自行清理。
|
||||
- 后续独立改动(不在本 change 内):归档记录 `format`/`columns`/`charset`/`time_zone` 与 `SHOW CREATE TABLE`,以支持自动建表和更强的核对。
|
||||
@@ -0,0 +1,46 @@
|
||||
## Why
|
||||
|
||||
归档把冷数据移出了热表,但“冷”不等于“永不查询”。目前把归档文件装回 MySQL 只能按 `docs/output-formats.md` 手工 `zcat | mysql`:没有范围选择、没有完整性校验、没有幂等保证,导错或导到一半都会污染原表,而且失败后无法判断哪些分片已经落入。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增 `archer import` 子命令,与导出共用同一个二进制;导入逻辑独立成 `internal/importer` 包。
|
||||
- 以归档目录中的 `manifest.jsonl` 为唯一权威:只导入清单中登记、文件存在且校验通过的分片;目录里游离的文件不导入。
|
||||
- 分片选择支持整表、分片序号区间、主键区间、日期桶区间,多次 `--select` 取并集;选择粒度为整个分片(`LOAD DATA` 不支持行级过滤)。
|
||||
- 列映射支持三种来源:归档记录的列清单、导入时 `--columns` 指定的文件字段顺序、`--assume-all-columns` 的位置映射(会警告)。
|
||||
- 默认要求 `state.json.complete == true`,避免静默导入半张表;`--allow-partial` 显式放开。
|
||||
- 默认对每个压缩分片做 SHA-256 预校验,失败即中止;`--verify off` 可关闭。
|
||||
- 默认 `--mode ignore`(`INSERT IGNORE`),利用归档中的主键实现重复导入幂等;可选 `insert` / `replace`。
|
||||
- 默认 `--engine load`:通过 `mysql.RegisterReaderHandler` 把解压流直接交给 `LOAD DATA LOCAL INFILE`,不落临时文件;启动时探测 `@@local_infile`,关闭则 fail-fast 并提示 `--engine insert`。`--engine insert` 复用现有批量参数化插入作为受限环境兜底。
|
||||
- 目标表必须预先存在。列映射以列名为准:归档记录了列清单时按名校验;默认全列归档必须显式提供 `--columns`,或显式接受 `--assume-all-columns` 的位置映射。文件字段数只作为前置检查,**不得**作为“映射正确”的证明。
|
||||
- 提供 `--dry-run`(打印选中分片、总行数/字节)、`--workers`、`--progress`、`--statistics`。
|
||||
- v1 只支持 `dump` 格式;`csv`/`jsonl` 明确报错并说明原因。
|
||||
- 新增 `docs/import.md`,并在 README 与 CLI 参考中登记导入入口。
|
||||
|
||||
**Non-goals:**
|
||||
|
||||
- 不做常驻服务、HTTP 接口、队列或定时任务。
|
||||
- 不引入第二个二进制或独立仓库。
|
||||
- 不支持 MySQL 以外的目标库。
|
||||
- 不做导入台账或断点续导;幂等由 `IGNORE` 与分片级原子装载保证。
|
||||
- 不做行级过滤,选择粒度只到分片边界。
|
||||
- 不自动建表、不生成 DDL、不修改表结构。
|
||||
- 不改变导出端的文件格式与清单格式。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `archive-import`: 从归档目录按清单重放分片到 MySQL,覆盖分片选择、完整性校验、幂等模式、装载引擎、目标前置检查、进度与失败语义。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `cli-contract`: 增加 `import` 子命令的参数、默认值与校验规则;明确原有“必填参数”仅作用于归档(导出)模式。
|
||||
|
||||
## Impact
|
||||
|
||||
- 代码:`cmd/archer/main.go`(子命令分发)、`internal/cli/import.go`(新增)、`internal/importer/`(新增);复用 `internal/shard`(清单)、`internal/sink`(插入兜底)、`internal/progress`、`internal/archererr`、`internal/atomicfile`。
|
||||
- 依赖:无新增外部依赖;`github.com/go-sql-driver/mysql` 已支持 `Reader::` 形式的 `LOAD DATA LOCAL INFILE`,且不需要 `allowAllFiles`。
|
||||
- 测试:新增 `internal/importer` 单元测试;新增导入集成测试,沿用 `ARCHER_TEST_DSN` 门控。
|
||||
- 文档:`docs/import.md`、`README.md`、`docs/cli-reference.md`。
|
||||
- 运维:目标库需要启用 `local_infile`(MySQL 8.0.3+ 默认关闭);不满足时使用 `--engine insert`,吞吐下降但语义不变。
|
||||
@@ -0,0 +1,241 @@
|
||||
## Purpose
|
||||
|
||||
定义如何把一次归档产出(分片文件 + `manifest.jsonl` + `state.json`)按需、可校验、可重复地重放进 MySQL 目标表,供冷数据查询与恢复使用。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 归档目录与清单权威性
|
||||
|
||||
一次导入 MUST 以一个包含 `manifest.jsonl` 的归档目录为单元。系统 MUST 以清单记录为唯一权威:只考虑清单中登记的分片,并按 `seq` 升序处理;清单之外的文件 MUST NOT 导入。清单条目指向的文件缺失时,系统 MUST 报错并终止,不得跳过该条目继续导入。
|
||||
|
||||
#### Scenario: 目录中存在未登记文件
|
||||
|
||||
- **WHEN** 归档目录中有一个已封分片文件,但 `manifest.jsonl` 没有对应记录
|
||||
- **THEN** 系统不导入该文件,并在统计中报告其被忽略
|
||||
|
||||
#### Scenario: 清单条目对应文件缺失
|
||||
|
||||
- **WHEN** 清单登记了 `000003.*`,但该文件已被删除
|
||||
- **THEN** 系统在开始装载前报错,指出缺失的分片序号与路径
|
||||
|
||||
#### Scenario: 清单包含损坏行
|
||||
|
||||
- **WHEN** `manifest.jsonl` 中某行不是合法 JSON
|
||||
- **THEN** 系统报错并终止,不得把损坏行当作“没有该分片”处理
|
||||
|
||||
### Requirement: 归档完成度门槛
|
||||
|
||||
默认情况下,系统 MUST 要求 `state.json` 存在且 `complete` 为 `true`;不满足时 MUST 在导入任何分片前报错,并提示可使用 `--allow-partial` 显式导入已封分片。启用 `--allow-partial` 时,系统 SHALL 忽略完成度标记,只导入清单中已封的分片。
|
||||
|
||||
#### Scenario: 未完成的归档
|
||||
|
||||
- **WHEN** `state.json` 中 `complete` 为 `false`,且未指定 `--allow-partial`
|
||||
- **THEN** 系统拒绝导入,说明该归档可能只包含部分数据
|
||||
|
||||
#### Scenario: 显式导入部分归档
|
||||
|
||||
- **WHEN** `complete` 为 `false`,且指定 `--allow-partial`
|
||||
- **THEN** 系统导入清单中所有已封分片,并在结束统计中标注“部分归档”
|
||||
|
||||
#### Scenario: 缺少 state.json
|
||||
|
||||
- **WHEN** 归档目录没有 `state.json`,且未指定 `--allow-partial`
|
||||
- **THEN** 系统拒绝导入,说明无法确认导出是否完成
|
||||
|
||||
### Requirement: 分片选择
|
||||
|
||||
系统 MUST 支持通过可重复的 `--select` 选择分片,多个选择条件取并集并按 `seq` 去重。支持的语法为:`all`、`seq:A-B`(闭区间)、`pk:LO-HI`、`date:D1..D2`(闭区间)。未提供 `--select` 时等价于 `all`。
|
||||
|
||||
`pk:LO-HI` MUST 选择主键范围与闭区间 `[LO,HI]` 相交的分片;由于装载不支持行级过滤,边界分片可能包含请求范围之外的行,系统 MUST 在选择结果中明示这一点。`date:D1..D2` MUST 只匹配清单中带日期桶的分片;归档不含日期信息时,系统 MUST 报错并说明该归档不是按日期分片导出的。
|
||||
|
||||
#### Scenario: 按序号选择
|
||||
|
||||
- **WHEN** `--select seq:3-9`
|
||||
- **THEN** 系统只导入 `seq` 在 3 到 9(含)之间的分片
|
||||
|
||||
#### Scenario: 主键区间命中边界分片
|
||||
|
||||
- **WHEN** 请求 `--select pk:150000-250000`,而分片 1 的范围是 `1-200000`、分片 2 是 `200001-400000`
|
||||
- **THEN** 系统选择分片 1 和 2,并提示分片 1 会带入 `1-149999` 的行
|
||||
|
||||
#### Scenario: 多次选择取并集
|
||||
|
||||
- **WHEN** 同时给出 `--select seq:1-2` 与 `--select seq:2-3`
|
||||
- **THEN** 系统导入分片 1、2、3,不重复处理分片 2
|
||||
|
||||
#### Scenario: 对非日期分片按日期选择
|
||||
|
||||
- **WHEN** 归档为 `--shard-by count` 导出(清单无日期桶),用户指定 `--select date:2025-01-01..2025-01-31`
|
||||
- **THEN** 系统报错,说明该归档无法按日期选择,只能按序号或主键范围选择
|
||||
|
||||
#### Scenario: 选择结果为空
|
||||
|
||||
- **WHEN** 选择条件没有命中任何分片
|
||||
- **THEN** 系统报错并以非零退出码结束,不连接目标库执行装载
|
||||
|
||||
### Requirement: 完整性校验
|
||||
|
||||
默认情况下,系统 MUST 在装载每个分片前计算其压缩文件的 SHA-256,并与清单记录比对;不一致时 MUST 中止该分片并终止本次导入。`--verify off` 可关闭预校验。
|
||||
|
||||
每个分片装载完成后,系统 MUST 核对实际写入行数:`insert` 模式下 MUST 等于清单 `rows`;`ignore` 模式下 MUST NOT 大于 `rows`,差额 SHALL 报告为跳过行数;`replace` 模式 SHALL 只报告受影响行数。不满足对应规则时 MUST 视为失败并终止。
|
||||
|
||||
#### Scenario: 分片内容损坏
|
||||
|
||||
- **WHEN** 某分片的 SHA-256 与清单不一致
|
||||
- **THEN** 系统在发送任何该分片数据前失败,指出分片序号与期望/实际哈希
|
||||
|
||||
#### Scenario: 严格插入的行数不足
|
||||
|
||||
- **WHEN** `--mode insert` 装载一个清单记录 200000 行的分片,但实际写入 199999 行
|
||||
- **THEN** 系统报错并终止,指出分片序号与行数差异
|
||||
|
||||
#### Scenario: 重复导入产生的跳过
|
||||
|
||||
- **WHEN** 使用默认 `--mode ignore` 重复导入同一分片
|
||||
- **THEN** 实际写入为 0、跳过为清单行数,导入继续并最终成功
|
||||
|
||||
### Requirement: 插入模式与幂等
|
||||
|
||||
系统 MUST 提供 `--mode ignore|insert|replace`,默认 `ignore`。三种模式互斥。`ignore` MUST 跳过与目标表现有唯一键冲突的行且不修改既有行;`insert` MUST 在遇到重复键时失败;`replace` MUST 用归档内容覆盖冲突行。
|
||||
|
||||
系统 MUST NOT 在分片内部按行过滤;选择只决定导入哪些分片。
|
||||
|
||||
#### Scenario: 重复导入原表
|
||||
|
||||
- **WHEN** 目标表已包含归档中的全部行,且使用默认 `--mode ignore`
|
||||
- **THEN** 导入成功,所有冲突行被跳过,目标表数据不变
|
||||
|
||||
#### Scenario: 严格插入遇到重复键
|
||||
|
||||
- **WHEN** 使用 `--mode insert`,目标表已存在相同主键
|
||||
- **THEN** 该分片装载失败,系统报告重复键错误并终止
|
||||
|
||||
#### Scenario: 覆盖模式
|
||||
|
||||
- **WHEN** 使用 `--mode replace`,目标表存在相同主键但列值不同
|
||||
- **THEN** 目标行被归档内容覆盖
|
||||
|
||||
### Requirement: 装载引擎与 local_infile
|
||||
|
||||
系统 MUST 提供 `--engine load|insert`,默认 `load`。
|
||||
|
||||
`load` 引擎 MUST 通过客户端流式读取解压后的数据并执行 `LOAD DATA LOCAL INFILE`,MUST NOT 依赖将完整分片写入临时文件,也 MUST NOT 要求驱动开启任意本地文件读取。其字段与行分隔规则 MUST 与 `dump` 格式的产出完全对应。
|
||||
|
||||
启动时,系统 MUST 查询目标会话的 `local_infile` 状态。`load` 引擎在 `local_infile` 关闭时 MUST 在导入任何分片前失败,并在错误信息中给出两条出路:启用 `local_infile`,或改用 `--engine insert`。系统 MUST NOT 静默回退到 `insert`。
|
||||
|
||||
`insert` 引擎 MUST 使用参数化批量插入,并遵守目标的 `max_allowed_packet`。两种引擎对同一归档、同一目标表的行结果 MUST 一致。
|
||||
|
||||
服务端报告告警时,系统 MUST 默认视为失败;`--allow-warnings` 可改为记录告警并继续。`ignore` 模式下因唯一键冲突被跳过的行 SHALL 计入跳过行数,其重复键告警 MUST NOT 单独导致分片失败,否则默认重跑无法幂等。
|
||||
|
||||
#### Scenario: local_infile 已关闭
|
||||
|
||||
- **WHEN** `SELECT @@local_infile` 返回 0,且使用默认 `--engine load`
|
||||
- **THEN** 系统在装载任何分片前失败,并提示启用该变量或改用 `--engine insert`
|
||||
|
||||
#### Scenario: 显式使用插入兜底
|
||||
|
||||
- **WHEN** `local_infile` 关闭,且指定 `--engine insert`
|
||||
- **THEN** 系统通过批量参数化插入完成导入,行为与 `load` 引擎一致
|
||||
|
||||
#### Scenario: 装载产生告警
|
||||
|
||||
- **WHEN** 服务端返回至少一条告警,且未指定 `--allow-warnings`
|
||||
- **THEN** 系统把该分片视为失败并终止
|
||||
|
||||
### Requirement: 目标表与列映射
|
||||
|
||||
目标表 MUST 预先存在;不存在时系统 MUST 在装载前报错,不尝试创建表。
|
||||
|
||||
列映射 MUST 以列名而不是文件位置为准。当归档记录了列清单时(`state.json` 的 `columns` 非空):
|
||||
|
||||
- 每个记录的列名 MUST 在目标表中存在,否则 MUST 报错;
|
||||
- 装载列清单 MUST 按记录顺序生成;
|
||||
- 记录中包含目标表的生成列时,系统 MUST 报错,不得静默丢弃该字段或写入生成列。
|
||||
|
||||
当归档为默认全列导出、未记录列名时,系统 MUST NOT 仅凭“文件字段数等于目标表列数”认为映射正确。此时用户 MUST 显式提供以下之一:
|
||||
|
||||
- `--columns`:按文件字段顺序给出目标列名,系统按名校验并生成装载列清单;
|
||||
- `--assume-all-columns`:接受位置映射,系统按目标表全部列的 ordinal 顺序生成装载列清单,把生成列映射为丢弃用的用户变量,并 MUST 打印位置映射警告。
|
||||
|
||||
文件字段数与装载列清单长度不一致时,系统 MUST 在装载前报错。字段数核对只是前置检查,列名与顺序的正确性由记录列清单或显式 `--columns` 保证。
|
||||
|
||||
#### Scenario: 目标表不存在
|
||||
|
||||
- **WHEN** `--dest` 指向的库中没有目标表
|
||||
- **THEN** 系统报错,提示需要先创建表
|
||||
|
||||
#### Scenario: 归档记录了列清单且目标缺列
|
||||
|
||||
- **WHEN** 归档记录列 `id,created_at,title`,目标表只有 `id,created_at`
|
||||
- **THEN** 系统在装载前报错,指出缺失的列名
|
||||
|
||||
#### Scenario: 归档列清单包含生成列
|
||||
|
||||
- **WHEN** 归档记录的列清单包含目标表的生成列 `full_name`
|
||||
- **THEN** 系统报错,说明生成列不能从归档写入
|
||||
|
||||
#### Scenario: 全列归档未提供映射
|
||||
|
||||
- **WHEN** 归档未记录列名,且既未提供 `--columns` 也未指定 `--assume-all-columns`
|
||||
- **THEN** 系统拒绝导入,并说明两种显式映射方式
|
||||
|
||||
#### Scenario: 位置映射遇到生成列
|
||||
|
||||
- **WHEN** 使用 `--assume-all-columns`,目标表含一个生成列,且文件字段数与全部列数一致
|
||||
- **THEN** 系统把生成列位置映射为丢弃变量,装载成功,并打印位置映射警告
|
||||
|
||||
#### Scenario: 字段数不一致
|
||||
|
||||
- **WHEN** 文件首行有 10 个字段,装载列清单长度为 11
|
||||
- **THEN** 系统在装载前报错,指出字段数与列清单长度
|
||||
|
||||
### Requirement: 进度、统计与 dry-run
|
||||
|
||||
启用 `--dry-run` 时,系统 MUST 打印解析后的配置、选中的分片列表(序号、路径、行数、字节数、日期桶)、总行数与总字节数,并 MUST NOT 执行任何装载或写入。启用 `--progress` 时,系统 SHALL 按分片完成情况输出已导入行数与分片进度。启用 `--statistics` 时,系统 MUST 在结束时输出选片数、成功/失败/跳过分片数、期望/实际/跳过的行数、字节数与耗时。
|
||||
|
||||
`--workers N` 默认 1(N 必须大于 0)。并行时系统 MUST 以连续 `seq` 区间分配分片,且最终数据结果 MUST 与串行导入一致。
|
||||
|
||||
#### Scenario: dry-run 不写数据
|
||||
|
||||
- **WHEN** 用户传入 `--dry-run`
|
||||
- **THEN** 标准输出包含选中分片与汇总信息,目标表不发生任何写入
|
||||
|
||||
#### Scenario: 并行导入结果一致
|
||||
|
||||
- **WHEN** 同一归档分别以 `--workers 1` 与 `--workers 4` 导入空表
|
||||
- **THEN** 两次导入后的目标表行集合相同
|
||||
|
||||
### Requirement: 失败语义与退出码
|
||||
|
||||
每个分片的装载 MUST 是原子的:分片失败时,系统 MUST NOT 在该分片留下部分行;此前已成功的分片 SHALL 保持已导入状态。系统 MUST 在首个分片失败时终止,并报告失败分片序号与失败前的累计导入行数。使用 `--mode ignore` 时,修复问题后重跑 MUST 安全。
|
||||
|
||||
成功完成时系统 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片,并返回非零退出码。
|
||||
|
||||
#### Scenario: 分片装载中断
|
||||
|
||||
- **WHEN** 第 3 个分片在装载过程中失败
|
||||
- **THEN** 分片 3 不留下部分行,分片 1、2 保持已导入,进程以非零退出码结束
|
||||
|
||||
#### Scenario: 修复后重跑
|
||||
|
||||
- **WHEN** 上次导入在第 3 个分片失败,修复原因后使用默认 `--mode ignore` 重跑
|
||||
- **THEN** 已导入的分片被跳过,导入从失败处继续完成
|
||||
|
||||
#### Scenario: 参数错误
|
||||
|
||||
- **WHEN** `--workers 0` 或未知 `--select` 语法
|
||||
- **THEN** 系统在连接数据库前报错,退出码为 2
|
||||
|
||||
### Requirement: 格式支持范围
|
||||
|
||||
v1 的导入 MUST 只支持 `dump` 格式。归档为 `csv` 或 `jsonl` 时,系统 MUST 报错并说明当前仅支持 `dump`,不得尝试按 dump 规则解析。
|
||||
|
||||
#### Scenario: csv 归档
|
||||
|
||||
- **WHEN** 选中的分片扩展名为 `.csv` 或 `.csv.gz`
|
||||
- **THEN** 系统报错,说明导入功能暂不支持 csv
|
||||
|
||||
#### Scenario: jsonl 归档
|
||||
|
||||
- **WHEN** 选中的分片扩展名为 `.jsonl`
|
||||
- **THEN** 系统报错,说明导入功能暂不支持 jsonl
|
||||
@@ -0,0 +1,106 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 必填参数
|
||||
|
||||
归档(导出)模式下,系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
|
||||
|
||||
导入模式(`archer import`)MUST 要求提供 `--file` 与 `--dest`;`--source`、`--where`、`--purge` 在导入模式下 MUST 被拒绝。缺少必需参数时,系统 MUST 在连接目标数据库前报错退出。
|
||||
|
||||
#### Scenario: 缺少过滤条件
|
||||
|
||||
- **WHEN** 归档模式未提供 `--where`
|
||||
- **THEN** 系统立即报错,提示 `--where` 必填,不建立数据库连接
|
||||
|
||||
#### Scenario: 没有任何输出目标
|
||||
|
||||
- **WHEN** 归档模式既未提供 `--file`、`--dest`,也未启用 `--purge`
|
||||
- **THEN** 系统报错,提示至少需要一种输出目标
|
||||
|
||||
#### Scenario: 导入模式缺少目标
|
||||
|
||||
- **WHEN** `archer import` 未提供 `--dest`
|
||||
- **THEN** 系统立即报错,提示 `--dest` 必填,不建立数据库连接
|
||||
|
||||
#### Scenario: 导入模式误用导出参数
|
||||
|
||||
- **WHEN** `archer import` 带上 `--source` 或 `--where`
|
||||
- **THEN** 系统在解析阶段报错,说明该参数仅用于归档模式
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 导入子命令
|
||||
|
||||
系统 MUST 提供 `archer import` 子命令,语法为 `archer import --file <dir> --dest <dsn> [flags]`。未知参数 MUST 报错。`archer import --help` MUST 打印导入模式的参数说明;`archer --version` 与 `archer import --version` MUST 均可打印版本并退出。
|
||||
|
||||
导入模式的参数与默认值:
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--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` / `insert` |
|
||||
| `--verify` | `pre` | `pre` / `off` |
|
||||
| `--workers` | `1` | 并行分片数,必须大于 0 |
|
||||
| `--charset` | `utf8mb4` | 装载时使用的字符集 |
|
||||
| `--time-zone` | 空 | 设置目标会话时区;空表示使用服务端默认 |
|
||||
| `--allow-partial` | 关闭 | 允许导入未完成归档的已封分片 |
|
||||
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
|
||||
| `--dry-run` | 关闭 | 只打印选片与配置 |
|
||||
| `--progress` | `auto` | 进度输出 |
|
||||
| `--statistics` | 关闭 | 结束汇总 |
|
||||
|
||||
#### Scenario: 最小导入命令
|
||||
|
||||
- **WHEN** 用户执行 `archer import --file ./export/orders --dest 'user:pass@tcp(host:3306)/db'`
|
||||
- **THEN** 系统按默认值解析为 `all` / `ignore` / `load` / `pre` / 1 个 worker
|
||||
|
||||
#### Scenario: 未知参数
|
||||
|
||||
- **WHEN** 用户给 `archer import` 传入未定义的参数
|
||||
- **THEN** 系统报错并以退出码 2 结束
|
||||
|
||||
#### Scenario: 非法 worker 数
|
||||
|
||||
- **WHEN** 用户指定 `--workers 0`
|
||||
- **THEN** 系统在连接数据库前报错,说明必须大于 0
|
||||
|
||||
#### Scenario: 非法模式
|
||||
|
||||
- **WHEN** 用户指定 `--mode merge` 或 `--engine bulk`
|
||||
- **THEN** 系统在解析阶段报错,列出允许的取值
|
||||
|
||||
#### Scenario: 列映射参数互斥
|
||||
|
||||
- **WHEN** 用户同时指定 `--columns` 与 `--assume-all-columns`
|
||||
- **THEN** 系统在连接数据库前报错,说明二者只能选一个
|
||||
|
||||
#### Scenario: 归档已记录列清单又显式指定映射
|
||||
|
||||
- **WHEN** `state.json` 的 `columns` 非空,且用户仍指定 `--columns` 或 `--assume-all-columns`
|
||||
- **THEN** 系统报错,避免两套映射来源冲突
|
||||
|
||||
### Requirement: 导入模式的 dry-run、进度与退出码
|
||||
|
||||
`--dry-run` 时,系统 MUST 打印解析后的导入配置、选中分片与汇总,MUST NOT 执行装载或写入。`--progress` 与 `--statistics` 在导入模式下的语义 SHALL 与归档模式一致,分别输出分片进度与结束汇总。
|
||||
|
||||
成功完成 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片并返回非零退出码。
|
||||
|
||||
#### Scenario: dry-run
|
||||
|
||||
- **WHEN** 用户执行 `archer import ... --dry-run`
|
||||
- **THEN** 标准输出包含选中分片、总行数与总字节数,目标库没有数据变化
|
||||
|
||||
#### Scenario: 结束统计
|
||||
|
||||
- **WHEN** 用户执行 `archer import ... --statistics`
|
||||
- **THEN** 进程退出前输出成功/跳过/失败分片数、行数与耗时
|
||||
|
||||
#### Scenario: 配置错误退出码
|
||||
|
||||
- **WHEN** `--select` 语法非法
|
||||
- **THEN** 进程以退出码 2 结束,不建立数据库连接
|
||||
@@ -0,0 +1,82 @@
|
||||
## 1. CLI 子命令与配置
|
||||
|
||||
- [x] 1.1 `cmd/archer/main.go`:在解析参数前识别 `os.Args[1] == "import"`,分发到导入入口;其余参数保持现有行为
|
||||
- [x] 1.2 新建 `internal/cli/import.go`:`ImportConfig`、`ParseImport`、`ValidateImport`,与现有 `Config` 解耦
|
||||
- [x] 1.3 实现导入参数与默认值:`--file`、`--dest`、`--dest-table`、`--columns`、`--assume-all-columns`、`--select`、`--mode`、`--engine`、`--verify`、`--workers`、`--charset`、`--time-zone`、`--allow-partial`、`--allow-warnings`、`--dry-run`、`--progress`、`--statistics`
|
||||
- [x] 1.4 拒绝导出专属参数(`--source`、`--where`、`--purge` 等)与未知参数,退出码 2;`--columns` 与 `--assume-all-columns` 互斥
|
||||
- [x] 1.5 `archer import --help` 与 `archer import --version` 可用
|
||||
- [x] 1.6 单元测试:默认值、参数互斥、非法 `--mode`/`--engine`/`--workers`/`--select`、导出参数被拒绝、列映射参数冲突
|
||||
|
||||
## 2. 归档读取与选片
|
||||
|
||||
- [x] 2.1 在 `internal/shard` 新增严格只读清单加载器:解析失败即报错,不打开追加句柄、不修改归档
|
||||
- [x] 2.2 从 `Entry.Path` 推导格式与压缩方式,并要求所有选中分片一致;非 `dump` 报错
|
||||
- [x] 2.3 实现 `--select` 解析:`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2`,多次取并集、按 `seq` 去重排序
|
||||
- [x] 2.4 `pk:` 使用分片区间相交语义;`date:` 在清单无日期桶时报错
|
||||
- [x] 2.5 使用 `checkpoint.Load` 实现完成度门槛:默认要求 `complete == true`,`--allow-partial` 放开
|
||||
- [x] 2.6 校验选中分片文件存在;清单损坏、条目文件缺失时在连接数据库前报错
|
||||
- [x] 2.7 单元测试:四种选择器、并集去重、空选择、日期桶缺失、损坏清单行、缺失文件、完成度门槛
|
||||
|
||||
## 3. 目标库前置检查与列映射
|
||||
|
||||
- [x] 3.1 建立目标连接,执行 `SELECT @@local_infile, @@version`;`--engine load` 且关闭时给出可操作错误
|
||||
- [x] 3.2 校验目标表存在(`information_schema.tables`),不存在时报错
|
||||
- [x] 3.3 加载目标列元数据(名、ordinal、是否为 `VIRTUAL/STORED GENERATED`)
|
||||
- [x] 3.4 归档记录列清单时:按记录顺序按名校验目标列存在、拒绝包含生成列、生成 `LOAD DATA` 列清单
|
||||
- [x] 3.5 `--columns` 模式:解析用户提供的文件字段顺序,做与 3.4 相同的名校验
|
||||
- [x] 3.6 `--assume-all-columns` 模式:按目标 ordinal 生成列清单,生成列替换为 `@_archer_skip_<i>` 丢弃变量,打印位置映射警告
|
||||
- [x] 3.7 无任何映射来源时拒绝导入,提示 `--columns` 或 `--assume-all-columns`
|
||||
- [x] 3.8 读取首个选中分片首行,按未转义 TAB 统计字段数,与列清单长度比较;不一致在装载前报错
|
||||
- [x] 3.9 每个 worker 使用固定 `*sql.Conn`,设置 `character_set` 与可选 `time_zone`
|
||||
- [x] 3.10 单元测试:名校验、缺失列、生成列拒绝、位置映射丢弃变量、字段数不一致、映射来源缺失
|
||||
|
||||
## 4. load 引擎
|
||||
|
||||
- [x] 4.1 实现单分片流式装载:注册唯一 `Reader` handler → 解压 Reader → 执行 `LOAD DATA LOCAL INFILE 'Reader::<name>'` → 注销
|
||||
- [x] 4.2 生成与 `dump` 编码严格对应的 SQL:`FIELDS TERMINATED BY '\t' ESCAPED BY '\\' LINES TERMINATED BY '\n'`、`CHARACTER SET`、可选列清单、`IGNORE`/`REPLACE`
|
||||
- [x] 4.3 实现 `--verify pre`:流式计算压缩文件 SHA-256 并与清单比对;`--verify off` 跳过
|
||||
- [x] 4.4 装载后在同一会话执行 `SHOW WARNINGS`;有告警且未指定 `--allow-warnings` 时失败
|
||||
- [x] 4.5 实现行数规则:`insert` 要求 affected == rows;`ignore` 要求 affected <= rows 并报告差额;`replace` 只报告
|
||||
- [x] 4.6 确保失败路径清理 handler 注册与文件句柄
|
||||
- [x] 4.7 单元测试:SQL 形状、模式映射、哈希不一致、告警失败、行数规则
|
||||
|
||||
## 5. insert 兜底引擎
|
||||
|
||||
- [x] 5.1 实现最小 `dump` 行解码器:TAB 分隔、`\N` → NULL、反转义 `\\ \t \n \r \0 \b \Z`
|
||||
- [x] 5.2 复用 `internal/sink.DB` 的分批插入逻辑,按 `max_allowed_packet` 切批
|
||||
- [x] 5.3 每个分片的所有批次包在同一个事务中,保证分片级原子
|
||||
- [x] 5.4 单元测试:解码器边界(空串、NULL、转义、中文、emoji、BLOB)、分批与事务提交/回滚
|
||||
|
||||
## 6. 运行编排
|
||||
|
||||
- [x] 6.1 实现 worker 池:按连续 `seq` 区间分配,默认 1,结果与串行一致
|
||||
- [x] 6.2 接入 `internal/progress.Reporter`:以清单总行数为总量,按分片与行数推进
|
||||
- [x] 6.3 实现 `--statistics`:选片数、成功/失败/跳过分片数、期望/实际/跳过行数、字节与耗时
|
||||
- [x] 6.4 实现 `--dry-run`:只读清单与首行,打印选片、总行数/字节、目标表与引擎,不连接目标库、不装载
|
||||
- [x] 6.5 失败即停:报告失败分片 `seq`、原因与累计行数;已成功分片保留
|
||||
- [x] 6.6 用 `internal/archererr` 映射退出码:配置 2、连接 3、写入 4、校验 5、中断 130
|
||||
- [x] 6.7 信号中断:停止开始新分片,当前分片完成或安全失败后以非零码退出
|
||||
|
||||
## 7. 测试
|
||||
|
||||
- [x] 7.1 单元测试:选片、清单、字段数、SQL、解码器、退出码
|
||||
- [x] 7.2 集成测试:导出小表 → 导入空表,比较行数与抽样内容(沿用 `ARCHER_TEST_DSN` 门控)
|
||||
- [x] 7.3 集成测试:`none`/`gzip`/`zstd`/`xz` 四种压缩的导入
|
||||
- [x] 7.4 集成测试:`ignore` 重复导入幂等、`insert` 遇重复失败、`replace` 覆盖
|
||||
- [x] 7.5 集成测试:篡改分片触发哈希失败、`complete=false` 默认拒绝与 `--allow-partial` 放开
|
||||
- [x] 7.6 集成测试:`--workers 1` 与 `--workers 4` 导入结果一致
|
||||
- [x] 7.7 集成测试:`--engine insert` 与 `--engine load` 结果一致
|
||||
- [x] 7.8 保真测试:NULL、TAB、换行、反斜杠、中文、emoji、BLOB 的导出→导入往返
|
||||
- [x] 7.9 列映射测试:归档列清单、`--columns`、`--assume-all-columns` 三种来源;目标表含生成列时丢弃变量生效;缺失列/字段数不一致被拒绝
|
||||
- [x] 7.10 `gofmt`、`go build ./...`、`go vet ./...`、`go test ./...` 通过
|
||||
|
||||
## 8. 文档与 OpenSpec
|
||||
|
||||
- [x] 8.1 新增 `docs/import.md`:使用示例、选片语义、完整性检查、两种引擎、`local_infile` 与代理限制、导回原表的注意事项
|
||||
- [x] 8.2 更新 `README.md` 的功能与文档索引
|
||||
- [x] 8.3 更新 `docs/cli-reference.md` 的导入参数表
|
||||
- [x] 8.4 运行 `openspec validate add-archive-import --strict`
|
||||
- [x] 8.5 在具备 MySQL 的环境中完成一次真实归档目录的按需导入,并记录结果
|
||||
- 2026-11-08:临时 MySQL 8.3.0 实例(`local_infile=ON`)。`ARCHER_TEST_DSN` 门控下运行 `go test ./internal/importer -run Integration -v`,导出→导入、四种压缩、三种模式、哈希/完成度门槛、workers 1/4、load/insert 引擎、保真往返、三种列映射全部通过。
|
||||
- 2026-11-08 手工 CLI:导出一张 7 行表为 3 个 count 分片;`archer import --workers 2 --assume-all-columns --statistics` 导入空表,7/7 行与原表逐列一致(affected=7,skipped=0)。默认 `ignore` 重跑:affected=0,skipped=7。`--dry-run` 未建立连接。
|
||||
- 同次运行 `go build ./...`、`go vet ./...`、全量 `go test ./...` 均通过。
|
||||
@@ -83,7 +83,7 @@
|
||||
|
||||
### Requirement: 删除语义
|
||||
|
||||
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`,且在日期分片模式下 MUST 被拒绝。
|
||||
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按 chunk 实际读取行的首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`。日期分片模式下,区间删除仅在“分片列相对扫描键单调、无回填”的前提下安全,系统 SHALL 允许该组合并在启动时打印该前提警告。
|
||||
|
||||
#### Scenario: 默认 IN 列表删除
|
||||
|
||||
@@ -98,7 +98,7 @@
|
||||
#### Scenario: 日期模式启用区间删除
|
||||
|
||||
- **WHEN** `--shard-by date` 与 `--bulk-delete` 同时出现
|
||||
- **THEN** 系统在启动校验阶段报错退出,不执行任何查询
|
||||
- **THEN** 系统允许执行,并在启动时警告:该组合要求分片列永不相对扫描键回退,否则迟到或回填的行可能在归档前被删除
|
||||
|
||||
### Requirement: 复制延迟保护
|
||||
|
||||
|
||||
@@ -0,0 +1,243 @@
|
||||
# archive-import Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
定义如何把一次归档产出(分片文件 + `manifest.jsonl` + `state.json`)按需、可校验、可重复地重放进 MySQL 目标表,供冷数据查询与恢复使用。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 归档目录与清单权威性
|
||||
|
||||
一次导入 MUST 以一个包含 `manifest.jsonl` 的归档目录为单元。系统 MUST 以清单记录为唯一权威:只考虑清单中登记的分片,并按 `seq` 升序处理;清单之外的文件 MUST NOT 导入。清单条目指向的文件缺失时,系统 MUST 报错并终止,不得跳过该条目继续导入。
|
||||
|
||||
#### Scenario: 目录中存在未登记文件
|
||||
|
||||
- **WHEN** 归档目录中有一个已封分片文件,但 `manifest.jsonl` 没有对应记录
|
||||
- **THEN** 系统不导入该文件,并在统计中报告其被忽略
|
||||
|
||||
#### Scenario: 清单条目对应文件缺失
|
||||
|
||||
- **WHEN** 清单登记了 `000003.*`,但该文件已被删除
|
||||
- **THEN** 系统在开始装载前报错,指出缺失的分片序号与路径
|
||||
|
||||
#### Scenario: 清单包含损坏行
|
||||
|
||||
- **WHEN** `manifest.jsonl` 中某行不是合法 JSON
|
||||
- **THEN** 系统报错并终止,不得把损坏行当作“没有该分片”处理
|
||||
|
||||
### Requirement: 归档完成度门槛
|
||||
|
||||
默认情况下,系统 MUST 要求 `state.json` 存在且 `complete` 为 `true`;不满足时 MUST 在导入任何分片前报错,并提示可使用 `--allow-partial` 显式导入已封分片。启用 `--allow-partial` 时,系统 SHALL 忽略完成度标记,只导入清单中已封的分片。
|
||||
|
||||
#### Scenario: 未完成的归档
|
||||
|
||||
- **WHEN** `state.json` 中 `complete` 为 `false`,且未指定 `--allow-partial`
|
||||
- **THEN** 系统拒绝导入,说明该归档可能只包含部分数据
|
||||
|
||||
#### Scenario: 显式导入部分归档
|
||||
|
||||
- **WHEN** `complete` 为 `false`,且指定 `--allow-partial`
|
||||
- **THEN** 系统导入清单中所有已封分片,并在结束统计中标注“部分归档”
|
||||
|
||||
#### Scenario: 缺少 state.json
|
||||
|
||||
- **WHEN** 归档目录没有 `state.json`,且未指定 `--allow-partial`
|
||||
- **THEN** 系统拒绝导入,说明无法确认导出是否完成
|
||||
|
||||
### Requirement: 分片选择
|
||||
|
||||
系统 MUST 支持通过可重复的 `--select` 选择分片,多个选择条件取并集并按 `seq` 去重。支持的语法为:`all`、`seq:A-B`(闭区间)、`pk:LO-HI`、`date:D1..D2`(闭区间)。未提供 `--select` 时等价于 `all`。
|
||||
|
||||
`pk:LO-HI` MUST 选择主键范围与闭区间 `[LO,HI]` 相交的分片;由于装载不支持行级过滤,边界分片可能包含请求范围之外的行,系统 MUST 在选择结果中明示这一点。`date:D1..D2` MUST 只匹配清单中带日期桶的分片;归档不含日期信息时,系统 MUST 报错并说明该归档不是按日期分片导出的。
|
||||
|
||||
#### Scenario: 按序号选择
|
||||
|
||||
- **WHEN** `--select seq:3-9`
|
||||
- **THEN** 系统只导入 `seq` 在 3 到 9(含)之间的分片
|
||||
|
||||
#### Scenario: 主键区间命中边界分片
|
||||
|
||||
- **WHEN** 请求 `--select pk:150000-250000`,而分片 1 的范围是 `1-200000`、分片 2 是 `200001-400000`
|
||||
- **THEN** 系统选择分片 1 和 2,并提示分片 1 会带入 `1-149999` 的行
|
||||
|
||||
#### Scenario: 多次选择取并集
|
||||
|
||||
- **WHEN** 同时给出 `--select seq:1-2` 与 `--select seq:2-3`
|
||||
- **THEN** 系统导入分片 1、2、3,不重复处理分片 2
|
||||
|
||||
#### Scenario: 对非日期分片按日期选择
|
||||
|
||||
- **WHEN** 归档为 `--shard-by count` 导出(清单无日期桶),用户指定 `--select date:2025-01-01..2025-01-31`
|
||||
- **THEN** 系统报错,说明该归档无法按日期选择,只能按序号或主键范围选择
|
||||
|
||||
#### Scenario: 选择结果为空
|
||||
|
||||
- **WHEN** 选择条件没有命中任何分片
|
||||
- **THEN** 系统报错并以非零退出码结束,不连接目标库执行装载
|
||||
|
||||
### Requirement: 完整性校验
|
||||
|
||||
默认情况下,系统 MUST 在装载每个分片前计算其压缩文件的 SHA-256,并与清单记录比对;不一致时 MUST 中止该分片并终止本次导入。`--verify off` 可关闭预校验。
|
||||
|
||||
每个分片装载完成后,系统 MUST 核对实际写入行数:`insert` 模式下 MUST 等于清单 `rows`;`ignore` 模式下 MUST NOT 大于 `rows`,差额 SHALL 报告为跳过行数;`replace` 模式 SHALL 只报告受影响行数。不满足对应规则时 MUST 视为失败并终止。
|
||||
|
||||
#### Scenario: 分片内容损坏
|
||||
|
||||
- **WHEN** 某分片的 SHA-256 与清单不一致
|
||||
- **THEN** 系统在发送任何该分片数据前失败,指出分片序号与期望/实际哈希
|
||||
|
||||
#### Scenario: 严格插入的行数不足
|
||||
|
||||
- **WHEN** `--mode insert` 装载一个清单记录 200000 行的分片,但实际写入 199999 行
|
||||
- **THEN** 系统报错并终止,指出分片序号与行数差异
|
||||
|
||||
#### Scenario: 重复导入产生的跳过
|
||||
|
||||
- **WHEN** 使用默认 `--mode ignore` 重复导入同一分片
|
||||
- **THEN** 实际写入为 0、跳过为清单行数,导入继续并最终成功
|
||||
|
||||
### Requirement: 插入模式与幂等
|
||||
|
||||
系统 MUST 提供 `--mode ignore|insert|replace`,默认 `ignore`。三种模式互斥。`ignore` MUST 跳过与目标表现有唯一键冲突的行且不修改既有行;`insert` MUST 在遇到重复键时失败;`replace` MUST 用归档内容覆盖冲突行。
|
||||
|
||||
系统 MUST NOT 在分片内部按行过滤;选择只决定导入哪些分片。
|
||||
|
||||
#### Scenario: 重复导入原表
|
||||
|
||||
- **WHEN** 目标表已包含归档中的全部行,且使用默认 `--mode ignore`
|
||||
- **THEN** 导入成功,所有冲突行被跳过,目标表数据不变
|
||||
|
||||
#### Scenario: 严格插入遇到重复键
|
||||
|
||||
- **WHEN** 使用 `--mode insert`,目标表已存在相同主键
|
||||
- **THEN** 该分片装载失败,系统报告重复键错误并终止
|
||||
|
||||
#### Scenario: 覆盖模式
|
||||
|
||||
- **WHEN** 使用 `--mode replace`,目标表存在相同主键但列值不同
|
||||
- **THEN** 目标行被归档内容覆盖
|
||||
|
||||
### Requirement: 装载引擎与 local_infile
|
||||
|
||||
系统 MUST 提供 `--engine load|insert`,默认 `load`。
|
||||
|
||||
`load` 引擎 MUST 通过客户端流式读取解压后的数据并执行 `LOAD DATA LOCAL INFILE`,MUST NOT 依赖将完整分片写入临时文件,也 MUST NOT 要求驱动开启任意本地文件读取。其字段与行分隔规则 MUST 与 `dump` 格式的产出完全对应。
|
||||
|
||||
启动时,系统 MUST 查询目标会话的 `local_infile` 状态。`load` 引擎在 `local_infile` 关闭时 MUST 在导入任何分片前失败,并在错误信息中给出两条出路:启用 `local_infile`,或改用 `--engine insert`。系统 MUST NOT 静默回退到 `insert`。
|
||||
|
||||
`insert` 引擎 MUST 使用参数化批量插入,并遵守目标的 `max_allowed_packet`。两种引擎对同一归档、同一目标表的行结果 MUST 一致。
|
||||
|
||||
服务端报告告警时,系统 MUST 默认视为失败;`--allow-warnings` 可改为记录告警并继续。`ignore` 模式下因唯一键冲突被跳过的行 SHALL 计入跳过行数,其重复键告警 MUST NOT 单独导致分片失败,否则默认重跑无法幂等。
|
||||
|
||||
#### Scenario: local_infile 已关闭
|
||||
|
||||
- **WHEN** `SELECT @@local_infile` 返回 0,且使用默认 `--engine load`
|
||||
- **THEN** 系统在装载任何分片前失败,并提示启用该变量或改用 `--engine insert`
|
||||
|
||||
#### Scenario: 显式使用插入兜底
|
||||
|
||||
- **WHEN** `local_infile` 关闭,且指定 `--engine insert`
|
||||
- **THEN** 系统通过批量参数化插入完成导入,行为与 `load` 引擎一致
|
||||
|
||||
#### Scenario: 装载产生告警
|
||||
|
||||
- **WHEN** 服务端返回至少一条告警,且未指定 `--allow-warnings`
|
||||
- **THEN** 系统把该分片视为失败并终止
|
||||
|
||||
### Requirement: 目标表与列映射
|
||||
|
||||
目标表 MUST 预先存在;不存在时系统 MUST 在装载前报错,不尝试创建表。
|
||||
|
||||
列映射 MUST 以列名而不是文件位置为准。当归档记录了列清单时(`state.json` 的 `columns` 非空):
|
||||
|
||||
- 每个记录的列名 MUST 在目标表中存在,否则 MUST 报错;
|
||||
- 装载列清单 MUST 按记录顺序生成;
|
||||
- 记录中包含目标表的生成列时,系统 MUST 报错,不得静默丢弃该字段或写入生成列。
|
||||
|
||||
当归档为默认全列导出、未记录列名时,系统 MUST NOT 仅凭“文件字段数等于目标表列数”认为映射正确。此时用户 MUST 显式提供以下之一:
|
||||
|
||||
- `--columns`:按文件字段顺序给出目标列名,系统按名校验并生成装载列清单;
|
||||
- `--assume-all-columns`:接受位置映射,系统按目标表全部列的 ordinal 顺序生成装载列清单,把生成列映射为丢弃用的用户变量,并 MUST 打印位置映射警告。
|
||||
|
||||
文件字段数与装载列清单长度不一致时,系统 MUST 在装载前报错。字段数核对只是前置检查,列名与顺序的正确性由记录列清单或显式 `--columns` 保证。
|
||||
|
||||
#### Scenario: 目标表不存在
|
||||
|
||||
- **WHEN** `--dest` 指向的库中没有目标表
|
||||
- **THEN** 系统报错,提示需要先创建表
|
||||
|
||||
#### Scenario: 归档记录了列清单且目标缺列
|
||||
|
||||
- **WHEN** 归档记录列 `id,created_at,title`,目标表只有 `id,created_at`
|
||||
- **THEN** 系统在装载前报错,指出缺失的列名
|
||||
|
||||
#### Scenario: 归档列清单包含生成列
|
||||
|
||||
- **WHEN** 归档记录的列清单包含目标表的生成列 `full_name`
|
||||
- **THEN** 系统报错,说明生成列不能从归档写入
|
||||
|
||||
#### Scenario: 全列归档未提供映射
|
||||
|
||||
- **WHEN** 归档未记录列名,且既未提供 `--columns` 也未指定 `--assume-all-columns`
|
||||
- **THEN** 系统拒绝导入,并说明两种显式映射方式
|
||||
|
||||
#### Scenario: 位置映射遇到生成列
|
||||
|
||||
- **WHEN** 使用 `--assume-all-columns`,目标表含一个生成列,且文件字段数与全部列数一致
|
||||
- **THEN** 系统把生成列位置映射为丢弃变量,装载成功,并打印位置映射警告
|
||||
|
||||
#### Scenario: 字段数不一致
|
||||
|
||||
- **WHEN** 文件首行有 10 个字段,装载列清单长度为 11
|
||||
- **THEN** 系统在装载前报错,指出字段数与列清单长度
|
||||
|
||||
### Requirement: 进度、统计与 dry-run
|
||||
|
||||
启用 `--dry-run` 时,系统 MUST 打印解析后的配置、选中的分片列表(序号、路径、行数、字节数、日期桶)、总行数与总字节数,并 MUST NOT 执行任何装载或写入。启用 `--progress` 时,系统 SHALL 按分片完成情况输出已导入行数与分片进度。启用 `--statistics` 时,系统 MUST 在结束时输出选片数、成功/失败/跳过分片数、期望/实际/跳过的行数、字节数与耗时。
|
||||
|
||||
`--workers N` 默认 1(N 必须大于 0)。并行时系统 MUST 以连续 `seq` 区间分配分片,且最终数据结果 MUST 与串行导入一致。
|
||||
|
||||
#### Scenario: dry-run 不写数据
|
||||
|
||||
- **WHEN** 用户传入 `--dry-run`
|
||||
- **THEN** 标准输出包含选中分片与汇总信息,目标表不发生任何写入
|
||||
|
||||
#### Scenario: 并行导入结果一致
|
||||
|
||||
- **WHEN** 同一归档分别以 `--workers 1` 与 `--workers 4` 导入空表
|
||||
- **THEN** 两次导入后的目标表行集合相同
|
||||
|
||||
### Requirement: 失败语义与退出码
|
||||
|
||||
每个分片的装载 MUST 是原子的:分片失败时,系统 MUST NOT 在该分片留下部分行;此前已成功的分片 SHALL 保持已导入状态。系统 MUST 在首个分片失败时终止,并报告失败分片序号与失败前的累计导入行数。使用 `--mode ignore` 时,修复问题后重跑 MUST 安全。
|
||||
|
||||
成功完成时系统 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片,并返回非零退出码。
|
||||
|
||||
#### Scenario: 分片装载中断
|
||||
|
||||
- **WHEN** 第 3 个分片在装载过程中失败
|
||||
- **THEN** 分片 3 不留下部分行,分片 1、2 保持已导入,进程以非零退出码结束
|
||||
|
||||
#### Scenario: 修复后重跑
|
||||
|
||||
- **WHEN** 上次导入在第 3 个分片失败,修复原因后使用默认 `--mode ignore` 重跑
|
||||
- **THEN** 已导入的分片被跳过,导入从失败处继续完成
|
||||
|
||||
#### Scenario: 参数错误
|
||||
|
||||
- **WHEN** `--workers 0` 或未知 `--select` 语法
|
||||
- **THEN** 系统在连接数据库前报错,退出码为 2
|
||||
|
||||
### Requirement: 格式支持范围
|
||||
|
||||
v1 的导入 MUST 只支持 `dump` 格式。归档为 `csv` 或 `jsonl` 时,系统 MUST 报错并说明当前仅支持 `dump`,不得尝试按 dump 规则解析。
|
||||
|
||||
#### Scenario: csv 归档
|
||||
|
||||
- **WHEN** 选中的分片扩展名为 `.csv` 或 `.csv.gz`
|
||||
- **THEN** 系统报错,说明导入功能暂不支持 csv
|
||||
|
||||
#### Scenario: jsonl 归档
|
||||
|
||||
- **WHEN** 选中的分片扩展名为 `.jsonl`
|
||||
- **THEN** 系统报错,说明导入功能暂不支持 jsonl
|
||||
@@ -8,18 +8,107 @@
|
||||
|
||||
### Requirement: 必填参数
|
||||
|
||||
系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
|
||||
归档(导出)模式下,系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
|
||||
|
||||
导入模式(`archer import`)MUST 要求提供 `--file` 与 `--dest`;`--source`、`--where`、`--purge` 在导入模式下 MUST 被拒绝。缺少必需参数时,系统 MUST 在连接目标数据库前报错退出。
|
||||
|
||||
#### Scenario: 缺少过滤条件
|
||||
|
||||
- **WHEN** 用户未提供 `--where`
|
||||
- **WHEN** 归档模式未提供 `--where`
|
||||
- **THEN** 系统立即报错,提示 `--where` 必填,不建立数据库连接
|
||||
|
||||
#### Scenario: 没有任何输出目标
|
||||
|
||||
- **WHEN** 用户既未提供 `--file`、`--dest`,也未启用 `--purge`
|
||||
- **WHEN** 归档模式既未提供 `--file`、`--dest`,也未启用 `--purge`
|
||||
- **THEN** 系统报错,提示至少需要一种输出目标
|
||||
|
||||
#### Scenario: 导入模式缺少目标
|
||||
|
||||
- **WHEN** `archer import` 未提供 `--dest`
|
||||
- **THEN** 系统立即报错,提示 `--dest` 必填,不建立数据库连接
|
||||
|
||||
#### Scenario: 导入模式误用导出参数
|
||||
|
||||
- **WHEN** `archer import` 带上 `--source` 或 `--where`
|
||||
- **THEN** 系统在解析阶段报错,说明该参数仅用于归档模式
|
||||
|
||||
### Requirement: 导入子命令
|
||||
|
||||
系统 MUST 提供 `archer import` 子命令,语法为 `archer import --file <dir> --dest <dsn> [flags]`。未知参数 MUST 报错。`archer import --help` MUST 打印导入模式的参数说明;`archer --version` 与 `archer import --version` MUST 均可打印版本并退出。
|
||||
|
||||
导入模式的参数与默认值:
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--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` / `insert` |
|
||||
| `--verify` | `pre` | `pre` / `off` |
|
||||
| `--workers` | `1` | 并行分片数,必须大于 0 |
|
||||
| `--charset` | `utf8mb4` | 装载时使用的字符集 |
|
||||
| `--time-zone` | 空 | 设置目标会话时区;空表示使用服务端默认 |
|
||||
| `--allow-partial` | 关闭 | 允许导入未完成归档的已封分片 |
|
||||
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
|
||||
| `--dry-run` | 关闭 | 只打印选片与配置 |
|
||||
| `--progress` | `auto` | 进度输出 |
|
||||
| `--statistics` | 关闭 | 结束汇总 |
|
||||
|
||||
#### Scenario: 最小导入命令
|
||||
|
||||
- **WHEN** 用户执行 `archer import --file ./export/orders --dest 'user:pass@tcp(host:3306)/db'`
|
||||
- **THEN** 系统按默认值解析为 `all` / `ignore` / `load` / `pre` / 1 个 worker
|
||||
|
||||
#### Scenario: 未知参数
|
||||
|
||||
- **WHEN** 用户给 `archer import` 传入未定义的参数
|
||||
- **THEN** 系统报错并以退出码 2 结束
|
||||
|
||||
#### Scenario: 非法 worker 数
|
||||
|
||||
- **WHEN** 用户指定 `--workers 0`
|
||||
- **THEN** 系统在连接数据库前报错,说明必须大于 0
|
||||
|
||||
#### Scenario: 非法模式
|
||||
|
||||
- **WHEN** 用户指定 `--mode merge` 或 `--engine bulk`
|
||||
- **THEN** 系统在解析阶段报错,列出允许的取值
|
||||
|
||||
#### Scenario: 列映射参数互斥
|
||||
|
||||
- **WHEN** 用户同时指定 `--columns` 与 `--assume-all-columns`
|
||||
- **THEN** 系统在连接数据库前报错,说明二者只能选一个
|
||||
|
||||
#### Scenario: 归档已记录列清单又显式指定映射
|
||||
|
||||
- **WHEN** `state.json` 的 `columns` 非空,且用户仍指定 `--columns` 或 `--assume-all-columns`
|
||||
- **THEN** 系统报错,避免两套映射来源冲突
|
||||
|
||||
### Requirement: 导入模式的 dry-run、进度与退出码
|
||||
|
||||
`--dry-run` 时,系统 MUST 打印解析后的导入配置、选中分片与汇总,MUST NOT 执行装载或写入。`--progress` 与 `--statistics` 在导入模式下的语义 SHALL 与归档模式一致,分别输出分片进度与结束汇总。
|
||||
|
||||
成功完成 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片并返回非零退出码。
|
||||
|
||||
#### Scenario: dry-run
|
||||
|
||||
- **WHEN** 用户执行 `archer import ... --dry-run`
|
||||
- **THEN** 标准输出包含选中分片、总行数与总字节数,目标库没有数据变化
|
||||
|
||||
#### Scenario: 结束统计
|
||||
|
||||
- **WHEN** 用户执行 `archer import ... --statistics`
|
||||
- **THEN** 进程退出前输出成功/跳过/失败分片数、行数与耗时
|
||||
|
||||
#### Scenario: 配置错误退出码
|
||||
|
||||
- **WHEN** `--select` 语法非法
|
||||
- **THEN** 进程以退出码 2 结束,不建立数据库连接
|
||||
|
||||
### Requirement: 默认值
|
||||
|
||||
系统 SHALL 采用以下默认值:`--chunk-size 2000`、`--shard-by none`、`--shard-rows 0`、`--format dump`、`--compress none`、`--compress-level 3`、`--max-lag 1s`、`--check-interval 1s`、`--retries 1`、`--safe-auto-increment true`、`--progress 0`。
|
||||
@@ -31,7 +120,7 @@
|
||||
|
||||
### Requirement: 参数依赖与互斥
|
||||
|
||||
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge` 且在日期模式下禁止;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误。违反时 MUST 在启动阶段报错。
|
||||
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge`;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误。违反时 MUST 在启动阶段报错。
|
||||
|
||||
#### Scenario: 数量模式误传日期列
|
||||
|
||||
|
||||
Reference in new issue
Block a user