Files
archer/openspec/changes/archive/2026-11-06-add-archer-archiver/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

3.2 KiB

Purpose

定义行数据到文件的编码规则与压缩方式,确保导出产物可以被 MySQL、PostgreSQL、ClickHouse、Spark 等常见工具直接导入。

ADDED 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,默认 none。每个分片 MUST 独立压缩,压缩后的文件扩展名分别为 .gz 与 .zst。gzip 与 zstd 的默认压缩级别 MUST 为 3(吞吐优先)。

Scenario: gzip 分片

  • WHEN --compress gzip
  • THEN 每个分片是一个独立的 gzip 流,文件名为 *.gz

Scenario: zstd 分片

  • WHEN --compress zstd
  • THEN 每个分片是一个独立的 zstd 帧,文件名为 *.zst

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