OctoSQL 0.13.0 配置参数详解

OctoSQL 0.13.0 配置面逐项实测：octosql.yml 数据库连接（postgres 六参数含 README 未列的 schema 必填）、文件源 FROM 内联配置与列命名规则、插件仓库与落盘布局、OCTOSQL_NO_TELEMETRY/OCTOSQL_POSTGRES_QUERY_LOGGING 环境变量、~/.octosql 运行时目录，附 tail 选项无效等 5 条排障实录。

OctoSQLOctoSQLSQLPostgreSQL配置参数详解Parquet2026/11/03

OctoSQL 0.13.0 配置参数详解

OctoSQL 的配置面分四块：命名数据库连接清单 ~/.octosql/octosql.yml（唯一的全局配置文件）、文件数据源的查询内联配置（FROM 子句里的反引号记法与 ?key=value 选项）、插件仓库体系（plugins.repositories 与 ~/.octosql/plugins/ 落盘布局）、环境变量（遥测与插件查询日志）。本文逐项拆解并全部实测，环境为 app01（Ubuntu 22.04）+ db01（PostgreSQL 16，admin/q1w2e3r4），部署过程见《OctoSQL 0.13.0 安装部署指南》。

先纠正一个流传甚广的误区：网上部分教程让你去编辑 ~/.octosql/config.json，那是早期 clockwork-io 时代版本的形态。v0.13.0 实测根本不存在 config.json，配置文件只有 YAML 一种：~/.octosql/octosql.yml。

一、octosql.yml：命名数据库连接

1.1 完整结构与实测全文

octosql.yml 只有一个顶层键 databases，是命名连接的列表。app01 上连接 db01 的实际配置（cat ~/.octosql/octosql.yml）：

databases:
  - name: hrdb
    type: postgres
    config:
      host: db01
      port: 5432
      database: demo
      schema: public
      user: admin
      password: q1w2e3r4

声明后，hrdb 就成了 SQL 里的一个"库名"：SELECT * FROM hrdb.bonus 直接查 db01 上 demo.public.bonus 表。

1.2 顶层三参数

参数必填说明
name是连接名，SQL 中 name.table 的第一段；建议小写短名
type是插件类型，取已安装插件名（实测 plugins.available_plugins 只有 postgres、mysql、random_data）
config是传给插件的参数映射，随 type 而异

1.3 postgres 插件 config 逐项

postgres 插件 0.3.0 的 README 列了 5 个参数，实测还要求第 6 个：

参数必填说明
host是数据库服务器地址（本机可写 localhost）
port是端口，PostgreSQL 默认 5432
user是账号
password是密码
database是库名
schema是（README 未列）模式名，如 public。缺失时查询报 `schema` configuration setting is required（见第六节实录 3）

mysql 插件的 config 参数集与 postgres 相同（host/port/user/password/database，插件 README 实测一致），但没有 schema 概念，模式即库。

1.4 多连接与命名规则

databases 可以列任意多个连接，同名互不冲突。实测追加第二个连接 hrdb2（同库同表）后，用 hrdb2.bonus 参与 JOIN 完全正常：

root@app01:/opt/datasets# octosql "SELECT a.name, b.quarter FROM employees.csv a JOIN hrdb2.bonus b ON b.emp_id = a.id LIMIT 2"
+--------------+----------+
|     name     | quarter  |
+--------------+----------+
| 'Alice Wang' | '2026Q3' |
| 'Bob Chen'   | '2026Q3' |
+--------------+----------+

表名引用规则（实测）：

  • 两段式 连接名.表名（hrdb.bonus）是唯一合法形式；
  • 三段式 连接名.模式.表名 直接解析失败：Error: couldn't parse query: invalid argument syntax error at position 27——模式已经由配置里的 schema 固定，SQL 中不能再写；
  • 表名不存在时报 table nosuchtable does not exist（插件侧透传）。

二、文件数据源：FROM 内联配置

文件不写进 octosql.yml，"配置"发生在查询字符串里，共三种写法（实测）：

2.1 裸路径与扩展名自动探测

octosql "SELECT * FROM employees.csv"          # CSV
octosql "SELECT * FROM cities.tsv"             # TSV
octosql "SELECT * FROM employees.parquet"      # Parquet
octosql "SELECT * FROM mydir/myfile.csv"       # 相对/绝对路径均可

自动识别的扩展名只有 .csv、.tsv、.json、.parquet。其他扩展名（.jsonl、.txt、.md 等）裸写会报 no such table：

root@app01:/opt/datasets# octosql "SELECT * FROM departments.jsonl"
Error: typecheck error: couldn't create datasource: no such table: departments.jsonl

2.2 反引号记法：格式.路径

用反引号显式指定格式处理器，路径里可以带任意扩展名：

octosql "SELECT * FROM \`json.departments.jsonl\`"   # JSON Lines
octosql "SELECT * FROM \`lines.notes.txt\`"          # 按行读取任意文本
octosql "SELECT * FROM \`csv.nohdr.csv\`"            # 等价于裸写 .csv

格式名对应：csv、tsv、json（JSON Lines）、parquet、lines。注意 json 处理器只认一行一个对象的 JSON Lines；标准 JSON 数组文件会报 couldn't parse json: cannot parse JSON: cannot parse array: missing ']'，需先 jq -c '.[]' 转换。

2.3 查询串选项：格式.路径?key=value

实测可用选项：

选项适用效果
header=falsecsv/tsv文件无表头，列名生成 column_0、column_1…
tail=NREADME 宣称 json/lines 支持实测无效（见 2.4）
root@app01:/opt/datasets# octosql "SELECT * FROM \`csv.nohdr.csv?header=false\`"
+----------+----------+
| column_0 | column_1 |
+----------+----------+
|        1 | 'x'      |
|        2 | 'y'      |
+----------+----------+

2.4 实测坑：tail 选项被静默忽略

README 写着"tail: how many lines to read from the end of the file"，实测三种格式全部无效——?tail=1 仍返回整个文件且不报错：

root@app01:/opt/datasets# octosql "SELECT * FROM \`lines.notes.txt?tail=2\`"
+------------+----------+
| txt.number | txt.text |
+------------+----------+
|          0 | 'alpha'  |
|          1 | 'beta'   |
|          2 | 'gamma'  |
+------------+----------+

需要"只看文件尾"时别指望这个选项，用 shell 的 tail -n 2 notes.txt | 管道进 stdin.lines 更可靠。

2.5 列命名规则（跨源 JOIN 前必读）

实测两种风格并存：

  • .csv/.tsv/.parquet：列名就是表头/字段名本身（id、name），可裸引用；
  • json./lines. 反引号记法：列名带扩展名前缀，如 jsonl.id、txt.text：
|       name       |   type   | time_field |
| 'jsonl.id'       | 'Float'  | false      |
| 'jsonl.location' | 'String' | false      |
| 'jsonl.name'     | 'String' | false      |

裸写 SELECT id FROM \json.departments.jsonl`会报unknown variable: 'id'。两种解法：反引号全名 `` jsonl.id ``，或**给表起别名后按后缀访问**（d.id能解析到jsonl.id`，推荐，跨版本最稳）：

root@app01:/opt/datasets# octosql "SELECT d.name, e.name FROM \`json.departments.jsonl\` d JOIN employees.csv e ON e.dept_id = int(d.id)"
+---------------+--------------+
|    d.name     |    e.name    |
+---------------+--------------+
| 'Engineering' | 'Alice Wang' |
| 'Engineering' | 'Bob Chen'   |
| 'Engineering' | 'Grace Sun'  |
| 'Finance'     | 'Carol Li'   |
| 'Finance'     | 'Dave Zhang' |
| 'Operations'  | 'Eve Liu'    |
| 'Operations'  | 'Frank Zhao' |
+---------------+--------------+

同理注意类型：JSON 数字一律 Float，CSV 数字是 Int，JOIN 键必须 int()/float() 显式对齐，否则静默空结果。

2.6 stdin 虚拟表

标准输入也是"数据源"，固定两个表名：stdin.json（JSON Lines）与 stdin.lines（列 number/text，实测 describe 为 Int/String）：

root@app01:/opt/datasets# seq 100 | octosql "SELECT SUM(int(text)) AS total FROM stdin.lines"
+-------+
| total |
+-------+
|  5050 |
+-------+

三、插件体系配置

3.1 插件仓库

内置一个默认仓库 core（实测 octosql "SELECT * FROM plugins.repositories" -o batch_table）：

+--------+--------------------------+--------------------------+
|  slug  |           name           |       description        |
+--------+--------------------------+--------------------------+
| 'core' | 'Core OctoSQL Plugin     | 'The official place to   |
|        | Repository'              | publish and look for     |
|        |                          | open-source OctoSQL      |
|        |                          | plugins.'                |
+--------+--------------------------+--------------------------+

core 索引文件就是主仓库里的 plugin_repository.json（https://raw.githubusercontent.com/cube2222/octosql/master/plugin_repository.json，2026-11-03 实抓，节选）：

{
    "name": "Core OctoSQL Plugin Repository",
    "description": "The official place to publish and look for open-source OctoSQL plugins.",
    "slug": "core",
    "plugins": [
        {
            "name": "postgres",
            "description": "Adds support for querying PostgreSQL databases.",
            "website": "https://github.com/cube2222/octosql-plugin-postgres",
            "license": "Mozilla Public License Version 2.0",
            "readme_url": "https://raw.githubusercontent.com/cube2222/octosql-plugin-postgres/main/README.md",
            "manifest_url": "https://raw.githubusercontent.com/cube2222/octosql-plugin-postgres/main/octosql_manifest.json"
        }
    ]
}

每个插件条目通过 manifest_url 指向插件仓库里的 octosql_manifest.json（版本与下载地址清单），实际二进制从对应插件仓库的 GitHub Release 拉取——这也是为什么插件安装同样受 GitHub 链路可用性影响（见安装指南第十节实录 1）。

可用插件全集用 SQL 查（实测返回 mysql/postgres/random_data 三行）：

root@app01:/opt/datasets# octosql "SELECT name, description FROM plugins.available_plugins" -o batch_table
+---------------+--------------------------+
|     name      |       description        |
+---------------+--------------------------+
| 'mysql'       | 'Adds support for        |
|               | querying MySQL           |
|               | databases.'              |
| 'postgres'    | 'Adds support for        |
|               | querying PostgreSQL      |
|               | databases.'              |
| 'random_data' | 'Generates random data   |
|               | for testing.'            |
+---------------+--------------------------+

3.2 第三方仓库

octosql plugin repository add <owner>/<name> <ref> 添加 GitHub 仓库形式的插件仓库，<ref> 是分支/标签/提交。实测子命令树里 repository 下只有 add（没有 list/remove，卸载插件需手动删目录）：

Usage:
  octosql plugin repository [command]

Available Commands:
  add

3.3 插件落盘布局

安装后的目录结构（实测 find /root/.octosql/plugins）：

/root/.octosql/plugins/core
/root/.octosql/plugins/core/octosql-plugin-postgres
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0/LICENSE
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0/README.md
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0/octosql-plugin-postgres

按 仓库slug/插件名/版本/ 三层组织，同一插件可存多个版本。octosql.yml 的 type 引用插件名，主程序按索引里的版本要求匹配可执行文件并以 Unix socket 拉起进程（日志里可见 socket 路径 /root/.octosql/tmp/plugins/core$postgres<随机数>/<id>.sock）。

3.4 file_extension_handlers.json

~/.octosql/file_extension_handlers.json 是插件扩展名注册表，实测内容为 {}（当前三个插件都不注册新文件扩展名），了解即可，不要手改。

四、环境变量

变量效果实测
OCTOSQL_NO_TELEMETRY=1关闭遥测上报（默认上报到已失效的 telemetry.octosql.dev）关闭后查询正常，logs.txt 不再新增 lookup 失败
OCTOSQL_POSTGRES_QUERY_LOGGING=1postgres 插件把每条下推 SQL 记入 ~/.octosql/logs.txt见下

开启查询日志后实测 logs.txt 尾部：

[plugin][core/postgres][hrdb] 2026-11-03 03:45:54 Listening execution on /root/.octosql/tmp/plugins/core$postgres3954127066/01M6FR6WN07VKHB69BG6TFMQKN.sock
[plugin][core/postgres][hrdb] 2026-11-03 03:45:54 info Query map[args:[] pid:202 rowCount:9 sql:SELECT  FROM bonus WHERE (TRUE) time:227.553µs]

这行日志同时证实了插件进程模型：每次查询由 octosql 拉起插件进程、经 Unix socket 通信，插件侧把 WHERE 等谓词拼进真实 SQL 下推给 db01。

五、~/.octosql 运行时目录

实测 find /root/.octosql -maxdepth 4（节选）：

/root/.octosql
/root/.octosql/file_extension_handlers.json
/root/.octosql/logs.txt
/root/.octosql/octosql.yml
/root/.octosql/plugins
/root/.octosql/plugins/core
/root/.octosql/plugins/core/octosql-plugin-postgres
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0
/root/.octosql/tmp
/root/.octosql/tmp/plugins
/root/.octosql/tmp/plugins/core$postgres3954127066
/root/.octosql/.octosql
/root/.octosql/.octosql/telemetry
/root/.octosql/.octosql/telemetry/device_id
/root/.octosql/.octosql/telemetry/pending

注意 ~/.octosql/.octosql/telemetry 这个套娃目录是实测真实存在的（遥测模块把数据目录又拼了一层 .octosql）。遥测域名已失效，pending/ 里的 JSON 会一直堆积，无碍运行，看着碍眼可定期清空。logs.txt 按 README 说明只保留最近一次执行的日志，排障时别拿旧日志对号入座。

六、排障实录

实录 1：YAML 缩进错误。 databases 列表项缩进多一格，任何查询启动即报：

Error: couldn't read config: couldn't unmarshal yaml configuration: yaml: line 1: did not find expected '-' indicator

YAML 报错的行号经常指不到真正出错的位置，逐行核对缩进（列表项 - name: 顶两格、config: 子项再进两格）即可。

实录 2：密码错误报"unexpected message type"。 password 写错时，报错完全不提认证：

Error: typecheck error: couldn't create datasource: couldn't get table from plugin: rpc error: code = Unknown desc = couldn't get table: couldn't connect to database: couldn't open database: unexpected message type

这是 postgres 驱动在 TLS/认证握手阶段被拒的表现，排查时直接去 db01 上用同账号 psql 验证凭据，别在报错文字里找线索。

实录 3：postgres 缺 schema 参数。

Error: ... couldn't get table: `schema` configuration setting is required

插件 README 没写这个必填项（见 1.3），补 schema: public 即好。

实录 4：octosql.yml 声明了连接但插件没装。

Error: database 'hrdb' plugin 'core/postgres' used in configuration is not installed with the required version - run `octosql plugin install` to install all missing plugins

连纯文件查询都会被拦（配置加载期校验）。装插件或删掉对应 databases 条目。

实录 5：配置为空时查数据库表。 octosql.yml 存在但没声明 hrdb，查询报 no such table: hrdb.bonus——与"文件不存在"同款报错，先确认连接名拼写与配置文件是否被读到。

七、安全建议

  1. octosql.yml 明文存密码，务必 chmod 600 ~/.octosql/octosql.yml，并加入 .gitignore，不要随脚本仓库入库。
  2. 给 OctoSQL 建只读专用账号并在 db01 的 pg_hba.conf 里限制来源 IP，替代 admin 这类管理账号。
  3. 遥测默认开启且上报域名已失效（数据只会本地堆积），生产环境统一 export OCTOSQL_NO_TELEMETRY=1。
  4. 插件是独立可执行文件，从第三方 repository add 前确认仓库可信；~/.octosql/plugins 目录权限保持 700/755。

八、小结

OctoSQL 的配置哲学是"最小化"：全局只有一个 octosql.yml 管数据库连接，文件源全部在 FROM 子句里内联声明。需要背下来的实测要点就四条——postgres 的 schema 必填；表名只能两段式；json./lines. 列名带扩展名前缀且 JSON 数字是 Float；tail 选项无效。掌握这些，跨源 JOIN 的语法与调试见《OctoSQL 0.13.0 常用 CLI 命令详解》。