Connection to ClickHouse

To connect a ClickHouse database to the DQC Platform — both ClickHouse Cloud and self-hosted instances are supported — you provide a host, port, database name and credentials of a SQL user with read access. Each table in the database becomes available for data quality checks.

Add a ClickHouse connector

To begin:

Go to the Connectors > Data sources screen
Click the ClickHouse tile
Enter the connection parameters described below

Required connection information

Field	Example	Description
Name	`Marketing ClickHouse`	A custom name to identify this connector inside DQC
User	`dqc_reader`	ClickHouse user with read permissions on the target database
Password	`{your password here}`	Password of the ClickHouse user
Host	`dqc1xx99.eu-central-1.aws.clickhouse.cloud`	Hostname of the ClickHouse server. Bound to the connector and cannot be changed after creation.
Port	`8443`	HTTP(S) interface port. `8123` for plain HTTP, `8443` for HTTPS / ClickHouse Cloud. Bound to the connector.
Database	`default`	Name of the database to connect to. Defaults to `default`. Bound to the connector and cannot be changed after creation.
Secure connection	`✔`	Enables TLS for the connection. Required for ClickHouse Cloud and any HTTPS endpoint (port 8443). Bound to the connector.

ClickHouse Cloud vs. self-hosted

ClickHouse Cloud — host follows the pattern <id>.<region>.<provider>.clickhouse.cloud, port 8443, Secure connection enabled.
Self-hosted (HTTPS) — port 8443, Secure connection enabled. Make sure the certificate is trusted by DQC.
Self-hosted (plain HTTP) — port 8123, Secure connection disabled. Only suitable inside a private network.

Permissions and network

Create a dedicated read-only user (e.g. dqc_reader) with SELECT permission on the target database / tables
If your ClickHouse instance enforces IP allow-listing, whitelist the DQC platform's outbound IP
DQC validates the connection by listing tables — make sure the user has SHOW TABLES privileges

What gets imported

Every table the user can read in the configured database becomes a DQC table
Materialised views and dictionaries are included when readable
Database, host, port and TLS setting are bound to the cache and cannot be changed afterwards — create a new connector to point at a different host or database

Connect and assign permissions

After saving, DQC validates the credentials, lists the available tables and lets you pick which ones to expose. To control who can use the connector inside DQC, see Data source access permissions.

Troubleshooting

When DQC cannot connect to ClickHouse or load its tables, it shows the reason with a short fix and links to this section. Look up the beginning of the message:

Message in DQC	Likely cause	Fix
`Wrong password for user …`	Wrong password, or the user does not exist	Check user name and password
`Connection to …:… not possible. …`	Wrong host or port, or DNS cannot resolve the host	Use the HTTP(S) interface port (`8443` with Secure connection, `8123` without), not the native port `9000`
`Database … does not exist`	Wrong database name	Check the database name
`Unable to connect to ClickHouse database. Reason: … timed out`	The IP access list of ClickHouse Cloud or a firewall blocks the DQC IP address	Add the DQC Platform IP address to the IP access list, or connect through the DQC Proxy
`Unable to connect to ClickHouse database. Reason: … SSL …`	TLS setting and port do not match	Turn on Secure connection for port `8443`, turn it off for `8123`
`Unable to connect to ClickHouse database. Reason: … ACCESS_DENIED`	The user may not list or read the tables	Grant `SHOW TABLES` and `SELECT` on the database
`Could not connect to the data source. Check the connection details …`	DQC could not classify the error of the connection test	Check every field of the form, the network access and the permissions described above
`Table not accessible anymore …`	The table was renamed, moved or deleted, or the user lost access to it after the last sync	Restore the table or the access, then resync the connector

Synchronization failed: when a sync cannot connect, the connector shows Failed on the Data sources screen and the badge links to this section. Edit the connector and click Load tables or Save: DQC tests the connection again and shows the current reason.
Still stuck? Write to support@dqc.ai with the connector name, the time of the attempt and the full message.