Connect a Warehouse

A database connector is a set of query templates. Each template becomes one tool: an agent supplies the named parameters, the query runs read-only where the connection string lives, and the rows come back capped and masked. On the hosted service that place is your organization’s data-plane agent; Danube stores a reference to the connection string and never the string.

Engines

Engine	Driver in the agent image	Parameters	Read-only enforcement
`postgres`	`psycopg`	`%(name)s`	`BEGIN READ ONLY` plus `statement_timeout`
`redshift`	`psycopg` (Postgres protocol)	`%(name)s`	`BEGIN READ ONLY` plus `statement_timeout`
`mysql`	`pymysql`	`%(name)s`	`SET SESSION TRANSACTION READ ONLY` plus `max_execution_time`
`snowflake`	`snowflake-connector-python`	`%(name)s`	validator plus a read-only role; `STATEMENT_TIMEOUT_IN_SECONDS`
`bigquery`	`google-cloud-bigquery`	`@name`	validator plus a viewer role; job timeout
`databricks`	`databricks-sql-connector`	`:name`	validator plus a read-only grant; `STATEMENT_TIMEOUT`
`clickhouse`	`clickhouse-connect`	`%(name)s`	`readonly=2` plus `max_execution_time`
`trino`	`trino`	positional `?`	validator plus a read-only role; `query_max_execution_time`

You write every template the same way, with :name placeholders; the engine rewrites them per driver. Whatever the engine, the template is validated before it runs: one SELECT (or WITH ... SELECT), no comments, no second statement, no data-modifying keyword anywhere.

The connection reference

connection_ref names where the connection string is, in one of three forms:

Form	Resolved by
`env://ANALYTICS_DSN`	An environment variable on the data-plane agent’s host (or on a self-hosted control plane)
`vault://<mount>/<path>#<field>`	HashiCorp Vault KV v2, with the agent’s `VAULT_ADDR` and `VAULT_TOKEN`
`ANALYTICS_DSN`	A bare variable name, read as `env://ANALYTICS_DSN`

A value in that field (anything with a scheme, a host or a password) is refused at registration, by the dashboard and by the agent. What the variable holds, per engine:

Engine	The variable holds
`postgres`	`postgresql://user:password@host:5432/database`
`redshift`	`postgresql://user:password@cluster.region.redshift.amazonaws.com:5439/database`
`mysql`	`mysql://user:password@host:3306/database`, `?ssl=true` for TLS
`snowflake`	`snowflake://user:password@account/database/schema?warehouse=WH&role=ROLE` (`authenticator`, `token` and `private_key_file` pass through as query parameters)
`bigquery`	`bigquery://project` with default credentials on the host, `bigquery://project?credentials=/path/sa.json&location=EU`, or the path of a service-account JSON file
`databricks`	`databricks://token:TOKEN@workspace-host?http_path=/sql/1.0/warehouses/ID&catalog=main&schema=gold`
`clickhouse`	`https://user:password@host:8443/database` (`http://` for port 8123)
`trino`	`trino://user:password@host:443/catalog/schema` (`https` whenever a password is set)

A read-only role

The validator refuses writes, and Postgres, Redshift, MySQL and ClickHouse refuse them a second time on the connection. For the others the role is the second layer, so create one that can only read:

-- Postgres and Redshift
CREATE ROLE danube_reader LOGIN PASSWORD '...';
GRANT USAGE ON SCHEMA public TO danube_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO danube_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO danube_reader;

-- MySQL
CREATE USER 'danube_reader'@'%' IDENTIFIED BY '...';
GRANT SELECT ON shop.* TO 'danube_reader'@'%';

-- Snowflake
CREATE ROLE danube_reader;
GRANT USAGE ON WAREHOUSE wh TO ROLE danube_reader;
GRANT USAGE ON DATABASE analytics TO ROLE danube_reader;
GRANT USAGE ON ALL SCHEMAS IN DATABASE analytics TO ROLE danube_reader;
GRANT SELECT ON ALL TABLES IN DATABASE analytics TO ROLE danube_reader;
GRANT ROLE danube_reader TO USER danube;

-- Databricks (Unity Catalog)
GRANT USE CATALOG ON CATALOG main TO `danube-reader`;
GRANT USE SCHEMA, SELECT ON SCHEMA main.gold TO `danube-reader`;

-- ClickHouse
CREATE USER danube_reader IDENTIFIED BY '...' SETTINGS readonly = 2;
GRANT SELECT ON events.* TO danube_reader;

-- Trino (file-based access control: a rule for the user)
-- {"catalog": "hive", "user": "danube", "allow": "read-only"}

BigQuery: grant the service account roles/bigquery.dataViewer on the dataset and roles/bigquery.jobUser on the project.

Drivers in the agent image

The published image ships no database driver. Build your own from dataplane-agent/ with the engines you need, comma-separated:

docker build \
  --build-arg DANUBE_DB_ENGINES=postgres,snowflake \
  -t registry.example.com/danube-dataplane:0.3.0 \
  dataplane-agent

install_drivers.sh installs the pinned lines from requirements-drivers.txt for those engines and nothing else; an engine that is not built in fails a query with driver_missing. postgres and redshift share one driver.

Register

From Connector Builder, choose Database, the organization as owner (Runs inside your network is preselected), the engine, the reference and the queries. Preview import lists the tools it would create. Over the API:

curl -X POST "https://api.danubeai.com/v1/organizations/ORG_ID/services" \
  -H "danube-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "database",
    "visibility": "local_only",
    "database": {
      "name": "Warehouse",
      "description": "Read-only questions against the analytics warehouse",
      "db_type": "snowflake",
      "connection_ref": "env://ANALYTICS_DSN",
      "max_rows": 200,
      "queries": [
        {
          "name": "Customers by region",
          "description": "Customers in one region",
          "sql": "SELECT id, name, last_seen FROM customers WHERE region = :region ORDER BY last_seen DESC LIMIT 50",
          "parameters": [{"name": "region", "type": "string", "required": true}]
        }
      ]
    },
    "dry_run": true
  }'

Each query becomes a method: SQL tool at /queries/<slug> with the engine, the reference and the template in its metadata. A parameter used in the template and not declared is reported as a warning: an agent will not know to send it, and a call without it fails with bad_request: missing parameter.

Limits

One read statement per template. Comments, ;, dollar quotes and # are refused.
At most 1,000 rows per call (max_rows on the connector lowers it); truncated: true in the result says more matched.
A 30 second statement timeout by default (timeout_seconds, up to 55 inside the 60 second dispatch budget) and a 10 second connect timeout.
Cells are returned JSON-safe: dates as ISO 8601, decimals as numbers, bytes as base64. Credential-shaped values in rows are masked like any other tool result.
POST /v1/connectors/database/test, /introspect, /infer and /dry-run connect from the control plane and are for self-hosted deployments; for a local_only connector they answer 400 and the test is a tool run after registration.

Troubleshooting

`error_type`	`fault`	Meaning	Fix
`dataplane_required`	caller	A database tool that is not `local_only` on the hosted service	Register it for the organization as `local_only`
`no_dataplane_agent`	caller	No agent of the organization has polled in the last two minutes	Start or enroll an agent
`driver_missing`	caller	The agent image was built without this engine’s driver	Rebuild with `DANUBE_DB_ENGINES=<engine>`
`credential_reference_unresolved`	caller	The `env://` or `vault://` reference could not be resolved on the agent’s host	Set the variable on the agent, or check `VAULT_ADDR`, `VAULT_TOKEN` and the `#<field>` suffix
`auth_required`	caller	The database refused the credentials in the connection string	Check the user, password, role or token in the referenced value
`bad_request`	caller	The template failed validation, a placeholder had no value, or the engine rejected the query	Read the message; the engine’s own text is passed through
`timeout`	upstream	The statement timeout elapsed	Narrow the query or raise `timeout_seconds`
`connection_error`	upstream	The agent could not reach the database	Network path, TLS and the host in the connection string

Get Started

Organizations & Governance

Account

CLI

MCP Clients

SDKs & Integrations

Connect a Warehouse

Engines

The connection reference

A read-only role

Drivers in the agent image

Register

Limits

Troubleshooting

​Engines

​The connection reference

​A read-only role

​Drivers in the agent image

​Register

​Limits

​Troubleshooting

Engines

The connection reference

A read-only role

Drivers in the agent image

Register

Limits

Troubleshooting