trdsql 介绍与选型指南

目标：认识 trdsql 这个"用 SQL 查询 CSV/JSON 等文本文件、并把结果写回 SQLite/PostgreSQL/MySQL 数据库"的 Go 单二进制 CLI，明确它的架构、能力边界与同类工具的量化选型结论。本章为认知篇，全部结论来自官方仓库与站内已交付文档的联网溯源（查询日期 2026-11-03），安装与命令实测见本专栏后续各篇。

一、环境信息

• 溯源对象：github.com/noborus/trdsql（GitHub 仓库页 / README / LICENSE / releases.atom）
• 星数、fork 数、最后提交时间：shields.io 徽章实测，查询日期 2026-11-03
• 最新稳定版：v1.2.3（releases.atom 实查，发布于 2026-05-29）
• 许可证：MIT（shields.io license 徽章实查，仓库 LICENSE 一致）
• 社区指标：stars 2.2k、forks 84、最后提交 last saturday（即 2026-10-31，shields.io last-commit 徽章）
• 后续实测环境（供参考）：Ubuntu 24.04.5 LTS（x86_64）+ PostgreSQL 16.15 + SQLite 3.45.1，trdsql v1.2.3

二、软件概述

trdsql 是一个命令行 SQL 查询工具，官方 README 开篇定义："trdsql is a CLI tool that can execute SQL queries on CSV, LTSV, JSON, YAML and TBLN files"——对 CSV、LTSV、JSON、YAML、TBLN 等文本文件直接执行 SQL 查询。README 同时点明它与 q、textql 等同类工具的关键区别："it allows the use of PostgreSQL or MySQL syntax"——它允许你选用 PostgreSQL 或 MySQL 的 SQL 方言与函数库来查询，而不是只能用 SQLite 语法。

这句话是理解 trdsql 设计的关键：trdsql 把文本文件读进一个 SQL 引擎（默认内嵌 SQLite3，可切换 PostgreSQL/MySQL 驱动），SQL 在这个引擎里执行，因此引擎支持什么语法、函数、窗口操作，查询就支持什么。反过来，查询结果也能以十余种文本格式输出，或直接落回 SQLite/PostgreSQL/MySQL 目标表——"文件 ↔ 数据库"的双向通道是它相对同类工具最突出的强项。

基本事实（官方 README，查询日期 2026-11-03）：

• 开发语言：Go，单二进制交付，无守护进程、无常驻服务，用完即退；
• 仓库：github.com/noborus/trdsql，作者 Noboru Saito（noborus），持续活跃维护（2026-10-31 仍有提交，v1.2.3 发布于 2026-05-29）；
• 安装渠道：官方 Releases 二进制（Linux/macOS/Windows，含 386/amd64/arm64/arm5-7/mips 等架构）、go install、Homebrew、MacPorts、FreeBSD pkg install；
• 源码编译要求：Go 1.25 或更高（README §1.1.1 "Requirements"）；
• 亦可作为 Go 库嵌入自己的程序（README §6 Library，godoc 有专页）；
• 同作者生态件：psutilsql（用 SQL 查系统状态）、mdtsql（查 Markdown 表格）、xlsxsql（查 Excel）。

💡 技术拓展：trdsql 名称含义——"trdsql"读作"transduce SQL"，即"转换（transduce）+ SQL"：SQL 查询文本数据并把结果转写成另一种格式/数据库，一条命令同时覆盖"查询、转换、导入、导出"四件事，这也是它区别于只做查询（csvq/dsq）或只做跨源联邦查询（OctoSQL）工具的定位所在。

三、核心架构

trdsql 内部是"Importer → SQL 引擎 → Exporter"三段流水线（README Usage 与 Library 章节、-debug 回显可佐证）：

1. Importer（导入器）：按扩展名猜测（-ig，默认开启）或显式指定（-icsv/-ijson/-iltsv/-iyaml/-itbln/-iwidth/-itext）解析输入。输入可以是文件、-/stdin 标准输入、通配符多文件（如 tt*.csv），gzip/bz2/zstd/lz4/xz 压缩文件自动解压。解析出的每一行作为数据装入 SQL 引擎的临时表，表名即文件名（如 SELECT * FROM test.csv），无表头时列名自动取 c1,c2,...。
2. SQL 引擎（driver）：-driver 可选 sqlite3（默认，内嵌 go-sqlite3，零外部依赖）、postgres、mysql，或 CGO-free 的 sqlite。选 postgres/mysql 时经 lib/pq、go-sql-driver 连真实数据库服务器执行——引擎决定 SQL 方言、函数集（窗口函数、generate_series、GROUP_CONCAT、SHA2 等）与类型转换语法（::int vs CAST）。
3. Exporter（导出器）：结果按 -o* 系列标志转写为 csv/tsv/json/jsonl/ltsv/yaml/tbln/md/at/raw/vf 九种文本格式（可叠加 -oz 压缩输出），或当 SQL 是 CREATE TABLE ... AS SELECT / INSERT INTO 时直接写入目标数据库表。

文件/stdin/压缩包 ──Importer──▶ 临时表(SQL引擎: sqlite3|postgres|mysql) ──Exporter──▶ 文本格式/压缩文件/数据库表

💡 技术拓展：内嵌 SQL 引擎的"借壳"方式业界常见三种——

方式	代表	特点
内嵌单文件库（自包含）	trdsql（go-sqlite3）、dsq、csvq	零外部依赖，方言固定
连接外部数据库服务器执行	trdsql -driver postgres/mysql	方言/函数随真实服务器，需有库可连
自研查询引擎	OctoSQL、csvq 部分	不依赖 SQL 库，能力由项目自定

trdsql 同时支持第 1、2 种：默认内嵌 SQLite3 开箱即用，需要 PostgreSQL/MySQL 方言时挂真实数据库服务器执行，这正是它"允许使用 PostgreSQL 或 MySQL 语法"的实现路径。

四、功能特性

按官方 README 逐项归纳（括号内为对应命令行标志）：

• 多格式输入：CSV（-id 自定义分隔符、-ih 首行作列名）、TSV、LTSV、JSON/JSONL（支持 jq 表达式取层级数据，-ijq ".items" 或表名后缀 test.json::".menu.popup.menuitem"）、YAML、TBLN、定宽文本（-iwidth）、纯文本行（-itext）；扩展名自动猜测（-ig 默认）。
• 压缩透明读取：.gz/.bz2/.zst/.lz4/.xz 自动解压后按内部格式继续猜测。
• SQL 全家桶：JOIN（文件×文件、文件×数据库表）、子查询、GROUP BY/ORDER BY/LIMIT、窗口函数（postgres 驱动）、generate_series（postgres）、GROUP_CONCAT/SHA2（mysql）——能力随所选引擎。
• 多格式输出：CSV/TSV/JSON/JSONL/LTSV/YAML/TBLN/Markdown 表格/ASCII 表格/垂直格式（psql \x 风格）/raw；-out 按文件名后缀自动猜格式与压缩；-oz gz|bz2|zstd|lz4|xz 压缩输出；-oh 输出表头、-od 自定义分隔符、-oaq 全字段加引号、-ocrlf CRLF 换行。
• NULL 语义控制：-inull "" 把空串读成 SQL NULL，-onull "(NULL)" 把 NULL 写成指定字符串（JSON 的 null 天然等价 NULL）。
• 写回数据库：CREATE TABLE t AS SELECT ... FROM x.csv 建表导入、INSERT INTO t SELECT ... 追加导入，目标支持 SQLite 文件、PostgreSQL、MySQL——这是"轻量 ETL 入口"的形态。
• 文件分析器：-a 文件名 自动探测文件类型/列名/数据类型并给出建议 SQL；-A 只输出建议 SQL。
• 多查询串执行：一条命令以分号分隔多条 SQL（如 UPDATE ...; SELECT ...）。
• 连接配置管理：config.json 预定义多组命名连接（driver+dsn），-db pdb 一键切换查询引擎，-dblist 列出配置。
• 库形态：Go library 嵌入（trdsql.NewTRDSQL(...)）。

五、快速开始（最小可用示例）

以下示例摘自官方 README（本章为认知篇不本地实测，逐条实测回显见《trdsql 1.2.3 常用 CLI 命令与工具详解》篇）：

# 1. 直接查 CSV：文件名即表名，无表头时列名为 c1,c2
trdsql "SELECT * FROM test.csv"

# 2. 聚合：对带表头的 CSV 分组求和
trdsql -ih "SELECT city, count(*), sum(price) FROM sales.csv GROUP BY city"

# 3. 格式转换：CSV 转 JSON（-ojson），或整文件转 TSV（-otsv -t）
trdsql -ih -ojson "SELECT * FROM sales.csv"
trdsql -otsv -t test.csv

# 4. 管道：标准输入当表（表名写 - 或 stdin）
cat test.csv | trdsql -icsv -oltsv "SELECT c1,c2 FROM -"

# 5. 用 PostgreSQL 引擎查询并把 CSV 导入数据库表
trdsql -driver postgres -dsn "dbname=test" "SELECT row_number() OVER (ORDER BY c2), c1, c2 FROM test.csv"
trdsql -driver postgres -dsn "dbname=test" "CREATE TABLE fruits (id, name) AS SELECT c1::int, c2 FROM fruits.csv"

六、适用场景与限制

适用：

• 运维/数据日常：不建库直接 SQL 查日志导出件、报表 CSV、接口 JSON，一行命令出聚合结果；
• 格式转换：CSV↔JSON↔YAML↔LTSV↔压缩文件之间的批量转写（含 gz/bz2/zstd/lz4/xz）；
• 轻量 ETL：把文本数据直接 CREATE TABLE AS SELECT / INSERT INTO 进 SQLite/PostgreSQL/MySQL，省去中间脚本；
• 需要 PostgreSQL/MySQL 方言（窗口函数、类型转换、专有函数）查文件的场景；
• 脚本/Makefile/CI 中嵌入（单二进制、退出码干净），或作为 Go 库。

限制（官方 README + 实测环境事实，选型需知）：

• 列默认全部按文本（text）导入临时表：数值比较/排序需显式 CAST(price AS INTEGER)（SQLite）或 price::int（PostgreSQL），否则按字典序得出"错误但符合语义"的结果（详见 D1 篇实测）；
• 输入格式不含 Parquet/Excel/Avro（这类覆盖更广的是 dsq，见下节对比）；
• 文件查询本质是"整文件装载进 SQL 引擎"，超大文件受引擎与内存约束，GB 级分析建议 DuckDB；
• 无守护进程/服务形态，不提供 HTTP/交互 shell，纯一次性命令；
• 源码编译要求 Go 1.25+（README §1.1.1）。

七、同类选型对比

同赛道（"SQL 查文本文件"CLI）五款工具量化对比。星数/最后提交取自 shields.io 徽章，版本/发布日期取自各仓库 releases.atom，查询日期均为 2026-11-03；csvq/dsq/OctoSQL 三项数据与站内已交付 A1 篇互证（见文末站内链接）：

关键差异解读：

• 维护活跃度：五者中只有 trdsql 在 2026 年仍持续发版提交；textql 星数最高（9.1k）但 2015 年后无正式 release，属"高星停摆"典型。
• SQL 方言：trdsql 可挂 PostgreSQL/MySQL 真实引擎获得完整方言与函数；csvq 用自研方言、dsq/textql 锁 SQLite。
• 输入覆盖：dsq 最广（Parquet/Excel/Avro/日志类）；trdsql 胜在文本类格式全 + 透明读压缩文件，但无 Parquet/Excel。
• 输出/写回：trdsql 是唯一支持把查询结果直接写回 SQLite/PostgreSQL/MySQL 表的（CREATE TABLE ... AS SELECT / INSERT INTO）；OctoSQL 强在"多源 JOIN 读"但输出只落文件。
• 跨源 JOIN：OctoSQL 主打文件×数据库联邦读；trdsql 用"挂真实数据库驱动"实现文件×库表 JOIN（-driver postgres 下 CSV 临时表与库内表直接 LEFT JOIN）。

选型建议：

• 需要"查文件 + 转格式 + 导入数据库"一条龙、且在意长期维护 → trdsql（本专栏实测对象）；
• 要查 Parquet/Excel/Avro 等二进制列存格式 → dsq（接受停更风险）；
• 多异构数据源联邦 JOIN 为主、输出到文件即可 → OctoSQL；
• 只查 CSV 且偏好类 SQL 方言 → csvq；textql 不建议新项目选用（停摆 10 年）。

站内互链：《csvq 1.18.1 介绍与选型指南》、《dsq 介绍与选型指南》、《OctoSQL 0.13.0 介绍与选型指南》。

八、参考链接

• 官方仓库：https://github.com/noborus/trdsql （README/LICENSE/releases.atom，查询日期 2026-11-03）
• 官方文档站：https://noborus.github.io/trdsql/index.html
• godoc 库参考：https://pkg.go.dev/github.com/noborus/trdsql
• Go Report Card：https://goreportcard.com/report/github.com/noborus/trdsql
• 同作者相关工具：psutilsql（https://github.com/noborus/psutilsql）、mdtsql（https://github.com/noborus/mdtsql）、xlsxsql（https://github.com/noborus/xlsxsql）
• 站内：《csvq 1.18.1 介绍与选型指南》、《dsq 介绍与选型指南》、《OctoSQL 0.13.0 介绍与选型指南》