Connect a ClickHouse Cloud Service

When you sign in to RunReveal with ClickHouse and pick a service, RunReveal prepares that service to store your logs. It creates a database, two roles, and the user RunReveal connects as, then saves the service as a destination. Resetting that user's password later from the destination settings repeats the same steps.

RunReveal runs those statements in the ClickHouse SQL console as you, the signed-in user. Your ClickHouse access on that service decides whether they can run. RunReveal checks for Admin data access first, and ClickHouse enforces the rest when the statements run.

Required access

You need Admin data access on the service you connect. In ClickHouse Cloud terms, that is SQL console admin: the same database access as the service's default user.

These ClickHouse roles have it by default:

• Admin, the organization role, on every service in the organization.
• Service Admin on every service, unless an organization admin has reduced its SQL console access.

Other roles don't. Service Reader has read-only data access. Service API Admin can manage services through the API but has no SQL console access. Member has no service access at all.

You don't need an organization-wide role. A custom role scoped to one service works, as long as it gives Admin data access on that service.

Grant access with a custom role

An organization admin can create a custom role, or edit an existing one, under Users and roles > Roles in the ClickHouse Cloud console. Give the role these three policies:

1. Organization: allow Access organization, so the user can sign in.
2. Service: select the service and allow View selected services, so the user can see it.
3. Data: select the service and choose Admin access.

Then assign the role to the user and have them connect the service again. Service permissions such as managing the service, scaling, or backups don't give database access. A role that has only those still can't connect a service.

ClickHouse applies Data policies only on services running ClickHouse 26.4 or later, with JWT authentication enabled for the SQL console. To check, open the service, go to Settings, and find the JWT authentication card in the Security section. The SQL Console toggle must be on. The organization Admin and Service Admin system roles don't depend on a Data policy.

See ClickHouse's Manage custom roles guide for the full steps.

Custom data access can block connecting

A Data policy with Custom access replaces Admin and Read-only access on its service. ClickHouse applies this to every member of the role, organization Admins included: their SQL console sessions on that service get only the privileges the custom grants list.

If the custom grants don't include everything RunReveal's setup needs, ClickHouse refuses it and connecting fails. To connect, remove that policy from your roles, or have someone without one connect the service. For a service in a warehouse, a Custom policy on the warehouse's primary service applies to every service in the warehouse.

Services in a warehouse

Services in the same ClickHouse Cloud warehouse share storage, so they also share databases and users. Preparing one service prepares all of them.

If your workspace already writes to one service in a warehouse, RunReveal won't connect another service from that warehouse. Doing so would reset the password of the user the first destination signs in as and break it.

If connecting fails

• "You need administrator access on service": none of your roles gives Admin data access on that service. A Read-only Data policy counts as none. Add a Data policy with Admin access, as described above, or have an admin connect the service.
• "ClickHouse denied administrator access on service": your roles look like they have Admin data access, but ClickHouse refused the setup. A deny rule or a Custom data policy on your roles is the usual cause.

Reference

• Console roles and permissions (ClickHouse docs)
• Manage custom roles (ClickHouse docs)
• Destinations