Skip to main content
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.
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

ResourceReadGrant 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 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: 
  -- 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;
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.

​
2. Add Clickhouse to Opal

In Opal, go to Inventory > + App, then select ClickHouse. Fill in the connection form using the following details.
FieldWhere to find itExample
HostnameClickHouse Cloud → your service → Connect tababc123.us-east-1.aws.clickhouse.cloud
PortAlways 8443 on ClickHouse Cloud (HTTPS)8443
Use TLSAlways enabled on ClickHouse Cloud-
UsernameThe service account created in step 1opal_service
PasswordThe 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.
Only imported resources with “Allow Requests” toggled ON will appear in Opal’s Request Access catalog.
Last modified on April 21, 2026