Skip to main content
Every query travels over HTTP to port 8123. The native TCP protocol on 9000 is not used, so the server’s HTTP interface has to be on. Any version connects, though data-skipping indices need 19.17 or newer to show up. The driver ships inside the app.

​
Quick setup

Click Create Connection…, select ClickHouse, fill in host, port, and credentials, then click Save & Connect.

​
Connection settings

Switching database happens in place, with no reconnect, and the sidebar’s choice only affects new tabs: an open tab stays on its own database. See Tabs. For unencrypted HTTP to a remote server, use SSH tunneling.

​
Connection URL

See Connection URL Reference for all parameters.

​
Browsing

The sidebar lists the current database’s tables, views, and materialized views. Press Cmd+K or click the database name in the toolbar to switch. Choose View > Sidebar as Tree to list every database and expand them in place.
ClickHouse Parts tab showing partitions with Optimize, Drop, and Detach actions

The Parts tab with partition actions

The Server Dashboard covers ClickHouse with active sessions, server metrics, and slow queries.

​
EXPLAIN variants

Click the Explain dropdown in the query editor to choose:

​
Running queries

Each request carries a query id and asks for progress in the HTTP headers, so a long query reports rows read as it goes. Cancelling sends KILL QUERY for that id, stopping the query on the server rather than only dropping the connection. The query timeout bounds each request at the timeout plus 30 seconds. Grid edits go out as INSERT, ALTER TABLE … UPDATE, and ALTER TABLE … DELETE.
ClickHouse mutations run in the background, so the grid reports the statement as accepted rather than applied, and a large table can take a long time. Watch SELECT * FROM system.mutations WHERE is_done = 0 for progress.

​
SSL/TLS

The default is Disabled, which sends plain HTTP. Any other mode switches the URL scheme to https. The CA file may be PEM or DER. If Verify CA cannot read it, the connection fails rather than falling back to the public root store. See SSL/TLS.

​
Limitations

  • No foreign keys and no multi-statement transactions.
  • No auto-increment, and the primary key and sorting key are fixed at creation. Structure editing covers adding, modifying, and dropping columns and data-skipping indexes; recreate the table for anything else.
  • A SET does not carry to the next statement. Every statement is its own HTTP request with no session id, and the setting is gone by the next one. Put it in a SETTINGS clause on the query itself.
  • A query with its own FORMAT clause, such as SELECT 1 FORMAT JSON, shows the server’s raw output in one column instead of a parsed table. Drop the clause to get a grid.

​
Troubleshooting

Connection refused: curl http://localhost:8123/ping should answer Ok.. The usual cause is the port: 8123 is HTTP, 8443 HTTPS, 9000 native TCP and unused here. If the HTTP interface is off, check <http_port> in /etc/clickhouse-server/config.xml. Authentication failed (HTTP 403): Check the user exists (SELECT name, auth_type FROM system.users) and reaches the target database (SHOW GRANTS FOR app_user). Connection timeout: Check host, port, firewall rules, and, on ClickHouse Cloud, that your IP is in the allowed list.