Altinity SQL Browser — an OAuth-gated SQL console for ClickHouse
One HTML file · Zero third-party requests

A SQL console for ClickHouse
that you can host anywhere

An OAuth-gated query browser with charts, EXPLAIN pipeline graphs, data-flow graphs and smart autocomplete — built as a single self-contained HTML file. Serve it from ClickHouse itself, or run it locally with one command.

Try the live demo ↗ Run it locally →
curl -fsSL https://raw.githubusercontent.com/Altinity/altinity-sql-browser/main/install.sh | sh
The Altinity SQL Browser showing a query result rendered as a column chart, with the schema tree and saved-query library in the sidebar.

Query → table → chart, with a schema tree, tabbed editor and saved-query library — all in one page.

Why it's different

A full query workbench with no backend to run

The browser talks straight to ClickHouse over HTTP. There is no app server, no database of its own, and no third-party requests — just one HTML file and your OAuth provider.

OAuth-gated, no static secret

Each user signs in with your IdP (any OIDC provider) via Authorization-Code + PKCE. ClickHouse sees their JWT and enforces their own grants. The app never holds a shared credential.

One self-contained file

esbuild bundles everything — including Chart.js and the graph layout engine — into a single sql.html. No CDN, no fonts, no external calls. Serve it from ClickHouse's user_files and you're done.

More than a textarea

Charts, five EXPLAIN views including a pipeline graph, a live data-flow diagram that opens in its own tab, autocomplete from system.*, find/replace, a portable query library that exports to Markdown or SQL, and share links.

Three ways to run it

Deploy it your way

The same artifact runs as a hosted app on your cluster, as a local desktop-style app, or straight from a dev checkout.

Hosted on ClickHouse

Served from your cluster

Upload the SPA + config to user_files and let ClickHouse's HTTP handlers serve it at /sql, gated by your IdP.

  • Shared, always-on URL for your team
  • SSO via any OIDC provider
  • One deploy/install.sh command
Deployment guide →
Local app · curl | sh

Run it on your laptop

One command installs a launcher and a zero-dependency Python runner. Point it at the clusters in your clickhouse-client config.

  • Needs only python3
  • Reads your saved connections
  • Nothing leaves your machine but queries
Install locally →
From source

Develop & build

Clone the repo, npm run local, and iterate. The tested ES modules build to the single artifact via esbuild.

  • Vanilla ES modules, no framework
  • 100% coverage on the core layers
  • Playwright + vitest test suites
Quick start →
How it works

No app-specific backend

The only moving parts are ClickHouse's HTTP interface and your OAuth provider.

browser ──https──▶ ClickHouse GET /sql → the SPA (one HTML file) GET /sql/config.json → { issuer, client_id } │ OAuth2 Authorization-Code + PKCE via OIDC discovery (any IdP) │ id_token kept in sessionStorage, silently refreshed ▼ ClickHouse POST / Authorization: Bearer <id_token> ← every query (validated by CH token_processor / JWKS, or a delegated verifier)

Explore every feature →

From the blog

Engineering notes

Short pieces on how it works and why it's built this way.

Architecture

The SQL console with no backend

One HTML file ClickHouse serves itself — OAuth in the browser, per-user grants, zero third-party requests.
Schema

Map the materialized-view web

Drag a database in and get a typed data-flow graph of MVs, dictionaries and Distributed tables.
Performance

Read your query plan as a graph

EXPLAIN PIPELINE as a processor DAG — read parallelism and the Resize funnel at a glance.

All posts →

Start querying in a minute

Try the public demo, or install the local app with one command.

Open the live demo ↗ Star on GitHub ↗