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:
voidandClaude Sonnet 4.6 committed 2026-11-06 22:12:17 +08:00
commit bc4a6b504f
99 files changed
+12752

No files matched your search

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-06
@@ -0,0 +1,3 @@
# add-compress-level-and-xz
新增 xz 压缩格式,并引入统一 1-9 压缩档位 --compress-level
@@ -0,0 +1,85 @@
# 设计:xz 压缩与统一压缩档位
## 依赖选择
采用 `github.com/ulikunitz/xz`(纯 Go、BSD-3、读写齐全)。
| 方案 | 结论 |
|---|---|
| `klauspost/compress` | 不支持 xz |
| cgo 绑定 liblzma | 破坏交叉编译与"纯 Go 构建"约束 |
| 外部 `xz` 进程 | 额外运行时依赖、错误处理与安全面变大 |
| `ulikunitz/xz` | 唯一可行,本机 module cache 已有 v0.5.17 |
## 档位模型:1–9 是语义档位,不是原生级别
zstd 库没有连续 1–22 级别,只有 4 个 `EncoderLevel`;xz 库没有 preset 参数。因此 1–9 被定义为**跨格式语义档位**,各格式显式映射,9 表示该格式最强:
| level | gzip (flate) | zstd | xz 字典 |
|---|---|---|---|
| 1 | 1 | SpeedFastest | 1 MiB |
| 2 | 2 | SpeedFastest | 2 MiB |
| 3 | 3 | SpeedDefault | 4 MiB |
| 4 | 4 | SpeedDefault | 4 MiB |
| 5 | 5 | SpeedDefault | 8 MiB |
| 6 | 6 | SpeedBetterCompression | 8 MiB |
| 7 | 7 | SpeedBetterCompression | 16 MiB |
| 8 | 8 | SpeedBetterCompression | 32 MiB |
| 9 | 9 | SpeedBestCompression | 64 MiB |
默认 3:gzip 与现行 `NewWriterLevel(3)` 一致;zstd 的 `SpeedDefault` 与现行代码一致;xz 无历史行为。
xz 映射只设置 `WriterConfig.DictCap`,其余使用库默认(CRC64、hash-table matcher)。这与 `xz -N` 的字典表一致,但不比特级复刻 xz-utils 的 preset(matcher 不同,压缩率略低),文档需说明产物仍是标准 xz。
## xz 读取的字典上限
`ulikunitz/xz` 的 reader 默认 `DictCap = 8 MiB`;读取 level 9(64 MiB 字典)的流会失败。
**决定:xz reader 固定使用 64 MiB 上限,而不是按当前 level 推导。**
原因:
1. 本工具可能产出的最大字典就是 64 MiB;
2. `--force-resume` 允许改配置续跑。若按当前 level 推导,从 9 降到 1 后读取旧分片会因上限不足而失败;
3. 读侧只出现在续跑与清单补录路径,不在主写入热路径,一次 64 MiB 缓冲可接受。
## checkpoint 会产生多 stream
`Writer.Checkpoint()` 关闭当前压缩流、记录偏移,再在偏移处开启新流。gzip 多 member、zstd 多 frame、xz 多 stream 都是合法拼接;`ulikunitz/xz` 的 `SingleStream` 默认 `false`,会解码全部 stream,`xz -dc` 同样如此。
**要求:必须有测试覆盖"checkpoint 后的 xz 分片能被完整读回",防止 `--purge` 场景下静默丢行。**
## 指纹兼容性
现有 `state.json` 的指纹里没有 `compress_level`。无条件加字段会让本功能上线前启动的任务全部续跑失败。
**决定:仅当 `compress != none && level != 3` 时把 `compress_level` 加入指纹。**
- 老任务(无键)+ 新进程默认 3 → 哈希输入逐字节不变,无缝续跑;
- 非默认档位才出现新键,`DiffFields` 会显示 `compress_level: "5" -> (absent)` 并拒绝;
- 从 5 改回 3 也因键消失被识别。
`compress == none` 时档位不参与哈希,因为不影响产物。
## none 与 level 的组合
`compress == none && level != 3` → 配置错误;`level == 3`(默认值)静默接受。这样既能拒绝无意义组合,又不会惩罚"只是没传"的用户。
## 崩溃恢复识别 `.xz`
`manifest.go` 的 `shardNameRE` 目前只列 `\.gz|\.zst`,且 `Adopt` 用 `mt[3] != comp.Ext` 过滤。不加 `\.xz` 时,崩溃在 rename 与 manifest 追加之间的 xz 分片不会被计入 `maxSeq`,续跑会重算序号并覆盖已封分片。
**决定:正则与扩展名判断都识别 `.xz`,并补一条针对性测试。**
## Compressor 结构与扩展名收敛
`Compressor` 从 `{Name, Ext}` 扩展为 `{Name, Ext, Level}`,构造签名改为 `NewCompressor(name string, level int)`。gzip/zstd/xz 都从同一个对象取 `Ext`。
`app/dryrun.go` 的 `compressExt()` 是第二份扩展名表,改成复用 `Compressor.Ext`,避免新增格式时漏改一处。
## 被否决的方案
- **把 zstd 暴露为 1–22**:与 gzip/xz 的 1–9 不一致,校验和文档复杂度上升;zstd `best` 已足够,空间优先交给 xz。
- **按当前 level 推导 reader 字典**:与 `--force-resume` 降级续跑冲突。
- **xz 使用默认 8 MiB 字典**:level 3 与 xz preset 3 不一致,且高档位无法表达。
- **无条件把档位写入指纹**:打断存量任务续跑。
@@ -0,0 +1,34 @@
## Why
当前只支持 `none|gzip|zstd`,且压缩级别写死为 3,用户无法在"吞吐优先"与"空间优先"之间取舍。xz 能显著降低长期归档的存储成本,但压缩吞吐远低于 gzip/zstd;把它作为一个显式选项,同时把级别做成统一档位,才能让三种压缩器在同一语义下被选择。
## What Changes
- 新增 `--compress xz`,每个分片是一个独立 xz 流,扩展名为 `.xz`。
- 新增 `--compress-level 1..9`,默认 3;1–9 是跨格式统一档位,按格式映射到各自的压缩参数,9 表示该格式最强。默认档位 3 与现有行为一致。
- `--compress none` 与非默认 `--compress-level` 同时出现时视为配置错误。
- 配置指纹:仅当 `compress != none` 且 `level != 3` 时把 `compress_level` 纳入指纹,保证本功能之前启动的任务仍能无缝续跑;非默认档位变化仍会被识别并拒绝。
- 崩溃恢复扫描必须识别 `.xz` 分片,避免重算序号覆盖已封分片。
- 收敛扩展名逻辑:dry-run 复用 `Compressor.Ext`,删除重复的 `compressExt` 表。
- 引入纯 Go 依赖 `github.com/ulikunitz/xz`。
- **BREAKING**: 无。未设置 `--compress-level` 时,gzip/zstd 的产物与当前版本一致。
## Capabilities
### New Capabilities
(无)
### Modified Capabilities
- `output-formats`: 压缩 Requirement 从 3 种压缩器扩展为 4 种,并定义 1–9 档位到各格式的映射与 xz 场景。
- `cli-contract`: 默认值中加入 `--compress-level 3`,参数依赖规则加入 `none` 与非默认档位的冲突校验。
- `archive-core`: 断点续跑指纹纳入非默认压缩档位,并明确档位变化时的拒绝行为。
- `file-sharding`: 文件命名与分片清单覆盖 `.xz`,并明确崩溃后按压缩扩展名识别已封分片。
## Impact
- 代码:`internal/cli/{config,parse,validate,hash}.go`、`internal/shard/{compress,manifest}.go`、`internal/app/{app,dryrun}.go`
- 依赖:`go.mod` / `go.sum` 新增 `github.com/ulikunitz/xz`
- 文档:`README.md` 压缩章节、档位表与 xz 导入示例
- 测试:`internal/shard/writer_test.go`、`internal/app/integration_test.go`、`internal/cli` 校验与指纹测试
@@ -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** 指纹一致,系统正常续跑
@@ -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** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
@@ -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** 续跑扫描识别该分片,补录清单,后续序号从其后继续,不覆盖该文件
@@ -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** 系统接受配置并产出对应扩展名的独立压缩分片
@@ -0,0 +1,42 @@
## 1. 依赖与压缩器
- [x] 1.1 `go get github.com/ulikunitz/xz@v0.5.17`,更新 `go.mod` / `go.sum`
- [x] 1.2 `Compressor` 增加 `Level` 字段;`NewCompressor(name string, level int)` 接受档位
- [x] 1.3 实现档位映射:gzip 直传 1–9;zstd 按 1-2 fastest / 3-5 default / 6-8 better / 9 best;xz 按字典表 1/2/4/4/8/8/16/32/64 MiB
- [x] 1.4 xz writer 使用 `xz.WriterConfig{DictCap: ...}`;reader 固定 `DictCap 64 MiB` 并保留多 stream 解码
## 2. CLI
- [x] 2.1 `cli/config.go`:`CompressLevel int`,默认 3
- [x] 2.2 `cli/parse.go`:注册 `--compress-level`,help 标注 1–9
- [x] 2.3 `cli/validate.go`:档位必须在 1–9;`--compress none` 且档位非 3 时报配置错误
- [x] 2.4 `cli/hash.go`:仅当 `compress != none && level != 3` 时加入 `compress_level`
## 3. 装配与扩展名收敛
- [x] 3.1 `app/app.go`:用 `NewCompressor(cfg.Compress, cfg.CompressLevel)` 构造
- [x] 3.2 `app/dryrun.go`:输出压缩档位;删除 `compressExt()`,改用 `Compressor.Ext`
## 4. 崩溃恢复
- [x] 4.1 `shard/manifest.go`:`shardNameRE` 增加 `\.xz`,`Adopt` 能识别 xz 分片并计入序号
## 5. 测试
- [x] 5.1 档位映射边界单测(含 gzip/zstd/xz 与非法档位)
- [x] 5.2 `shard/writer_test.go` 的压缩往返循环加入 `xz`
- [x] 5.3 新增:`Checkpoint()` 后多 stream xz 分片能被完整读回
- [x] 5.4 新增:无 manifest 记录的 `.xz` 分片可被 `Adopt` 补录且不影响序号
- [x] 5.5 CLI 测试:非法档位、`none` + 非默认档位、默认档位的指纹向后兼容、非默认档位变化被拒绝
- [x] 5.6 `app/integration_test.go`:压缩循环加入 `xz`,`decompressFile` 增加 xz 分支
## 6. 文档
- [x] 6.1 `README.md`:压缩选项加入 xz 与 `--compress-level`,补档位表、xz 导入示例(`xz -dc`)与 xz 吞吐/空间定位说明
## 7. 验证
- [x] 7.1 `go test ./...`
- [x] 7.2 `go vet ./...`
- [x] 7.3 `openspec validate add-compress-level-and-xz --strict`
- [ ] 7.4 如有 MySQL 环境,跑一次 `ARCHER_TEST_DSN=... go test ./internal/app -run TestIntegration -v`