Files
archer/openspec/changes/archive/2026-11-06-add-compress-level-and-xz/proposal.md
T
voidandClaude Sonnet 4.6 bc4a6b504f 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>
2026-11-06 22:12:17 +08:00

2.2 KiB

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 校验与指纹测试