'%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M0%2062.3176C0%2027.9001%2027.8995%200.00181961%2062.3134%200.00181961L62.3999%2062.2311C62.3999%2096.6462%2034.5004%20124.544%200.0852901%20124.544'%20fill='%233A3D3C'/%3e%3c/g%3e%3cpath%20d='M62.3994%2062.2461V0C96.8133%200%20124.713%2027.8982%20124.713%2062.3158'%20fill='url(%23paint0_linear_6331_3458)'/%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M45.617%2026.2827C47.7276%2026.2827%2049.4382%2027.9933%2049.4382%2030.1052C49.4382%2032.2146%2047.7276%2033.9252%2045.617%2033.9252C43.5064%2033.9252%2041.7958%2032.2146%2041.7958%2030.1052C41.7958%2027.9933%2043.5064%2026.2827%2045.617%2026.2827Z'%20fill='%23F9F6EF'/%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M45.6168%2045.2338C37.2596%2045.2338%2030.4857%2038.461%2030.4857%2030.1038C30.4857%2021.7454%2037.2596%2014.9702%2045.6168%2014.9702C53.9753%2014.9702%2060.7492%2021.7454%2060.7492%2030.1038C60.7492%2038.461%2053.9753%2045.2338%2045.6168%2045.2338ZM45.6168%2012.6686C35.9875%2012.6686%2028.1816%2020.4744%2028.1816%2030.1038C28.1816%2039.7308%2035.9875%2047.5378%2045.6168%2047.5378C55.245%2047.5378%2063.0508%2039.7308%2063.0508%2030.1038C63.0508%2020.4744%2055.245%2012.6686%2045.6168%2012.6686Z'%20fill='%23FECE01'/%3e%3cdefs%3e%3clinearGradient%20id='paint0_linear_6331_3458'%20x1='62.2719'%20y1='4.01754'%20x2='108.703'%20y2='70.5262'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20stop-color='%239ED5CB'/%3e%3cstop%20offset='1'%20stop-color='%23FCE18E'/%3e%3c/linearGradient%3e%3c/defs%3e%3c/svg%3e)
Connection concepts and credentials security
Target Audience: Makers, developers, and security reviewers who need to understand what a database connection is in Toucan AI and how credentials are protected.
TL;DR
- A datasource is the configured link between Toucan AI and an external database or warehouse.
- Toucan AI uses that connection for read-only queries: schema discovery, previews, AI analysis, charts, and embedded analytics.
- Your business data stays in your database. Toucan AI does not copy your warehouse into a separate data lake.
- Connection credentials (passwords, keys, service-account secrets) are encrypted at rest on the platform and masked in the UI and API when you view or edit a connection.
- You remain responsible for who can create or edit connections, for using read-only database users, and for network allow-listing.
When to use this
Use this page before or while connecting a database, or when evaluating how Toucan AI handles secrets. For step-by-step setup, see Add a database. For encryption details across the platform, see Secrets & encryption.
What a connection is
A connection stores everything Toucan AI needs to reach your source system:
| Element | Role |
|---|---|
| Datasource type | PostgreSQL, MySQL, Google BigQuery, ClickHouse, Snowflake, or Oracle |
| Connection details | Host, port, database/warehouse, project, account, etc. (depends on connector) |
| Credentials | Username/password, private key, service-account JSON, wallet, or similar secrets |
| Optional settings | SSL/TLS, schema/owner, role, charset, variables on supported fields |
Once connected, Toucan AI can:
- Discover schemas and tables (read-only)
- Preview sample rows (read-only)
- Propose semantic metadata (descriptions, display names, type casts) stored on the Toucan AI platform, never written back to your database
- Run queries that power charts, dashboards, and the AI assistant
Read-only access: Toucan AI does not write to your connected database. Prefer a dedicated read-only database user or service account with the minimum privileges required.
How data access works
Toucan AI separates platform data from your connected data:
| Zone | What it is | Where it lives |
|---|---|---|
| Platform | Accounts, dashboards, chart configs, AI history, encrypted connection credentials | Toucan AI database |
| Your database | Tables and rows (system of record) | Your infrastructure |
| Request-time results | Rows returned for a chart or AI answer | Processed per request — not stored as a bulk Toucan copy |
At query time, Toucan AI decrypts credentials server-side, runs the query against your database (with RLS/CLS when configured), and uses the result only for that operation.
See Data access boundaries and Data storage & retention.
Credentials security
Storage and encryption
When you save a connection:
- Secrets are encrypted at rest in the Toucan AI platform database.
- Only authorized server-side operations (for example test connection, schema discovery, chart queries) can decrypt them.
- Sensitive fields are masked in the product UI and API responses when you view or edit a connection.
- Encryption keys can be rotated; older ciphertext may be re-encrypted when credentials are accessed with a newer key.
Credentials remain stored until you delete the connection in the product.
What encryption does not cover
- Encryption does not replace access control inside your Toucan organization — anyone who can create or edit connections can supply or replace credentials.
- Variable fields on connection forms: default values stored on the platform for testing are not encrypted as secrets in the current version. Runtime values supplied via the embed token (user attributes) are protected because the token itself is encrypted (JWE) (see Variable management).
- Query result rows are not kept in a dedicated encrypted cache; protection relies on TLS (as configured), access control, and not persisting bulk copies of your data.
Network and transport
- Allow-list Toucan AI static IPs on your firewall or security group (see Supported databases).
- Prefer TLS-enabled database endpoints where your connector supports them (SSL mode, wallets, cloud-managed TLS, etc.).
Shared responsibilities
| Responsibility | You | Toucan AI |
|---|---|---|
| Create and manage database users / service accounts | ✅ | — |
| Use least-privilege, preferably read-only credentials | ✅ | — |
| Allow-list Toucan AI IPs / network path | ✅ | — |
| Restrict who can create or edit connections in Toucan | ✅ | — |
| Encrypt connection secrets at rest | — | ✅ |
| Mask secrets in UI/API | — | ✅ |
| Decrypt only for authorized server-side query paths | — | ✅ |
| Enforce RLS/CLS on queries | You define rules | Toucan enforces at query time |
Best practices
- Create a dedicated read-only account for Toucan AI; avoid shared admin credentials.
- Rotate database passwords and keys on a regular schedule; update the connection after rotation.
- Limit Toucan roles so only trusted admins manage connections.
- Never commit connection strings, passwords, private keys, or service-account JSON to source control.
- Use TLS wherever the connector supports it.
- After deleting a connection in Toucan, revoke or rotate the corresponding credentials on your side if they are no longer needed.
Related pages
- Supported databases — connectors and network requirements
- Add a database — setup steps per connector
- Data readiness requirements — prepare data before connecting
- Secrets & encryption — platform-wide secret handling
- Data storage & retention — what is persisted vs queried on demand
- Variable management — dynamic values on connection fields
Constraints
- Toucan AI performs read-only operations on connected databases.
- Connection secrets are encrypted at rest; organization role hygiene remains your control for who can manage them.
- Authentication formats differ by connector (password, PEM private key, service-account JSON, Oracle wallet, etc.).
- Network connectivity must be opened on the database side; failed allow-listing blocks Test Connection and queries.