数据源配置（Datasources）

配置 agent.services.datasources 下的数据库连接。

概览

Datus Agent 在 agent.yml 中通过 agent.services 统一管理运行时集成。本页聚焦 services.datasources 下的数据库连接；语义层、BI 平台和调度器分别在同级页面单独说明。

主要特性：

• 统一连接入口：支持 Snowflake、StarRocks、SQLite、DuckDB 等数据库，以及语义层、BI、调度器服务
• 凭证安全：支持 ${ENV_VAR} 环境变量展开
• 默认数据库：可通过 default: true 标记默认数据库
• 插件适配器：可按需安装数据库适配器
• 动态发现：支持通过 path_pattern 批量发现多个本地数据库文件

说明：早期版本的 services.databases 键已重命名为 services.datasources。请在 agent.yml 中手动更改键名——运行时会拒绝旧键。

配置结构

数据库统一配置在 agent.services.datasources 下，每个条目都是一个独立数据库连接：

agent:
  services:
    datasources:
      my_snowflake:
        type: snowflake
        account: ${SNOWFLAKE_ACCOUNT}
        username: ${SNOWFLAKE_USER}
        password: ${SNOWFLAKE_PASSWORD}  # 可配置 private_key，或在没有 private_key 时 password 和 private_key_file 二选一
        # private_key: ${SNOWFLAKE_PRIVATE_KEY}
        # private_key_file: ${SNOWFLAKE_PRIVATE_KEY_FILE}
        # private_key_file_pwd: ${SNOWFLAKE_PRIVATE_KEY_FILE_PWD}
        database: ${SNOWFLAKE_DATABASE}  # 可选
        schema: ${SNOWFLAKE_SCHEMA}      # 可选
        warehouse: ${SNOWFLAKE_WAREHOUSE}
        role: ${SNOWFLAKE_ROLE}          # 可选
        default: true

      my_duckdb:
        type: duckdb
        uri: ./data/analytics.duckdb

    semantic_layer:
      metricflow: {}

    bi_platforms:
      superset:
        type: superset
        api_base_url: http://localhost:8088
        username: ${SUPERSET_USER}
        password: ${SUPERSET_PASSWORD}

    schedulers:
      airflow_prod:
        type: airflow
        api_base_url: ${AIRFLOW_URL}
        username: ${AIRFLOW_USER}
        password: ${AIRFLOW_PASSWORD}
        dags_folder: ${AIRFLOW_DAGS_DIR}

服务分组

配置段	用途	选择方式
services.datasources	SQL 与知识库操作使用的数据库连接	--datasource / 当前数据库 / 默认数据库
services.semantic_layer	语义适配器配置，例如 MetricFlow 或 OSI	active/default semantic layer
services.bi_platforms	BI 平台凭据与数据集物化配置	bi_platform
services.schedulers	调度器服务实例，例如 Airflow	scheduler_service

支持的数据库类型

Snowflake

my_snowflake:
  type: snowflake
  account: ${SNOWFLAKE_ACCOUNT}
  username: ${SNOWFLAKE_USER}
  password: ${SNOWFLAKE_PASSWORD}      # 可配置 private_key，或在没有 private_key 时 password 和 private_key_file 二选一
  # private_key: ${SNOWFLAKE_PRIVATE_KEY}
  # private_key_file: ${SNOWFLAKE_PRIVATE_KEY_FILE}
  # private_key_file_pwd: ${SNOWFLAKE_PRIVATE_KEY_FILE_PWD}  # 可选
  database: ${SNOWFLAKE_DATABASE}    # 可选
  schema: ${SNOWFLAKE_SCHEMA}        # 可选
  warehouse: ${SNOWFLAKE_WAREHOUSE}
  role: ${SNOWFLAKE_ROLE}            # 可选
  default: true                      # 可选：设为默认数据库

Snowflake 支持密码认证和 key-pair 认证。托管/SaaS 场景推荐把 PEM 私钥作为 secret 配置到 private_key； 本地或 CI 已有私钥文件时可以使用 private_key_file。如果配置了 private_key，它会优先于 private_key_file 和 password；没有 private_key 时，password 和 private_key_file 必须二选一。 私钥加密时再配置 private_key_file_pwd；适配器内部会使用 Snowflake JWT 认证。

Snowflake 使用 database + schema 命名空间。Snowflake 不要配置 catalog；catalog 过滤只适用于 StarRocks 等支持 catalog 的引擎。

MaxCompute

my_maxcompute:
  type: maxcompute
  database: ${MAXCOMPUTE_PROJECT}
  endpoint: ${MAXCOMPUTE_ENDPOINT}
  access_key_id: ${MAXCOMPUTE_ACCESS_KEY_ID}
  access_key_secret: ${MAXCOMPUTE_ACCESS_KEY_SECRET}
  # schema: default               # 可选；仅三层模型项目使用
  namespace_mode: auto            # auto、two_level 或 three_level
  # quota_name: ${MAXCOMPUTE_QUOTA_NAME}
  # tunnel_endpoint: ${MAXCOMPUTE_TUNNEL_ENDPOINT}
  # query_timeout_seconds: 600

database 对应 MaxCompute 项目。两层模型不要配置 schema；开启 schema 的项目未配置时默认使用 default。datasource 不使用 catalog，且查询范围保持在配置的项目内。命名空间与 endpoint 说明见 数据库适配器。

StarRocks

my_starrocks:
  type: starrocks
  host: ${STARROCKS_HOST}
  port: ${STARROCKS_PORT}
  username: ${STARROCKS_USER}
  password: ${STARROCKS_PASSWORD}
  database: ${STARROCKS_DATABASE}
  catalog: ${STARROCKS_CATALOG}      # 可选

SQLite

my_sqlite:
  type: sqlite
  uri: sqlite:////Users/xxx/data/orders.db

DuckDB

my_duckdb:
  type: duckdb
  uri: duckdb:////Users/xxx/data/analytics.duckdb

MySQL

my_mysql:
  type: mysql
  host: localhost
  port: 3306
  username: ${MYSQL_USER}
  password: ${MYSQL_PASSWORD}
  database: analytics

PostgreSQL

my_postgresql:
  type: postgresql
  host: localhost
  port: 5432
  username: ${POSTGRES_USER}
  password: ${POSTGRES_PASSWORD}
  database: analytics

Apache Doris

my_doris:
  type: doris
  host: ${DORIS_HOST}
  port: 9030                    # FE 查询端口（MySQL 协议）
  username: ${DORIS_USER}
  password: ${DORIS_PASSWORD}
  database: ${DORIS_DATABASE}
  catalog: internal             # 可选，默认为 internal

TiDB

my_tidb:
  type: tidb
  host: ${TIDB_HOST}
  port: 4000                    # TiDB 自身默认端口，不是 MySQL 的 3306
  username: ${TIDB_USER}
  password: ${TIDB_PASSWORD}
  database: ${TIDB_DATABASE}

Hologres

my_hologres:
  type: hologres
  host: ${HOLOGRES_ENDPOINT}    # 控制台 endpoint，hostname 或 hostname:port
  port: 80
  username: ${HOLOGRES_ACCESS_KEY_ID}
  password: ${HOLOGRES_ACCESS_KEY_SECRET}
  database: ${HOLOGRES_DATABASE}
  schema: public                # 可选
  sslmode: prefer               # 可选

GaussDB / openGauss

my_gaussdb:
  type: gaussdb
  host: ${GAUSSDB_HOST}
  port: 5432
  username: ${GAUSSDB_USER}
  password: ${GAUSSDB_PASSWORD}
  database: postgres
  schema: public
  # driver: pg8000              # 可选；省略时使用平台默认值
  sslmode: verify-ca             # 生产环境基线配置
  sslrootcert: /etc/datus/certs/gaussdb-ca.pem

支持的驱动为 gaussdb（Linux；sha256/md5/sm3 认证）、pg8000（Linux/macOS；sha256/md5）和 仅支持 md5 的 psycopg2 兜底方案。TLS 模式支持 disable、allow、prefer（默认）、require、 verify-ca 和 verify-full。生产环境应以 verify-ca 配合 sslrootcert 提供服务端 CA 为基线；当配置的 hostname 能保证与证书匹配时，使用 verify-full 可提供更严格的 hostname 验证，否则继续使用 verify-ca。当前仅支持单向 TLS，不支持客户端证书双向认证。 模式、平台、认证方式及 A/B/PG 兼容模式详情见数据库适配器。

路径模式（批量发现多个文件）

使用 glob 模式自动发现数据库文件：

bird_benchmark:
  type: sqlite
  path_pattern: benchmark/bird/dev_20240627/dev_databases/**/*.sqlite

常见模式包括：*.sqlite、**/*.sqlite、data/2024/*.db

配置参数

通用参数

参数	是否必填	说明
type	是	数据库类型，例如 sqlite、duckdb、snowflake、starrocks、mysql、postgresql、doris、hologres 等
default	否	设为 true 后作为默认数据库
uri	文件型数据库必填	SQLite / DuckDB 的连接 URI
host	服务型数据库必填	数据库主机地址
port	服务型数据库必填	数据库端口
username	服务型数据库必填	用户名
password	服务型数据库必填	密码
database	否	数据库名

数据库特定参数

• Snowflake：account、warehouse、role、schema
• StarRocks：catalog
• SQLite/DuckDB：path_pattern 用于批量发现数据库文件
• MySQL/PostgreSQL：host、port、username、password、database
• Apache Doris：catalog（默认为 internal）
• Hologres：schema、sslmode；access_key_id/access_key_secret 可作为 username/password 的别名
• GaussDB/openGauss：schema、driver、sslmode、sslrootcert

管理数据库

交互式配置

使用 datus-agent configure 交互式添加、删除或管理数据库：

datus-agent configure

它会先展示当前模型与数据库，然后提供菜单：

Current Databases:
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name         ┃ Type      ┃ Connection              ┃ Default ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ demo         │ duckdb    │ ./demo.duckdb           │ *       │
│ prod_sf      │ snowflake │ account=my_account      │         │
└──────────────┴───────────┴─────────────────────────┴─────────┘

What would you like to do?
  → [add_database] Add a database
    [delete_database] Delete a database
    [done] Done

当你选择未安装的数据库类型（例如 snowflake、mysql）时，适配器插件会自动安装。

CLI 命令

# 列出所有数据库
datus-agent service list

# 交互式添加数据库
datus-agent service add

# 交互式删除数据库
datus-agent service delete

指定自定义配置文件

datus-agent service list --config /path/to/agent.yml
datus-agent configure --config /path/to/agent.yml

默认数据库选择

运行 CLI 命令时，可以显式指定要使用的数据库：

datus-cli --datasource my_duckdb
datus-agent run --datasource my_snowflake --task "..." --task_db_name ANALYTICS

如果没有指定 --datasource：

1. 若某个数据库设置了 default: true，则自动使用它
2. 若只配置了一个数据库，则自动使用该数据库
3. 若配置了多个数据库且都未设置默认值，则展示可选列表

安全建议

凭证管理

# 推荐：使用环境变量
username: ${DB_USERNAME}
password: ${DB_PASSWORD}

# 不推荐：直接硬编码凭证
username: "actual_username"
password: "actual_password"

相关文档

• 数据库适配器 - 安装 MySQL、Snowflake、StarRocks 等插件适配器
• 语义层配置 - 配置语义适配器
• BI 平台配置 - 配置 Superset 或 Grafana
• 调度器配置 - 配置 Airflow 等调度器
• CLI 命令 - 查看 configure、init、service 等完整命令说明