Connect a Data Source

A Data Source is one connection to a database or data warehouse of your company, which the agent queries directly. You connect Data Sources in the Data Studio.

You need the Right “Create Data Sources and Managed Databases” to add one. Admins hold it. Without it, the Data Studio shows you the Data Sources you have a Right on, read-only.

Which databases you can connect

PostgreSQL, Amazon Redshift, MySQL and MariaDB, Microsoft SQL Server and Azure SQL, Snowflake, Google BigQuery, Databricks SQL and ClickHouse. Databases that speak PostgreSQL’s or MySQL’s protocol connect as those: choose PostgreSQL for CockroachDB, YugabyteDB, Neon, Supabase or TimescaleDB, and MySQL / MariaDB for TiDB, PlanetScale or SingleStore.

Your database has to be reachable from the internet. For a database in a private network, ask Scavenger AI to set up a Tenant network.

The connection string

Paste it as your database’s console or another tool shows it. Besides a URL such as postgresql://user:password@db.example.com:5432/sales?sslmode=require, the dialog takes:

• a JDBC URL, such as jdbc:postgresql://db.example.com:5432/sales?user=agent&password=…, jdbc:sqlserver://…;databaseName=sales;encrypt=true or jdbc:snowflake://…;
• for SQL Server and Azure SQL, the ADO.NET or ODBC string the Azure portal shows: Server=tcp:….database.windows.net,1433;Initial Catalog=sales;User ID=…;Password=…;Encrypt=True;;
• a password with characters such as @ or / that aren’t encoded.

Options it understands, beside each database’s own:

• Schema: ?schema=analytics (or currentSchema=) for PostgreSQL and Redshift sets the schema the agent works in. For Snowflake, it’s the part after the database: snowflake://…/SALES/ANALYTICS; for Databricks, ?catalog=…&schema=….
• TLS: each database’s own option, such as sslmode= for PostgreSQL or ssl_mode= for MySQL, and the spellings of other tools: ssl=true, useSSL=true or encrypt=true.
• Snowflake key pairs: ?authenticator=SNOWFLAKE_JWT&private_key=… with the private key in PEM or base64.

Options meant for another tool, such as connection_limit or pgbouncer, are ignored. So are options that name a file, such as a client certificate: no file of yours exists on our side.

Add a Data Source

1. Open the Data Studio from the app switcher. It opens on Data Sources. Select Add Data Source.
2. Choose the database, and enter its connection string. The dialog shows an example of the right shape for the database you chose.
3. Select Test connection. We connect to your database with the connection string and check that it answers.
4. Once the test says Connected., enter a name, and optionally a description for the agent: what the database holds, so the agent knows when to use it. Then select Add Data Source.

The connection is tested again when you add it. If you change the connection string or the database after a test, test again.

The connection string is stored encrypted. Nobody can see it again after you added the Data Source, not even you.

Allow our addresses on your firewall

Queries to your database always come from the same few IP addresses. The dialog lists them. Allow them on your database’s firewall, and the test can reach it.

Choose the database user with care

The agent can do whatever the database user in the connection string may do, including changing data. The platform adds no read-only limit of its own. If the agent should only read, use a database user that may only read. See Security.

When the test fails

The dialog says why, in plain words:

• This isn’t a connection string for the database you chose. Compare it with the example. A BigQuery connection string needs its service account key (credentials_base64).
• This address isn’t on the public internet. We connect only to public addresses.
• There is no such host. Check the address for typos.
• Nothing answered at this address. Check the port, and that our addresses are allowed on the firewall.
• The database didn’t answer in time.
• The database refused the user or password.
• The encrypted connection failed. Check the database’s certificate and TLS settings.
• The database answered with an error. Its own message follows, without your password.

Encrypt the connection

If the connection string doesn’t ask for TLS, the test warns you: data would travel over the internet in plain text. Add the option your database uses to require it: sslmode=require for PostgreSQL and Redshift, ssl_mode=REQUIRED for MySQL, encrypt=true for SQL Server and secure=true for ClickHouse. Snowflake, BigQuery and Databricks always encrypt.

To have the database’s certificate checked as well, use sslmode=verify-full for PostgreSQL or ssl_mode=VERIFY_IDENTITY for MySQL. We trust the public certificate authorities and Amazon RDS’s, so Amazon RDS and Aurora pass, as does any database whose certificate a public authority signed. A certificate of your own or of a provider’s own authority doesn’t, such as a self-signed one or Google Cloud SQL’s; use sslmode=require or ssl_mode=REQUIRED for it, which encrypts without checking the certificate.

Who sees a Data Source

When you add a Data Source, you get access to it and both Rights on its Context Change Requests. Users with the Right “Access to all Data Sources” see every Data Source of your Tenant, and so do users with “Accept on all Data Sources”, without access to the data. See Roles and Rights.

Adding a Data Source is recorded in the Audit Log with the database’s host, never the connection string.

Once a Data Source is added, users with access to it can ask the agent about its data.