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