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 and its relatives: Supabase, Amazon RDS and Aurora, Neon, and CockroachDB;
• MySQL and its relatives: MariaDB, PlanetScale and TiDB;
• SQL Server and Azure SQL, with a SQL login;
• Amazon Redshift, with a password;
• Snowflake, with a password, a key pair or a programmatic access token;
• Databricks SQL, with a personal access token.

Signing in with Microsoft Entra ID, IAM, Databricks OAuth or a client certificate isn’t supported yet. If you paste such a connection string, the Data Studio says so and which sign-in to use instead.

Your database has to be reachable from the internet, or through your Tenant network if Scavenger AI set one up for your company’s private network.

The connection string

Paste it exactly as your database’s console, its docs or another tool shows it. We read it and recognise the database. These forms work:

• a URL, such as postgresql://user:password@db.example.com:5432/sales?sslmode=require, also with postgres://, sqlserver:// or a vendor’s own scheme;
• a JDBC URL, such as jdbc:postgresql://…, jdbc:sqlserver://…;databaseName=sales;encrypt=true, jdbc:redshift://… or jdbc:snowflake://…;
• an ADO.NET or ODBC string, such as the one the Azure portal shows: Server=tcp:….database.windows.net,1433;Initial Catalog=sales;User ID=…;Password=…;Encrypt=True;;
• libpq’s key=value form: host=db.example.com dbname=sales user=agent password=… sslmode=require;
• a psql, mysql, mariadb or sqlcmd command line, as you’d type it.

A password may hold any character, such as @, /, ?, #, :, %, + or a space, whether it’s percent-encoded or not.

The Examples for each database in the dialog show one connection string per database.

If a connection string fits more than one database, such as a postgresql:// URL on port 26257, which CockroachDB and PostgreSQL both use, the Data Studio asks which one you mean. After a test it shows the database and host it recognised; if the database is wrong, correct it there and the connection is tested again.

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

What it refuses, and why

The Data Studio refuses a connection string it can’t use, and says why in its own words, never by guessing. For example:

• a placeholder that is still in it, such as [YOUR-PASSWORD]: replace it with the real value;
• a socket, a pipe or a file on your own machine, or an option that reads or writes a file, such as sslkey or passfile: we can’t reach your machine, so paste a host name and port, and a certificate as text;
• a value an option can’t have, such as sslmode=verify-all: the message lists the values it takes;
• several hosts in one string: paste one, such as the cluster’s endpoint;
• a sign-in that isn’t supported yet.

Add a Data Source

1. Open the Data Studio from the app switcher. It opens on Data Sources. Select Add Data Source.
2. Enter a name, and paste the connection string.
3. If your database’s TLS certificate is signed by a certificate authority of its own, paste that CA certificate (see below).
4. Select Test connection. We read the connection string, sign in, check that the database exists, and run SELECT 1. Only then does the test say Connected.
5. Choose where the connection string may be used (see below). If your Tenant has a Tenant network, choose the Network too: Public internet, or Private network for a database in your private network. Optionally add a description for the agent: what the database holds, so the agent knows when to use it.
6. Select Add Data Source.

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

When the test fails

The dialog names the step that failed, with the database’s own message, never your password:

• The address failed: the host doesn’t exist, or it isn’t on the public internet. We never connect to private, loopback, link-local or cloud metadata addresses.
• The network failed: nothing answered in time. Check the port, and that our addresses are allowed on your firewall.
• The sign-in failed: the database refused the user, the password or the token.
• TLS failed: the encrypted connection couldn’t be set up or its certificate couldn’t be verified. Check the certificate, or add the database’s CA certificate.
• The database failed: it doesn’t exist, or it answered with an error.

Encrypt the connection

If a connection string doesn’t ask for TLS, the Data Studio warns you: data would travel over the internet in plain text. Add the option your database uses, such as sslmode=require for PostgreSQL, ssl-mode=REQUIRED for MySQL or Encrypt=True for SQL Server. We understand each driver’s spelling, such as ssl=true, useSSL=true or sslMode=VerifyFull, whichever tool it was written for. Snowflake and Databricks always encrypt.

To have the database’s certificate verified as well, use sslmode=verify-full or ssl-mode=VERIFY_IDENTITY. We trust the public certificate authorities and Amazon RDS’s, so Amazon RDS, Aurora and Redshift pass without anything to add.

The CA certificate

Some databases have a certificate signed by a certificate authority of their own: Supabase, CockroachDB Cloud, or a server you run yourself. To have it verified, download that CA’s certificate from your provider and paste it into CA certificate, as the text that starts with -----BEGIN CERTIFICATE-----. It is stored encrypted, like the connection string.

Where the connection string may be used

• Query tool only (the default): the agent queries the database through our query service, and the connection string never leaves it.
• Also in the Sandbox: code the agent runs can connect to the database directly, for large extracts. The code then holds the connection string and can use it like any database client, within what the database user may do. The Data Studio warns you before you choose it.

Also in the Sandbox

Every user with access to the Data Source gets its connection string in the Sandbox of their Conversations, and the agent knows by name which Data Sources are there. What the code prints shows the connection string and its password as hidden credential, and neither appears in the Conversation or anywhere else we keep.

• Internet access is needed for a public Data Source. Code reaches your database over the internet, so a user without the Right “Sandbox has internet access” doesn’t get the connection string. The agent tells them so and queries the Data Source with the query tool instead. See Let the agent run code.
• Allow the Sandbox on your firewall. The code connects from the Sandbox’s own address, not from the query service’s addresses that the dialog lists.
• Changes reach running Sandboxes. When a user loses access to the Data Source, or its connection string changes, a Sandbox that holds the old one starts fresh at the next run of code, without it.
• A Data Source on the private network is reached from your Tenant network instead, where code has no internet access. See Use the private network in the Sandbox.
• Managed Databases stay with the query tool only.

Allow our addresses on your firewall

Queries to your database always come from the same IP addresses, which the dialog lists. Allow them on your database’s firewall. They don’t change with our releases, so your firewall rule keeps working.

Queries to a Data Source on the private network don’t come from these addresses: see Reach databases in your private network.

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.

Keep a Data Source current

If you have access to a Data Source and the Right “Create Data Sources and Managed Databases”, you manage it: the Data Studio shows Edit, Replace connection string and Delete under it. Everyone else sees it read-only.

Rename it and describe it for the agent

Select Edit to change its name and its description. The agent reads the description before it queries, so say what the database holds and when to use it.

Replace the connection string

When the database’s password changes, or it moves, select Replace connection string:

1. Paste the whole connection string again, with the new password. The old one can’t be shown, so there is nothing to edit.
2. If the Data Source trusts a CA certificate of its own, paste it again to keep it, or paste a new one. Left empty, the Data Source trusts the public certificate authorities and Amazon RDS’s only.
3. Select Test connection, then Replace.

The old connection string stays until the test passes, and the connection is tested again when you replace it. If the database has changed, the Data Studio shows the database and host it recognised now.

Delete a Data Source

Select Delete. The dialog says what happens before you confirm:

• the agent can no longer query it, and its connection string and CA certificate are deleted;
• Cards in Conversations stay readable, with the data they showed;
• Cards on Dashboards show “Data Source deleted” and can’t be refreshed;
• its Query Log is deleted;
• the database itself stays as it is.

Deleting can’t be undone. To use the database again, add it as a new Data Source.

A Managed Database’s Data Source shows only Edit: you delete it with its Managed Database, and its connection string is never replaced.

Read the Query Log

Every query the agent runs on a Data Source goes into its Query Log. If you may accept Context Change Requests on a Data Source, through a grant on it or the Right “Accept on all Data Sources”, the Data Studio shows Query Log under it, and its page has a Query Log tab. It lists the queries newest first, each with:

• the question the agent asked it for, and the query itself;
• whether it succeeded, succeeded with its rows cut, failed (with the kind of error), timed out or was cancelled;
• how long it took and who asked;
• the 👍 or 👎 that user gave the Turn, as it stands now: changed or removed Feedback shows at once.

Filter it by status, by who asked and by days, to find failing queries, for example. The Query Log never holds the rows a query returned. Each entry is deleted a year after the query. When a user leaves your Tenant, their entries stay, with “removed user” in place of their name. Deleting the Data Source deletes its Query Log.

Users without that Right on the Data Source can’t open its Query Log, even if they may query it.

Who sees a Data Source

Each Data Source has three Rights of its own:

• Access: the agent may query it for the user, and they see it in the Data Studio;
• Create Context Change Requests and Accept Context Change Requests: the Rights on the changes to what the agent knows about it. They give no access to its data.

When you add a Data Source, you get all three. A user holds a Right on a Data Source when it is granted to them, or to one of their Groups. Users with the Right “Access to all Data Sources” have access to every Data Source of your Tenant, future ones too, and users with “Accept on all Data Sources” hold the accept Right on every one, without access to the data. See Roles and Rights.

The Data Studio lists the Data Sources you hold a Right on. Select one to open its page, which shows what it is and your Rights on it.

Adding, editing, replacing the connection string of and deleting a Data Source are recorded in the Audit Log, never with the connection string. When a user leaves your Tenant, their access to Data Sources goes with them; the Data Sources they added stay.

Grant and revoke its Rights

Who manages a Data Source grants its Rights: users with the Right “Create Data Sources and Managed Databases” who have access to it. Users with the Right “Manage Roles and Rights” may grant the Rights on every Data Source, even one they hold no Right on, for example when whoever added it has left. They see every Data Source in the Data Studio.

1. In the Data Studio, select the Data Source, then the Access tab. It lists who holds which Right, Groups first.
2. To grant, choose a user or Group under Grant Rights, select the Rights, and select Grant.
3. To change what someone holds, select or clear a Right in their row. To revoke all of them, select the cross in their row.

A change takes effect at once: a user whose access you revoke loses it from their next request on. Every Right granted or revoked is recorded in the Audit Log.

The Users and Groups pages of the Admin App show the Rights each user and Group holds on single Data Sources, read-only.

The Data Studio shows in the app switcher to everyone who may create Data Sources or holds any Right on a Data Source.

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