Local app · curl | sh

Run the SQL Browser on your laptop

One command installs a launcher and a zero-dependency Python runner. It serves the app at localhost:8900/sql and points it at the clusters already in your clickhouse-client config.

curl -fsSL https://raw.githubusercontent.com/Altinity/altinity-sql-browser/main/install.sh | sh

Needs only python3 (preinstalled on macOS & Linux) plus curl or wget.

The local app's login screen with a Saved connection dropdown listing the clusters from clickhouse-client, and a Target of localhost:8900.

The launcher opens a connection picker built from your saved clickhouse-client connections.

What the one-liner does

Four steps, no build toolchain

  1. Resolves the latest release

    Asks the GitHub API for the newest tag, then downloads altinity-sql-browser.tar.gz and verifies its SHA-256 checksum.

  2. Installs into your home directory

    Extracts the prebuilt sql.html and the Python runner into ~/.altinity-sql-browser, and drops a launcher at ~/.local/bin/altinity-sql-browser.

  3. Adds sample connections

    Installs ~/.clickhouse-client/sql-browser.xml with public demo endpoints — without touching your real config.xml.

  4. Ready to launch

    Run altinity-sql-browser and it boots the runner, probes which clusters are reachable, and opens http://localhost:8900/sql.

The runner

A thin, zero-dependency Python server

There's nothing to proxy: the browser talks to ClickHouse directly. The runner only serves the SPA and a generated config.json. It merges connections from your own ~/.clickhouse-client/config.xml (which wins on a name clash) and the sample sql-browser.xml, and offers each as a Saved connection:

At startup it probes each connection's HTTP interface — trying both standard ports (443 then 8443 for secure, 8123 then 80 for plain) and using whichever answers on /ping — and skips native-only endpoints so they aren't dead picks.

Run it from a source checkout instead

npm run local      # build dist/sql.html, then start the picker on :8900

Environment overrides

VariableEffect
PORTListen port (default 8900).
ASB_VERSIONInstall a specific release tag (default: latest).
ASB_HOMEInstall directory (default ~/.altinity-sql-browser).
ASB_BINLauncher directory (default ~/.local/bin).
LOCAL_CH_CONFIGUse a single explicit connections file.
SQL_BROWSER_PROBESet 0 to keep all hosts (skip the reachability probe).
Queries go straight to ClickHouse. The runner never sees your data — it only hands the browser the app and the list of hosts. Credentials and tokens stay in the tab's sessionStorage.
Try it against public data

Bundled demo endpoints

The sample connection file ships with public ClickHouse demos, so you can explore immediately:

antalya

Altinity Antalya demo — the ontime flight dataset.

clickhouse-sql

The public ClickHouse playground (read-only).

altinity-demo

Altinity github.demo cluster.

Want a guided tour? Load the ontime chart demo — ten ready-made queries that walk through every chart type.

Install it now

curl -fsSL https://raw.githubusercontent.com/Altinity/altinity-sql-browser/main/install.sh | sh