Skip to main content

Connecting databases

Every conversation, notebook, and tile in QRY is bound to a datasource: a connection to a database your users will query. This page is for the admin who wires those connections up.

Supported databases​

Out of the box, in alphabetical order:

DatabaseDriver modelNotes
BigQuerysync (ThreadPoolExecutor)Service account JSON key
ClouderasyncImpala / Hive
DatabrickssyncPersonal access token or OAuth
Oraclesynccx_Oracle / oracledb
PostgreSQLasync (asyncpg)Native async; the only async driver
RedshiftsyncPostgres-compatible
Salesforceasync (httpx)REST API, not SQL
SAP HANAsyncSee SAP module integration for the extra module level
SnowflakesyncUsername/password or key-pair
SQL Serversyncpyodbc
StarburstsyncTrino-compatible

Sync drivers run via _run_sync() → ThreadPoolExecutor so the event loop stays non-blocking. PostgreSQL is the exception — it uses native asyncpg.

Where to configure​

Admin > Datasources. The list shows every configured datasource, its type, current connection state (connected / failed / unknown), and whether schema cache is fresh.

Adding a datasource​

Click + New Datasource. Pick the type, fill in the connection params (specific to each driver — see the next section), and click Test Connection. Green = ready; red = error message inline.

Click Save to commit. The datasource appears in users' Catalog as soon as you grant them access via RBAC.

Credential storage​

Connection secrets (passwords, JSON keys, OAuth tokens) are stored Fernet-encrypted (AES-128) in PostgreSQL. The Fernet key is derived from JWT_SECRET_KEY via SHA-256 — the settings module reads JWT_SECRET_KEY, not SECRET_KEY (this matters when bootstrapping).

Both clusters that share user data (e.g. puedata.com and ixen.ai, or DR replicas) must use the same JWT_SECRET_KEY so credentials remain decryptable across them. This was fixed in v0.85.3.

Per-driver config notes​

BigQuery​

  • Provide the service-account JSON key file or paste its contents.
  • Default location matters for query cost — set it to where your data lives.
  • The catalog level in QRY maps to a GCP project; schema maps to a BigQuery dataset.

Snowflake​

  • Username + password works; key-pair auth recommended for service accounts.
  • Warehouse, role, and default database go in the connection string. Without a warehouse, queries fail at runtime, not at connection time.

Databricks​

  • Use a personal access token at first; rotate to OAuth when production-ready.
  • The host is your workspace URL (e.g. https://adb-xxx.azuredatabricks.net).

SAP HANA​

  • The base connection is per host:port → SID. Schemas appear under the SID. For module-aware setups, add module configurations after the base datasource — see SAP module integration.

PostgreSQL​

  • Async driver; uses asyncpg's connection pool, not a thread pool.
  • For very high concurrency, tune pool_min_size / pool_max_size in the datasource's Advanced panel.

Salesforce​

  • REST-based, not SQL. QRY exposes Salesforce objects as if they were tables; SQL queries are translated to SOQL on the way in.

Schema cache​

Every datasource has a schema cache QRY uses to inject context into the LLM prompt. Refresh it after upstream schema changes (new tables, renamed columns):

  • Manually — Refresh schema button on the datasource details page.
  • Automatically — for some drivers, on a configurable cadence in Admin > Datasources > {datasource} > Schema refresh.

Refresh latency: typically under 60 seconds for standard schemas. SAP HANA full refresh against many modules can take several minutes.

Default query timeout​

30 seconds at the datasource level. Override per datasource if your workloads expect longer-running queries; users can also override per query in chat ("…with a 5-minute timeout").

For batch-style operations, prefer scheduled notebooks over chat — the chat UX assumes a short turnaround.

Common issues​

"Test Connection" returns Could not decrypt credentials. The cluster you're configuring on doesn't share JWT_SECRET_KEY with the cluster where the credentials were originally encrypted. Either re-enter credentials in this cluster or sync the secret. Both clusters must use the same key.

Queries time out at exactly 30s. Hitting the default datasource timeout. Bump it in the datasource's Advanced panel or filter the user's query to return less data.

Schema refresh takes several minutes. Common with SAP HANA against large landscapes. Either narrow the schema scope (per SAP module integration) or accept the slower refresh.

A user is granted the datasource but sees "Permission denied" on every query. Datasource access ≠ table access. Check RBAC at the schema or table level, plus any ABAC tag policies.

asyncpg>=0.31.0 import error after PG18 upgrade. PostgreSQL 18 requires asyncpg 0.31+. Bump the requirement and rebuild.

See also​

QRYA product of IXEN.