> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-feat-721-compare-sync.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> Connect to ClickHouse over its HTTP interface with TablePro

TablePro connects to ClickHouse over its HTTP interface (port 8123 by default), not the native TCP protocol. The driver ships inside the app; there is nothing to install.

## Quick Setup

Click **New Connection**, select **ClickHouse**, enter host, port, credentials, and database, then click **Save & Connect**.

## Connection Settings

| Field        | Default     | Notes                                                                  |
| ------------ | ----------- | ---------------------------------------------------------------------- |
| **Host**     | `localhost` |                                                                        |
| **Port**     | `8123`      | HTTP port (not 9000 native TCP)                                        |
| **Username** | `default`   | Leave empty and TablePro sends `default`. Set a password in production |
| **Database** | `default`   | Leave empty and the server uses `default`. Switch with Cmd+K           |

**SSL/TLS**: Setting any non-Disabled SSL Mode switches the URL scheme to `https`. **Preferred** and **Required** skip certificate verification, **Verify CA** validates against the supplied CA file, **Verify Identity** uses system default HTTPS trust (certificate chain plus hostname). Use **Verify Identity** for ClickHouse Cloud (port 8443); its certificates chain to a public CA. Use **Required** only for a self-signed certificate you have no CA file for. See [SSL/TLS](/features/ssl).

For unencrypted HTTP to a remote server, use [SSH tunneling](/databases/ssh-tunneling).

## Connection URL

```text theme={null}
clickhouse://user:password@host:8123/database
```

See [Connection URL Reference](/databases/connection-urls) for all parameters.

## Features

### Database and Table 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 databases. Choose **View > Sidebar as Tree** to list every database and expand them in place.

For each table, TablePro shows:

* **Structure**: Columns with ClickHouse data types, default expressions, and comments
* **Indexes**: The sorting key, listed as `PRIMARY (sorting key)`, plus data-skipping indices (minmax, set, bloom\_filter, and others)
* **DDL**: The full CREATE TABLE statement including engine and settings
* **Parts**: Partition and part details from `system.parts` (rows, disk size, active status), with Optimize Table, Drop Partition, and Detach Partition actions

<Frame caption="The Parts tab with partition actions">
  <img className="block dark:hidden" src="https://mintcdn.com/ngquct-feat-721-compare-sync/TlGri84ui62H4Saf/images/clickhouse-parts-tab.png?fit=max&auto=format&n=TlGri84ui62H4Saf&q=85&s=a3991065fb9bae2dcb5bbcfdb8e776fc" alt="ClickHouse Parts tab showing partitions with Optimize, Drop, and Detach actions" width="1560" height="960" data-path="images/clickhouse-parts-tab.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/ngquct-feat-721-compare-sync/TlGri84ui62H4Saf/images/clickhouse-parts-tab-dark.png?fit=max&auto=format&n=TlGri84ui62H4Saf&q=85&s=9cedf44ae0c8b5b877636b1a6af21011" alt="ClickHouse Parts tab showing partitions with Optimize, Drop, and Detach actions" width="1560" height="960" data-path="images/clickhouse-parts-tab-dark.png" />
</Frame>

### 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/port info |
| **AST**      | Abstract syntax tree of the parsed query          |
| **Syntax**   | Query after syntax optimizations                  |
| **Estimate** | Estimated rows, marks, and parts to read          |

### Server-side Query Cancellation

Cancelling a running query sends `KILL QUERY` to the server, stopping the query itself, not just the HTTP connection.

### Server Dashboard

The [Server Dashboard](/features/server-dashboard) supports ClickHouse: active sessions, server metrics, and slow queries.

### Data Editing

Edit cells, insert rows, and delete rows in the data grid. Edits are submitted as INSERT, `ALTER TABLE ... UPDATE`, and `ALTER TABLE ... DELETE` statements.

<Warning>
  ClickHouse mutations (UPDATE and DELETE) are asynchronous. They run in the background and can take time on large tables. Check progress with `SELECT * FROM system.mutations WHERE is_done = 0`.
</Warning>

### Export and Import

Export query results or table data to CSV, JSON, SQL, and XLSX. Import SQL, JSON, and CSV files. See [Import and Export](/features/import-export).

## Troubleshooting

**Connection refused**: Check ClickHouse is listening on the HTTP port: `curl http://localhost:8123/ping` should return `Ok.`. Common port mix-up: 8123 is HTTP, 8443 is HTTPS, 9000 is native TCP (not used by TablePro). If the HTTP interface is disabled, check `<http_port>` in `/etc/clickhouse-server/config.xml`.

**Authentication failed (HTTP 403)**: Verify the username and password, that the user exists (`SELECT name, auth_type FROM system.users`), and that it has access to the target database (`SHOW GRANTS FOR app_user`).

**Connection timeout**: Verify host, port, firewall rules, and, for cloud-hosted ClickHouse, that your IP is in the allowed list.

## Limitations

* No foreign keys or multi-statement transactions
* No auto-increment; primary key and sorting key are immutable after creation
* Structure editing supports add, modify, and drop columns, plus data-skipping indexes. Foreign keys and primary key changes are not available
* UPDATE/DELETE run as asynchronous background mutations via `ALTER TABLE`
* ClickHouse is designed for batch inserts, not single-row writes
* A query with its own `FORMAT` clause (for example `SELECT 1 FORMAT JSON`) shows the server's raw output in a single column instead of a parsed table