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>
This commit is contained in:
commit
bc4a6b504f
99 files changed
+12752
No files matched your search
@@ -0,0 +1,151 @@
|
||||
## 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` 文件,最终文件名对应的文件不存在,续跑时系统忽略或清理该临时文件
|
||||
Reference in new issue
Block a user