Add archer import and allow date-mode bulk delete
archer import replays a sealed archive into an existing table: shard selection (`--select`), SHA-256 pre-verification, idempotent modes (`ignore`/`insert`/`replace`), and both LOAD DATA and batched-INSERT engines. It reads manifest.jsonl strictly so corruption is reported instead of skipped, and supports --dry-run, --allow-partial, and per-shard workers. --bulk-delete no longer rejects --shard-by date. Range deletion now derives its bounds from the chunk's actual keys (date scanners rewrite LastKey into a resumption cursor) and keeps safe-auto-increment semantics by excluding the current max key. A startup warning documents the monotonic-shard-column assumption. Also splits CLI/format/sharding/progress/safety reference docs out of the README, and adds the corresponding OpenSpec change artifacts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
1 parent
bc4a6b504f
commit
366d61ca25
49 files changed
+5099
-342
No files matched your search
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-08
|
||||
@@ -0,0 +1,153 @@
|
||||
## Context
|
||||
|
||||
动机见 `proposal.md`。与本设计直接相关的现状:
|
||||
|
||||
- 归档目录由 `manifest.jsonl`(`internal/shard/manifest.go` 的 `Entry`:`seq`、`path`、`date`、`pk_lo`、`pk_hi`、`rows`、`bytes`、`sha256`)与 `state.json`(`internal/checkpoint.State`:`config`、`complete`)描述。
|
||||
- 全列导出取 `information_schema.COLUMNS` 的全部列并按 ordinal 排序(`probe.go:81-85`、`schema.go:241-247`),包含生成列与不可见列;文件没有列名,`state.json` 只保存原始 `--columns` 字符串,不保存解析后的列名与顺序。
|
||||
- 每个分片独立压缩,`internal/shard/compress.go` 的 `Compressor.Reader` 已能把 gzip/zstd/xz 包装成 `io.ReadCloser`。
|
||||
- 当前 `cmd/archer/main.go` 直接把所有参数交给单一 `flag.FlagSet`;`cli.Config.Validate` 强制要求 `--source`/`--table`/`--where`,导入不能复用这套校验。
|
||||
- `internal/sink.DB` 已实现按 `max_allowed_packet` 分批的参数化多行 `INSERT`,可直接作为插入引擎。
|
||||
- 驱动 `go-sql-driver/mysql` 在握手中无条件发送 `clientLocalFiles`(`packets.go:288`);`LOAD DATA LOCAL INFILE 'Reader::<name>'` 只查 `RegisterReaderHandler` 注册表(`infile.go:105`),不要求 `allowAllFiles`,也不暴露任意文件读取。
|
||||
- MySQL 8.0.3+ 的 `local_infile` 默认关闭;MariaDB 默认开启;托管库由参数组控制。代理/连接池可能不转发本地文件请求。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 按清单安全、可重复、可选择范围地把归档重放进 MySQL。
|
||||
- 复用现有分片、压缩、错误分类与进度基础设施,不改变导出端格式。
|
||||
- 在受限环境(`local_infile` 关闭、经过代理)仍提供可用的兜底路径。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不做行级过滤、断点续导台账或导入状态持久化。
|
||||
- 不自动建表、不推导/迁移表结构。
|
||||
- 不引入服务化入口或第二个二进制。
|
||||
- 不在 v1 支持 csv/jsonl 导入。
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1:同一二进制内的 `import` 子命令
|
||||
|
||||
`main.go` 在解析参数前检查 `os.Args[1] == "import"`,命中则交给 `internal/importer` 的独立解析与运行路径;其余参数仍走现有 `cli.Parse`。这样对现有导出调用完全向后兼容,也不需要拆分仓库或构建两套产物。
|
||||
|
||||
替代方案是新增 `cmd/archer-import` 二进制,但导入要复用清单解析、压缩、错误码、进度与插入实现,独立二进制只会增加发布与版本对齐成本,收益接近于零。
|
||||
|
||||
### D2:清单使用严格只读加载器
|
||||
|
||||
现有 `Manifest.readExisting` 会静默跳过无法解析的行,这对导出续跑是合理的容错,但导入不能把损坏行当成“分片不存在”。新增只读加载函数(例如 `shard.LoadManifest(root)`):逐行解析,遇到非法 JSON 立即报错;不打开 `O_APPEND` 句柄,不修改归档目录。`Entry` 结构保持不变。
|
||||
|
||||
### D3:完成度以 `state.json` 为准,默认拒绝部分归档
|
||||
|
||||
导入前调用 `checkpoint.Load`。默认要求 `complete == true`;`state.json` 缺失或 `complete == false` 时,只有在 `--allow-partial` 下才继续。理由:分片清单只能证明“这些分片已封”,不能证明“导出已覆盖全表”。
|
||||
|
||||
### D4:选择粒度到分片,主键区间按相交语义
|
||||
|
||||
`--select` 可重复,解析为选择器集合,按 `seq` 去重排序:
|
||||
|
||||
- `all`:全部清单条目;
|
||||
- `seq:A-B`:`A <= seq <= B`;
|
||||
- `pk:LO-HI`:分片的 `[pk_lo, pk_hi]` 与 `[LO, HI]` 相交即入选;
|
||||
- `date:D1..D2`:`Entry.Date` 落入闭区间。`count` 分片的 `Date` 为空(`writer.go:357` 只在日期模式下写 bucket),因此对非日期归档按日期选择必须报错。
|
||||
|
||||
`LOAD DATA` 不能过滤行,所以 `pk:`/`date:` 的边界分片会带入范围外的行。`--dry-run` 与启动摘要必须显式提示这一点,避免用户误以为“只导入这个主键段”。
|
||||
|
||||
替代方案是把边界分片解压后逐行过滤再装载,但那样既要写解码器又要丢弃 `LOAD DATA` 的性能优势,v1 不值得。
|
||||
|
||||
### D5:格式与压缩从清单路径推导,v1 只接受 dump
|
||||
|
||||
`Entry.Path` 形如 `<seq>.<lo>-<hi>.<format>[.<comp>]`。导入从扩展名推导格式与压缩器,并要求所有选中条目一致;推导结果不是 `dump` 时报错。这样无需修改归档格式,也对 `none/gzip/zstd/xz` 全部生效。
|
||||
|
||||
### D6:SHA-256 预校验,而不是边导边校验
|
||||
|
||||
`--verify pre`(默认)先以流式读取压缩文件计算 SHA-256,与清单比对,通过后再打开一次用于解压装载。
|
||||
|
||||
替代方案是边装载边计算哈希,末尾不一致时回滚该分片。它省一次顺序读,但要求把整个分片放进一个大事务,且 `LOAD DATA` 在事务中的回滚代价与内存行为不易预测。压缩分片通常是几 MB 到几 GB,额外的顺序读是磁盘带宽级别,远比事务风险便宜。
|
||||
|
||||
### D7:`load` 引擎用注册的流式 Reader,不落临时文件
|
||||
|
||||
每个 worker 持有自己的 `*sql.Conn`,装载单个分片时:
|
||||
|
||||
1. 为分片生成唯一 handler 名(如 `archer-import-<pid>-<seq>-<nonce>`);
|
||||
2. `mysql.RegisterReaderHandler(name, func() io.Reader { ... })` 返回解压 Reader;
|
||||
3. 执行 `LOAD DATA LOCAL INFILE 'Reader::<name>' ...`;
|
||||
4. `DeregisterReaderHandler(name)`。
|
||||
|
||||
字段规则与 `internal/row/dump.go` 的编码严格对应:
|
||||
|
||||
```sql
|
||||
LOAD DATA LOCAL INFILE 'Reader::<name>'
|
||||
INTO TABLE <db>.<table>
|
||||
CHARACTER SET <charset>
|
||||
FIELDS TERMINATED BY '\t' ESCAPED BY '\\'
|
||||
LINES TERMINATED BY '\n'
|
||||
-- 可选: (col1, col2, ...)
|
||||
```
|
||||
|
||||
模式映射为语句中的 `IGNORE` / `REPLACE` 关键字;`insert` 模式不带关键字。会话级 `time_zone` 在连接建立后设置。
|
||||
|
||||
### D8:`insert` 引擎复用 `sink.DB`,每个分片一个事务
|
||||
|
||||
`--engine insert` 使用 `internal/sink.DB.InsertChunk` 的同一套分批逻辑,但输入来自解压后的行解码,而不是扫描结果。为保持“分片失败不留半截数据”,每个分片的所有批次 MUST 包在同一个事务中;这比 `LOAD DATA` 的单语句事务粒度更粗,但只作为兜底路径。
|
||||
|
||||
v1 的 `insert` 引擎同样只支持 `dump`:按行 Split 后把字段转成 `row.Value`(`\N` → NULL,反转义表与 `dumpEncoder` 对称)。这需要一个最小的 dump 解码器;csv/jsonl 的解码各自有歧义或类型依赖,留待后续。
|
||||
|
||||
### D9:启动探测 `local_infile`,失败即停,不静默降级
|
||||
|
||||
在建立目标连接后、装载任何分片前,执行 `SELECT @@local_infile, @@version`。`--engine load` 且值为 0 时返回配置类错误,错误信息同时给出“启用 local_infile”和“改用 `--engine insert`”两条出路。
|
||||
|
||||
静默回退会让几十 GB 的导入从分钟级变成小时级且用户毫无察觉,违背本仓库既有的 fail-fast 风格。
|
||||
|
||||
### D10:列映射按列名,字段数只做前置检查
|
||||
|
||||
先明确归档里到底有什么:全列导出取的是 `information_schema.COLUMNS` 的全部列、按 `ORDINAL_POSITION` 排序(`probe.go:81-85`、`schema.go:241-247`),包含生成列与不可见列;文件本身没有列名。`state.json` 只记录原始 `--columns` 字符串,为空表示“导出时全部列”,**不记录解析后的列名与顺序**。
|
||||
|
||||
因此“文件字段数 == 目标表列数”既不是充分条件(同数换列、改名、交换顺序都能通过),也不应作为映射依据。字段数只用于在装载前给出更早、更清晰的错误。
|
||||
|
||||
列映射按以下优先级确定:
|
||||
|
||||
1. **归档记录了列清单**(`state.json` 的 `columns` 非空):按记录顺序生成 `LOAD DATA` 列清单;逐个校验列名存在于目标表;若记录中包含目标表的生成列,直接报错(生成列不能从归档写入)。
|
||||
2. **`--columns`**:用户按文件字段顺序给出目标列名,做与上一条相同的名校验。它与归档记录的列清单互斥,避免两套来源冲突。
|
||||
3. **`--assume-all-columns`**:接受位置映射。按目标表全部列的 ordinal 顺序生成列清单;生成列替换为丢弃用的用户变量(`@_archer_skip_<i>`),由目标表重新计算;首行字段数必须等于清单长度;启动时打印位置映射警告。
|
||||
4. 以上都不可用时拒绝导入,提示用户提供 `--columns` 或显式接受 `--assume-all-columns`。
|
||||
|
||||
使用显式列清单还能消除 `LOAD DATA` 对不可见列是否计入“全部列”的歧义,因为不可见列可以被显式命名并写入。
|
||||
|
||||
不做自动建表:归档没有记录 DDL,猜测 schema 的风险远大于收益。需要“装到全新实例”时,用户应先建同构表。把有序列名、类型与 `SHOW CREATE TABLE` 写进归档,是让默认全列导出也能严格校验的根治方案,作为后续独立的导出侧改动。
|
||||
|
||||
### D11:告警与行数核对依赖同一会话
|
||||
|
||||
驱动的 `Result` 只暴露 affected rows,不能读取 LOAD DATA 的 `Records/Skipped/Warnings` 信息串。因此每个 worker 必须用固定 `*sql.Conn`(而不是连接池),在装载后立即执行 `SHOW WARNINGS`:
|
||||
|
||||
- 有告警且未指定 `--allow-warnings`:该分片失败;例外是 `ignore` 模式下唯一键冲突产生的告警(错误码 1062),它们是“跳过”而非数据缺陷,已被行数规则计入跳过行数,否则默认 `ignore` 无法做到重复导入幂等;
|
||||
- 行数规则:`insert` 模式要求 affected == 清单 `rows`;`ignore` 模式要求 affected <= `rows`,差额报告为跳过;`replace` 模式的 affected 可能大于 `rows`(覆盖计为删除+插入),只报告不强制相等。
|
||||
|
||||
这比“解析 OK 包信息串”更依赖会话,但驱动没有暴露后者;使用固定连接也顺带保证 `time_zone`/`character_set` 等会话设置不被连接池复用破坏。
|
||||
|
||||
### D12:进度与统计复用现有组件
|
||||
|
||||
`internal/progress.Reporter` 以清单总行数为总量,按分片完成/行数推进;`--statistics` 输出选片数、成功/失败/跳过分片数、期望/实际/跳过行数、字节与耗时。`--dry-run` 只读清单与首行(用于字段数),不连接目标库,也不装载。
|
||||
|
||||
### D13:失败即停,分片原子
|
||||
|
||||
默认在首个失败分片处终止,并报告该分片 `seq`、失败原因与失败前的累计行数。`load` 引擎的单条 `LOAD DATA` 在 InnoDB 下是原子的;`insert` 引擎用每分片一个事务保证同样的可见性。已完成分片不回滚,重跑依赖 `--mode ignore` 的幂等性。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **`local_infile` 被安全基线关闭** → 提供 `--engine insert`;启动时明确报错而不是降级。走代理/连接池时需实测,必要时直连目标实例。
|
||||
- **字符集导致非 ASCII/BLOB 失真** → 默认 `--charset utf8mb4`,提供 `--charset binary`;集成测试覆盖中文、emoji、BLOB、TAB/换行/反斜杠/NULL。
|
||||
- **`TIMESTAMP` 时区漂移** → 归档未记录导出会话时区;提供 `--time-zone` 显式设置目标会话时区,文档说明风险,测试覆盖显式设置与默认两种情况。
|
||||
- **导回线上表造成锁等待/主从延迟** → 默认 `--workers 1`,文档建议低峰执行并监控;`LOAD DATA` 的行锁范围取决于目标表索引。
|
||||
- **部分导入给出不完整查询结果** → 启动与结束摘要显式列出导入范围与行数;`--dry-run` 强制先看选片。
|
||||
- **再次归档边界** → 导回原表的行可能落在下一次归档的 `--where` 范围内;文档提醒归档条件应覆盖“纯冷时间段”。
|
||||
- **位置映射无法发现“同数换列/改名”** → `--assume-all-columns` 只保证字段数一致并打印警告,不具备名校验能力;严格场景要求归档列清单或显式 `--columns`。根治方案是后续让导出端记录有序列名。
|
||||
- **生成列与不可见列** → `--assume-all-columns` 下生成列映射为丢弃变量、由目标表重算;记录列清单包含生成列时直接报错;不可见列通过显式列清单写入。
|
||||
- **没有导入台账** → 依赖 `ignore` 幂等;`insert`/`replace` 重跑可能失败或覆盖,文档明确这一点。
|
||||
- **`SHOW WARNINGS` 需要同会话** → 强制使用 `*sql.Conn`,并在测试中覆盖连接复用场景。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
- 纯增量:现有导出行为、文件格式、清单与 `state.json` 均不变。
|
||||
- 发布:与现有二进制一同构建;`archer import` 对新旧归档都可用。
|
||||
- 回滚:不调用 `import` 子命令即可;已导入的数据需要按业务自行清理。
|
||||
- 后续独立改动(不在本 change 内):归档记录 `format`/`columns`/`charset`/`time_zone` 与 `SHOW CREATE TABLE`,以支持自动建表和更强的核对。
|
||||
@@ -0,0 +1,46 @@
|
||||
## Why
|
||||
|
||||
归档把冷数据移出了热表,但“冷”不等于“永不查询”。目前把归档文件装回 MySQL 只能按 `docs/output-formats.md` 手工 `zcat | mysql`:没有范围选择、没有完整性校验、没有幂等保证,导错或导到一半都会污染原表,而且失败后无法判断哪些分片已经落入。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增 `archer import` 子命令,与导出共用同一个二进制;导入逻辑独立成 `internal/importer` 包。
|
||||
- 以归档目录中的 `manifest.jsonl` 为唯一权威:只导入清单中登记、文件存在且校验通过的分片;目录里游离的文件不导入。
|
||||
- 分片选择支持整表、分片序号区间、主键区间、日期桶区间,多次 `--select` 取并集;选择粒度为整个分片(`LOAD DATA` 不支持行级过滤)。
|
||||
- 列映射支持三种来源:归档记录的列清单、导入时 `--columns` 指定的文件字段顺序、`--assume-all-columns` 的位置映射(会警告)。
|
||||
- 默认要求 `state.json.complete == true`,避免静默导入半张表;`--allow-partial` 显式放开。
|
||||
- 默认对每个压缩分片做 SHA-256 预校验,失败即中止;`--verify off` 可关闭。
|
||||
- 默认 `--mode ignore`(`INSERT IGNORE`),利用归档中的主键实现重复导入幂等;可选 `insert` / `replace`。
|
||||
- 默认 `--engine load`:通过 `mysql.RegisterReaderHandler` 把解压流直接交给 `LOAD DATA LOCAL INFILE`,不落临时文件;启动时探测 `@@local_infile`,关闭则 fail-fast 并提示 `--engine insert`。`--engine insert` 复用现有批量参数化插入作为受限环境兜底。
|
||||
- 目标表必须预先存在。列映射以列名为准:归档记录了列清单时按名校验;默认全列归档必须显式提供 `--columns`,或显式接受 `--assume-all-columns` 的位置映射。文件字段数只作为前置检查,**不得**作为“映射正确”的证明。
|
||||
- 提供 `--dry-run`(打印选中分片、总行数/字节)、`--workers`、`--progress`、`--statistics`。
|
||||
- v1 只支持 `dump` 格式;`csv`/`jsonl` 明确报错并说明原因。
|
||||
- 新增 `docs/import.md`,并在 README 与 CLI 参考中登记导入入口。
|
||||
|
||||
**Non-goals:**
|
||||
|
||||
- 不做常驻服务、HTTP 接口、队列或定时任务。
|
||||
- 不引入第二个二进制或独立仓库。
|
||||
- 不支持 MySQL 以外的目标库。
|
||||
- 不做导入台账或断点续导;幂等由 `IGNORE` 与分片级原子装载保证。
|
||||
- 不做行级过滤,选择粒度只到分片边界。
|
||||
- 不自动建表、不生成 DDL、不修改表结构。
|
||||
- 不改变导出端的文件格式与清单格式。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `archive-import`: 从归档目录按清单重放分片到 MySQL,覆盖分片选择、完整性校验、幂等模式、装载引擎、目标前置检查、进度与失败语义。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `cli-contract`: 增加 `import` 子命令的参数、默认值与校验规则;明确原有“必填参数”仅作用于归档(导出)模式。
|
||||
|
||||
## Impact
|
||||
|
||||
- 代码:`cmd/archer/main.go`(子命令分发)、`internal/cli/import.go`(新增)、`internal/importer/`(新增);复用 `internal/shard`(清单)、`internal/sink`(插入兜底)、`internal/progress`、`internal/archererr`、`internal/atomicfile`。
|
||||
- 依赖:无新增外部依赖;`github.com/go-sql-driver/mysql` 已支持 `Reader::` 形式的 `LOAD DATA LOCAL INFILE`,且不需要 `allowAllFiles`。
|
||||
- 测试:新增 `internal/importer` 单元测试;新增导入集成测试,沿用 `ARCHER_TEST_DSN` 门控。
|
||||
- 文档:`docs/import.md`、`README.md`、`docs/cli-reference.md`。
|
||||
- 运维:目标库需要启用 `local_infile`(MySQL 8.0.3+ 默认关闭);不满足时使用 `--engine insert`,吞吐下降但语义不变。
|
||||
@@ -0,0 +1,241 @@
|
||||
## Purpose
|
||||
|
||||
定义如何把一次归档产出(分片文件 + `manifest.jsonl` + `state.json`)按需、可校验、可重复地重放进 MySQL 目标表,供冷数据查询与恢复使用。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 归档目录与清单权威性
|
||||
|
||||
一次导入 MUST 以一个包含 `manifest.jsonl` 的归档目录为单元。系统 MUST 以清单记录为唯一权威:只考虑清单中登记的分片,并按 `seq` 升序处理;清单之外的文件 MUST NOT 导入。清单条目指向的文件缺失时,系统 MUST 报错并终止,不得跳过该条目继续导入。
|
||||
|
||||
#### Scenario: 目录中存在未登记文件
|
||||
|
||||
- **WHEN** 归档目录中有一个已封分片文件,但 `manifest.jsonl` 没有对应记录
|
||||
- **THEN** 系统不导入该文件,并在统计中报告其被忽略
|
||||
|
||||
#### Scenario: 清单条目对应文件缺失
|
||||
|
||||
- **WHEN** 清单登记了 `000003.*`,但该文件已被删除
|
||||
- **THEN** 系统在开始装载前报错,指出缺失的分片序号与路径
|
||||
|
||||
#### Scenario: 清单包含损坏行
|
||||
|
||||
- **WHEN** `manifest.jsonl` 中某行不是合法 JSON
|
||||
- **THEN** 系统报错并终止,不得把损坏行当作“没有该分片”处理
|
||||
|
||||
### Requirement: 归档完成度门槛
|
||||
|
||||
默认情况下,系统 MUST 要求 `state.json` 存在且 `complete` 为 `true`;不满足时 MUST 在导入任何分片前报错,并提示可使用 `--allow-partial` 显式导入已封分片。启用 `--allow-partial` 时,系统 SHALL 忽略完成度标记,只导入清单中已封的分片。
|
||||
|
||||
#### Scenario: 未完成的归档
|
||||
|
||||
- **WHEN** `state.json` 中 `complete` 为 `false`,且未指定 `--allow-partial`
|
||||
- **THEN** 系统拒绝导入,说明该归档可能只包含部分数据
|
||||
|
||||
#### Scenario: 显式导入部分归档
|
||||
|
||||
- **WHEN** `complete` 为 `false`,且指定 `--allow-partial`
|
||||
- **THEN** 系统导入清单中所有已封分片,并在结束统计中标注“部分归档”
|
||||
|
||||
#### Scenario: 缺少 state.json
|
||||
|
||||
- **WHEN** 归档目录没有 `state.json`,且未指定 `--allow-partial`
|
||||
- **THEN** 系统拒绝导入,说明无法确认导出是否完成
|
||||
|
||||
### Requirement: 分片选择
|
||||
|
||||
系统 MUST 支持通过可重复的 `--select` 选择分片,多个选择条件取并集并按 `seq` 去重。支持的语法为:`all`、`seq:A-B`(闭区间)、`pk:LO-HI`、`date:D1..D2`(闭区间)。未提供 `--select` 时等价于 `all`。
|
||||
|
||||
`pk:LO-HI` MUST 选择主键范围与闭区间 `[LO,HI]` 相交的分片;由于装载不支持行级过滤,边界分片可能包含请求范围之外的行,系统 MUST 在选择结果中明示这一点。`date:D1..D2` MUST 只匹配清单中带日期桶的分片;归档不含日期信息时,系统 MUST 报错并说明该归档不是按日期分片导出的。
|
||||
|
||||
#### Scenario: 按序号选择
|
||||
|
||||
- **WHEN** `--select seq:3-9`
|
||||
- **THEN** 系统只导入 `seq` 在 3 到 9(含)之间的分片
|
||||
|
||||
#### Scenario: 主键区间命中边界分片
|
||||
|
||||
- **WHEN** 请求 `--select pk:150000-250000`,而分片 1 的范围是 `1-200000`、分片 2 是 `200001-400000`
|
||||
- **THEN** 系统选择分片 1 和 2,并提示分片 1 会带入 `1-149999` 的行
|
||||
|
||||
#### Scenario: 多次选择取并集
|
||||
|
||||
- **WHEN** 同时给出 `--select seq:1-2` 与 `--select seq:2-3`
|
||||
- **THEN** 系统导入分片 1、2、3,不重复处理分片 2
|
||||
|
||||
#### Scenario: 对非日期分片按日期选择
|
||||
|
||||
- **WHEN** 归档为 `--shard-by count` 导出(清单无日期桶),用户指定 `--select date:2025-01-01..2025-01-31`
|
||||
- **THEN** 系统报错,说明该归档无法按日期选择,只能按序号或主键范围选择
|
||||
|
||||
#### Scenario: 选择结果为空
|
||||
|
||||
- **WHEN** 选择条件没有命中任何分片
|
||||
- **THEN** 系统报错并以非零退出码结束,不连接目标库执行装载
|
||||
|
||||
### Requirement: 完整性校验
|
||||
|
||||
默认情况下,系统 MUST 在装载每个分片前计算其压缩文件的 SHA-256,并与清单记录比对;不一致时 MUST 中止该分片并终止本次导入。`--verify off` 可关闭预校验。
|
||||
|
||||
每个分片装载完成后,系统 MUST 核对实际写入行数:`insert` 模式下 MUST 等于清单 `rows`;`ignore` 模式下 MUST NOT 大于 `rows`,差额 SHALL 报告为跳过行数;`replace` 模式 SHALL 只报告受影响行数。不满足对应规则时 MUST 视为失败并终止。
|
||||
|
||||
#### Scenario: 分片内容损坏
|
||||
|
||||
- **WHEN** 某分片的 SHA-256 与清单不一致
|
||||
- **THEN** 系统在发送任何该分片数据前失败,指出分片序号与期望/实际哈希
|
||||
|
||||
#### Scenario: 严格插入的行数不足
|
||||
|
||||
- **WHEN** `--mode insert` 装载一个清单记录 200000 行的分片,但实际写入 199999 行
|
||||
- **THEN** 系统报错并终止,指出分片序号与行数差异
|
||||
|
||||
#### Scenario: 重复导入产生的跳过
|
||||
|
||||
- **WHEN** 使用默认 `--mode ignore` 重复导入同一分片
|
||||
- **THEN** 实际写入为 0、跳过为清单行数,导入继续并最终成功
|
||||
|
||||
### Requirement: 插入模式与幂等
|
||||
|
||||
系统 MUST 提供 `--mode ignore|insert|replace`,默认 `ignore`。三种模式互斥。`ignore` MUST 跳过与目标表现有唯一键冲突的行且不修改既有行;`insert` MUST 在遇到重复键时失败;`replace` MUST 用归档内容覆盖冲突行。
|
||||
|
||||
系统 MUST NOT 在分片内部按行过滤;选择只决定导入哪些分片。
|
||||
|
||||
#### Scenario: 重复导入原表
|
||||
|
||||
- **WHEN** 目标表已包含归档中的全部行,且使用默认 `--mode ignore`
|
||||
- **THEN** 导入成功,所有冲突行被跳过,目标表数据不变
|
||||
|
||||
#### Scenario: 严格插入遇到重复键
|
||||
|
||||
- **WHEN** 使用 `--mode insert`,目标表已存在相同主键
|
||||
- **THEN** 该分片装载失败,系统报告重复键错误并终止
|
||||
|
||||
#### Scenario: 覆盖模式
|
||||
|
||||
- **WHEN** 使用 `--mode replace`,目标表存在相同主键但列值不同
|
||||
- **THEN** 目标行被归档内容覆盖
|
||||
|
||||
### Requirement: 装载引擎与 local_infile
|
||||
|
||||
系统 MUST 提供 `--engine load|insert`,默认 `load`。
|
||||
|
||||
`load` 引擎 MUST 通过客户端流式读取解压后的数据并执行 `LOAD DATA LOCAL INFILE`,MUST NOT 依赖将完整分片写入临时文件,也 MUST NOT 要求驱动开启任意本地文件读取。其字段与行分隔规则 MUST 与 `dump` 格式的产出完全对应。
|
||||
|
||||
启动时,系统 MUST 查询目标会话的 `local_infile` 状态。`load` 引擎在 `local_infile` 关闭时 MUST 在导入任何分片前失败,并在错误信息中给出两条出路:启用 `local_infile`,或改用 `--engine insert`。系统 MUST NOT 静默回退到 `insert`。
|
||||
|
||||
`insert` 引擎 MUST 使用参数化批量插入,并遵守目标的 `max_allowed_packet`。两种引擎对同一归档、同一目标表的行结果 MUST 一致。
|
||||
|
||||
服务端报告告警时,系统 MUST 默认视为失败;`--allow-warnings` 可改为记录告警并继续。`ignore` 模式下因唯一键冲突被跳过的行 SHALL 计入跳过行数,其重复键告警 MUST NOT 单独导致分片失败,否则默认重跑无法幂等。
|
||||
|
||||
#### Scenario: local_infile 已关闭
|
||||
|
||||
- **WHEN** `SELECT @@local_infile` 返回 0,且使用默认 `--engine load`
|
||||
- **THEN** 系统在装载任何分片前失败,并提示启用该变量或改用 `--engine insert`
|
||||
|
||||
#### Scenario: 显式使用插入兜底
|
||||
|
||||
- **WHEN** `local_infile` 关闭,且指定 `--engine insert`
|
||||
- **THEN** 系统通过批量参数化插入完成导入,行为与 `load` 引擎一致
|
||||
|
||||
#### Scenario: 装载产生告警
|
||||
|
||||
- **WHEN** 服务端返回至少一条告警,且未指定 `--allow-warnings`
|
||||
- **THEN** 系统把该分片视为失败并终止
|
||||
|
||||
### Requirement: 目标表与列映射
|
||||
|
||||
目标表 MUST 预先存在;不存在时系统 MUST 在装载前报错,不尝试创建表。
|
||||
|
||||
列映射 MUST 以列名而不是文件位置为准。当归档记录了列清单时(`state.json` 的 `columns` 非空):
|
||||
|
||||
- 每个记录的列名 MUST 在目标表中存在,否则 MUST 报错;
|
||||
- 装载列清单 MUST 按记录顺序生成;
|
||||
- 记录中包含目标表的生成列时,系统 MUST 报错,不得静默丢弃该字段或写入生成列。
|
||||
|
||||
当归档为默认全列导出、未记录列名时,系统 MUST NOT 仅凭“文件字段数等于目标表列数”认为映射正确。此时用户 MUST 显式提供以下之一:
|
||||
|
||||
- `--columns`:按文件字段顺序给出目标列名,系统按名校验并生成装载列清单;
|
||||
- `--assume-all-columns`:接受位置映射,系统按目标表全部列的 ordinal 顺序生成装载列清单,把生成列映射为丢弃用的用户变量,并 MUST 打印位置映射警告。
|
||||
|
||||
文件字段数与装载列清单长度不一致时,系统 MUST 在装载前报错。字段数核对只是前置检查,列名与顺序的正确性由记录列清单或显式 `--columns` 保证。
|
||||
|
||||
#### Scenario: 目标表不存在
|
||||
|
||||
- **WHEN** `--dest` 指向的库中没有目标表
|
||||
- **THEN** 系统报错,提示需要先创建表
|
||||
|
||||
#### Scenario: 归档记录了列清单且目标缺列
|
||||
|
||||
- **WHEN** 归档记录列 `id,created_at,title`,目标表只有 `id,created_at`
|
||||
- **THEN** 系统在装载前报错,指出缺失的列名
|
||||
|
||||
#### Scenario: 归档列清单包含生成列
|
||||
|
||||
- **WHEN** 归档记录的列清单包含目标表的生成列 `full_name`
|
||||
- **THEN** 系统报错,说明生成列不能从归档写入
|
||||
|
||||
#### Scenario: 全列归档未提供映射
|
||||
|
||||
- **WHEN** 归档未记录列名,且既未提供 `--columns` 也未指定 `--assume-all-columns`
|
||||
- **THEN** 系统拒绝导入,并说明两种显式映射方式
|
||||
|
||||
#### Scenario: 位置映射遇到生成列
|
||||
|
||||
- **WHEN** 使用 `--assume-all-columns`,目标表含一个生成列,且文件字段数与全部列数一致
|
||||
- **THEN** 系统把生成列位置映射为丢弃变量,装载成功,并打印位置映射警告
|
||||
|
||||
#### Scenario: 字段数不一致
|
||||
|
||||
- **WHEN** 文件首行有 10 个字段,装载列清单长度为 11
|
||||
- **THEN** 系统在装载前报错,指出字段数与列清单长度
|
||||
|
||||
### Requirement: 进度、统计与 dry-run
|
||||
|
||||
启用 `--dry-run` 时,系统 MUST 打印解析后的配置、选中的分片列表(序号、路径、行数、字节数、日期桶)、总行数与总字节数,并 MUST NOT 执行任何装载或写入。启用 `--progress` 时,系统 SHALL 按分片完成情况输出已导入行数与分片进度。启用 `--statistics` 时,系统 MUST 在结束时输出选片数、成功/失败/跳过分片数、期望/实际/跳过的行数、字节数与耗时。
|
||||
|
||||
`--workers N` 默认 1(N 必须大于 0)。并行时系统 MUST 以连续 `seq` 区间分配分片,且最终数据结果 MUST 与串行导入一致。
|
||||
|
||||
#### Scenario: dry-run 不写数据
|
||||
|
||||
- **WHEN** 用户传入 `--dry-run`
|
||||
- **THEN** 标准输出包含选中分片与汇总信息,目标表不发生任何写入
|
||||
|
||||
#### Scenario: 并行导入结果一致
|
||||
|
||||
- **WHEN** 同一归档分别以 `--workers 1` 与 `--workers 4` 导入空表
|
||||
- **THEN** 两次导入后的目标表行集合相同
|
||||
|
||||
### Requirement: 失败语义与退出码
|
||||
|
||||
每个分片的装载 MUST 是原子的:分片失败时,系统 MUST NOT 在该分片留下部分行;此前已成功的分片 SHALL 保持已导入状态。系统 MUST 在首个分片失败时终止,并报告失败分片序号与失败前的累计导入行数。使用 `--mode ignore` 时,修复问题后重跑 MUST 安全。
|
||||
|
||||
成功完成时系统 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片,并返回非零退出码。
|
||||
|
||||
#### Scenario: 分片装载中断
|
||||
|
||||
- **WHEN** 第 3 个分片在装载过程中失败
|
||||
- **THEN** 分片 3 不留下部分行,分片 1、2 保持已导入,进程以非零退出码结束
|
||||
|
||||
#### Scenario: 修复后重跑
|
||||
|
||||
- **WHEN** 上次导入在第 3 个分片失败,修复原因后使用默认 `--mode ignore` 重跑
|
||||
- **THEN** 已导入的分片被跳过,导入从失败处继续完成
|
||||
|
||||
#### Scenario: 参数错误
|
||||
|
||||
- **WHEN** `--workers 0` 或未知 `--select` 语法
|
||||
- **THEN** 系统在连接数据库前报错,退出码为 2
|
||||
|
||||
### Requirement: 格式支持范围
|
||||
|
||||
v1 的导入 MUST 只支持 `dump` 格式。归档为 `csv` 或 `jsonl` 时,系统 MUST 报错并说明当前仅支持 `dump`,不得尝试按 dump 规则解析。
|
||||
|
||||
#### Scenario: csv 归档
|
||||
|
||||
- **WHEN** 选中的分片扩展名为 `.csv` 或 `.csv.gz`
|
||||
- **THEN** 系统报错,说明导入功能暂不支持 csv
|
||||
|
||||
#### Scenario: jsonl 归档
|
||||
|
||||
- **WHEN** 选中的分片扩展名为 `.jsonl`
|
||||
- **THEN** 系统报错,说明导入功能暂不支持 jsonl
|
||||
@@ -0,0 +1,106 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 必填参数
|
||||
|
||||
归档(导出)模式下,系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
|
||||
|
||||
导入模式(`archer import`)MUST 要求提供 `--file` 与 `--dest`;`--source`、`--where`、`--purge` 在导入模式下 MUST 被拒绝。缺少必需参数时,系统 MUST 在连接目标数据库前报错退出。
|
||||
|
||||
#### Scenario: 缺少过滤条件
|
||||
|
||||
- **WHEN** 归档模式未提供 `--where`
|
||||
- **THEN** 系统立即报错,提示 `--where` 必填,不建立数据库连接
|
||||
|
||||
#### Scenario: 没有任何输出目标
|
||||
|
||||
- **WHEN** 归档模式既未提供 `--file`、`--dest`,也未启用 `--purge`
|
||||
- **THEN** 系统报错,提示至少需要一种输出目标
|
||||
|
||||
#### Scenario: 导入模式缺少目标
|
||||
|
||||
- **WHEN** `archer import` 未提供 `--dest`
|
||||
- **THEN** 系统立即报错,提示 `--dest` 必填,不建立数据库连接
|
||||
|
||||
#### Scenario: 导入模式误用导出参数
|
||||
|
||||
- **WHEN** `archer import` 带上 `--source` 或 `--where`
|
||||
- **THEN** 系统在解析阶段报错,说明该参数仅用于归档模式
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 导入子命令
|
||||
|
||||
系统 MUST 提供 `archer import` 子命令,语法为 `archer import --file <dir> --dest <dsn> [flags]`。未知参数 MUST 报错。`archer import --help` MUST 打印导入模式的参数说明;`archer --version` 与 `archer import --version` MUST 均可打印版本并退出。
|
||||
|
||||
导入模式的参数与默认值:
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `--file` | 必填 | 归档目录,必须存在且包含 `manifest.jsonl` |
|
||||
| `--dest` | 必填 | 目标 MySQL DSN |
|
||||
| `--dest-table` | 归档记录的源表名 | 目标表名;归档未记录表名时必须显式提供 |
|
||||
| `--columns` | 空 | 按文件字段顺序给出目标列名;与 `--assume-all-columns` 互斥 |
|
||||
| `--assume-all-columns` | 关闭 | 接受与目标表 ordinal 顺序一致的位置映射,并打印警告 |
|
||||
| `--select` | `all` | 可重复;`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2` |
|
||||
| `--mode` | `ignore` | `ignore` / `insert` / `replace` |
|
||||
| `--engine` | `load` | `load` / `insert` |
|
||||
| `--verify` | `pre` | `pre` / `off` |
|
||||
| `--workers` | `1` | 并行分片数,必须大于 0 |
|
||||
| `--charset` | `utf8mb4` | 装载时使用的字符集 |
|
||||
| `--time-zone` | 空 | 设置目标会话时区;空表示使用服务端默认 |
|
||||
| `--allow-partial` | 关闭 | 允许导入未完成归档的已封分片 |
|
||||
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
|
||||
| `--dry-run` | 关闭 | 只打印选片与配置 |
|
||||
| `--progress` | `auto` | 进度输出 |
|
||||
| `--statistics` | 关闭 | 结束汇总 |
|
||||
|
||||
#### Scenario: 最小导入命令
|
||||
|
||||
- **WHEN** 用户执行 `archer import --file ./export/orders --dest 'user:pass@tcp(host:3306)/db'`
|
||||
- **THEN** 系统按默认值解析为 `all` / `ignore` / `load` / `pre` / 1 个 worker
|
||||
|
||||
#### Scenario: 未知参数
|
||||
|
||||
- **WHEN** 用户给 `archer import` 传入未定义的参数
|
||||
- **THEN** 系统报错并以退出码 2 结束
|
||||
|
||||
#### Scenario: 非法 worker 数
|
||||
|
||||
- **WHEN** 用户指定 `--workers 0`
|
||||
- **THEN** 系统在连接数据库前报错,说明必须大于 0
|
||||
|
||||
#### Scenario: 非法模式
|
||||
|
||||
- **WHEN** 用户指定 `--mode merge` 或 `--engine bulk`
|
||||
- **THEN** 系统在解析阶段报错,列出允许的取值
|
||||
|
||||
#### Scenario: 列映射参数互斥
|
||||
|
||||
- **WHEN** 用户同时指定 `--columns` 与 `--assume-all-columns`
|
||||
- **THEN** 系统在连接数据库前报错,说明二者只能选一个
|
||||
|
||||
#### Scenario: 归档已记录列清单又显式指定映射
|
||||
|
||||
- **WHEN** `state.json` 的 `columns` 非空,且用户仍指定 `--columns` 或 `--assume-all-columns`
|
||||
- **THEN** 系统报错,避免两套映射来源冲突
|
||||
|
||||
### Requirement: 导入模式的 dry-run、进度与退出码
|
||||
|
||||
`--dry-run` 时,系统 MUST 打印解析后的导入配置、选中分片与汇总,MUST NOT 执行装载或写入。`--progress` 与 `--statistics` 在导入模式下的语义 SHALL 与归档模式一致,分别输出分片进度与结束汇总。
|
||||
|
||||
成功完成 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片并返回非零退出码。
|
||||
|
||||
#### Scenario: dry-run
|
||||
|
||||
- **WHEN** 用户执行 `archer import ... --dry-run`
|
||||
- **THEN** 标准输出包含选中分片、总行数与总字节数,目标库没有数据变化
|
||||
|
||||
#### Scenario: 结束统计
|
||||
|
||||
- **WHEN** 用户执行 `archer import ... --statistics`
|
||||
- **THEN** 进程退出前输出成功/跳过/失败分片数、行数与耗时
|
||||
|
||||
#### Scenario: 配置错误退出码
|
||||
|
||||
- **WHEN** `--select` 语法非法
|
||||
- **THEN** 进程以退出码 2 结束,不建立数据库连接
|
||||
@@ -0,0 +1,82 @@
|
||||
## 1. CLI 子命令与配置
|
||||
|
||||
- [x] 1.1 `cmd/archer/main.go`:在解析参数前识别 `os.Args[1] == "import"`,分发到导入入口;其余参数保持现有行为
|
||||
- [x] 1.2 新建 `internal/cli/import.go`:`ImportConfig`、`ParseImport`、`ValidateImport`,与现有 `Config` 解耦
|
||||
- [x] 1.3 实现导入参数与默认值:`--file`、`--dest`、`--dest-table`、`--columns`、`--assume-all-columns`、`--select`、`--mode`、`--engine`、`--verify`、`--workers`、`--charset`、`--time-zone`、`--allow-partial`、`--allow-warnings`、`--dry-run`、`--progress`、`--statistics`
|
||||
- [x] 1.4 拒绝导出专属参数(`--source`、`--where`、`--purge` 等)与未知参数,退出码 2;`--columns` 与 `--assume-all-columns` 互斥
|
||||
- [x] 1.5 `archer import --help` 与 `archer import --version` 可用
|
||||
- [x] 1.6 单元测试:默认值、参数互斥、非法 `--mode`/`--engine`/`--workers`/`--select`、导出参数被拒绝、列映射参数冲突
|
||||
|
||||
## 2. 归档读取与选片
|
||||
|
||||
- [x] 2.1 在 `internal/shard` 新增严格只读清单加载器:解析失败即报错,不打开追加句柄、不修改归档
|
||||
- [x] 2.2 从 `Entry.Path` 推导格式与压缩方式,并要求所有选中分片一致;非 `dump` 报错
|
||||
- [x] 2.3 实现 `--select` 解析:`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2`,多次取并集、按 `seq` 去重排序
|
||||
- [x] 2.4 `pk:` 使用分片区间相交语义;`date:` 在清单无日期桶时报错
|
||||
- [x] 2.5 使用 `checkpoint.Load` 实现完成度门槛:默认要求 `complete == true`,`--allow-partial` 放开
|
||||
- [x] 2.6 校验选中分片文件存在;清单损坏、条目文件缺失时在连接数据库前报错
|
||||
- [x] 2.7 单元测试:四种选择器、并集去重、空选择、日期桶缺失、损坏清单行、缺失文件、完成度门槛
|
||||
|
||||
## 3. 目标库前置检查与列映射
|
||||
|
||||
- [x] 3.1 建立目标连接,执行 `SELECT @@local_infile, @@version`;`--engine load` 且关闭时给出可操作错误
|
||||
- [x] 3.2 校验目标表存在(`information_schema.tables`),不存在时报错
|
||||
- [x] 3.3 加载目标列元数据(名、ordinal、是否为 `VIRTUAL/STORED GENERATED`)
|
||||
- [x] 3.4 归档记录列清单时:按记录顺序按名校验目标列存在、拒绝包含生成列、生成 `LOAD DATA` 列清单
|
||||
- [x] 3.5 `--columns` 模式:解析用户提供的文件字段顺序,做与 3.4 相同的名校验
|
||||
- [x] 3.6 `--assume-all-columns` 模式:按目标 ordinal 生成列清单,生成列替换为 `@_archer_skip_<i>` 丢弃变量,打印位置映射警告
|
||||
- [x] 3.7 无任何映射来源时拒绝导入,提示 `--columns` 或 `--assume-all-columns`
|
||||
- [x] 3.8 读取首个选中分片首行,按未转义 TAB 统计字段数,与列清单长度比较;不一致在装载前报错
|
||||
- [x] 3.9 每个 worker 使用固定 `*sql.Conn`,设置 `character_set` 与可选 `time_zone`
|
||||
- [x] 3.10 单元测试:名校验、缺失列、生成列拒绝、位置映射丢弃变量、字段数不一致、映射来源缺失
|
||||
|
||||
## 4. load 引擎
|
||||
|
||||
- [x] 4.1 实现单分片流式装载:注册唯一 `Reader` handler → 解压 Reader → 执行 `LOAD DATA LOCAL INFILE 'Reader::<name>'` → 注销
|
||||
- [x] 4.2 生成与 `dump` 编码严格对应的 SQL:`FIELDS TERMINATED BY '\t' ESCAPED BY '\\' LINES TERMINATED BY '\n'`、`CHARACTER SET`、可选列清单、`IGNORE`/`REPLACE`
|
||||
- [x] 4.3 实现 `--verify pre`:流式计算压缩文件 SHA-256 并与清单比对;`--verify off` 跳过
|
||||
- [x] 4.4 装载后在同一会话执行 `SHOW WARNINGS`;有告警且未指定 `--allow-warnings` 时失败
|
||||
- [x] 4.5 实现行数规则:`insert` 要求 affected == rows;`ignore` 要求 affected <= rows 并报告差额;`replace` 只报告
|
||||
- [x] 4.6 确保失败路径清理 handler 注册与文件句柄
|
||||
- [x] 4.7 单元测试:SQL 形状、模式映射、哈希不一致、告警失败、行数规则
|
||||
|
||||
## 5. insert 兜底引擎
|
||||
|
||||
- [x] 5.1 实现最小 `dump` 行解码器:TAB 分隔、`\N` → NULL、反转义 `\\ \t \n \r \0 \b \Z`
|
||||
- [x] 5.2 复用 `internal/sink.DB` 的分批插入逻辑,按 `max_allowed_packet` 切批
|
||||
- [x] 5.3 每个分片的所有批次包在同一个事务中,保证分片级原子
|
||||
- [x] 5.4 单元测试:解码器边界(空串、NULL、转义、中文、emoji、BLOB)、分批与事务提交/回滚
|
||||
|
||||
## 6. 运行编排
|
||||
|
||||
- [x] 6.1 实现 worker 池:按连续 `seq` 区间分配,默认 1,结果与串行一致
|
||||
- [x] 6.2 接入 `internal/progress.Reporter`:以清单总行数为总量,按分片与行数推进
|
||||
- [x] 6.3 实现 `--statistics`:选片数、成功/失败/跳过分片数、期望/实际/跳过行数、字节与耗时
|
||||
- [x] 6.4 实现 `--dry-run`:只读清单与首行,打印选片、总行数/字节、目标表与引擎,不连接目标库、不装载
|
||||
- [x] 6.5 失败即停:报告失败分片 `seq`、原因与累计行数;已成功分片保留
|
||||
- [x] 6.6 用 `internal/archererr` 映射退出码:配置 2、连接 3、写入 4、校验 5、中断 130
|
||||
- [x] 6.7 信号中断:停止开始新分片,当前分片完成或安全失败后以非零码退出
|
||||
|
||||
## 7. 测试
|
||||
|
||||
- [x] 7.1 单元测试:选片、清单、字段数、SQL、解码器、退出码
|
||||
- [x] 7.2 集成测试:导出小表 → 导入空表,比较行数与抽样内容(沿用 `ARCHER_TEST_DSN` 门控)
|
||||
- [x] 7.3 集成测试:`none`/`gzip`/`zstd`/`xz` 四种压缩的导入
|
||||
- [x] 7.4 集成测试:`ignore` 重复导入幂等、`insert` 遇重复失败、`replace` 覆盖
|
||||
- [x] 7.5 集成测试:篡改分片触发哈希失败、`complete=false` 默认拒绝与 `--allow-partial` 放开
|
||||
- [x] 7.6 集成测试:`--workers 1` 与 `--workers 4` 导入结果一致
|
||||
- [x] 7.7 集成测试:`--engine insert` 与 `--engine load` 结果一致
|
||||
- [x] 7.8 保真测试:NULL、TAB、换行、反斜杠、中文、emoji、BLOB 的导出→导入往返
|
||||
- [x] 7.9 列映射测试:归档列清单、`--columns`、`--assume-all-columns` 三种来源;目标表含生成列时丢弃变量生效;缺失列/字段数不一致被拒绝
|
||||
- [x] 7.10 `gofmt`、`go build ./...`、`go vet ./...`、`go test ./...` 通过
|
||||
|
||||
## 8. 文档与 OpenSpec
|
||||
|
||||
- [x] 8.1 新增 `docs/import.md`:使用示例、选片语义、完整性检查、两种引擎、`local_infile` 与代理限制、导回原表的注意事项
|
||||
- [x] 8.2 更新 `README.md` 的功能与文档索引
|
||||
- [x] 8.3 更新 `docs/cli-reference.md` 的导入参数表
|
||||
- [x] 8.4 运行 `openspec validate add-archive-import --strict`
|
||||
- [x] 8.5 在具备 MySQL 的环境中完成一次真实归档目录的按需导入,并记录结果
|
||||
- 2026-11-08:临时 MySQL 8.3.0 实例(`local_infile=ON`)。`ARCHER_TEST_DSN` 门控下运行 `go test ./internal/importer -run Integration -v`,导出→导入、四种压缩、三种模式、哈希/完成度门槛、workers 1/4、load/insert 引擎、保真往返、三种列映射全部通过。
|
||||
- 2026-11-08 手工 CLI:导出一张 7 行表为 3 个 count 分片;`archer import --workers 2 --assume-all-columns --statistics` 导入空表,7/7 行与原表逐列一致(affected=7,skipped=0)。默认 `ignore` 重跑:affected=0,skipped=7。`--dry-run` 未建立连接。
|
||||
- 同次运行 `go build ./...`、`go vet ./...`、全量 `go test ./...` 均通过。
|
||||
Reference in new issue
Block a user