# file-sharding Specification ## Purpose 定义导出文件的分片模式、顺序不变量、命名规则、句柄管理与分片清单,确保大规模导出的结果可被分段、有序、独立地导入。 ## 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=/].-.[.]` 命名,`seq` 为从 1 开始的六位零填充序号。日期模式 MUST 按日期建立子目录。输出目录下同时生成 `manifest.jsonl` 与 `state.json`。 #### Scenario: 数量分片命名 - **WHEN** 第一个分片主键范围为 1..5000000,格式为 dump,压缩为 zstd - **THEN** 文件名为 `000001.1-5000000.dump.zst` #### Scenario: xz 分片命名 - **WHEN** 第一个分片主键范围为 1..5000000,格式为 dump,压缩为 xz - **THEN** 文件名为 `000001.1-5000000.dump.xz` #### Scenario: 日期分片布局 - **WHEN** `--shard-by date` 导出的首个日期为 2025-06-01 - **THEN** 文件位于 `date=2025-06-01/` 子目录下,序号在该日期内从 000001 开始 ### Requirement: 分片清单 系统 SHALL 在每次分片关闭后向 `manifest.jsonl` 追加一行并 flush,记录序号、相对路径、日期(如适用)、首尾主键、行数、字节数与 SHA-256。清单 MUST 在进程崩溃后仍可用于识别已完成的分片。对于已重命名但尚无清单记录的分片,续跑 MUST 按当前输出格式与压缩扩展名识别、补录并计入序号,不得覆盖。 #### Scenario: 分片关闭后写入清单 - **WHEN** 一个分片完成 flush 并重命名 - **THEN** `manifest.jsonl` 追加一条包含 seq、path、pk_lo、pk_hi、rows、bytes、sha256、closed_at 的记录 #### Scenario: 崩溃后识别已完成分片 - **WHEN** 进程在写完两个分片后崩溃 - **THEN** `manifest.jsonl` 中保留这两条完整记录,残留的 `.partial` 文件不进入清单 #### Scenario: xz 分片在清单追加前崩溃 - **WHEN** 一个 `.xz` 分片完成重命名后、写 `manifest.jsonl` 前进程崩溃 - **THEN** 续跑扫描识别该分片,补录清单,后续序号从其后继续,不覆盖该文件 ### Requirement: 分片文件原子性 每个分片 MUST 先写入同目录下的 `.partial` 临时文件,成功 flush 后原子重命名为最终文件名。每个分片 MUST 独立压缩,使单个文件可以脱离其他分片单独导入。 #### Scenario: 崩溃留下临时文件 - **WHEN** 进程在分片写入过程中崩溃 - **THEN** 目录中留下 `.partial` 文件,最终文件名对应的文件不存在,续跑时系统忽略或清理该临时文件