Getting started

Local CLI (pip)

Run OptiHouse on your own machine before connecting anything. The CLI reads ClickHouse `system.*` tables in read-only mode and never sends your data anywhere — the same engine as the hosted product, with a teaser slice of the findings. Full fixes, all 40 advisors and the dashboard unlock with a free account.

Install

bash

pip install optihouse

To scan a real cluster you also need the ClickHouse driver. The bundled demo needs nothing extra.

bash

pip install "optihouse[clickhouse]"

Try it instantly (no cluster)

Runs against a bundled synthetic cluster so you can see the exact output in seconds — no connection, no signup.

bash

optihouse scan --demo

Scan a real cluster (read-only)

Create a dedicated read-only user, then point the CLI at your cluster. Everything is SELECT-only against system.* — no writes, no agents, nothing leaves the host.

sql

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

bash

# native protocol
optihouse scan --host clickhouse.internal --port 9000 \
  --user optihouse --password '***'

# over TLS (secure native port, usually 9440)
optihouse scan --host ch.example.com --port 9440 --secure \
  --user optihouse --password '***'

Behind a bastion?

The CLI connects to whatever is reachable from the machine it runs on — run it from inside the network where ClickHouse is already reachable. For SaaS-side SSH bastion / tunnel modes, see Connecting ClickHouse.

Options

--demo — analyse the bundled synthetic cluster (no connection).
--host / --port — ClickHouse address (native protocol, default port 9000).
--user / --password — credentials for your read-only user.
--secure — use TLS (secure native port, usually 9440).
--database — default database to connect to.

Audit exactly what it collects

Don't take the read-only claim on faith. Print every statement the CLI would run — without connecting anything. They are all SELECT-only against system.* (table sizes, part counts, column codecs, aggregated query_log patterns); no data rows are read and nothing leaves the host. The package is MIT-licensed, so the source is auditable too.

bash

optihouse queries

Compatibility

Works on ClickHouse 22.x through 26.x (and back to 20.1 for the core scan). It only touches stable system.* views; version-specific checks are skipped automatically on older servers instead of failing.

What's gated

The CLI shows the cluster summary and every finding with its estimated $/month impact. The ready-to-apply ALTER/SELECT SQL for each fix, all 40 advisors and the historical dashboard unlock with a free account.

Package

https://pypi.org/project/optihouse/ · MIT licensed. Prefer a UI? The same analysis runs in the browser — connect a cluster from the app.