数仓连接器¶
Dosi 靠 SQL 下推执行：把指标查询编译成对应方言的 SQL，交给数仓去跑。连接器负责建立连接、提交语句，并把结果归一成 ResultSet——列，加上 Null | Bool | Int | Float | Str 的行，日期统一为 ISO-8601 字符串——这样各引擎的结果才能逐格比对。
这一节是配置指南。先看所有连接器共用的连接配置格式，再按下面的路由表跳到你那个数据库的页面。Arrow 原生结果传输（DuckDB、ClickHouse、StarRocks/Doris、Databricks）在 Arrow 里讲。
连接配置¶
连接配置沿用 Datus agent.yml 的 datasources: 词汇表——dosi-exec 自己保留一套极简的 QueryExecutor 接口（刻意不与 datus-db-adapters 对齐），但配置是共用的，所以已有的 Datus 环境不用做任何转换。
--connections <path>（环境变量 DOSI_CONNECTIONS）既接受完整的 agent.yml（配置在 services.datasources 下），也接受把同样的 map 放在顶层 datasources: 的独立文件。
datasources:
local-duck:
type: duckdb
uri: duckdb:///warehouse.duckdb # 不写就是内存库
prod-sr:
type: starrocks
host: sr.internal
port: 9030
username: dosi
password: ${SR_PASSWORD} # ${VAR} / ${VAR:-fallback} 从环境变量取
database: analytics
default: true # --execute 不带 --connection 时用它
跑一下：
--execute 不带 --connection 时，有 default: true 就用它，否则用本地 DuckDB（--db <file>，或内存库）。
配置文件从哪里找¶
不传 --connections 时，按顺序取第一个存在的路径：
| # | 路径 |
|---|---|
| 1 | $DOSI_CONNECTIONS |
| 2 | ./dosi-connections.yaml |
| 3 | ./osi-connections.yaml （改名前的旧路径） |
| 4 | ~/.config/dosi/connections.yaml |
| 5 | ~/.config/osi/connections.yaml （改名前的旧路径） |
| 6 | ./conf/agent.yml |
| 7 | ~/.datus/conf/agent.yml |
所以已经装了 Datus 的机器零配置就能用。注意每个 osi- 旧路径都紧跟在对应的 dosi- 路径之后，而不是排在最末尾。
所有连接器共用的键¶
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
type |
string | 是 | — | 选定连接器。取值见下面的路由表；精确匹配、小写、没有别名（postgresql、pg、opengauss 都会报错）。 |
default |
bool | 否 | false |
整个文件里最多一个配置能设。--execute 不带 --connection 时用它。 |
其余的键都是各连接器自己的：对应页面会列出它真正会读的键，以及它解析了但根本不用的键。
密钥与 ${VAR}¶
任何字符串值都可以写成 ${VAR} 或 ${VAR:-fallback} 来引用环境变量。对 password: 和 private_key_file_pwd: 来说，写法本身有区别：
- 值恰好是
${VAR}时，解析是延迟的——变量没设也能把文件加载起来，只有真正用到这个连接时才报错，并附上export提示。 - 值只是包含
${VAR}，加载文件时就会解析。 - 明文密钥也能用，但会在 stderr 上告警：
warning: connection "x" has a plaintext password in the connections file; prefer password: ${VAR}。
一个配置写坏了会怎样¶
某个配置解析失败——变量没设、type: 写错——不会把整个文件带崩。它的错误会被记下来，只在用到这个名字时才抛出，所以一条坏配置挡不住你正在用的那些。
不认识的键会被忽略：Datus 的适配器把自己的私有设置放在同一个文件里。唯一的例外是 1.0 之前的旧拼写，它们会带着迁移提示直接报错，而不是悄悄不生效：
| 已废弃 | 改用 |
|---|---|
dialect: |
type: |
user: |
username: |
password_env: |
password: ${VAR} |
private_key_passphrase: |
private_key_file_pwd: |
private_key_passphrase_env: |
private_key_file_pwd: ${VAR} |
path: |
uri: duckdb:///<path> |
url: |
uri: |
顶层的 connections: 列表 |
按名字索引的 datasources: map |
连接器¶
type: |
页面 | Cargo feature | 怎么与引擎通信 | Arrow 原生 |
|---|---|---|---|---|
duckdb |
DuckDB | exec-duckdb （默认开） |
进程内，库随包附带 | 是 |
sqlite |
SQLite | exec-duckdb |
本地文件，只读，经 DuckDB 打开 | 是 |
mysql |
MySQL | exec-mysql |
MySQL 线协议 | 否 |
tidb |
TiDB | exec-mysql |
MySQL 线协议 | 否 |
starrocks |
StarRocks | exec-mysql、exec-flightsql |
MySQL 线协议，或 Arrow Flight SQL | 可选开启 |
doris |
Apache Doris | exec-mysql、exec-flightsql |
MySQL 线协议，或 Arrow Flight SQL | 可选开启 |
postgres |
PostgreSQL | exec-postgres |
Postgres 线协议 | 否 |
hologres |
Hologres | exec-hologres |
Postgres 线协议 | 否 |
dws |
华为云 DWS | exec-dws |
Postgres 线协议 + 数据库模式探测 | 否 |
gaussdb |
GaussDB / openGauss | exec-gaussdb |
Postgres 线协议 + SHA256 认证 | 否 |
oracle |
Oracle Database | exec-oracle |
经 ODPI-C 走 OCI | 否 |
clickhouse |
ClickHouse | exec-http、exec-http-arrow |
HTTP 接口 | 可选开启 |
trino |
Trino | exec-http |
REST /v1/statement |
否 |
snowflake |
Snowflake | exec-snowflake |
HTTPS 上的 SQL API v2 | 否 |
bigquery |
BigQuery | exec-bigquery |
HTTPS 上的 jobs.query REST |
否 |
databricks |
Databricks | exec-databricks、exec-databricks-arrow |
Statement Execution API | 可选开启 |
redshift 也是合法的 type: 取值，SQL 能编译出来，但还没有执行器：在 --execute 里指定它会报 no executor for redshift yet (planned)。
你手上的构建带了哪些¶
官方发布的二进制和 dosi-engine wheel 带全部连接器。自己编译的二进制默认只有 DuckDB，其余的用 --features exec-all 一次带全，或者按需单独指定。缺哪个它会直说：
this build has no postgres executor (feature "exec-postgres" not enabled)
hint: rebuild with --features exec-postgres
排错¶
下面这些来自连接配置文件本身，还没走到任何一个连接器。
| 报错 | 原因 |
|---|---|
no connections file found; pass --connections <path>, set DOSI_CONNECTIONS, or create ./dosi-connections.yaml |
七个发现路径一个都不存在。 |
<path> has no datasources: map (nor services.datasources) |
文件能解析，但配置不在这两个位置。 |
<path> uses the removed connections: list format |
1.0 之前的老文件；把条目挪到 datasources: map 下。 |
datasource "x" is missing required field "type" |
每个配置都要有 type:。 |
datasource "x": unknown dialect "postgresql" |
用路由表里的精确拼写（postgres）。 |
datasource "x": "user" is the legacy osi-connections spelling |
见上面的旧拼写对照表。 |
<path> marks 2 datasources as default: a, b |
default: true 最多一个。 |
datasource "x": environment variable "PW" is not set |
export 一下，或者写成 ${PW:-fallback}。 |
no connection named "x"——并附 hint: available: … |
--connection 拼错了；提示里会列出文件里定义的名字。 |