Files
archer/openspec/changes/archive/2026-11-06-add-archer-archiver/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

3.4 KiB
Raw Blame History

Why

pt-archiver 是归档大表的可靠方案,但它的文件导出只在启动时计算一次文件名,无法把一次归档拆成多个可独立导入的文件;它也不支持按数据自身的日期或行数做有序分片。同时它是 Perl 工具,部署和二次开发成本较高。

需要一个 Go 原生的归档工具:复用 pt-archiver 的 seek 式分块扫描与 file + dest + purge 语义,并补齐“导出文件可有序分片”这一能力,让大表导出结果能按日期或按行数切成连续、无重叠、可并行导入的文件。

What Changes

  • 新增 Go CLI archer,对齐 pt-archiver 的核心归档语义:按唯一索引 seek 分块,支持 file、dest 表、purge 三件套。
  • 新增导出分片能力:
    • --shard-by count:按固定行数流式封片,分片沿扫描顺序连续、有序、主键范围不重叠。
    • --shard-by date:按用户显式指定的日期/时间列分片,每个文件只含一个日期。
    • --shard-by none:不分片,输出单文件。
  • 新增日期分片的两种扫描路径:存在 (shard_column, pk) 联合索引时走 keyset 分块(短事务);仅存在 shard_column 单列索引时走逐日流式(长游标 + 第二连接删除)。
  • 新增输出格式 dump(TSV,NULL=\N)、csv(RFC4180 + 表头)、jsonl(类型化 JSON),支持每分片独立 gzip 或 zstd 压缩。
  • 新增 manifest.jsonl 与 state.json:记录分片边界、行数、校验和与断点,支持崩溃续跑;一致性等级为 at-least-once。
  • 新增安全控制:--dry-run、--max-lag 复制延迟等待、--safe-auto-increment、--bulk-delete 的适用性限制、续跑时配置指纹校验。
  • BREAKING: 新项目,无既有接口需要兼容。--chunk-size 取代 pt-archiver 的 --limit,语义为“每次 SELECT 的行数”;--limit 仅作为隐藏别名。

非目标(v1 不做):PostgreSQL 等非 MySQL 数据源、Parquet 输出、字符串日期列分片、按预计算边界并行导出、文件侧 exactly-once、PXC Flow Control 适配。

Capabilities

New Capabilities

  • archive-core: 扫描与归档执行——按唯一索引 seek 分块、file/dest/purge 三件套提交顺序、事务边界、复制延迟等待、安全护栏与断点续跑。
  • file-sharding: 分片路由与产物管理——none/count/date 三种分片模式、有序连续不变量、文件命名、句柄管理、manifest.jsonl 与 state.json。
  • output-formats: 行编码与压缩——dump/csv/jsonl 的精确格式规则、NULL 与类型处理、每分片独立 gzip/zstd。
  • cli-contract: 命令行契约——参数集合与默认值、互斥与依赖校验、日期列类型与索引探测、错误信息与 --dry-run 输出。

Modified Capabilities

无。这是新项目,openspec/specs/ 下没有既有能力。

Impact

  • 代码:新建 Go module 与目录结构(cmd/archer、internal/{cli,schema,scan,row,sink,shard,purge,checkpoint})。
  • 依赖:github.com/go-sql-driver/mysql;github.com/klauspost/compress(zstd)。其余用标准库。
  • 运行环境:MySQL 5.7+/8.0 与 MariaDB 10.x;不引入服务端组件。
  • 输出:新增用户指定目录下的分片文件、manifest.jsonl、state.json。
  • 数据安全:启用 --purge 会删除源表数据,需要显式确认;--bulk-delete 在日期模式或被拒绝。