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

42 lines
3.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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` 在日期模式或被拒绝。