RunReveal

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.

CREATE DATABASE IF NOT EXISTS runreveal;
 
CREATE ROLE runreveal_readwrite;
GRANT SELECT ON runreveal.* TO runreveal_readwrite WITH GRANT OPTION;
GRANT INSERT ON runreveal.* TO runreveal_readwrite WITH GRANT OPTION;
GRANT ALTER, CREATE TABLE, CREATE VIEW, DROP TABLE, DROP VIEW ON runreveal.* TO runreveal_readwrite;
GRANT CREATE ROW POLICY, ALTER ROW POLICY, DROP ROW POLICY ON runreveal.* TO runreveal_readwrite;
GRANT SELECT ON system.numbers TO runreveal_readwrite WITH GRANT OPTION;
GRANT SELECT ON system.data_skipping_indices TO runreveal_readwrite WITH GRANT OPTION;
GRANT SELECT ON system.mutations TO runreveal_readwrite;
GRANT CREATE ROLE, DROP ROLE, ROLE ADMIN ON *.* TO runreveal_readwrite;
GRANT S3, CREATE TEMPORARY TABLE ON *.* TO runreveal_readwrite WITH GRANT OPTION;
 
CREATE ROLE runreveal_readonly;
GRANT SELECT ON runreveal.* TO runreveal_readonly;
GRANT SELECT ON system.numbers TO runreveal_readonly;
 
CREATE USER runreveal IDENTIFIED BY 'REDACTED' DEFAULT ROLE runreveal_readwrite;
GRANT runreveal_readonly TO runreveal;

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:

GrantWhy RunReveal needs it
SELECT and INSERT on runreveal.*, with grant optionRead 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 optionPassed on to the roles that run your queries.
SELECT on system.mutationsDeleting 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 optionPassed on for storing the results of long-running queries. ClickHouse has no database-scoped form of these privileges.
runreveal_readonlyRead 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 GRANT statements that are missing. Run them as an admin user, then connect again.

On this page