Connect Your Own ClickHouse Database
A RunReveal workspace stores its logs in a ClickHouse database. When you set up a workspace on a deployment that isn't connected to ClickHouse Cloud, RunReveal asks for the connection details of a database user you've created for it. It tests the connection, saves it as the workspace's destination, and then runs its migrations.
Signed in with a ClickHouse Cloud account at app.runreveal.clickhouse.cloud? RunReveal creates this user for you. See Connect a ClickHouse Cloud Service.
Create the database user
RunReveal runs its migrations, manages roles and writes logs as one user. Create that user before you connect, from the ClickHouse SQL console or clickhouse-client, signed in as an admin user. On ClickHouse Cloud that is default.
Run these statements, replacing REDACTED with a password of your own. If you choose another user name, name the roles by appending _readwrite and _readonly to it.
ClickHouse Cloud requires a password of at least 12 characters with an uppercase letter, a lowercase letter, a digit and a special character.
What each grant is for:
| Grant | Why RunReveal needs it |
|---|---|
SELECT and INSERT on runreveal.*, with grant option | Read and write logs, and pass those privileges on to the roles RunReveal manages. The grant option covers the whole database, so a later table can be delegated too. |
ALTER, CREATE TABLE, CREATE VIEW, DROP TABLE, DROP VIEW on runreveal.* | Schema migrations. |
CREATE ROW POLICY, ALTER ROW POLICY, DROP ROW POLICY on runreveal.* | The row policies that isolate workspaces. |
SELECT on system.numbers and system.data_skipping_indices, with grant option | Passed on to the roles that run your queries. |
SELECT on system.mutations | Deleting a source waits on that table's mutations. |
CREATE ROLE, DROP ROLE, and ROLE ADMIN on *.* | Each workspace and custom role is a ClickHouse role. Creating a role does not let its creator grant it. |
S3 and CREATE TEMPORARY TABLE on *.*, with grant option | Passed on for storing the results of long-running queries. ClickHouse has no database-scoped form of these privileges. |
runreveal_readonly | Read access that stays inactive until RunReveal selects a role. Leave it off the default role. |
You can use a different database or user name. Use the same names when you connect.
Connect the database
After you name your workspace, RunReveal asks for:
- Host and port: the native protocol endpoint of your ClickHouse server. ClickHouse Cloud uses port
9440. - Database, username and password: the ones you created above.
- Service ID: optional. On ClickHouse Cloud it's shown on the service's settings page.
Select Connect database. RunReveal connects, checks the user's privileges and saves the destination. Then it runs its migrations, which create the tables your logs are written to.
You can also select Skip for now and add a destination later from the workspace's settings.
If connecting fails
- The connection is refused or times out: check the host and port, and that your ClickHouse server accepts connections from RunReveal.
- Authentication fails: check the username and password.
- "Connected, but the user is missing privileges RunReveal needs": the message lists the
GRANTstatements that are missing. Run them as an admin user, then connect again.