Skip to main content

​
Linking ClickHouse as a Source

This guide walks through connecting a ClickHouse database to Actioneer. The setup creates a dedicated read-only user with SELECT-only permissions on the databases you specify.
  
  Prerequisites  ClickHouse instance (self-hosted or ClickHouse Cloud), Actioneer account
  Access granted  SELECT queries on specified databases
  Estimated time  ~15 minutes
  Actioneer IP  35.244.14.238
Actioneer cannot insert, update, delete, or modify any data, tables, or settings in your ClickHouse instance.
1

Locate your ClickHouse connection details

Two values are needed: the host address and port.ClickHouse Cloud: Open your service in the ClickHouse Cloud console. The host and port are displayed on the service overview page.Self-hosted: Use the hostname or IP address of your ClickHouse server.
  Value  Location  Example
  Host  Service overview or server config  my-instance.clickhouse.cloud
  Port  See port table below  8443 (Cloud) or 8123 (self-hosted)
Port reference:
  Port  Environment  Protocol
  8443  ClickHouse Cloud  HTTPS (required)
  8123  Self-hosted  HTTP
Native port 9000 is not supported by this connector. Use the HTTP interface (8123 for self-hosted, 8443 for ClickHouse Cloud).
2

Create a read-only database user

Connect to your ClickHouse instance using a SQL client and run the following. Replace your_database with the database Actioneer should query.
-- Create a dedicated read-only user
CREATE USER actioneer_readonly
  IDENTIFIED BY 'Choose-A-Strong-Password-Here'
  SETTINGS readonly = 1;

-- Grant read access to all tables in the target database
GRANT SELECT ON your_database.* TO actioneer_readonly;

-- Grant access to system tables for schema discovery
GRANT SELECT ON system.* TO actioneer_readonly;
Replace your_database with your actual database name. Run the GRANT SELECT statement for each database Actioneer should access.
Save the password you set for actioneer_readonly. You will enter it in Actioneer in the next step. Store it in a password manager.
3

Allow Actioneer's IP address

If your ClickHouse instance restricts inbound connections, add Actioneer’s IP so it can reach the HTTP interface.ClickHouse Cloud
  1. Open your service in the ClickHouse Cloud console.
  2. Go to Settings → IP Access List.
  3. Add 35.244.14.238/32 and save.
Self-hosted
  1. Ensure your firewall allows inbound TCP on the port from Step 1 (8123 or 8443) from 35.244.14.238.
If your instance is in a private network with no public endpoint, skip this step and use the SSH Tunnel option in Actioneer instead (see the connection form in the next step).
4

Connect ClickHouse in Actioneer

  1. In Actioneer, click Data in the left sidebar.
  2. Select ClickHouse from the list of data sources.
  3. When prompted, select Direct Connection.
  4. Complete the connection form:
  Field  Value
  Connection Name  A descriptive label, e.g. Production ClickHouse
  Host  From Step 1 (e.g., my-instance.clickhouse.cloud)
  Port  From Step 1 (e.g., 8123)
  Database Name  The database from Step 2 (e.g., analytics)
  Username  actioneer_readonly
  Password  The password set in Step 2
  SSH Tunnel  Optional — enable to connect via a bastion host for private instances
  1. Click Connect.

​
Common questions

No. The actioneer_readonly user is configured with readonly = 1 and holds only SELECT grants. It cannot insert, update, delete, or alter any objects in your instance.
Enable SSH Tunnel if your ClickHouse instance is in a private network (e.g., behind a VPC with no public endpoint). The tunnel is a network routing mechanism — it routes traffic through a bastion host that has access to your private instance. It does not replace or provide encryption. TLS encryption is applied to all Actioneer connections independently, regardless of whether SSH Tunnel is enabled.
All credentials are encrypted at rest with AES-256 and encrypted in transit with TLS 1.3. They are never stored in plain text or logged. Actioneer is SOC 2 Type II certified, ISO 27001 certified (audited by Schellman), and GDPR compliant.

Need a hand?

Stuck on a step or running into an error? Reach out at connect@actioneer.com.