Skip to main content

​
Setup

​
Step 1: Create a dedicated user for ClarityQ

Connect to ClickHouse as an admin (a SQL client, or the SQL Console on ClickHouse Cloud) and create a service account:
On ClickHouse Cloud you can instead issue a JWT for the account and use Access Token authentication in Step 4.

​
Step 2: Grant database permissions

Configure the required permissions for ClarityQ to discover schemas, query data, and cancel its own queries:
ClickHouse filters its metadata views by these grants, so the account’s SELECT privileges determine which tables ClarityQ discovers.

​
Step 3: Configure network access

Ensure your ClickHouse server allows connections from the following ClarityQ IP addresses:
  • 44.218.213.75
  • 54.161.37.107
  • 54.208.212.67
On ClickHouse Cloud, select your service, go to Settings → Security and add these addresses to the IP access list. A new service starts with no addresses allowed, so ClarityQ reaches it once they are added. On a self-hosted server, allow inbound connections on the HTTP port (8443 or 8123) in your firewall or security group.

​
Step 4: Configure connection in ClarityQ

In the ClarityQ interface, fill out the connection form with the following fields:

​
Required Fields

  • Connection Name: Choose a name for this connection (e.g., “Production ClickHouse”)
  • Host: Your ClickHouse hostname (e.g., your-instance.clickhouse.cloud)
  • Port: 8443 (default, pre-filled) for TLS, 8123 for plaintext HTTP
  • Connect over TLS: Enabled (default). Disable it for a self-hosted server that serves the plaintext HTTP port on a private network
  • User: clarityq_user (the user you created in Step 1)

​
Optional Fields

  • Database: Leave empty to catalogue every database the user can read, or set it to confine ClarityQ to one database (e.g., analytics)

​
Authentication Type

Choose your authentication method using the toggle buttons: Password Authentication (default):
  • Password: Enter the password you set for clarityq_user
Access Token Authentication:
  • Access Token (JWT): Paste a JWT issued for clarityq_user (ClickHouse Cloud)
Set the Port to match the transport whenever you toggle Connect over TLS: ClickHouse serves TLS on 8443 and plaintext on 8123.

​
Step 5: Test the connection

Verify the connection in ClarityQ to ensure:
  • Authentication succeeds
  • Databases are visible to clarityq_user
  • Table metadata can be discovered
  • Query execution works correctly

​
Troubleshooting

​
Common connection issues

Connection times out
  • Add the ClarityQ IP addresses to the Cloud IP access list, firewall or security group (see Step 3)
  • Enter the hostname on its own, with the scheme and port left out of the field
Connection refused or TLS handshake error
  • Match the Port to the transport: 8443 with Connect over TLS enabled, 8123 with it disabled
  • Behind a proxy, use the port your ClickHouse URL uses
Database not found
  • Check the spelling of the Database field against the databases listed in the error message
  • Clear the field to catalogue every database the user can read
Database is not visible to the user
  • Grant the user access to it: GRANT SELECT ON your_database.* TO clarityq_user
User has no grants on any database
  • Grant SELECT on the databases ClarityQ should read (see Step 2)
Cannot read system.databases
  • Allow the user to read ClickHouse’s metadata views, which ClarityQ uses to discover schemas
Authentication failed
  • Re-enter the credential your server uses, either Password or Access Token — one credential is stored per connection
  • For access tokens, issue a fresh JWT if the previous one has expired
Tables missing after discovery
  • Clear the Database field to catalogue every database instead of the one you named
  • Grant the user SELECT on the missing databases
  • Query system and information_schema tables by name; they stay out of the catalog
Stopping a question leaves the query running
  • Grant SELECT(query_id, user, query) ON system.processes so ClarityQ can cancel with KILL QUERY (see Step 2)