数仓连接器¶
Dosi 靠 SQL 下推执行:把指标查询编译成对应方言的 SQL,交给数仓去跑。连接器负责建立连接、提交语句,并把结果归一成 ResultSet——列,加上 Null | Bool | Int | Float | Str 的行,日期统一为 ISO-8601 字符串——这样各引擎的结果才能逐格比对。
这一节是配置指南。先看所有连接器共用的连接配置格式,再按下面的路由表跳到你那个数据库的页面。Arrow 原生结果传输(DuckDB、ClickHouse、StarRocks/Doris、Databricks)在 Arrow 里讲。
让 Agent 来连接¶
编程 Agent 里装了 Dosi 插件,连接就不用你自己写。说一句“帮我连上数据”,或者直接点名(“连上我们的 Snowflake,账号 xy12345”),Agent 会:
- 先找现成的配置。 通过
dosi migrate conf读取 dbt 的profiles.yml或 Cube 的.env;本地的.duckdb、.sqlite文件直接连;数仓则按该连接器的模板写一条配置,只问你那些不涉密的字段; - 口令不进入对话。 它写一个
${NAME}占位符,告诉你真实口令放在哪里:直接填进dosi-connections.yaml(它会把这个文件加进.gitignore),或者以NAME=...写进~/.config/dosi/secrets.env。它从不在对话里要口令,也从不打开这些文件; - 测试连接。 用
dosi connection test测一次,成功就报一行;失败时说清发生了什么、为什么、下一步做什么。
以后要改连接,也是跟 Agent 说。它读不了这个文件,所以会告诉你改哪一行。快速上手在示例库上演示了完整流程。
本页其余部分讲的就是 Agent 写出的那个文件:想手动配置连接,或者想复核 Agent 写了什么,都看这里。
连接配置¶
连接配置沿用 Datus agent.yml 的 datasources: 词汇表——Dosi 用自己的连接器执行查询(刻意不用 datus-db-adapters),通用词汇保持一致。各连接器页面说明支持的传输和认证配置;Redshift Data API 使用目标资源与身份字段,需转换原有的 TCP host/password 配置。
--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 (改名前的旧路径) |
注意每个 osi- 旧路径都紧跟在对应的 dosi- 路径之后,而不是排在最末尾。Datus 的 agent.yml(./conf/agent.yml、~/.datus/conf/agent.yml)不会被自动发现,要用就用 --connections 指定。 |
所有连接器共用的键¶
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
type |
string | 是 | — | 选定连接器,不区分大小写。取值见下面的路由表;也接受 postgresql 和 greenplum,均使用 postgres 连接器与 SQL 方言。pg 和 opengauss 不是受支持的别名。 |
default |
bool | 否 | false |
整个文件里最多一个配置能设。--execute 不带 --connection 时用它;仅编译的 query、select 在未显式指定方言、连接或本地数据库时,也使用它的方言。 |
其余的键都是各连接器自己的:对应页面会列出它真正会读的键,以及它解析了但根本不用的键。
密钥与 ${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}。
从 dbt 或 Cube 迁移¶
如果 dbt(或 MetricFlow)或 Cube 已经能连上你的数仓,dosi migrate conf
会替你写好连接配置,再用 dosi connection test 验证其中一个:
dbt。 按 dbt 自己的顺序找 profiles.yml:$DBT_PROFILES_DIR,然后 ./profiles.yml,
然后 ~/.dbt/profiles.yml。每个 profile × target 生成一个连接,命名为 <profile>.<target>;
dbt_project.yml 指定的 profile 当前所选的 target 标记为 default。
{{ env_var('X') }} 转成 ${X},{{ env_var('X', 'd') }} 转成 ${X:-d};
其他 Jinja 写法会让这个 target 以 unsupported_config 被拒绝。
Cube。 从 ./.env(不会去上级目录找)和环境变量里读 CUBEJS_DB_*。
CUBEJS_DATASOURCES=default,events 加上 CUBEJS_DS_EVENTS_DB_*,每个数据源生成一个连接,
命名为 cube.<name>;cube.default 标记为 default。在环境变量里设置的值写成 ${NAME};
只在 .env 里的值原样复制。cube.js / cube.py 里的 driverFactory 是用代码建连接,
只报告、不迁移。
dbt type / Cube CUBEJS_DB_TYPE |
转换为 | 以 unsupported_auth 拒绝 |
|---|---|---|
snowflake |
snowflake(key pair:private_key_path) |
密码、内联 private_key、snowflake_jwt 以外的任何 authenticator(浏览器 SSO、OAuth、MFA、Okta) |
bigquery |
bigquery(keyfile、keyfile_json、CUBEJS_DB_BQ_KEY_FILE / _CREDENTIALS) |
method: oauth 等令牌方式;完全没有 key |
databricks / databricks-jdbc |
databricks(从 http_path / httpPath 取 SQL warehouse,token) |
没有 token(OAuth) |
postgres、mysql、tidb、starrocks、doris、oracle |
同名 type |
— |
duckdb |
duckdb(path 转成绝对路径) |
MotherDuck(md:)为 unsupported_dialect |
trino |
trino |
none 以外的 method;密码或令牌 |
athena |
Amazon Athena | exec-athena |
clickhouse |
走 HTTP(S) 的 clickhouse |
—(driver: native 为 unsupported_config) |
其他(redshift、sqlserver、spark 等) |
不写入:unsupported_dialect |
交互式登录会被拒绝,因为 agent 运行 dosi 时没有人在键盘前;把这个 target 改成 key 或 token 后重新运行即可。
值。 报告里从不打印。写进文件时,字面值——包括密码——原样复制;文件以仅属主可读写(0600)
的权限写入;如果它位于 git 工作区里,它的路径会被加进该工作区的 .gitignore。
重复运行会替换同名连接,其他连接保持不动;已经标记为 default 的连接继续保留这个角色——即使它的设置被替换——导入的 target 不会抢走它。
Datus 的 agent.yml 永远不会被改写——需要独立文件时请传 --out。
一个配置写坏了会怎样¶
某个配置解析失败——变量没设、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 | 否 |
hana |
SAP HANA | exec-hana |
SAP HDBODBC | no |
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 |
Amazon Redshift | exec-redshift |
AWS SDK Data API | 否 |
你手上的构建带了哪些¶
官方发布的二进制和 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 "pg" |
使用 postgres、postgresql 或 greenplum;不支持 pg 别名。 |
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 拼错了;提示里会列出文件里定义的名字。 |