Files
archer/openspec/changes/archive/2026-11-06-add-archer-archiver/specs/file-sharding/spec.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

7.4 KiB

Purpose

定义导出文件的分片模式、顺序不变量、命名规则、句柄管理与分片清单,确保大规模导出的结果可被分段、有序、独立地导入。

ADDED Requirements

Requirement: 分片模式

系统 SHALL 支持三种分片模式:none(不分片,单文件)、count(按固定行数封片)、date(按用户指定的日期或时间列封片)。分片模式 SHALL 由 --shard-by 选择,默认 none。

Scenario: 不分片

  • WHEN --shard-by none
  • THEN 本次扫描的全部行写入同一个文件

Scenario: 按数量分片

  • WHEN --shard-by count --shard-rows 5000000
  • THEN 每写满 500 万行封一个文件,最后一个文件可少于 500 万行

Scenario: 按日期分片

  • WHEN --shard-by date --shard-column created_at
  • THEN 每个文件只包含 created_at 落在同一个日期的行

Requirement: 有序连续不变量

对于任何分片模式,系统 MUST 保证:分片按扫描顺序编号;相邻分片的主键范围连续且不重叠;所有分片合并后等于本次扫描读取的全部行;每个分片内部的行顺序与扫描顺序一致;文件名中的首尾主键为该分片实际写入的第一行与最后一行主键。

Scenario: 分片边界连续

  • WHEN 一次扫描读取主键 1..2500,且 --shard-rows 1000
  • THEN 生成三个分片,主键范围分别为 1-1000、1001-2000、2001-2500,无重叠也无空洞

Scenario: 主键存在空洞时仍连续

  • WHEN 扫描读取到主键 1,2,100,101,且 --shard-rows 2
  • THEN 分片范围分别为 1-2 与 100-101,文件名反映实际首尾主键

Requirement: 按行数流式封片

在 count 模式下,系统 SHALL 在写入过程中逐行判断当前分片是否已满,写满 --shard-rows 行后立即封片。--chunk-size 与 --shard-rows SHALL 相互独立,系统 MUST 支持一个 chunk 跨越多个分片,且不要求两者存在整除关系。

Scenario: chunk 跨越分片边界

  • WHEN --chunk-size 2000 且 --shard-rows 2500
  • THEN 第二个 chunk 的前 1500 行写入第一个分片,后 500 行写入第二个分片

Scenario: 文件在关闭时才确定名称

  • WHEN 一个分片正在写入
  • THEN 该文件在关闭前以 .partial 形式存在,关闭并 flush 后重命名为包含实际首尾主键的最终文件名

Requirement: 日期分片的列契约

--shard-by date 时,系统 MUST 要求显式提供 --shard-column;即使表中只有一个日期列也不得自动选择。该列类型 MUST 属于 DATE、DATETIME、TIMESTAMP 或整数类型(epoch,需显式声明单位)。其他类型 MUST 被拒绝。

Scenario: 缺少分片列

  • WHEN --shard-by date 但未提供 --shard-column
  • THEN 系统报错,并列出表中所有候选的日期/时间列及其类型与可空性

Scenario: 多个日期列

  • WHEN 表中有 created_at、updated_at、paid_at 三个日期列,用户指定 --shard-column created_at
  • THEN 系统只按 created_at 分片,其他日期列作为普通导出列

Scenario: 整数时间戳列未声明单位

  • WHEN --shard-column created_at 指向 BIGINT 列,且未提供 --shard-column-type
  • THEN 系统报错,采样该列最小/最大值,并分别展示按秒、毫秒、微秒解释后的日期范围供用户选择

Scenario: 不支持的列类型

  • WHEN --shard-column 指向 VARCHAR 或 TIME 列
  • THEN 系统报错,并说明 v1 仅支持日期时间类型与显式声明的 epoch 整数

Requirement: 日期值归属规则

系统 MUST 按列语义决定日期归属:DATE 与 DATETIME 使用原值,不做时区换算;TIMESTAMP 按连接会话时区换算;epoch 整数按 --shard-time-zone(默认 UTC)换算。NULL 值默认落入 date=_null 分片;零日期默认报错并给出行主键,可通过 --zero-date bucket 改为落入 date=0000-00-00 分片。--shard-time-zone MUST 计入配置指纹。

Scenario: NULL 日期值

  • WHEN 某行的 created_at 为 NULL,且使用默认配置
  • THEN 该行写入 date=_null 分片,扫描顺序与分片顺序仍保持一致

Scenario: 零日期值

  • WHEN 某行的 created_at 为 0000-00-00 00:00:00,且未指定 --zero-date
  • THEN 系统报错并输出该行主键,不生成静默的错误分片

Scenario: 时区改变后续跑

  • WHEN 续跑时 --shard-time-zone 与 state.json 记录不一致
  • THEN 系统拒绝续跑,除非显式传入 --force-resume

Requirement: 日期扫描路径选择

系统 SHALL 在启动时探测分片列的索引,并据此选择扫描路径:存在 (shard_column, pk) 联合索引时使用 keyset 分块(短事务);仅存在 shard_column 单列索引时使用逐日流式读取(长游标,purge 使用独立连接);两者都不存在时 MUST fail fast,除非显式传入 --allow-full-scan。

Scenario: 存在联合索引

  • WHEN 表上存在 (created_at, id) 联合索引
  • THEN 系统按 (created_at, id) 做 keyset 分块,每个 chunk 独立提交

Scenario: 仅存在单列索引

  • WHEN 表上只有 created_at 单列索引
  • THEN 系统按日期逐日发出查询并流式读取,日期内按 created_at, id 排序;删除操作使用第二条源连接

Scenario: 没有任何相关索引

  • WHEN 分片列上既无联合索引也无单列索引
  • THEN 系统报错并提示创建索引,或由用户显式传入 --allow-full-scan 以接受全表扫描

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: 日期分片布局

  • WHEN --shard-by date 导出的首个日期为 2025-06-01
  • THEN 文件位于 date=2025-06-01/ 子目录下,序号在该日期内从 000001 开始

Requirement: 分片清单

系统 SHALL 在每次分片关闭后向 manifest.jsonl 追加一行并 flush,记录序号、相对路径、日期(如适用)、首尾主键、行数、字节数与 SHA-256。清单 MUST 在进程崩溃后仍可用于识别已完成的分片。

Scenario: 分片关闭后写入清单

  • WHEN 一个分片完成 flush 并重命名
  • THEN manifest.jsonl 追加一条包含 seq、path、pk_lo、pk_hi、rows、bytes、sha256、closed_at 的记录

Scenario: 崩溃后识别已完成分片

  • WHEN 进程在写完两个分片后崩溃
  • THEN manifest.jsonl 中保留这两条完整记录,残留的 .partial 文件不进入清单

Requirement: 分片文件原子性

每个分片 MUST 先写入同目录下的 .partial 临时文件,成功 flush 后原子重命名为最终文件名。每个分片 MUST 独立压缩,使单个文件可以脱离其他分片单独导入。

Scenario: 崩溃留下临时文件

  • WHEN 进程在分片写入过程中崩溃
  • THEN 目录中留下 .partial 文件,最终文件名对应的文件不存在,续跑时系统忽略或清理该临时文件