OptiHouseDocs
Open app
Getting started

Quick start

Connect a ClickHouse cluster and get your first ranked recommendations in under five minutes. You only need a read-only user and network reachability between OptiHouse and your cluster.

Prerequisites

  • A reachable ClickHouse cluster (version 20.1 or newer — see compatibility note below).
  • A read-only ClickHouse user with SELECT access to system.*.
  • Either direct network access, or an SSH bastion the platform can tunnel through.
ClickHouse version
The core scan works on 20.1+. A few advanced analyzers need newer system views — projections needs 22.3, data_skipping_indices needs 20.3. Older versions simply skip those checks instead of failing.

1. Create a read-only user

Run this in clickhouse-client against your cluster. It grants exactly what OptiHouse needs — read access to system tables — and nothing more.

sql
CREATE USER dataeff IDENTIFIED WITH plaintext_password BY '<strong-random>';
GRANT SELECT ON system.* TO dataeff;
ALTER USER dataeff SETTINGS readonly = 1;

Verify the grant: SELECT version() should work, and any INSERT should fail with a read-only error.

2. Add the connection

  1. 1
    Open Connections
    In the app sidebar, go to Connections and click Add connection.
  2. 2
    Fill in the host
    Enter host, port (9000 for the native protocol), username and password. For a VPC-locked cluster, expand Connect via SSH bastion — see the Connecting ClickHouse page.
  3. 3
    Test it
    Click Test. OptiHouse opens a short-lived connection and runs SELECT version(). A green check means you are ready to scan.

3. Run your first scan

A scan starts automatically right after the connection is saved, and then repeats every 15 minutes. You can also trigger one manually from the Dashboard. The first scan takes roughly 10–60 seconds depending on the size of query_log.

What you'll see
Once the scan finishes, Recommendations fills with ranked findings, Cluster health shows replica and disk state, and Anomalies stays empty until there is a second scan to diff against.

4. Apply a fix

Open any recommendation. Each one ships with a runbook: probable causes, diagnostic SQL you can paste, remediation steps and references. Apply the fix on your side, then either mark it applied — or let auto-apply detect it for you on the next scan (see Auto-apply & verification).

Try it without connecting anything
Not ready to wire up a cluster? The SQL Optimizer works standalone — paste a query and the same Wave 1–7 rules rewrite it on the spot.