> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tablepro.app/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> Connect to ClickHouse over its HTTP interface with TablePro

# ClickHouse Connections

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`   | Set a password in production                           |
| **Database** | `default`   | Leave empty to browse all databases. Switch with Cmd+K |

**SSL/TLS**: Setting any non-Disabled SSL Mode switches the URL scheme to `https`. **Required** skips certificate verification, **Verify CA** validates against the supplied CA file, **Verify Identity** uses system default HTTPS trust (certificate chain plus hostname). Use **Required** for ClickHouse Cloud (port 8443). 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 all databases on the server. Expand one to see its tables, views, and materialized views. Press Cmd+K or click the database name in the toolbar to switch.

For each table, TablePro shows:

* **Structure**: Columns with ClickHouse data types, default expressions, and comments
* **Indexes**: 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/tXWaltqW4Zqkau0T/images/clickhouse-parts-tab.png?fit=max&auto=format&n=tXWaltqW4Zqkau0T&q=85&s=a75dbff231b40c4cdd4346d9dea4d169" 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/tXWaltqW4Zqkau0T/images/clickhouse-parts-tab-dark.png?fit=max&auto=format&n=tXWaltqW4Zqkau0T&q=85&s=e76e55fd70ee159a8fa0721492ef805d" 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, and other formats. Import data from 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.

## Known 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