# Supported databases

## Connect a Database or Data Warehouse

This guide explains how to connect a database or data warehouse to Toucan AI.\
A data connection is required before you can analyze data, create charts, or build dashboards.

***

### Prerequisites

* Access to a Toucan AI organization
* Network access from Toucan AI to your database or warehouse

<details>

<summary>Adding Toucan AI's static IP addresses to your allow-list</summary>

To ensure uninterrupted connectivity from your Toucan AI Cloud to your databases, please add our static IP address to the allow-list in your security group or firewall settings.

* EU IP: **51.15.216.216**

</details>

* Valid credentials for the target database
* Read-only access to the data (recommended)

***

### Access the Databases Page

1. Open the Toucan AI application.
2. From the main navigation, go to **Databases** (`/databases`).

You will see one of the following states:

* **A list of existing database connections**, if databases are already configured.
* **An empty state**, showing:
  * *“No databases added”*
  * *“Get started by connecting your first database”*

3. Click **Add a database** to start creating a new connection.

***

### Supported Databases

Toucan AI currently supports the following databases and warehouses:

* [PostgreSQL](#postgresql)
* [Google BigQuery](#google-bigquery)

Other connectors (MySQL, Redshift, Snowflake, ClickHouse) are not supported yet.

***

### Security and Network Configuration

#### Read-only Access (Recommended)

Toucan AI only needs to read data.\
We strongly recommend using a **read-only database user** to ensure no data can be modified.

Database-specific permission details are described in each connector section below.

#### Allow-list Toucan AI IP Addresses

If your database is protected by a firewall or IP allow-list, you must add Toucan AI’s static IP addresses to your configuration.

This step is required for Toucan AI to reach your database.

***

### PostgreSQL

Use this connector to connect to a PostgreSQL database.

#### Connection Fields

**Name**

An internal identifier for this database connection in Toucan AI.

**Connection settings**

* **Host**\
  The hostname or IP address where the PostgreSQL server is running.
* **Port**\
  The port used by the PostgreSQL server (default: `5432`).
* **Database**\
  The name of the PostgreSQL database to connect to.
* **User**\
  The database username used for authentication.
* **Password**\
  The password associated with the database user.
* **SSL**\
  Enable this option to encrypt the connection using SSL.

#### Complete the Connection

* Click **Test connection** to verify that Toucan AI can access the database.
* Click **Connect** to save and activate the connection.

If successful, a confirmation message appears and the database is added to the list.

***

### Google BigQuery

Use this connector to connect to Google BigQuery using a service account.

#### Connection Fields

**Name**

An internal identifier for this database connection in Toucan AI.

**Connection settings**

* **Service account (JSON key file)**\
  Upload the JSON credentials file for a Google Cloud service account.
* **View raw credentials**\
  Displays the parsed content of the uploaded JSON file for verification.

<details>

<summary>Create a Service Account</summary>

To connect BigQuery using a service account:

1. Create a service account in your Google Cloud project.\
   See Google documentation:\
   <https://docs.cloud.google.com/iam/docs/service-accounts-create>
2. Generate a JSON key for the service account and store it securely.

You need permissions in your Google Cloud project to create service accounts and keys.\
If you do not have these permissions, you must use an account managed by your GCP administrator.

#### Required Permissions

The service account must have the following roles:

* `roles/bigquery.dataViewer`\
  Allows reading data from BigQuery datasets.
* `roles/bigquery.jobUser`\
  Allows running queries in BigQuery.

If your data spans multiple BigQuery projects, grant `roles/bigquery.dataViewer` on each additional project.

</details>

#### Complete the Connection

1. Upload the service account JSON key file in the connection form.
2. Click **Connect** to finish the setup.

Once connected, the BigQuery project and datasets become available in Toucan AI.

***

### Not Yet Supported Connectors

The following databases are not supported yet:

* MySQL
* Amazon Redshift
* Snowflake
* ClickHouse

Support for these connectors is planned but not available at this time.

***

### Next Steps

Once your database is connected, you can:

* Browse schemas and tables
* Analyze your database with AI to generate metadata
* Create charts and dashboards using AI or manual configuration

Connecting a database is the first step in the Toucan AI workflow.
