Files
archer/openspec/specs/output-formats/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

98 lines
4.2 KiB
Markdown

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