Skip to main content

Connect an external database

Run a query against a database you operate, outside the platform. Its credentials are stored once as a connection secret, and the query references the secret's key — never the credentials directly.

Your database must be reachable from TaruviBase over the network and use one of the supported connectors. Run a simple test query before you build on a new connection.

Prerequisites​

  • A database reachable from the platform, and credentials for an account that can only read.
  • A connection secret holding those credentials, and a Console account on a non-production site. See who can manage queries.
Use a read-only credential

Use an account scoped to read-only access for the connection secret. Analytics refuses a query that writes when it is saved and runs SQL queries with a read-only session setting, but only a read-only database account is enforced by the database itself. Use one as a second layer of protection.

Procedure​

1. Choose the matching secret type​

The secret's type selects the connector — the piece of Analytics that knows how to talk to that kind of database. Pick the type matching your database from the connector reference — for example, analytics-postgres for PostgreSQL, analytics-elasticsearch for Elasticsearch. A secret of any other type is rejected when a query tries to use it.

2. Store the credentials as a connection secret​

Create the secret with the host, port, database or index, and read-only username and password your database requires. The secret type schema validates what can be stored, but it is not proof that every field is consumed by the connector:

  • SQL secret schemas accept options, but the SQL connector currently ignores it when building the SQLAlchemy URL.
  • The Elasticsearch schema accepts api_key, verify_certs, and ca_certs, but the connector currently ignores all three. It uses username/password and custom headers, and the Requests session keeps its own default TLS verification behavior.

Do not rely on an ignored field for authentication, TLS policy, or connection configuration.

Site-level secrets are available to every app in the site; app-level secrets are scoped to one app. Choose the narrower scope unless you specifically need to share the connection.

3. Create the query against the secret​

Select Analytics, then Create Query. Turn Internal Query off, and select your new secret under Database Connection — the list shows only secrets of an analytics type, each labelled with its connector. If none are available, Console says: No analytics connections found. Create a secret with an analytics- type first.*

Enter a Query Name, then write the statement under Query Text * for that connector's language: SQL for PostgreSQL, MySQL, Redshift, and ClickHouse; a JSON search body for Elasticsearch. Save with Create Query. The text is checked in that connector's own SQL dialect when it is saved.

4. Verify the connection​

Run the query once, supplying a value for any placeholder it contains. A connection failure and a query error both come back as HTTP 400; the database's message tells them apart — see Troubleshoot Analytics if the run fails and it is not obvious which of the two happened.

Verify​

The connection is working when the query saves without a secret-resolution error and returns rows on execution. See Run a query and read the results for reading what comes back, including the different result shape Elasticsearch aggregations produce.

Rotate credentials​

Update the connection secret's value with the new credentials; the query still points at the same key. Secret values are cached for up to one hour, so a query can occasionally keep using the old credential for up to an hour after you rotate it. Verify the new connection works, and keep the old credential valid for at least an hour before you retire it.

Troubleshoot​

If the secret is not found, is the wrong type, or the connection fails, see Troubleshoot Analytics.