OctoSQL 0.13.0 介绍与选型指南

OctoSQL 是一个用 Go 编写的单二进制联邦查询 CLI：它不装数据库、不起服务，把一条 SQL 直接打到 CSV、TSV、JSON、Parquet 文件、标准输入乃至远程 PostgreSQL/MySQL 上，让不同来源的数据在一条查询里完成 JOIN 和聚合，再把结果以表格、CSV、JSON 等形式吐出来。对运维和数据工程师来说，它相当于"数据界的瑞士军刀"——临时核对两份导出文件、把数据库表和 Excel 导出的 CSV 关联一下、对日志管道做个统计，都不必先 ETL 进某个库。

本文基于 2026-11-03 对官方仓库与 releases 的联网溯源，以及 app01（Ubuntu 22.04）+ db01（PostgreSQL 16）两台服务器上的实测环境，介绍 OctoSQL 的定位、能力、同类工具选型对比、适用与不适用场景，并如实说明它的维护状态——这对你决定是否把它纳入工具箱至关重要。

一、它是什么：核心定位

官方 README 对 OctoSQL 的定义是"一个用于查询数据库和文件格式的 CLI 工具"，其核心卖点是把 SQL 查询能力带到几乎任何数据源上，并支持跨源 JOIN。拆开看有三层：

1. 单二进制、零依赖。Linux amd64 的可执行文件约 19 MB（实测 du -h /usr/local/bin/octosql 输出 19M），拷贝即用，不需要 Python 运行时、不需要 JVM，天然适合跳板机、堡垒机、临时作业环境。
2. 文件与数据库同席。内置支持 CSV、TSV、JSON（JSON Lines）、Parquet、Lines 五种文件格式；PostgreSQL、MySQL 等网络数据库通过插件体系接入（实测 plugins.available_plugins 返回 mysql、postgres、random_data 三个插件）。
3. 流式查询引擎。查询被编译成有向无环图（DAG），每个算子是一个 goroutine，数据以记录流的形式在算子间流动。这带来两个副产品：对大文件的低内存占用，以及一套面向流处理的扩展语法（TRIGGER 触发器、水位线、事件时间、tumble 窗口聚合、poll/range 等表值函数）。

项目以 MPL-2.0 许可开源（实测 release 包内 LICENSE 首行为 Mozilla Public License Version 2.0），当前仓库地址为 https://github.com/cube2222/octosql。

二、核心能力一览

以下能力全部在 app01 上实测过（完整命令与输出见《OctoSQL 0.13.0 常用 CLI 命令详解》）：

三、选型对比（量化，来源与查询日期见注）

把 OctoSQL 放进"用 SQL 查文件/小数据"这个赛道，与常见同类逐项对比（GitHub 星数取自 shields.io 徽章，版本与发布日期取自各仓库 releases.atom，查询日期均为 2026-11-03；DataHand 为域名实测，SQLite FDW 为 PGXN 目录实测）：

对比要点：

• csvq（mithrandie/csvq）本质是"给单个 CSV/JSON 文件一个 SQL 引擎"，JOIN 发生在同一加载源内部，不做跨文件/跨库联邦查询，与 OctoSQL 的赛道只重叠一半。
• dsq（multiprocessio/dsq）支持多文件 JOIN 且格式覆盖面广（csv/json/parquet/excel/sqlite），但没有任何网络数据库源，且停更比 OctoSQL 更久。
• trdsql（noborus/trdsql）是这批工具里唯一仍在活跃发版的（v1.2.3，2026-05-29），多文件 JOIN + 导入导出很顺手；它与数据库的关系是"借用 postgres/mysql 引擎来算文件"，而不是"一条 SQL 同时查文件和数据库"。若你的核心需求是纯文件分析且在意长期维护，trdsql 是比 OctoSQL 更稳的选择。
• DataHand 曾是图形化数据集成工具，2026-11-03 实测其官网域名已无法解析（直连与代理均失败），无可用公开发布渠道，不建议新项目选型。
• SQLite FDW（PGXN sqlite_fdw 2.5.0）解决的是反向问题——把 SQLite 文件挂进 PostgreSQL 当外表查，适合"已有 PG、想读 SQLite"的场景，不是独立 CLI。

官方仓库 README 还附有一张基准表（v0.8.0 时代、M1 MacBook、本地文件，来源 README.md，查询日期 2026-11-03，仅供量级参考）：

聚合与 JOIN 是 OctoSQL 的强项，全量拉取（SELECT *）则不占优。

四、典型适用场景

1. 跨源临时核对：业务导出的 CSV 名单 × 部门 JSON 表 × 生产库里的季度奖金表，一条 SQL 对齐，不用写一次性脚本。本专栏实测的三源 JOIN 即此类。
2. 日志/管道统计：grep ... | octosql "SELECT ... FROM stdin.lines"，把管道文本当表算。
3. Parquet 抽检：数据湖交付前，不装任何引擎直接 SELECT * FROM part-000.parquet 看 schema 和聚合。
4. 堡垒机/跳板机作业：单二进制 + 一个 YAML 配置，无法安装运行时的受限环境也能用。
5. 轻量 ETL 导出：-o csv/-o json 重定向到文件，完成"查出来落盘"的最小闭环。

五、局限与不适用场景

1. 没有交互 REPL。实测 octosql 不带参数运行只打印 usage 帮助。网上流传的"/connect、/tables 元命令 + ~/.octosql/config.json"是早期 clockwork-io 时代的形态，现行版本已改为"一次进程一条查询" + ~/.octosql/octosql.yml + 插件体系。
2. JSON 只认 JSON Lines（一行一个对象）。标准 JSON 数组文件直接报错 couldn't parse json: cannot parse array: missing ']'，需先用 jq '.[]' -c 转 JSONL。
3. 类型对齐要自己负责。CSV 数字列解析为 Int，JSON 数字解析为 Float，两者 JOIN 会静默返回空结果（不报错），必须显式 int()/float() 转换——这是实测踩到的第一个大坑。
4. 数据库源生态薄。官方插件仓库索引目前只有 postgres、mysql、random_data 三个；MongoDB、Excel、Google Sheets 均不支持（那是旧版或同类工具的能力，别按旧文档预期）。
5. 不适合做常驻数据服务。它是查询执行器，不是查询服务器：无并发服务、无权限模型、无结果缓存；流式扩展语法（TRIGGER/水位线）官方自己也标注为实验特性。
6. --explain 依赖 graphviz，无 dot 命令时报 couldn't render graph: exec: "dot": executable file not found in $PATH。

六、维护状态（2026-11-03 实测甄别）

这是选 OctoSQL 前必须知道的事实链：

• 原仓库 github.com/clockwork-io/octosql 已 404（实测 HTTP 404），项目现由原作者以个人账号维护：github.com/cube2222/octosql（5.3k stars / 215 forks，shields.io 徽章实测）。
• 仓库未归档（页面实测无 archived 横幅），但最后一次发版 v0.13.0 停在 2024-05-11，距查询日已约 2.5 年；上一版 v0.12.2 是 2023-05-30，节奏明显放缓。
• 官网域名 octosql.io 已无法解析（实测 getent hosts octosql.io 无结果，直连与代理访问均失败），文档只能依赖仓库 README 与 release 包内自带的 README.md。
• 遥测端点 telemetry.octosql.dev 同样失效（实测 ~/.octosql/logs.txt 中留下 dial tcp: lookup telemetry.octosql.dev ... no such host 记录），可用 OCTOSQL_NO_TELEMETRY=1 关闭。
• 插件下载走 GitHub Releases，目前可用（实测 postgres 插件直连 10.7 秒装完）。

结论：OctoSQL 处于"作者个人维护、低频更新、基础设施（域名）已失守"的状态。功能面在 v0.13.0 是完整可用的，但把它写进长期依赖的运维手册前，建议按第五节的局限逐条评估，并保持"随时可迁往 trdsql/duckdb 类活跃项目"的退路。

七、快速上手（最小可运行示例）

以下两条命令在 app01（Ubuntu 22.04，数据目录 /opt/datasets）实测，输出逐行照抄。

第一条：查一个 CSV 文件。

root@app01:~# cd /opt/datasets
root@app01:/opt/datasets# octosql "SELECT * FROM employees.csv"
+------+--------------+---------+--------+
|  id  |     name     | dept_id | salary |
+------+--------------+---------+--------+
| 1001 | 'Alice Wang' |       1 |  18500 |
| 1002 | 'Bob Chen'   |       1 |  16200 |
| 1003 | 'Carol Li'   |       2 |  21000 |
| 1004 | 'Dave Zhang' |       2 |  19800 |
| 1005 | 'Eve Liu'    |       3 |  15600 |
| 1006 | 'Frank Zhao' |       3 |  17400 |
| 1007 | 'Grace Sun'  |       1 |  22300 |
+------+--------------+---------+--------+

第二条：CSV × JSON Lines × PostgreSQL 三源 JOIN（数据库连接配置见《OctoSQL 0.13.0 配置参数详解》，安装与插件见《OctoSQL 0.13.0 安装部署指南》）：

root@app01:/opt/datasets# octosql "SELECT e.name, d.name AS dept, d.location, b.quarter, b.bonus FROM employees.csv e JOIN \`json.departments.jsonl\` d ON e.dept_id = int(d.id) JOIN hrdb.bonus b ON b.emp_id = e.id ORDER BY e.name, b.quarter"
+--------------+---------------+------------+----------+-------+
|     name     |     dept      |  location  | quarter  | bonus |
+--------------+---------------+------------+----------+-------+
| 'Alice Wang' | 'Engineering' | 'Shanghai' | '2026Q3' |  3000 |
| 'Alice Wang' | 'Engineering' | 'Shanghai' | '2026Q4' |  3500 |
| 'Bob Chen'   | 'Engineering' | 'Shanghai' | '2026Q3' |  2500 |
| 'Carol Li'   | 'Finance'     | 'Beijing'  | '2026Q3' |  4200 |
| 'Carol Li'   | 'Finance'     | 'Beijing'  | '2026Q4' |  4600 |
| 'Dave Zhang' | 'Finance'     | 'Beijing'  | '2026Q3' |  3800 |
| 'Eve Liu'    | 'Operations'  | 'Shenzhen' | '2026Q3' |  1500 |
| 'Grace Sun'  | 'Engineering' | 'Shanghai' | '2026Q4' |  5100 |
+--------------+---------------+------------+----------+-------+

注意 int(d.id)：JSON 里的数字是 Float，CSV 里的是 Int，不转换 JOIN 结果为空（见第五节第 3 条）。

八、参考链接

• OctoSQL 仓库：https://github.com/cube2222/octosql（查询日期 2026-11-03）
• Releases：https://github.com/cube2222/octosql/releases（最新 v0.13.0，2024-05-11）
• 插件索引：https://raw.githubusercontent.com/cube2222/octosql/master/plugin_repository.json
• csvq：https://github.com/mithrandie/csvq（v1.18.1，2023-03-26）
• dsq：https://github.com/multiprocessio/dsq（v0.23.0，2022-10-20）
• trdsql：https://github.com/noborus/trdsql（v1.2.3，2026-05-29）
• SQLite FDW：https://pgxn.org/dist/sqlite_fdw/（2.5.0）

九、FAQ

Q1：OctoSQL 不是有个交互模式吗？我记得有 /connect、/tables 这样的命令？ A：那是早期 clockwork-io 时代版本（v0.11.x 及更早）的形态。现行 v0.13.0 实测不带参数运行只打印 usage 帮助，没有内置 REPL；连接定义改到 ~/.octosql/octosql.yml，表发现直接写在 SQL 的 FROM 子句里（如 SELECT * FROM hrdb.bonus、SELECT * FROM employees.csv）。按旧教程找元命令会一无所获。

Q2：我有一个正常的 JSON 数组文件，为什么报错读不了？ A：OctoSQL 的 JSON 源只支持 JSON Lines（一行一个对象）。数组文件实测报错 couldn't parse json: cannot parse JSON: cannot parse array: missing ']'。转换方法：jq -c '.[]' departments.json > departments.jsonl，然后用 `json.departments.jsonl` 反引号记法读取。

Q3：CSV 和 JSON 明明都有 id=1 的记录，JOIN 出来却是空表？ A：类型不匹配。实测 CSV 数字列是 Int，JSON 数字是 Float，Int = Float 的比较不成立且不报错，静默返回空。用 int()/float() 显式转换即可，这是跨源 JOIN 最常见的坑。

Q4：能查 MongoDB / Excel / Google Sheets 吗？ A：不能。v0.13.0 的官方插件仓库只有 postgres、mysql、random_data 三个插件（实测 plugins.available_plugins 输出）。MongoDB/Excel/Sheets 是旧版或同类工具（如 dsq 的 Excel 文件支持）的能力。

Q5：项目还活着吗，敢不敢上生产？ A：仓库未归档、代码可用、GitHub Releases 下载链路完好，但 2.5 年没发版、官网域名已失效、插件生态只有三个。适合做个人/运维的临时查询工具；若进入生产脚本，请锁定 v0.13.0 二进制与校验和，并准备 trdsql/DuckDB 作为迁移退路。

决定试用后的三篇配套：部署看《OctoSQL 0.13.0 安装部署指南》，配置看《OctoSQL 0.13.0 配置参数详解》，全部命令与排障看《OctoSQL 0.13.0 常用 CLI 命令详解》。