Skip to content
Saiku Cloud

Connecting a ClickHouse warehouse

This guide walks you through connecting a ClickHouse database (ClickHouse Cloud or self-hosted) to Saiku Cloud. Five minutes if your warehouse is already public; ten if you need to create a read-only user.

Tier impact: every Saiku Cloud tier (Starter, Team, Business) supports ClickHouse BYOC.

What you’ll need

  • A ClickHouse 23.8+ instance (older versions work but the dialect surface we test against is 23.8+).
  • Network reachability — see Step 1.
  • Admin access to your warehouse so you can create a read-only user (or an existing read-only user’s credentials).

Step 1 — Allowlist our egress IP

Saiku Cloud’s queries to your warehouse all originate from a single static IP:

87.99.153.244

Add this to your warehouse’s network allowlist before testing the connection. Per-provider notes:

  • ClickHouse Cloud: Console → your service → Settings → Network → IP access list. Add 87.99.153.244 as a single-IP rule.
  • Self-hosted: firewall in front (UFW, iptables, your cloud provider’s security group) plus <allow_for_users> in users.xml if you’ve narrowed who can connect.

The IP is stable — we commit to at least 30 days notice before any rotation. Full policy: our egress-IP stability commitment.

Step 2 — Create a read-only user in ClickHouse

Saiku Cloud only ever reads from your warehouse — never writes, never alters schemas. The least-privilege shape:

-- As the default user or another superuser:
CREATE USER saiku_read IDENTIFIED WITH plaintext_password BY 'pick-something-strong';


-- Grant read access to the database(s) you want Saiku to see.
-- Repeat for each database.
GRANT SELECT ON analytics.* TO saiku_read;

A few notes:

  • plaintext_password is the simplest auth method; ClickHouse Cloud also supports sha256_password and double_sha1_password. Either works for our JDBC connection — the driver hashes before transit.
  • ClickHouse Cloud has a UI for user management (Console → Users) if you prefer not to write SQL.
  • Settings profile: consider creating a separate profile for saiku_read with a tight max_memory_usage + max_execution_time cap so a runaway query can’t impact your production workload. See ClickHouse’s quota docs.

Step 3 — Build the JDBC URL

The shape:

jdbc:clickhouse://<host>:<port>/<database>?ssl=true

Concrete examples:

  • ClickHouse Cloud: jdbc:clickhouse://my-service.us-east-1.aws.clickhouse.cloud:8443/default?ssl=true&sslMode=STRICT
  • Self-hosted with HTTPS reverse-proxy: jdbc:clickhouse://ch.yourcompany.com:443/analytics?ssl=true
  • Self-hosted plaintext (private network only): jdbc:clickhouse://ch.internal:8123/analytics. Saiku Cloud’s egress IP must be allowed at the network layer; plaintext is OK INSIDE a trusted network but not over the open internet.

Key parameters:

  • ssl=true — enables TLS. Required for ClickHouse Cloud + recommended for any public deployment.
  • sslMode=STRICT — verifies the server cert chains to a CA we trust + verifies the hostname matches. ClickHouse Cloud uses Let’s Encrypt so this works out of the box.
  • compress=true — opt-in client-side compression (LZ4 by default). Cuts JDBC payload size for large result sets; usually a win for BI workloads. The shaded clickhouse-jdbc-all driver bundles the LZ4 + Brotli + Zstd native libs.

Step 4 — Connect via the Saiku Cloud wizard

  1. Sign in at https://cloud.saiku.bi/.

  2. Navigate to Connections in the left sidebar.

  3. Under 1. Pick warehouse type, click the ClickHouse tile.

  4. Fill in:

    • JDBC URL — the URL from Step 3.
    • Username — saiku_read (or whatever you named the user in Step 2).
    • Password — the password from Step 2.

  5. Click Test connection.

A green outcome banner: ✓ Connection successful plus the detected ClickHouse version → proceed to Step 5.

A red outcome banner → see Troubleshooting.

Step 5 — Save the connection

After a successful test, the wizard renders a 3. Save connection section. Fill in:

  • Password (re-enter for save) — the same password.
  • Label — Production ClickHouse or Analytics warehouse.

Click Save connection.

Troubleshooting

✗ Connection failed (HOST_UNREACHABLE) or (TIMEOUT)

  1. Wrong port — you used 9000 (native protocol) instead of 8123 (HTTP) or 8443 (HTTPS). The fix is in Step 3.
  2. Firewall / IP allowlist — Step 1 wasn’t applied. ClickHouse Cloud’s “IP access list” sometimes takes a minute to propagate after save; retry.
  3. DNS — nslookup <host> from your laptop. If it resolves to a private IP, the SSRF guard would surface HOST_DENIED (not HOST_UNREACHABLE).

✗ Connection failed (AUTH_FAILED)

ClickHouse error 192 / 193 / 516. Username or password is wrong.

  • Username case-sensitivity — ClickHouse user names are case-sensitive.
  • Allowed hosts — your user might be locked to specific IPs via <allow_for_hosts> in users.xml. Add 87.99.153.244 to that list, or remove the <allow_for_hosts> clause to allow from anywhere (and rely on the firewall).
  • plaintext_password vs sha256_password — both work with our driver, but if you mismatched the user’s stored hash type and the password you provided, the server-side hash check fails. Usually only an issue when you migrate a user between hash types.

✗ Connection failed (DATABASE_NOT_FOUND)

ClickHouse error 81. The host accepts your credentials but the database name in the JDBC URL doesn’t exist. Verify it:

SHOW DATABASES;

✗ Connection failed (DIALECT_UNSUPPORTED)

The URL doesn’t start with jdbc:clickhouse:. If you pasted a jdbc:ch: URL, the dialect resolver matches that as a separate scheme and accepts it too — but make sure the URL itself starts with one of those two.

Anything else

Take a screenshot of the wizard with the red outcome banner visible (Kind: ... line in particular) and send it to support@saiku.bi.

Enterprise: private network

For Enterprise customers running a private network setup, the egress IP rule is replaced by VPC peering. The connection wizard’s flow is otherwise identical. Contact your account team to provision the peering.

Try with FoodMart

Want to test Saiku Cloud with this dialect before connecting your own data? Download the FoodMart sample dataset packaged for ClickHouse:

FoodMart sample dataset for ClickHouse