# Add a ClickHouse connector

## Connector features

{% hint style="info" %}
This data connector is compatible with [NativeSQL](https://docs-v3.toucantoco.com/data-management-in-datahub/datasets-in-toucan/preparing-data/youprep-tm-native-sql) with our new data execution system
{% endhint %}

## Configuring a ClickHouse connection¶

You can use the Toucan ClickHouse connector to connect to your ClickHouse cluster with a basic authentication and access `tables` with a SQL query.

With this connection, you can fetch data from your ClickHouse to fill your charts and dashboards.

{% hint style="info" %}
**Changelog**

**September 25**\
\- This connector is supported by our new Data execution system
{% endhint %}

## Configuring a ClickHouse connection¶

Follow the steps described in [..](https://docs-v3.toucantoco.com/data-management-in-datahub/datasources-in-toucan/managing-connectors/setting-up-a-connector "mention"), choose `ClickHouse` and fill out the form with the following info:

<table><thead><tr><th>Field</th><th width="139.28515625">Format / Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>Name (mandatory)</td><td>String</td><td>Use it to identify your connection</td><td><em>my_clickhouse_connector</em></td></tr><tr><td>Host (mandatory)</td><td>String</td><td>could be an IP address or an hostname (e.g localhost)</td><td>"<em>db.example.com</em>" or "<em>192.168.1.100</em>"</td></tr><tr><td>Port (mandatory)</td><td>Integer</td><td>an integer, by default ClickHouse runs on port 9000</td><td><em>9000</em> (default)</td></tr><tr><td>User (mandatory)</td><td>String</td><td>Your login user</td><td><em>db_user</em></td></tr><tr><td>Password (mandatory)</td><td>String</td><td>Your login password (this value will be stored as a secret)</td><td><em>abcD1234</em></td></tr><tr><td>SSL_connection (optional)</td><td>Boolean</td><td>Allow to enable to enable SSL wrapped TCP connection, to enable if your Toucan workspace and your ClickHouse cluster are not in the same network</td><td></td></tr><tr><td>Retry Policy (optional)</td><td>Boolean</td><td><p><em>Boolean</em> allows to configure a retry policy if the connection is flaky.</p><ul><li>max attempts: maximum number of retries before giving up</li><li>max_delay: in seconds, above the connection is dropped</li><li>wait_time: time in seconds between each retry</li></ul></td><td></td></tr><tr><td>Slow Queries' Cache Expiration Time (optional)</td><td>Integer</td><td>Slow queries' cache expiration time in seconds</td><td></td></tr></tbody></table>

Click on the `SAVE` button to add the connection

{% hint style="success" %}
After successfully configuring the connector, you will be able to find it in the Connector section of the DataHub "Datasource" tab
{% endhint %}

## **Create a dataset from a ClickHouse connection**

{% hint style="info" %}
This data connector is only supported in [code/SQL mode](https://docs-v3.toucantoco.com/data-management-in-datahub/datasources-in-toucan/managing-connectors/create-a-dataset-from-a-connector/code-mode-and-single-mode)
{% endhint %}

Fill the mandatory fields:

* `Simple mode`
  * `Database`, a dropdown list of available databases
  * `Table`, a drop down list of available tables. The list will be populated only when a database is selected.
  * `columns`, a drop down list of available columns, we will select only the columns you checked
* Alternatively, in `SQL/code mode`
  * `Database`, a dropdown list of available databases
  * in the Query content section a SQL query field, where you can write your SQL query, if left blank a `select * from Table limit 50` will run

### How to troubleshoot a ClickHouse connection

If a warning icon appears after adding a ClickHouse connection, it indicates that Toucan cannot establish a stable connection to your ClickHouse cluster. In this case if you try to `create a new dataset from this connector`, you will not be able to pick a database from the dropdown (a `detailedHttpError` will be displayed when landing on the UI)

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-aacff4be2465846f4fea886393b6ee2271ea175f%2FCapture%20d%E2%80%99e%CC%81cran%202025-10-22%20a%CC%80%2011.26.26.png?alt=media" alt=""><figcaption></figcaption></figure>

**Mandatory fields**

Ensure all mandatory fields (`Name`, `Host`, `Port`, `User`, `Password`) are filled.

#### Network access

* Verify that the Host (IP or DNS) is **reachable** from Toucan IP and is not blocked by firewalls.

{% hint style="info" %}
Check our IP for our [Current Data Execution System](https://toucantoco.com/public-servers-list.html) and [New Data Execution System](https://docs-v3.toucantoco.com/new-data-execution-system#ip-allowlisting)
{% endhint %}

* Check that the `Port` (default is 9000) matches the **ClickHouse cluster's configuration** and is **open**.

#### Authentication

* Confirm `User` and `Password` are valid and have been granted connect permissions to the target database.

#### Other options

**Connect timeout**

* Adjust `Connect Timeout` if timeouts occur, especially in remote or slow network situations.

**Advanced troubleshooting**

* Review logs on PostgreSQL server for more detailed error information.
* For persistent issues, attempt to connect using CLI with the same parameters to isolate issues.