Datasources¶

A datasource is a named database connection used by Datus for SQL execution, metadata discovery, and knowledge-base indexing. Configure datasources under agent.services.datasources in agent.yml.

agent:
  services:
    datasources:
      analytics:
        type: postgresql
        host: ${POSTGRES_HOST}
        port: 5432
        username: ${POSTGRES_USER}
        password: ${POSTGRES_PASSWORD}
        database: analytics
        schema: public
        default: true

Each key under datasources is the datasource name. Names may contain letters, numbers, underscores, and hyphens. Set default: true on at most one entry; when only one datasource exists, Datus selects it automatically.

Note

The configuration path remains agent.services.datasources. Configure semantic adapters under Adapters, and prefer plugins for integrations such as Airflow.

Choose a datasource¶

SQLite and DuckDB are built into Datus. Every other datasource is provided by an independently installable datus-<type> adapter. Datus can install a missing adapter when you add the datasource with /datasource; you can also install the package explicitly.

Datasource	`type`	Package	Namespace
SQLite	`sqlite`	built in	database file → table
DuckDB	`duckdb`	built in	database → schema → table
MySQL	`mysql`	`datus-mysql`	database → table
PostgreSQL	`postgresql`	`datus-postgresql`	database → schema → table
Greenplum	`greenplum`	`datus-greenplum`	database → schema → table
Amazon Redshift	`redshift`	`datus-redshift`	database → schema → table
Snowflake	`snowflake`	`datus-snowflake`	database → schema → table
Google BigQuery	`bigquery`	`datus-bigquery`	project → dataset → table
StarRocks	`starrocks`	`datus-starrocks`	catalog → database → table
Apache Doris	`doris`	`datus-doris`	catalog → database → table
TiDB	`tidb`	`datus-tidb`	database → table
ClickHouse	`clickhouse`	`datus-clickhouse`	database → table
Trino	`trino`	`datus-trino`	catalog → schema → table
Hive	`hive`	`datus-hive`	database → table
Spark SQL	`spark`	`datus-spark`	database → table
ClickZetta	`clickzetta`	`datus-clickzetta`	instance/workspace → schema → table
Hologres	`hologres`	`datus-hologres`	database → schema → table
MaxCompute	`maxcompute`	`datus-maxcompute`	project → optional schema → table
Oracle	`oracle`	`datus-oracle`	schema → table
GaussDB / openGauss	`gaussdb`	`datus-gaussdb`	database → schema → table
GaussDB(DWS)	`dws`	`datus-dws`	database → schema → table

Common profile keys¶

Each datasource page documents only its type-specific connection keys. The following profile keys are handled by Datus and apply to every datasource:

Key	Type	Required	Default	Notes
`type`	string	yes	—	Adapter type from the table above.
`default`	boolean	no	`false`	Marks this entry as the default datasource.

Adapter models reject unknown keys, so copy the field names exactly. Use environment variables for credentials:

username: ${DB_USERNAME}
password: ${DB_PASSWORD}

${NAME:-fallback} supplies a fallback. A missing ${NAME} expands to a visible missing-value marker and the connection will fail rather than silently using an empty credential.

File datasource patterns¶

SQLite and DuckDB can bind one datasource to several files with path_pattern instead of uri:

agent:
  services:
    datasources:
      benchmark:
        type: sqlite
        path_pattern: benchmark/databases/**/*.sqlite
        database: california_schools  # optional initial file stem

The matched files become databases within one datasource. Datus skips the entry at startup when the pattern matches no files.

Add, test, and select a datasource¶

The recommended path is the interactive datasource manager:

datus

Run /datasource in the CLI. Adding or editing an entry validates its fields, installs a missing adapter, tests connectivity, and writes the result to the active agent.yml selected by --config or the normal configuration search order. Use /datasource <name> to switch the current session.

For a manually edited file, start Datus with the target entry. Connector construction and the initial metadata load surface configuration, network, and authentication failures:

datus --config conf/agent.yml --datasource analytics

Project-specific selection belongs in .datus/config.yml:

default_datasource: analytics

Troubleshooting¶

Symptom	Cause and fix
`Unsupported value ... for field datasource`	The selected name is not a key under `agent.services.datasources`. Check spelling and the active config file.
Adapter import or installation error	Install the package shown in the datasource's page into the same Python environment as `datus`.
Unknown or extra field	The installed adapter validates its own schema. Remove the field or use the exact key documented on that datasource page.
Connection succeeds but objects are missing	Check the adapter's namespace fields (`catalog`, `database`, `schema`, or `schema_name`) and the database user's grants.
Credential appears literally as `<MISSING:...>`	Export the referenced environment variable before starting Datus.