data-peek
Database Support

ClickHouse

Using data-peek with ClickHouse

ClickHouse

ClickHouse support is in beta. It is tested against ClickHouse 24.8. Report problems on GitHub.

data-peek connects to ClickHouse over its HTTP interface. ClickHouse support is for querying and browsing. You can run scripts, read typed results, explore databases and tables, and read query plans. Editing data and changing table structure are not available on ClickHouse connections.

Connection Setup

  1. Click Add Connection in the sidebar
  2. Select ClickHouse as the database type
  3. Enter your connection details:
    • Host: Your ClickHouse hostname or IP
    • Port: Default is 8123. ClickHouse usually serves HTTPS on 8443.
    • Database: Default is default
    • Username: Default is default
    • Password: Your password

Use the HTTP Port

data-peek uses the ClickHouse HTTP interface, not the native TCP protocol. Ports 9000 and 9440 are native-protocol ports. If you enter one of them, data-peek refuses the connection and suggests the HTTP port instead: usually 8123, or 8443 for TLS.

Connection Strings

Paste a URL that starts with clickhouse:// or clickhouses:// to fill in the form:

clickhouse://default:password@localhost:8123/default

A clickhouses:// URL, or a ?secure=true parameter, turns on SSL.

SSL and SSH Tunnels

Turn on SSL to connect over HTTPS. To reach a server behind a bastion host, use an SSH tunnel. See SSH Tunnels for configuration details.

Supported Features

FeatureSupport
Query execution✓
Multiple statements✓
Schema explorer✓
Table preview and pagination✓
Views and materialized views✓
Enum types✓
Query plansText plans
Cancel and timeouts✓
Column statistics✓
Performance analysis✓
Health MonitorActive Queries, Table Sizes
AI assistant✓
MCP server✓
SSH tunnels✓
Inline editing-
Table designer-
Transactions-

Not Available on ClickHouse

data-peek hides these features on ClickHouse connections:

  • Inline editing
  • Table designer
  • CSV import
  • Data generator
  • Transactions and step-through debugging
  • LISTEN/NOTIFY
  • Triggers
  • SQL dump export and import
  • Schema Intel
  • Health Monitor panels for locks and cache stats
  • Cross-tab @name references

Query Execution

Multiple Statements

data-peek runs a script one statement at a time on a single ClickHouse session. A SET applies to every statement after it in the same run:

SET max_threads = 2;
SELECT getSetting('max_threads');

Each statement that returns rows gets its own result tab. A SET does not carry over to your next run.

FORMAT Clauses

data-peek formats results itself. If a query ends with a FORMAT clause, such as FORMAT CSV, data-peek refuses it and asks you to remove the clause. To save results to a file, use Export.

Autocomplete

The editor suggests common ClickHouse functions, such as uniqExact, toStartOfInterval, and arrayJoin, and ClickHouse types, such as UInt64, LowCardinality, and DateTime64. Most ClickHouse function and type names are case-sensitive, so suggestions are inserted with ClickHouse’s own casing.

Types

  • Int64, UInt64, and Decimal values display exactly as the server returns them. data-peek never rounds them through JavaScript numbers, and these columns still sort numerically.
  • The results grid shows each column’s ClickHouse type as written, for example LowCardinality(String) or Nullable(DateTime64(3)).
  • Nullable(T) columns show as nullable in the schema explorer, including when wrapped in LowCardinality.
  • Enum8 and Enum16 columns list their allowed values.

Schema Explorer

  • Each ClickHouse database appears as a schema. The connection’s own database is listed first.
  • Tables, views, and materialized views appear with their columns and types.
  • The .inner tables that back materialized views are hidden.
  • The system, INFORMATION_SCHEMA, and information_schema databases are hidden. You can still query them in the editor.
  • Columns in a table’s primary key are marked as key columns. In ClickHouse, the primary key defaults to the sorting key.
  • Row counts come from the total_rows estimate in system.tables.

ClickHouse has no foreign keys, so ER diagrams show tables and columns without relationship lines.

Health Monitor

The Health Monitor (click Health Monitor in the sidebar) shows two panels for ClickHouse connections:

  • Active Queries — lists queries currently running in system.processes, with the user, elapsed time, and a truncated view of the query text. Use the Kill button (skull icon) to send KILL QUERY for a selected query. The PID column shows the ClickHouse query_id, which is a string rather than an integer.
  • Table Sizes — shows per-table disk usage from system.parts.

Cache hit ratios and lock monitoring are not available for ClickHouse.

Column Statistics

The column statistics panel shows row, null and distinct counts, plus min, max and average for numeric columns, and the most common values for text columns. The distinct count comes from ClickHouse’s uniq, so it is approximate on large tables.

Query Plans

The Explain button runs EXPLAIN indexes = 1 on the current statement and shows the plan as text. ClickHouse has no EXPLAIN ANALYZE, so Explain plans the statement without executing it.

You can also write EXPLAIN yourself. It returns one row per plan line:

EXPLAIN indexes = 1
SELECT count() FROM events WHERE event_date >= today() - 7;

Performance Analysis

Click Analyze in the results toolbar to check the current statement. data-peek reads the plan with EXPLAIN json = 1, indexes = 1 and flags a table read that skips few of the table’s granules. It also summarizes earlier runs of the same query shape from system.query_log over the last 7 days, and flags the query as slow when its p95 duration passes the threshold. Your query is not run again.

system.query_log is per node, so on a cluster only the runs on the connected node are counted, and a run from the last few seconds may not be logged yet. If your user cannot read system.query_log, the pruning check still runs. See Performance Analysis.

Cancel and Timeouts

Cancel stops the request and sends KILL QUERY for it, so the server stops the work too. The query timeout setting becomes ClickHouse’s max_execution_time, so the server ends a query that runs past it.

MCP Server

When an agent calls run_query on a ClickHouse connection, data-peek sends the query with the readonly = 1 setting. ClickHouse then refuses writes and table functions such as url(). See MCP Server.

Troubleshooting

Connection Refused or a Native-Port Error

  • Check that you are using the HTTP port: 8123, or 8443 with SSL
  • Verify the server is reachable from your network
  • Check firewall rules allow connections on that port

Authentication Failures

  • Verify your username and password. A fresh ClickHouse install has a user named default.
  • Ensure the user can read the database you entered

On this page