From 366d61ca2503608aaa445d1fdeeb4ed985c5fda3 Mon Sep 17 00:00:00 2001 From: void Date: Sun, 8 Nov 2026 21:14:05 +0800 Subject: [PATCH] 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 --- README.md | 353 ++------------ cmd/archer/main.go | 28 ++ docs/checkpoint-and-resume.md | 30 ++ docs/cli-reference.md | 140 ++++++ docs/development.md | 10 + docs/getting-started.md | 66 +++ docs/import.md | 145 ++++++ docs/output-formats.md | 50 ++ docs/progress.md | 41 ++ docs/safety.md | 11 + docs/sharding.md | 109 +++++ internal/app/app.go | 3 + internal/app/integration_test.go | 51 +++ internal/cli/cli_test.go | 4 +- internal/cli/import.go | 219 +++++++++ internal/cli/import_test.go | 122 +++++ internal/cli/validate.go | 3 - internal/importer/archive.go | 214 +++++++++ internal/importer/archive_test.go | 211 +++++++++ internal/importer/columns.go | 163 +++++++ internal/importer/columns_test.go | 151 ++++++ internal/importer/dump.go | 83 ++++ internal/importer/dump_test.go | 96 ++++ internal/importer/engines.go | 214 +++++++++ internal/importer/integration_test.go | 429 ++++++++++++++++++ internal/importer/run.go | 418 +++++++++++++++++ internal/importer/run_test.go | 104 +++++ internal/importer/sql.go | 167 +++++++ internal/importer/sql_test.go | 116 +++++ internal/purge/purge.go | 28 +- internal/purge/purge_test.go | 93 ++++ internal/shard/manifest.go | 37 ++ internal/shard/select.go | 262 +++++++++++ internal/shard/select_test.go | 131 ++++++ .../allow-date-bulk-delete/.openspec.yaml | 2 + .../changes/allow-date-bulk-delete/design.md | 50 ++ .../allow-date-bulk-delete/proposal.md | 32 ++ .../specs/archive-core/spec.md | 30 ++ .../specs/cli-contract/spec.md | 25 + .../changes/allow-date-bulk-delete/tasks.md | 26 ++ .../.openspec.yaml | 2 + .../2026-11-08-add-archive-import/design.md | 153 +++++++ .../2026-11-08-add-archive-import/proposal.md | 46 ++ .../specs/archive-import/spec.md | 241 ++++++++++ .../specs/cli-contract/spec.md | 106 +++++ .../2026-11-08-add-archive-import/tasks.md | 82 ++++ openspec/specs/archive-core/spec.md | 4 +- openspec/specs/archive-import/spec.md | 243 ++++++++++ openspec/specs/cli-contract/spec.md | 97 +++- 49 files changed, 5099 insertions(+), 342 deletions(-) create mode 100644 docs/checkpoint-and-resume.md create mode 100644 docs/cli-reference.md create mode 100644 docs/development.md create mode 100644 docs/getting-started.md create mode 100644 docs/import.md create mode 100644 docs/output-formats.md create mode 100644 docs/progress.md create mode 100644 docs/safety.md create mode 100644 docs/sharding.md create mode 100644 internal/cli/import.go create mode 100644 internal/cli/import_test.go create mode 100644 internal/importer/archive.go create mode 100644 internal/importer/archive_test.go create mode 100644 internal/importer/columns.go create mode 100644 internal/importer/columns_test.go create mode 100644 internal/importer/dump.go create mode 100644 internal/importer/dump_test.go create mode 100644 internal/importer/engines.go create mode 100644 internal/importer/integration_test.go create mode 100644 internal/importer/run.go create mode 100644 internal/importer/run_test.go create mode 100644 internal/importer/sql.go create mode 100644 internal/importer/sql_test.go create mode 100644 internal/purge/purge_test.go create mode 100644 internal/shard/select.go create mode 100644 internal/shard/select_test.go create mode 100644 openspec/changes/allow-date-bulk-delete/.openspec.yaml create mode 100644 openspec/changes/allow-date-bulk-delete/design.md create mode 100644 openspec/changes/allow-date-bulk-delete/proposal.md create mode 100644 openspec/changes/allow-date-bulk-delete/specs/archive-core/spec.md create mode 100644 openspec/changes/allow-date-bulk-delete/specs/cli-contract/spec.md create mode 100644 openspec/changes/allow-date-bulk-delete/tasks.md create mode 100644 openspec/changes/archive/2026-11-08-add-archive-import/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-08-add-archive-import/design.md create mode 100644 openspec/changes/archive/2026-11-08-add-archive-import/proposal.md create mode 100644 openspec/changes/archive/2026-11-08-add-archive-import/specs/archive-import/spec.md create mode 100644 openspec/changes/archive/2026-11-08-add-archive-import/specs/cli-contract/spec.md create mode 100644 openspec/changes/archive/2026-11-08-add-archive-import/tasks.md create mode 100644 openspec/specs/archive-import/spec.md diff --git a/README.md b/README.md index d9c993d..4cb443e 100644 --- a/README.md +++ b/README.md @@ -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`(默认) | 单文件 | `.-.` | -| `count` | 每 `--shard-rows` 行封片,流式滚动 | 同上,序号递增 | -| `date` | 每个日期一个目录;同一天内可再按 `--shard-rows` 切分 | `date=YYYY-MM-DD/.-.` | - -三种模式都保证: - -- 分片按扫描顺序编号; -- 相邻分片的主键范围连续、不重叠; -- 分片合并等于本次扫描读取到的全部行; -- 文件名中的 `lo`/`hi` 是该分片实际首尾键; -- 同一时刻只有一个活跃分片文件(因此没有 fd 上限问题)。 - -`--chunk-size`(每次 SELECT 的行数、事务大小、checkpoint 粒度)与 -`--shard-rows` 相互独立,一个 chunk 可以跨多个分片。 - -分片先写 `.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 () - 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) | 单元测试与集成测试 | diff --git a/cmd/archer/main.go b/cmd/archer/main.go index 3ab3f8a..00f2a79 100644 --- a/cmd/archer/main.go +++ b/cmd/archer/main.go @@ -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)) + } +} diff --git a/docs/checkpoint-and-resume.md b/docs/checkpoint-and-resume.md new file mode 100644 index 0000000..a892e8d --- /dev/null +++ b/docs/checkpoint-and-resume.md @@ -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` / 去重逻辑处理。 + +扫描期间不提供快照一致性:只保证读取到的行,并发写入可能改变行集合。 diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..15d6e63 --- /dev/null +++ b/docs/cli-reference.md @@ -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 [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 扩展 | diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..1b32d63 --- /dev/null +++ b/docs/development.md @@ -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`。 diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..5f51da3 --- /dev/null +++ b/docs/getting-started.md @@ -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) diff --git a/docs/import.md b/docs/import.md new file mode 100644 index 0000000..e725124 --- /dev/null +++ b/docs/import.md @@ -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_` 丢弃变量,由目标表重新计算。启动时打印位置映射警告。 +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 接口、队列或定时任务。 diff --git a/docs/output-formats.md b/docs/output-formats.md new file mode 100644 index 0000000..57f0e5e --- /dev/null +++ b/docs/output-formats.md @@ -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 +``` diff --git a/docs/progress.md b/docs/progress.md new file mode 100644 index 0000000..a94ca34 --- /dev/null +++ b/docs/progress.md @@ -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。 diff --git a/docs/safety.md b/docs/safety.md new file mode 100644 index 0000000..f11daac --- /dev/null +++ b/docs/safety.md @@ -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`;时区漂移会导致同一行落到相邻日期,续跑会被拒绝。 diff --git a/docs/sharding.md b/docs/sharding.md new file mode 100644 index 0000000..ea88093 --- /dev/null +++ b/docs/sharding.md @@ -0,0 +1,109 @@ +# 分片模式 + +| `--shard-by` | 行为 | 文件 | +|---|---|---| +| `none`(默认) | 单文件 | `.-.` | +| `count` | 每 `--shard-rows` 行封片,流式滚动 | 同上,序号递增 | +| `date` | 每个日期一个目录;同一天内可再按 `--shard-rows` 切分 | `date=YYYY-MM-DD/.-.` | + +三种模式都保证: + +- 分片按扫描顺序编号; +- 相邻分片的主键范围连续、不重叠; +- 分片合并等于本次扫描读取到的全部行; +- 文件名中的 `lo`/`hi` 是该分片实际首尾键; +- 同一时刻只有一个活跃分片文件(因此没有 fd 上限问题)。 + +`--chunk-size`(每次 SELECT 的行数、事务大小、checkpoint 粒度)与 +`--shard-rows` 相互独立,一个 chunk 可以跨多个分片。 + +分片先写 `.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 () + 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` 都计入配置指纹;续跑时不一致会拒绝。 diff --git a/internal/app/app.go b/internal/app/app.go index 0fa430d..59d8856 100644 --- a/internal/app/app.go +++ b/internal/app/app.go @@ -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 { diff --git a/internal/app/integration_test.go b/internal/app/integration_test.go index 133e2ab..da123c0 100644 --- a/internal/app/integration_test.go +++ b/internal/app/integration_test.go @@ -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) diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go index 8a79efe..53e03d6 100644 --- a/internal/cli/cli_test.go +++ b/internal/cli/cli_test.go @@ -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) } } diff --git a/internal/cli/import.go b/internal/cli/import.go new file mode 100644 index 0000000..af1ff5c --- /dev/null +++ b/internal/cli/import.go @@ -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 --dest [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) +} diff --git a/internal/cli/import_test.go b/internal/cli/import_test.go new file mode 100644 index 0000000..0e89461 --- /dev/null +++ b/internal/cli/import_test.go @@ -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") + } +} diff --git a/internal/cli/validate.go b/internal/cli/validate.go index 631675f..7cbd69a 100644 --- a/internal/cli/validate.go +++ b/internal/cli/validate.go @@ -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": diff --git a/internal/importer/archive.go b/internal/importer/archive.go new file mode 100644 index 0000000..048073f --- /dev/null +++ b/internal/importer/archive.go @@ -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)) +} diff --git a/internal/importer/archive_test.go b/internal/importer/archive_test.go new file mode 100644 index 0000000..b0875f4 --- /dev/null +++ b/internal/importer/archive_test.go @@ -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) + } +} diff --git a/internal/importer/columns.go b/internal/importer/columns.go new file mode 100644 index 0000000..73459f7 --- /dev/null +++ b/internal/importer/columns.go @@ -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 +} diff --git a/internal/importer/columns_test.go b/internal/importer/columns_test.go new file mode 100644 index 0000000..0f0fb31 --- /dev/null +++ b/internal/importer/columns_test.go @@ -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) + } +} diff --git a/internal/importer/dump.go b/internal/importer/dump.go new file mode 100644 index 0000000..14def0b --- /dev/null +++ b/internal/importer/dump.go @@ -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} +} diff --git a/internal/importer/dump_test.go b/internal/importer/dump_test.go new file mode 100644 index 0000000..bf84e75 --- /dev/null +++ b/internal/importer/dump_test.go @@ -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) + } +} diff --git a/internal/importer/engines.go b/internal/importer/engines.go new file mode 100644 index 0000000..c1e8707 --- /dev/null +++ b/internal/importer/engines.go @@ -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} +} diff --git a/internal/importer/integration_test.go b/internal/importer/integration_test.go new file mode 100644 index 0000000..5639d39 --- /dev/null +++ b/internal/importer/integration_test.go @@ -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("") + } 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|\n32|6132|\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) + } + } +} diff --git a/internal/importer/run.go b/internal/importer/run.go new file mode 100644 index 0000000..ad17fc1 --- /dev/null +++ b/internal/importer/run.go @@ -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 "" + } + c.Passwd = "" + return c.FormatDSN() +} diff --git a/internal/importer/run_test.go b/internal/importer/run_test.go new file mode 100644 index 0000000..1d43a0f --- /dev/null +++ b/internal/importer/run_test.go @@ -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) + } + } +} diff --git a/internal/importer/sql.go b/internal/importer/sql.go new file mode 100644 index 0000000..f2e0e6c --- /dev/null +++ b/internal/importer/sql.go @@ -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 +} diff --git a/internal/importer/sql_test.go b/internal/importer/sql_test.go new file mode 100644 index 0000000..deb3e25 --- /dev/null +++ b/internal/importer/sql_test.go @@ -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") + } +} diff --git a/internal/purge/purge.go b/internal/purge/purge.go index 11f011a..d8c0ceb 100644 --- a/internal/purge/purge.go +++ b/internal/purge/purge.go @@ -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 { - q = fmt.Sprintf("DELETE FROM %s WHERE %s BETWEEN ? AND ? AND (%s)", - p.table(), sqlutil.Ident(p.KeyCols[0]), p.Where) - args = []any{lo[0].DriverValue(), hi[0].DriverValue()} + 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(), 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)), diff --git a/internal/purge/purge_test.go b/internal/purge/purge_test.go new file mode 100644 index 0000000..341664e --- /dev/null +++ b/internal/purge/purge_test.go @@ -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) + } +} diff --git a/internal/shard/manifest.go b/internal/shard/manifest.go index 11721d8..6a1df2b 100644 --- a/internal/shard/manifest.go +++ b/internal/shard/manifest.go @@ -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 { diff --git a/internal/shard/select.go b/internal/shard/select.go new file mode 100644 index 0000000..e43c49a --- /dev/null +++ b/internal/shard/select.go @@ -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 +} diff --git a/internal/shard/select_test.go b/internal/shard/select_test.go new file mode 100644 index 0000000..a4e6b43 --- /dev/null +++ b/internal/shard/select_test.go @@ -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") + } +} diff --git a/openspec/changes/allow-date-bulk-delete/.openspec.yaml b/openspec/changes/allow-date-bulk-delete/.openspec.yaml new file mode 100644 index 0000000..c0ad5ed --- /dev/null +++ b/openspec/changes/allow-date-bulk-delete/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-08 diff --git a/openspec/changes/allow-date-bulk-delete/design.md b/openspec/changes/allow-date-bulk-delete/design.md new file mode 100644 index 0000000..1cda9ec --- /dev/null +++ b/openspec/changes/allow-date-bulk-delete/design.md @@ -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 列表模式跳过最大行的行为一致。 diff --git a/openspec/changes/allow-date-bulk-delete/proposal.md b/openspec/changes/allow-date-bulk-delete/proposal.md new file mode 100644 index 0000000..b88236f --- /dev/null +++ b/openspec/changes/allow-date-bulk-delete/proposal.md @@ -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` 的任务行为不变。 diff --git a/openspec/changes/allow-date-bulk-delete/specs/archive-core/spec.md b/openspec/changes/allow-date-bulk-delete/specs/archive-core/spec.md new file mode 100644 index 0000000..eefad07 --- /dev/null +++ b/openspec/changes/allow-date-bulk-delete/specs/archive-core/spec.md @@ -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 ()` + +#### 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** 区间删除语句额外排除该最大键,最大行不被删除,其余区间内行正常删除 diff --git a/openspec/changes/allow-date-bulk-delete/specs/cli-contract/spec.md b/openspec/changes/allow-date-bulk-delete/specs/cli-contract/spec.md new file mode 100644 index 0000000..f110bb2 --- /dev/null +++ b/openspec/changes/allow-date-bulk-delete/specs/cli-contract/spec.md @@ -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** 系统在启动阶段报错 diff --git a/openspec/changes/allow-date-bulk-delete/tasks.md b/openspec/changes/allow-date-bulk-delete/tasks.md new file mode 100644 index 0000000..29a9378 --- /dev/null +++ b/openspec/changes/allow-date-bulk-delete/tasks.md @@ -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 <> ?` 排除当前最大键,不再退回 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 的环境中运行集成测试并完成归档 diff --git a/openspec/changes/archive/2026-11-08-add-archive-import/.openspec.yaml b/openspec/changes/archive/2026-11-08-add-archive-import/.openspec.yaml new file mode 100644 index 0000000..c0ad5ed --- /dev/null +++ b/openspec/changes/archive/2026-11-08-add-archive-import/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-08 diff --git a/openspec/changes/archive/2026-11-08-add-archive-import/design.md b/openspec/changes/archive/2026-11-08-add-archive-import/design.md new file mode 100644 index 0000000..01f37a9 --- /dev/null +++ b/openspec/changes/archive/2026-11-08-add-archive-import/design.md @@ -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::'` 只查 `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` 形如 `.-.[.]`。导入从扩展名推导格式与压缩器,并要求所有选中条目一致;推导结果不是 `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---`); +2. `mysql.RegisterReaderHandler(name, func() io.Reader { ... })` 返回解压 Reader; +3. 执行 `LOAD DATA LOCAL INFILE 'Reader::' ...`; +4. `DeregisterReaderHandler(name)`。 + +字段规则与 `internal/row/dump.go` 的编码严格对应: + +```sql +LOAD DATA LOCAL INFILE 'Reader::' +INTO TABLE . +CHARACTER SET +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_`),由目标表重新计算;首行字段数必须等于清单长度;启动时打印位置映射警告。 +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`,以支持自动建表和更强的核对。 diff --git a/openspec/changes/archive/2026-11-08-add-archive-import/proposal.md b/openspec/changes/archive/2026-11-08-add-archive-import/proposal.md new file mode 100644 index 0000000..077e2c1 --- /dev/null +++ b/openspec/changes/archive/2026-11-08-add-archive-import/proposal.md @@ -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`,吞吐下降但语义不变。 diff --git a/openspec/changes/archive/2026-11-08-add-archive-import/specs/archive-import/spec.md b/openspec/changes/archive/2026-11-08-add-archive-import/specs/archive-import/spec.md new file mode 100644 index 0000000..4086b97 --- /dev/null +++ b/openspec/changes/archive/2026-11-08-add-archive-import/specs/archive-import/spec.md @@ -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 diff --git a/openspec/changes/archive/2026-11-08-add-archive-import/specs/cli-contract/spec.md b/openspec/changes/archive/2026-11-08-add-archive-import/specs/cli-contract/spec.md new file mode 100644 index 0000000..bbd11be --- /dev/null +++ b/openspec/changes/archive/2026-11-08-add-archive-import/specs/cli-contract/spec.md @@ -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 --dest [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 结束,不建立数据库连接 diff --git a/openspec/changes/archive/2026-11-08-add-archive-import/tasks.md b/openspec/changes/archive/2026-11-08-add-archive-import/tasks.md new file mode 100644 index 0000000..58415d9 --- /dev/null +++ b/openspec/changes/archive/2026-11-08-add-archive-import/tasks.md @@ -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_` 丢弃变量,打印位置映射警告 +- [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::'` → 注销 +- [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 ./...` 均通过。 diff --git a/openspec/specs/archive-core/spec.md b/openspec/specs/archive-core/spec.md index 316b7d0..9ea68b9 100644 --- a/openspec/specs/archive-core/spec.md +++ b/openspec/specs/archive-core/spec.md @@ -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: 复制延迟保护 diff --git a/openspec/specs/archive-import/spec.md b/openspec/specs/archive-import/spec.md new file mode 100644 index 0000000..3778c19 --- /dev/null +++ b/openspec/specs/archive-import/spec.md @@ -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 diff --git a/openspec/specs/cli-contract/spec.md b/openspec/specs/cli-contract/spec.md index 62fcf05..c8ae640 100644 --- a/openspec/specs/cli-contract/spec.md +++ b/openspec/specs/cli-contract/spec.md @@ -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 --dest [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: 数量模式误传日期列