> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> Connect ClickHouse to ClarityQ

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

```sql theme={null}
-- Create the ClarityQ user
CREATE USER clarityq_user IDENTIFIED WITH sha256_password BY 'your_secure_password';
```

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:

```sql theme={null}
-- Grant read access to the databases ClarityQ should access
GRANT SELECT ON analytics.* TO clarityq_user;
GRANT SELECT ON events.* TO clarityq_user;

-- Or grant access to specific tables only
GRANT SELECT ON analytics.orders TO clarityq_user;

-- Grant query cancellation, so stopping a question stops the work on your server
GRANT SELECT(query_id, user, query) ON system.processes TO clarityq_user;
```

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)

<Warning>
  Set the **Port** to match the transport whenever you toggle **Connect over TLS**: ClickHouse serves TLS on `8443` and plaintext on `8123`.
</Warning>

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