Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr, docs, build scripts and ARCHER_* environment variables. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
commit
bc4a6b504f
99 files changed
+12752
No files matched your search
+25
@@ -0,0 +1,25 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 断点续跑
|
||||
|
||||
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。续跑时 MUST 校验源、表、过滤条件、列、分片参数、时区、输出格式与压缩设置的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。压缩档位仅在启用压缩且档位不是默认值 3 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。
|
||||
|
||||
#### Scenario: 配置一致时续跑
|
||||
|
||||
- **WHEN** 上次运行在 chunk 中途退出,且本次配置指纹一致
|
||||
- **THEN** 系统从 `state.json` 记录的游标位置继续,不重复处理已提交的 chunk
|
||||
|
||||
#### Scenario: 配置被修改
|
||||
|
||||
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出不一致的字段,拒绝开始扫描
|
||||
|
||||
#### Scenario: 压缩档位被修改
|
||||
|
||||
- **WHEN** 续跑时 `--compress-level` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出 `compress_level` 字段的变化,拒绝开始扫描
|
||||
|
||||
#### Scenario: 默认档位兼容存量任务
|
||||
|
||||
- **WHEN** `state.json` 由引入压缩档位之前的版本写入,且本次使用默认档位 3
|
||||
- **THEN** 指纹一致,系统正常续跑
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### 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`。
|
||||
|
||||
#### Scenario: 最小可运行配置
|
||||
|
||||
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
|
||||
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
|
||||
|
||||
### 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: 插入模式互斥
|
||||
|
||||
- **WHEN** 用户同时指定 `--insert-ignore` 与 `--replace`
|
||||
- **THEN** 系统报错,要求只能选择一种插入模式
|
||||
|
||||
#### Scenario: 压缩档位越界
|
||||
|
||||
- **WHEN** 用户指定 `--compress-level 0` 或 `--compress-level 10`
|
||||
- **THEN** 系统在启动阶段报错,说明档位必须在 1–9 之间
|
||||
|
||||
#### Scenario: 不压缩却指定非默认档位
|
||||
|
||||
- **WHEN** 用户指定 `--compress none` 与 `--compress-level 5`
|
||||
- **THEN** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 文件命名与目录布局
|
||||
|
||||
分片文件 MUST 按 `<输出目录>/[date=<YYYY-MM-DD>/]<seq>.<pk_lo>-<pk_hi>.<format>[.<compress>]` 命名,`seq` 为从 1 开始的六位零填充序号。日期模式 MUST 按日期建立子目录。输出目录下同时生成 `manifest.jsonl` 与 `state.json`。
|
||||
|
||||
#### Scenario: 数量分片命名
|
||||
|
||||
- **WHEN** 第一个分片主键范围为 1..5000000,格式为 dump,压缩为 zstd
|
||||
- **THEN** 文件名为 `000001.1-5000000.dump.zst`
|
||||
|
||||
#### Scenario: xz 分片命名
|
||||
|
||||
- **WHEN** 第一个分片主键范围为 1..5000000,格式为 dump,压缩为 xz
|
||||
- **THEN** 文件名为 `000001.1-5000000.dump.xz`
|
||||
|
||||
#### Scenario: 日期分片布局
|
||||
|
||||
- **WHEN** `--shard-by date` 导出的首个日期为 2025-06-01
|
||||
- **THEN** 文件位于 `date=2025-06-01/` 子目录下,序号在该日期内从 000001 开始
|
||||
|
||||
### Requirement: 分片清单
|
||||
|
||||
系统 SHALL 在每次分片关闭后向 `manifest.jsonl` 追加一行并 flush,记录序号、相对路径、日期(如适用)、首尾主键、行数、字节数与 SHA-256。清单 MUST 在进程崩溃后仍可用于识别已完成的分片。对于已重命名但尚无清单记录的分片,续跑 MUST 按当前输出格式与压缩扩展名识别、补录并计入序号,不得覆盖。
|
||||
|
||||
#### Scenario: 分片关闭后写入清单
|
||||
|
||||
- **WHEN** 一个分片完成 flush 并重命名
|
||||
- **THEN** `manifest.jsonl` 追加一条包含 seq、path、pk_lo、pk_hi、rows、bytes、sha256、closed_at 的记录
|
||||
|
||||
#### Scenario: 崩溃后识别已完成分片
|
||||
|
||||
- **WHEN** 进程在写完两个分片后崩溃
|
||||
- **THEN** `manifest.jsonl` 中保留这两条完整记录,残留的 `.partial` 文件不进入清单
|
||||
|
||||
#### Scenario: xz 分片在清单追加前崩溃
|
||||
|
||||
- **WHEN** 一个 `.xz` 分片完成重命名后、写 `manifest.jsonl` 前进程崩溃
|
||||
- **THEN** 续跑扫描识别该分片,补录清单,后续序号从其后继续,不覆盖该文件
|
||||
+35
@@ -0,0 +1,35 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 压缩
|
||||
|
||||
系统 SHALL 支持 `--compress none|gzip|zstd|xz`,默认 `none`。每个分片 MUST 独立压缩,压缩后的文件扩展名分别为 `.gz`、`.zst` 与 `.xz`。系统 SHALL 支持 `--compress-level 1..9`,默认 3;档位是跨格式统一语义,数值越大压缩率越高、吞吐越低,9 表示该压缩器的最强档位。gzip 与 zstd 在默认档位下的字节输出 MUST 与引入档位前保持一致。xz 分片 MUST 是标准 xz 流,可被通用 xz 工具解码。
|
||||
|
||||
#### Scenario: gzip 分片
|
||||
|
||||
- **WHEN** `--compress gzip`
|
||||
- **THEN** 每个分片是一个独立的 gzip 流,文件名为 `*.gz`
|
||||
|
||||
#### Scenario: zstd 分片
|
||||
|
||||
- **WHEN** `--compress zstd`
|
||||
- **THEN** 每个分片是一个独立的 zstd 帧,文件名为 `*.zst`
|
||||
|
||||
#### Scenario: xz 分片
|
||||
|
||||
- **WHEN** `--compress xz`
|
||||
- **THEN** 每个分片是一个独立的 xz 流,文件名为 `*.xz`
|
||||
|
||||
#### Scenario: xz 分片可被标准工具解码
|
||||
|
||||
- **WHEN** 产物为 `000001.1-1000.dump.xz`
|
||||
- **THEN** `xz -dc` 可将其还原为与该次扫描行内容一致的 dump 文本
|
||||
|
||||
#### Scenario: 默认档位保持既有产物
|
||||
|
||||
- **WHEN** 用户未指定 `--compress-level`
|
||||
- **THEN** gzip 与 zstd 使用档位 3,产物与引入该参数前的版本一致
|
||||
|
||||
#### Scenario: 各档位对三种压缩器均可用
|
||||
|
||||
- **WHEN** 用户指定 `--compress gzip|zstd|xz` 与任意 `--compress-level 1..9`
|
||||
- **THEN** 系统接受配置并产出对应扩展名的独立压缩分片
|
||||
Reference in new issue
Block a user