Add a database

Target Audience: Non technical users

Goal

Connect a PostgreSQL, MySQL, ClickHouse, Snowflake, Oracle, or Google BigQuery database/warehouse to Toucan.ai to enable metadata analysis and chart creation.

---

Prerequisites

• A verified Toucan.ai account.

• An active organization.

• Valid credentials/connection details depending on the selected connector:

  • PostgreSQL/MySQL: Host, Database Name, Username, Password, Port, and SSL settings.

  • ClickHouse: Host, Username, Password (optional), Port, and TLS setting.

  • Snowflake: Account, User, Private Key (PEM), Warehouse, Database, and optional Role/Schema/Passphrase.

  • Oracle: Host, Port, User, Password, and Service Name (plus a TLS wallet ZIP when your database requires TLS).

  • BigQuery: A Google service account credentials JSON file.

• Network access granted to Toucan.ai static IPs (see Supported Databases).

---

Steps

1. Navigate to the Database Section

• Click the Database tab from the Toucan.ai home page.

• View the list of currently connected databases.

2. Initialize the Connection

• Click the Add a database button in the top-right corner.

• Select a connector from the available list (PostgreSQL, Google BigQuery, MySQL, ClickHouse, Snowflake, Oracle).

3. Input Connection Details

• Enter a Name to identify the connection internally.

• Then provide the details required by your connector:

PostgreSQL

• Host address (e.g., database.mycompany.com)

• Port (default: 5432)

• Database name (e.g., analytics)

• Username and Password

• SSL toggle based on your security requirements

BigQuery

• Upload your Google service account credentials JSON file (credentials format depends on your service account)

• The form will load fields such as project_id, client_email, and the private key from the JSON

If you need to review or edit values, you can open View raw credentials (collapsible section) inside the form.

MySQL

• Host address

• Port (default: 3306)

• User and Password

• Charset

• Database name

• SSL Mode

• If SSL Mode is enabled, fill in SSL CA, SSL Cert, and SSL Key.

ClickHouse

• Host address (for example hostname.clickhouse.cloud)

• Port (default: 9000)

• User

• Password (optional, depending on your ClickHouse setup)

• TLS toggle

Snowflake

• Account (for example xy12345.us-east-1)

• User

• Warehouse (for example COMPUTE_WH)

• Database

• Schema (optional)

• Role (optional)

• Private key (PEM)

• Private key passphrase (optional)

Oracle

• Host address (e.g. db.example.com, or your cloud provider’s hostname)

• Port (default 1521; TLS setups often use a different port—use the value from your provider)

• User

• Password

• Service name (e.g. ORCL or the service name from your connection details)

• TLS wallet (ZIP) — only when your database requires TLS; upload the wallet archive as provided by your vendor (do not unzip it first)

Oracle TLS wallet: For managed Oracle databases that require TLS, download the wallet from your provider’s console (e.g. Autonomous Database → Database connection → download wallet), then upload that ZIP in the form. Toucan.ai accepts ZIP files up to 500 KB with wallet files at the archive root or in a single folder. Not supported: pasting files individually, archives larger than 500 KB, deeply nested folder layouts, or relying on tnsnames.ora instead of filling Host, Port, and Service name in the form.

4. Validate and Save

• Click Test Connection to verify that the credentials and network settings are valid.

• Wait for the success notification.

• Click Connect to save the configuration to your organization.

Constraint: If the test fails, verify that Toucan.ai IP(s) are allow-listed in your firewall. The UI will display an IP under IP Whitelist, and Toucan.ai also publishes the static IP 51.15.216.216 in its documentation.

---

Conclusion

The database is now connected and visible in your organization's database list. You may proceed to analyze the data with AI to generate metadata descriptions.

Suggested Next Steps: How-to: Analyse your database with AI