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, and so does a user with a read-only profile: a setting the server or the user’s profile does not allow is left out of each request. Data-skipping indices show up from 21.8, and editing a table comment needs 23.9. The driver ships inside the app.

​
Quick setup

Click New 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 actionsClickHouse 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, each with SETTINGS mutations_sync = 1, so a save returns once the rows have changed. A large table can take a long time. ClickHouse’s primary key is its sorting key, and rows can share it. An edit or a delete finds its row by every value the row was loaded with: right before the statement runs, the row is looked up, and the statement is limited to the data part that holds it (_part), so a row inserted in the meantime is left alone.
  • A row that another row matches in every column cannot be edited or deleted on its own. The save stops before anything is written. Deleting all of the identical rows at once works.
  • When the row still holds its old values after the statement, because its part was merged away or another client inserted the same values, the save reports it. Refresh the table before saving again.
  • A row holding an AggregateFunction column cannot be found by its values, so its edits are refused.
  • A table with no data parts, such as Memory, cannot be edited from the grid. Use the SQL editor.
Where your settings profile does not let you change mutations_sync, the plain UPDATE and DELETE go out, limited to the row’s part the same way. Values too long for the URL travel inside the statement in the request body, so a long text value or a large import is not held to the server’s URL limits. A statement longer than your user’s max_query_size raises that setting for its own request, unless the user is read-only or a settings constraint caps it lower.

​
Updating rows outside the grid

An import as Update or Insert or Update and a data compare sync change rows with ALTER TABLE … UPDATE, and the sync removes them with ALTER TABLE … DELETE. Copy as > UPDATE Statement(s) writes the same form. Each statement carries SETTINGS mutations_sync = 1, so it returns once the rows have changed, and a failure stops the run instead of waiting in system.mutations. Where your settings profile does not let you change mutations_sync, the plain UPDATE and DELETE go out instead. They finish before they return, and ClickHouse takes that UPDATE only on a table with lightweight updates turned on. Delete existing rows before an import or a copy writes TRUNCATE TABLE. ClickHouse refuses to update a column of the sorting, primary or partition key, with Cannot UPDATE key column, even to the value it holds. An import leaves such a column out of its updates, and a sync leaves it out unless its value differs, in which case the statement fails with that error.

​
SSL/TLS

The default is Disabled, which sends plain HTTP. Any other mode switches the URL scheme to https. Port 443 or 8443 turns on Verify Identity; see Ports that mean TLS. The CA file may be PEM or DER. Verify CA needs one, since it checks no hostname, and a connection without it is refused. If Verify CA or Verify Identity cannot read the file, the connection fails rather than falling back to the public root store. An imported URL with ssl=true opens as Verify Identity, and sslmode=none as Required. See SSL/TLS.

​
On iPhone and iPad

The ClickHouse driver is compiled into TablePro Mobile and talks to the same HTTP interface. Browsing, queries, and row editing work, with edits matched on every value of the row; creating or altering tables stays on the Mac. Unlike the Mac grid, a save or delete there waits for its mutation to finish, and one is refused when another row holds the same values. See iPhone and iPad. Behind an SSH tunnel, Verify Identity checks the certificate against the server’s own host name, not the local end of the tunnel.

​
Limitations

  • No foreign keys and no multi-statement transactions.
  • A materialized view opens read-only in the data grid. Edit the table a TO view writes into, or run ALTER TABLE … UPDATE and ALTER TABLE … DELETE on a view that stores its own rows from the SQL editor.
  • No auto-increment, and the primary key and sorting key are fixed at creation. Structure editing covers adding, modifying, and dropping columns, and dropping data-skipping indexes. Add or change a data-skipping index with ALTER TABLE … ADD INDEX in the SQL editor, and 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, and an export of it stops with an error naming the format. Drop the clause to get a grid or an export.
  • A column with even one value that is not valid UTF-8 shows every row as hex in the grid, and its cells do not open for inline editing. String and FixedString hold raw bytes, so a hash or a stray byte is enough. An export, an object copy and a data compare judge each value on its own, so a row holding text stays text there. Select toValidUTF8(column) to read it as text, with the bad bytes replaced.

​
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.