ClickHouse

Connection settings, the URL format, and the parts and partition tools for ClickHouse

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

Field	Default	Notes
Host	localhost
Port	8123	HTTP port, not 9000 native TCP
Username	default	Left empty, default is sent. Set a password in production
Database	default	Optional. Leave empty and the server uses default

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

clickhouse://user:password@host:8123/database

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.

Tab	Contents
Structure	Columns with types, default expressions, and comments
Indexes	The sorting key, listed as PRIMARY (sorting key), plus data-skipping indices (minmax, set, bloom_filter, and the rest)
DDL	The full CREATE TABLE, engine and settings included
Parts	Every part from system.parts with its partition, rows, disk size, modification time, and active flag, plus Optimize, Drop Partition, and Detach Partition

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:

Variant	Description
Plan	Logical query plan (default)
Pipeline	Physical execution pipeline with thread and port info
AST	Abstract syntax tree of the parsed query
Syntax	Query after syntax optimizations
Estimate	Estimated rows, marks, and parts to read

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.

Mode	Verifies	Pick it for
Preferred, Required	Nothing. Encryption only	A self-signed certificate you have no CA file for
Verify CA	The chain, against the CA file	Private PKI
Verify Identity	The chain and the hostname, against the system trust store	ClickHouse Cloud, on port 8443

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.