🔌Add a ClickHouse connector
Connector features
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.
Configuring a ClickHouse connection¶
Follow the steps described in Add a connector, choose ClickHouse
and fill out the form with the following info:
Name (mandatory)
String
Use it to identify your connection
my_clickhouse_connector
Host (mandatory)
String
could be an IP address or an hostname (e.g localhost)
"db.example.com" or "192.168.1.100"
Port (mandatory)
Integer
an integer, by default ClickHouse runs on port 9000
9000 (default)
User (mandatory)
String
Your login user
db_user
Password (mandatory)
String
Your login password (this value will be stored as a secret)
abcD1234
SSL_connection (optional)
Boolean
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
Retry Policy (optional)
Boolean
Boolean allows to configure a retry policy if the connection is flaky.
max attempts: maximum number of retries before giving up
max_delay: in seconds, above the connection is dropped
wait_time: time in seconds between each retry
Slow Queries' Cache Expiration Time (optional)
Integer
Slow queries' cache expiration time in seconds
Click on the SAVE
button to add the connection
After successfully configuring the connector, you will be able to find it in the Connector section of the DataHub "Datasource" tab
Create a dataset from a ClickHouse connection
Fill the mandatory fields:
Simple mode
Database
, a dropdown list of available databasesTable
, 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 databasesin 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)

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.
Check that the
Port
(default is 9000) matches the ClickHouse cluster's configuration and is open.
Authentication
Confirm
User
andPassword
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.
Last updated
Was this helpful?