ClickHouse client

Run analytical queries, inspect plans and pipelines, and manage table parts and partitions.

Works on MacDriver comes with the Mac app

Included in Free; paid plans add optional featuresOpen source (AGPL-3.0)

Download for Mac ClickHouse setup guide

The Parts tab for a ClickHouse MergeTree table, listing partitions and parts with their row counts.

At a glance

Query language: SQL
Driver: Comes with the Mac app
Connect with: Host and port, SSH tunnel, SSL/TLS
Default port: 8123
Minimum version: None
iPhone and iPad: Does not open

Connect

Enter a host, HTTP port, user and optional database. Switch databases without reconnecting. Open tabs keep their starting database; View > Sidebar as Tree expands databases in place.

Choose any SSL mode to switch to HTTPS. A port of 443 or 8443, the one ClickHouse Cloud uses, turns on Verify Identity, which checks the certificate against your CA file or the system trust store. Verify CA needs a CA file, and a client certificate and key reach servers that require mutual TLS.

Without TLS, reach a remote server through an SSH tunnel rather than sending plain HTTP across the network.

Query and edit

Track rows read during a query. Stop sends KILL QUERY, and the connection’s query timeout is passed to the server.

The Explain menu offers Plan, Pipeline, AST, Syntax and Estimate. The indented output is drawn as a diagram or a tree, and Estimate shows the rows, marks and parts a query would read.

Review Preview SQL before inserting rows or submitting UPDATE and DELETE mutations. A successful save means accepted, not applied; follow progress in system.mutations. Materialized views are read-only.

A result holding ClickHouse point or ring tuples opens on the Map view. A query with its own FORMAT clause shows the server’s raw output in one column, so leave the clause off to get a grid.

Tables, parts and partitions

A table opens with Structure, Indexes, DDL and Parts tabs. Indexes shows the sorting key and the data-skipping indices, and DDL shows the full CREATE TABLE, engine and settings included.

Inspect parts from system.parts, including partition, row count, size and active status. Run Optimize, Drop Partition or Detach Partition from the Parts tab.

The Structure tab adds, modifies and drops columns and drops data-skipping indices. The sorting key and primary key are fixed when a table is created, so add a data-skipping index with ALTER TABLE … ADD INDEX, and recreate the table for other changes.

Monitor

The Server Dashboard shows active queries, active merges, part mutations and disk usage, lists the other sessions with Terminate Session on each, and reads its slow query list from system.query_log: the most recent finished queries that took longer than a second.

Move data

Load CSV, TSV, JSON, JSONL, XLSX and SQL files with Import, and export tables or query results as CSV, JSON, SQL, XLSX, Markdown, HTML and XML. A column with even one value that is not valid UTF-8 shows as hex in the grid; select toValidUTF8(column) to read it as text.

iPhone and iPad

The iPhone and iPad app has no ClickHouse driver. ClickHouse connections synced from a Mac appear in its list but do not open.

Limits

Connections use ClickHouse’s HTTP interface. The native TCP protocol is not used.
TLS is off by default. Choose an SSL mode in the connection form to use HTTPS.
No foreign keys and no transactions.
A SET statement does not carry over to the next query.

Questions about ClickHouse

How do I change a setting for one query?

Put it in a SETTINGS clause on the query itself, such as SELECT … SETTINGS max_threads = 4. Each statement is its own HTTP request with no session, so a separate SET is gone by the next one.

Why does port 9000 not connect?

Port 9000 is ClickHouse’s native TCP port, which TablePro does not use. Connect to the HTTP port, or 8443 for HTTPS on ClickHouse Cloud, and check that the server’s HTTP interface is on: a request to /ping on that port answers Ok.