# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-v3.toucantoco.com/data-management-in-datahub/datasources-in-toucan/managing-connectors/setting-up-a-connector/database-and-data-warehouse-connectors/setting-up-a-clickhouse-connector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.