# 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` 在列顺序一致时可成功执行