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

# Connect ClickHouse

> Create a KUBIT user, roles and database in ClickHouse so Kubit queries your data in place.

Connect Kubit directly to ClickHouse so it queries your data in place. You create a dedicated user, roles and database for Kubit, grant read-only access to the tables it should see and allow Kubit's IP ranges. Nothing is copied out of your account.

## Before you start

* [ ] A ClickHouse user that can create users, roles and databases and grant privileges.
* [ ] The tables or views Kubit should query.
* [ ] A password for the Kubit user. The Kubit team generates a strong one and shares it with you.

## Steps

### 1. Create a user

In the [SQL Console](https://clickhouse.com/docs/en/integrations/sql-clients/sql-console), [create a user](https://clickhouse.com/docs/en/sql-reference/statements/create/user) named `KUBIT`. The Kubit team generates and shares a strong password to use here.

```sql theme={null}
CREATE USER KUBIT IDENTIFIED WITH sha256_password BY '*****';
```

### 2. Create roles

Create a read role and a write role.

```sql theme={null}
CREATE ROLE OR REPLACE KUBIT_R;
CREATE ROLE OR REPLACE KUBIT_W;
GRANT KUBIT_R TO KUBIT;
GRANT KUBIT_W TO KUBIT;
```

### 3. Create a database

[Create a database](https://clickhouse.com/docs/en/sql-reference/statements/create/database) named `KUBIT_DB`. Kubit uses it for small auxiliary tables and views.

```sql theme={null}
CREATE DATABASE KUBIT_DB;
```

### 4. Grant permissions

Grant `KUBIT_W` read and write access to `KUBIT_DB` so Kubit can create its auxiliary objects.

```sql theme={null}
GRANT SELECT,INSERT,ALTER,CREATE,DROP,TRUNCATE,SHOW ON KUBIT_DB.* TO KUBIT_W;
```

Grant `KUBIT_R` read-only (`SELECT`) access to `KUBIT_DB` and the tables or views Kubit should query.

```sql theme={null}
GRANT SELECT ON KUBIT_DB TO KUBIT_R;
GRANT SELECT ON INFORMATION_SCHEMA.* TO KUBIT_R;
GRANT SELECT ON system.parts TO KUBIT_R;
GRANT SELECT ON <your_table/or_view> TO KUBIT_R;
```

### 5. Allow Kubit's IP ranges

Add Kubit's [IP ranges](https://learn.kubit.ai/warehouses/connect/ip-allowlist.md) to your ClickHouse [IP filters](https://clickhouse.com/docs/en/cloud/security/setting-ip-filters).

![ClickHouse Cloud Service Settings page with Settings highlighted in the left nav and the IP access list link reading 1 specific location highlighted under Security.](https://mintlify.s3.us-west-1.amazonaws.com/kubit/images/warehouse/clickhouse-ip-access-list.png)

![ClickHouse Cloud IP Access List panel with Specific locations selected and the Add new IP button highlighted above the IP address or CIDR and Description fields.](https://mintlify.s3.us-west-1.amazonaws.com/kubit/images/warehouse/clickhouse-add-ip.png)

### 6. Split test and production workloads (optional)

As a best practice, create a second user, roles and service for development. Isolating development from production avoids accidental impact on live workloads.

### 7. Setting up the connection in Kubit

When configuring the JDBC URL in Kubit you will need to pass on the `&compress=0` parameter.

![ClickHouse Connection setup form](https://mintcdn.com/kubit/9i8QHxqek50tMBGy/images/warehouse/clickhouse.png?fit=max\&auto=format\&n=9i8QHxqek50tMBGy\&q=85\&s=c94e80ad565a4a53106c4c7f6dd701bc)

## Connection parameters

| Parameter | Required? | Notes |
| - | - | - |
| **Endpoint** | **Yes** | The cluster's endpoint |
| **User** | **Yes** | `KUBIT`, the user created above |
| **Password** | **Yes** | The password the Kubit team shared |
| **Database** | **Yes** | The database with the tables Kubit should query |
| JDBC parameter `compress` | **Yes** | `0` |

## If it fails

| Symptom | Cause | Fix |
| - | - | - |
| Connection times out | The IP access list blocks Kubit | Allow [Kubit's IP ranges](https://learn.kubit.ai/warehouses/connect/ip-allowlist.md) |
| `Code: 516. DB::Exception: KUBIT: Authentication failed: password is incorrect, or there is no user with such name. (AUTHENTICATION_FAILED)` | Wrong password or user | Reset the password with `ALTER USER KUBIT IDENTIFIED WITH sha256_password BY '<new-password>'` |
| `Code: 497. DB::Exception: KUBIT: Not enough privileges.` ending in `(ACCESS_DENIED)` | Missing `SELECT` grant | Run the **Grant permissions** step for each table or view |

## Next steps

* [Bring your own warehouse](https://learn.kubit.ai/warehouses/overview.md): how Kubit queries your warehouse in place.
* [Allow Kubit's IP ranges](https://learn.kubit.ai/warehouses/connect/ip-allowlist.md): the current ranges and how to keep firewall rules up to date.
* [Setup Kubit in the Modeler](https://learn.kubit.ai/warehouses/modeler.md): map your tables to fact tables, dimensions and subjects once the connection works.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.