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

# Clickhouse

> Learn how to connect Opal to Clickhouse to manage access.

<Note>
  **User matching**: Opal matches ClickHouse users to Opal accounts by email. If
  the user's email in Clickhouse does not match the user's email in Opal, the
  account will appear as unlinked and can be manually associated through
  Clickhouse.
</Note>

With Opal's ClickHouse integration:

* **Users** can request access to ClickHouse roles, databases, and tables directly from Opal, with time-limited grants that expire automatically
* **Admins** can import ClickHouse resources into Opal's catalog, configure reviewers, and see a full audit trail of who has access to what
* **Admins** can revoke access manually at any time — the change is applied immediately in ClickHouse

## Supported resources

| **Resource**        | **Read** | **Grant and revoke access** |
| ------------------- | -------- | --------------------------- |
| ClickHouse Database | ✔️       | ✔️                          |
| ClickHouse Table    | ✔️       | ✔️                          |
| ClickHouse Role     | ✔️       | ✔️                          |
| ClickHouse User     | ✔️       |                             |

## Requirements

To connect ClickHouse to Opal, you must first:

* Be an **Opal Admin**
* Have access to a running ClickHouse instance in ClickHouse Cloud
* Have credentials for a [ClickHouse admin](https://clickhouse.com/docs/cloud/security/common-access-management-queries#admin-user) user able to create new users and grant permissions

## 1. Create a service account in ClickHouse

Opal requires a dedicated service account in ClickHouse with read access to system tables and permission to manage grants.

In your ClickHouse SQL Console (or via `curl`), run:

```sql theme={null}
  -- Create the service user
  CREATE USER IF NOT EXISTS opal_service
      IDENTIFIED WITH sha256_password BY '<strong-password>';

  -- Grant read access to system tables
  GRANT SELECT ON system.users TO opal_service;
  GRANT SELECT ON system.roles TO opal_service;
  GRANT SELECT ON system.role_grants TO opal_service;
  GRANT SELECT ON system.grants TO opal_service;
  GRANT SELECT ON system.databases TO opal_service;
  GRANT SELECT ON system.tables TO opal_service;

  -- Grant access management permissions
  GRANT CURRENT GRANTS(ACCESS MANAGEMENT ON *.*) TO opal_service;
```

<Info>
  You must use `GRANT CURRENT GRANTS(ACCESS MANAGEMENT ON *.*)` instead of
  `GRANT ACCESS MANAGEMENT`. This is because the Cloud `default` user doesn't
  hold the full `ACCESS MANAGEMENT` bundle, so `CURRENT GRANTS` passes only the
  subset needed by Opal.
</Info>

## 2. Add Clickhouse to Opal

In Opal, go to **Inventory > + App**, then select **ClickHouse**.

Fill in the connection form using the following details.

| Field        | Where to find it                                   | Example                                 |
| ------------ | -------------------------------------------------- | --------------------------------------- |
| **Hostname** | ClickHouse Cloud → your service → Connect tab      | `abc123.us-east-1.aws.clickhouse.cloud` |
| **Port**     | Always `8443` on ClickHouse Cloud (HTTPS)          | `8443`                                  |
| **Use TLS**  | Always enabled on ClickHouse Cloud                 | -                                       |
| **Username** | The service account created in step 1              | `opal_service`                          |
| **Password** | The password set for the service account in step 1 |                                         |

Upon clicking **Create**, Opal will validate the connection by running a test query. If validation fails, verify that the hostname, port, and credentials are correct and that your IP is allowed in ClickHouse Cloud's network settings.

## 3. Import resources

After the connection is created, Opal will run an initial sync to discover your ClickHouse databases, tables, roles, and users. Go to **Assets** to see everything that was discovered.

To make a resource or role requestable, import them and configure reviewers and access policies as needed.

<Note>
  Only imported resources with “Allow Requests” toggled ON will appear in Opal's **Request Access** catalog.
</Note>