optihouse 0.1.2

Read-only ClickHouse cost & performance optimizer — local demo CLI

OptiHouse — local demo CLI

Read-only ClickHouse cost & performance optimizer you run on your own machine. Point it at a cluster and it reads system.* tables in read-only mode, estimates where storage and compute money is leaking, and shows you the top opportunities — without connecting your cluster to any service. Your credentials and data never leave your machine.

The full analysis (every finding, the exact $ figure, and ready-to-apply SQL fixes) lives at https://optihouse.io.

Install

pip install optihouse

To scan a real cluster, also install the driver:

pip install "optihouse[clickhouse]"

Try it in 10 seconds (no cluster needed)

optihouse scan --demo

Runs against a bundled synthetic cluster so you can see exactly what the tool produces before pointing it at anything real.

Scan your own cluster (read-only)

optihouse scan --host clickhouse.internal --user readonly --password '***'
# TLS:
optihouse scan --host ch.example.com --port 9440 --secure --user readonly --password '***'

Everything is SELECT-only against system.*. No writes, no agents, no data rows read, nothing sent anywhere.

What you get locally vs. on optihouse.io

	Local demo CLI	optihouse.io (free account)
Cluster summary & opportunity count	✅	✅
Every finding + its $ impact	✅	✅
Total $/month & $/year savings	✅	✅
Copy-paste ALTER/SELECT fixes	🔒	✅
All 40 advisors (demo runs a slice)	partial	✅
Dashboard + before/after impact tracking	—	✅

Prefer a UI over the terminal? The same analysis runs in the browser at https://optihouse.io — connect a cluster (read-only) and see figures measured on your own data.

Privacy & transparency

The CLI only issues read-only queries against ClickHouse system tables (table sizes, part counts, column codecs, aggregated query_log patterns). It does not read your data rows and does not transmit anything off the host.

Don't take our word for it — print every statement it would run, without connecting anything:

optihouse queries

The package is MIT-licensed, so the full source is auditable too.

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 (system.projections on 22.3+, system.data_skipping_indices on 20.3+) are skipped automatically on older servers instead of failing.