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:
voidandClaude Sonnet 4.6 committed 2026-11-06 22:12:17 +08:00
commit bc4a6b504f
99 files changed
+12752

No files matched your search

+177
View File
@@ -0,0 +1,177 @@
# archive-core Specification
## Purpose
定义 archer 如何按唯一索引分块读取源表,并以固定顺序完成文件写入、目标表写入与源行删除,同时提供复制延迟保护、安全护栏和可中断续跑能力。
## Requirements
### Requirement: 唯一索引 seek 分块扫描
系统 SHALL 以源表的一个唯一索引(优先主键)作为扫描游标。每个 chunk 的查询 MUST 使用“索引键大于上一次尾值”的条件、按索引列 `ORDER BY`、并带 `LIMIT chunk-size`;系统 MUST NOT 使用 `OFFSET` 翻页。返回行数小于 `chunk-size` 时,系统 SHALL 结束扫描。
#### Scenario: 主键连续
- **WHEN** 源表主键为连续的 1..N,且 `--chunk-size 2000`
- **THEN** 系统按 2000 行一个 chunk 依次读取,直到最后一个不足 2000 行的 chunk
#### Scenario: 主键存在空洞
- **WHEN** 主键序列为 1,2,100,101,且 `--chunk-size 2`
- **THEN** 第一个 chunk 返回 1,2,第二个 chunk 从 `id > 2` 继续并返回 100,101,不会跳过或重复
#### Scenario: 无可用唯一索引
- **WHEN** 源表既没有主键也没有唯一索引,且用户未指定索引
- **THEN** 系统在开始扫描前报错退出,并提示需要唯一索引
### Requirement: chunk 即事务
每个 chunk SHALL 构成唯一的事务边界,`--chunk-size` 同时决定 SELECT 批量、事务大小和 checkpoint 粒度。系统 SHALL NOT 提供跨 chunk 的事务,也 SHALL NOT 提供独立的 `--txn-size` 参数。
#### Scenario: 源表与目标表在同一实例
- **WHEN** `--source` 与 `--dest` 指向同一 MySQL 实例,且同时启用 dest 与 purge
- **THEN** 目标表写入与源行删除在同一个事务中提交,二者要么同时生效要么同时回滚
#### Scenario: 源表与目标表在不同实例
- **WHEN** `--source` 与 `--dest` 指向不同实例
- **THEN** 系统使用两个连接分别提交,并在任一步失败时按 `--retries` 重试;已提交的目标表写入可能在重跑时重复,行为为 at-least-once
### Requirement: 三件套提交顺序
当 file、dest、purge 中任意多项同时启用时,系统 MUST 对每个 chunk 按固定顺序执行:写文件、写目标表、删除源行、提交事务并更新 checkpoint。任何前置步骤失败时,系统 MUST NOT 执行后续步骤,也 MUST NOT 推进 checkpoint。
#### Scenario: 文件写入失败
- **WHEN** 写文件返回错误
- **THEN** 系统不写目标表、不删除源行、不推进 checkpoint,并以非零码退出
#### Scenario: 目标表写入失败
- **WHEN** 文件写入成功但目标表插入失败
- **THEN** 系统删除源行,回滚本次事务,不推进 checkpoint,并以非零码退出
### Requirement: 输出目标约束
系统 SHALL 要求 `--file`、`--dest`、`--purge` 至少启用一个,并且 `--where` 必填。三者可以任意组合,包括只导出文件、只删除、或文件与目标表同时输出。
#### Scenario: 只删不写
- **WHEN** 用户只指定 `--purge` 和 `--where`
- **THEN** 系统仅按 chunk 删除匹配行,不生成任何文件
#### Scenario: 文件与目标表同时输出
- **WHEN** 用户同时指定 `--file` 与 `--dest`
- **THEN** 同一批行既写入分片文件,也写入目标表
### Requirement: 目标表写入模式
目标表写入 SHALL 支持普通插入、`INSERT IGNORE` 与 `REPLACE` 三种模式,三者互斥。系统 MUST 使用多行批量插入,并在单条语句可能超过 `max_allowed_packet` 时自动拆分为多条语句。
#### Scenario: 默认插入遇到重复主键
- **WHEN** 使用默认插入模式,且目标表已存在相同主键
- **THEN** 该 chunk 失败并回滚,系统报告重复键错误
#### Scenario: ignore 模式遇到重复主键
- **WHEN** 使用 `--insert-ignore`
- **THEN** 重复行被跳过,其余行写入成功,chunk 正常提交
### Requirement: 删除语义
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`,且在日期分片模式下 MUST 被拒绝。
#### Scenario: 默认 IN 列表删除
- **WHEN** 一个 chunk 读取到主键 1001..3000,且 `--where "created_at < '2026-01-01'"`
- **THEN** 系统生成 `DELETE ... WHERE id IN (1001,...,3000)`,不删除未被读取的行
#### Scenario: 区间删除附带回填条件
- **WHEN** 启用 `--bulk-delete`,chunk 首尾主键为 1001 与 3000
- **THEN** 系统生成 `DELETE ... WHERE id BETWEEN 1001 AND 3000 AND (<where>)`
#### Scenario: 日期模式启用区间删除
- **WHEN** `--shard-by date` 与 `--bulk-delete` 同时出现
- **THEN** 系统在启动校验阶段报错退出,不执行任何查询
### Requirement: 复制延迟保护
当指定 `--check-replica-lag` 时,系统 SHALL 在每次拉取前检查该副本的延迟;延迟超过 `--max-lag` 或复制未运行时,系统 MUST 暂停并在 `--check-interval` 后重试。
#### Scenario: 延迟超限
- **WHEN** `--max-lag 1s`,副本延迟为 5s
- **THEN** 系统暂停拉取,直到延迟降到 1s 以下
#### Scenario: 副本复制中断
- **WHEN** 被检查的副本复制线程未运行
- **THEN** 系统持续等待并周期性重试,不继续归档
### Requirement: 安全护栏
系统 SHALL 默认启用 `--safe-auto-increment`,禁止通过 purge 删除当前最大自增主键行。`--dry-run` 时系统 MUST 只打印将要执行的 SQL 与实际生效配置,不连接写入、不创建或修改任何文件。
#### Scenario: 保护最大自增行
- **WHEN** purge 范围包含源表当前 `MAX(pk)`,且 `--safe-auto-increment` 为默认值
- **THEN** 该行不被删除,系统记录一条警告
#### Scenario: dry-run 无副作用
- **WHEN** 用户指定 `--dry-run`
- **THEN** 系统打印每条 SQL 与解析后的配置后退出,输出目录不产生任何文件
### Requirement: 断点续跑
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。`state.json` 中记录的源连接与目标连接 MUST 采用标准 MySQL DSN 形式(去除密码),例如 `user@tcp(host:3306)/db?charset=utf8mb4`。续跑时 MUST 校验源、表、过滤条件、列、分片参数、时区、输出格式、压缩设置,以及源/目标连接的全部规范化参数(含字符集与排序规则)的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。密码 MUST NOT 计入指纹,也 MUST NOT 写入 `state.json`。压缩档位仅在启用压缩且档位不是默认值 3 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。
#### Scenario: 配置一致时续跑
- **WHEN** 上次运行在 chunk 中途退出,且本次配置指纹一致
- **THEN** 系统从 `state.json` 记录的游标位置继续,不重复处理已提交的 chunk
#### Scenario: 配置被修改
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致,且未传 `--force-resume`
- **THEN** 系统报错并列出不一致的字段,拒绝开始扫描
#### Scenario: 压缩档位被修改
- **WHEN** 续跑时 `--compress-level` 与 `state.json` 记录不一致,且未传 `--force-resume`
- **THEN** 系统报错并列出 `compress_level` 字段的变化,拒绝开始扫描
#### Scenario: 默认档位兼容存量任务
- **WHEN** `state.json` 由引入压缩档位之前的版本写入,且本次使用默认档位 3
- **THEN** 指纹一致,系统正常续跑
#### Scenario: 连接字符集被修改
- **WHEN** 续跑时 `--source` 的 `charset` 或 `collation` 与 `state.json` 记录不一致,且未传 `--force-resume`
- **THEN** 系统报错并列出 `source` 字段的变化,拒绝开始扫描
#### Scenario: 密码轮换
- **WHEN** 续跑时仅 `--source` 或 `--dest` 的密码与上次运行不同
- **THEN** 指纹一致,系统正常续跑
#### Scenario: 连接信息的存储形态
- **WHEN** 查看任意一次运行生成的 `state.json`
- **THEN** `config.source` 与 `config.dest` 为标准 MySQL DSN,且不包含密码明文
### Requirement: 一致性等级
文件输出的一致性等级 SHALL 为 at-least-once:崩溃后重跑可能向分片文件重复追加已处理的行,系统 MUST 在文档与启动输出中明确该行为。
#### Scenario: 崩溃后重跑
- **WHEN** 文件已写入但 checkpoint 尚未更新时进程崩溃,随后以相同配置重跑
- **THEN** 系统从上一个已提交游标继续,文件可能出现重复行,数据不丢失
+110
View File
@@ -0,0 +1,110 @@
# cli-contract Specification
## Purpose
定义 archer 的命令行参数、默认值、参数之间的依赖与互斥规则,以及启动校验、错误信息和 dry-run 行为。
## Requirements
### Requirement: 必填参数
系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
#### Scenario: 缺少过滤条件
- **WHEN** 用户未提供 `--where`
- **THEN** 系统立即报错,提示 `--where` 必填,不建立数据库连接
#### Scenario: 没有任何输出目标
- **WHEN** 用户既未提供 `--file`、`--dest`,也未启用 `--purge`
- **THEN** 系统报错,提示至少需要一种输出目标
### Requirement: 默认值
系统 SHALL 采用以下默认值:`--chunk-size 2000`、`--shard-by none`、`--shard-rows 0`、`--format dump`、`--compress none`、`--compress-level 3`、`--max-lag 1s`、`--check-interval 1s`、`--retries 1`、`--safe-auto-increment true`、`--progress 0`。
#### Scenario: 最小可运行配置
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
### Requirement: 参数依赖与互斥
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge` 且在日期模式下禁止;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误。违反时 MUST 在启动阶段报错。
#### Scenario: 数量模式误传日期列
- **WHEN** `--shard-by count` 同时带上 `--shard-column`
- **THEN** 系统报错,说明该参数仅在日期模式下有效
#### Scenario: 未启用 purge 却要求 bulk-delete
- **WHEN** 用户指定 `--bulk-delete` 但未指定 `--purge`
- **THEN** 系统报错,说明 bulk-delete 必须配合 purge
#### Scenario: 插入模式互斥
- **WHEN** 用户同时指定 `--insert-ignore` 与 `--replace`
- **THEN** 系统报错,要求只能选择一种插入模式
#### Scenario: 压缩档位越界
- **WHEN** 用户指定 `--compress-level 0` 或 `--compress-level 10`
- **THEN** 系统在启动阶段报错,说明档位必须在 1–9 之间
#### Scenario: 不压缩却指定非默认档位
- **WHEN** 用户指定 `--compress none` 与 `--compress-level 5`
- **THEN** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
### Requirement: 日期列探测与错误提示
启动时,系统 SHALL 读取表元数据并判断 `--shard-column` 是否存在、类型是否受支持、是否可为 NULL。缺少 `--shard-column` 时 MUST 列出所有候选日期/时间列及其类型。整数列缺少单位声明时 MUST 采样最小/最大值,并展示按秒、毫秒、微秒解释后的日期范围。
#### Scenario: 列出候选列
- **WHEN** 用户指定 `--shard-by date` 但未给 `--shard-column`
- **THEN** 错误信息包含表内所有 DATE/DATETIME/TIMESTAMP 列的列名、类型与可空性
#### Scenario: epoch 单位提示
- **WHEN** 分片列为 BIGINT 且未声明单位
- **THEN** 错误信息展示采样范围以及三种单位解释下的日期范围,不自动选择
### Requirement: dry-run
`--dry-run` 时,系统 MUST 打印解析后的配置、索引探测结果、最终生效的分片与格式参数,以及第一条将要执行的 SELECT 和每类写入语句,然后退出。系统 MUST NOT 建立写入连接、创建目录或写文件。
#### Scenario: dry-run 输出 SQL
- **WHEN** 用户传入 `--dry-run`
- **THEN** 标准输出包含解析后的配置和将要执行的 SQL,进程以 0 退出
### Requirement: 进度与统计
当 `--progress N` 大于 0 时,系统 SHALL 每处理 N 行输出一次进度,包含已处理行数、当前分片序号与耗时。启用 `--statistics` 时,系统 MUST 在结束时输出读取行数、写入行数、删除行数、分片数与各阶段耗时。
#### Scenario: 周期进度
- **WHEN** `--progress 100000`
- **THEN** 每处理 100000 行打印一行进度信息
#### Scenario: 结束统计
- **WHEN** 启用 `--statistics`
- **THEN** 进程退出前输出汇总统计
### Requirement: 退出码
系统 SHALL 在成功完成时返回 0;配置错误、连接错误、写入错误或校验失败时返回非零退出码。被信号中断时 MUST 完成当前 chunk 的清理并返回非零退出码。
#### Scenario: 配置错误
- **WHEN** 参数校验失败
- **THEN** 进程以非零退出码结束,且不产生部分输出文件
#### Scenario: 信号中断
- **WHEN** 进程收到 SIGINT
- **THEN** 系统停止拉取新 chunk,关闭并 flush 当前分片,写入 checkpoint,然后以非零退出码结束
+163
View File
@@ -0,0 +1,163 @@
# 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=<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: 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` 文件,最终文件名对应的文件不存在,续跑时系统忽略或清理该临时文件
+97
View File
@@ -0,0 +1,97 @@
# output-formats Specification
## Purpose
定义行数据到文件的编码规则与压缩方式,确保导出产物可以被 MySQL、PostgreSQL、ClickHouse、Spark 等常见工具直接导入。
## Requirements
### Requirement: dump 格式
`--format dump` 时,系统 MUST 以制表符分隔字段、换行符结束行、`\N` 表示 NULL、反斜杠转义特殊字符,并且不写表头。转义规则 MUST 与 MySQL `SELECT ... INTO OUTFILE` 一致:反斜杠、制表符、换行、回车、NUL、退格、Ctrl-Z 均需转义。
#### Scenario: 默认 dump 输出
- **WHEN** 一行包含 `a\tb` 与 NULL
- **THEN** 输出为 `a\\tb\t\\N\n`,可被 `LOAD DATA INFILE` 以默认参数读回
#### Scenario: 数值与日期列
- **WHEN** 列类型为 DECIMAL、DATETIME
- **THEN** 直接输出 MySQL 返回的文本表示,不做重格式化
### Requirement: CSV 格式
`--format csv` 时,系统 MUST 输出 RFC4180 兼容内容:逗号分隔、首行为列名表头、含逗号/引号/CR/LF 的字段用双引号包裹、字段内双引号写为两个双引号、行尾为 CRLF。NULL 默认输出 `\N`,可通过 `--csv-null` 覆盖;空字符串输出为空字段。
#### Scenario: 字段包含逗号与引号
- **WHEN** 字段值为 `a,"b"`
- **THEN** 输出为 `"a,""b"""`
#### Scenario: 表头
- **WHEN** 生成任意 CSV 分片
- **THEN** 每个文件首行都是列名列表,顺序与 `--columns` 一致
### Requirement: JSONL 格式
`--format jsonl` 时,系统 MUST 每行输出一个 JSON 对象,键为列名。类型映射 MUST 为:DATETIME/TIMESTAMP 输出 RFC3339 字符串;DECIMAL 输出字符串以保留精度;BLOB/BINARY 输出 base64 字符串;NULL 输出 JSON `null`;整数与浮点输出 JSON 数字。
#### Scenario: 类型映射
- **WHEN** 一行包含 DECIMAL(10,2)=12.30、DATETIME、NULL
- **THEN** 对应字段分别为 `"12.30"`、RFC3339 时间字符串、`null`
#### Scenario: 每行独立可解析
- **WHEN** 读取 JSONL 分片的任意一行
- **THEN** 该行可以被标准 JSON 解析器独立解析,不依赖前后行
### Requirement: 压缩
系统 SHALL 支持 `--compress none|gzip|zstd|xz`,默认 `none`。每个分片 MUST 独立压缩,压缩后的文件扩展名分别为 `.gz`、`.zst` 与 `.xz`。系统 SHALL 支持 `--compress-level 1..9`,默认 3;档位是跨格式统一语义,数值越大压缩率越高、吞吐越低,9 表示该压缩器的最强档位。gzip 与 zstd 在默认档位下的字节输出 MUST 与引入档位前保持一致。xz 分片 MUST 是标准 xz 流,可被通用 xz 工具解码。
#### Scenario: gzip 分片
- **WHEN** `--compress gzip`
- **THEN** 每个分片是一个独立的 gzip 流,文件名为 `*.gz`
#### Scenario: zstd 分片
- **WHEN** `--compress zstd`
- **THEN** 每个分片是一个独立的 zstd 帧,文件名为 `*.zst`
#### Scenario: xz 分片
- **WHEN** `--compress xz`
- **THEN** 每个分片是一个独立的 xz 流,文件名为 `*.xz`
#### Scenario: xz 分片可被标准工具解码
- **WHEN** 产物为 `000001.1-1000.dump.xz`
- **THEN** `xz -dc` 可将其还原为与该次扫描行内容一致的 dump 文本
#### Scenario: 默认档位保持既有产物
- **WHEN** 用户未指定 `--compress-level`
- **THEN** gzip 与 zstd 使用档位 3,产物与引入该参数前的版本一致
#### Scenario: 各档位对三种压缩器均可用
- **WHEN** 用户指定 `--compress gzip|zstd|xz` 与任意 `--compress-level 1..9`
- **THEN** 系统接受配置并产出对应扩展名的独立压缩分片
### Requirement: 可导入性
系统 MUST 保证每种格式的产物可被至少一种常见工具直接导入:dump 可被 MySQL `LOAD DATA INFILE` 默认参数导入;csv 可被 PostgreSQL `COPY ... CSV HEADER`、ClickHouse `CSVWithNames`、Pandas/Spark 默认 CSV 读取器导入;jsonl 可被 ClickHouse `JSONEachRow` 及常见流式 JSON 工具导入。
#### Scenario: 压缩文件导入
- **WHEN** 产物为 `000001.1-1000.csv.gz`
- **THEN** 可以通过 `gunzip -c` 或 `zcat` 管道交给目标数据库导入,无需改写文件内容
#### Scenario: dump 直接导入 MySQL
- **WHEN** 使用 dump 格式且不压缩
- **THEN** `LOAD DATA INFILE '000001.1-1000.dump' INTO TABLE t` 在列顺序一致时可成功执行