跳转至

数仓连接器

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 时用它

跑一下:

$ dosi query --metrics revenue --group-by orders.status --execute --connection prod-sr

--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 验证其中一个:

$ dosi migrate conf
$ dosi connection test analytics.dev

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 拼错了;提示里会列出文件里定义的名字。

下一步

  • CLI 参考——--connections、--connection、--execute
  • Arrow——哪些连接器走 Arrow,能带来什么
  • REST API——同一份配置,通过 HTTP 提供服务