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>
3.4 KiB
3.4 KiB
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在日期模式或被拒绝。