// free tool

ClickHouse connection string builder

Build ClickHouse connection strings for the HTTP interface and the native protocol from one form, or paste one to check the port, protocol and TLS settings. It all runs in your browser: nothing you type is sent anywhere.

Open this connection in SQLly

Opens SQLly's connection editor filled in.

Private by design. The builder and decoder are plain JavaScript running in this tab. The page sends no request with what you type, stores nothing (not even in your browser), and keeps working offline once loaded. The Open in SQLly link goes from your browser straight to the app on your computer.

ClickHouse connection string formats

ClickHouse has two client protocols on different ports: HTTP (8123, or 8443 with TLS), used by JDBC, clickhouse-connect and the .NET driver, and the native TCP protocol (9000, or 9440 with TLS), used by clickhouse-client and clickhouse-go. Pointing a client at the other protocol's port is the most common connection error.

HTTP URL HTTP interface, curl

https://ch.example.com:8443/?database=analytics

Native DSN clickhouse-go v2

clickhouse://default:[email protected]:9440/analytics?secure=true

JDBC clickhouse-java 0.8+

jdbc:clickhouse:https://ch.example.com:8443/analytics?user=default&password=your_password&ssl=true

ADO.NET ClickHouse.Driver

Host=ch.example.com;Protocol=https;Username=default;Password=your_password;Database=analytics

Placeholders such as your_password are just that: build your own string with the form above. More about connecting SQLly to ClickHouse: SQLly for ClickHouse.

ClickHouse ports

From ClickHouse's network-ports guide.

KeywordSynonymsDefaultWhat it does
8123 - - HTTP interface.
8443 - - HTTPS interface.
9000 - - Native TCP protocol.
9440 - - Native protocol over TLS.
9004 / 9005 - - MySQL and PostgreSQL wire-compatibility interfaces.

clickhouse-go v2 DSN parameters

clickhouse://user:password@host1:9000,host2:9000/database?param=value; http:// and https:// DSNs use the HTTP interface.

KeywordSynonymsDefaultWhat it does
secure - false TLS.
skip_verify - false Skip certificate checks.
dial_timeout - 30s Connect timeout with a unit.
read_timeout - 5m Read timeout.
compress - - Compression method.
connection_open_strategy - - How hosts are picked.

ClickHouse.Driver (.NET) keys

ADO.NET style.

KeywordSynonymsDefaultWhat it does
Host - localhost Server host.
Port - 8123 / 8443 HTTP(S) port.
Protocol - http http or https.
Username - default User name.
Password - empty Password.
Database - empty Default database.
Compression - true Compress traffic.
UseSession - false Use a server-side session.
Timeout - 120 Seconds.

clickhouse-client options

clickhouse-client also takes a connection string as its first argument: clickhouse:[//[user[:password]@][hosts_and_ports]][/database][?query_parameters].

KeywordSynonymsDefaultWhat it does
--host, -h - localhost Server host.
--port - 9000 (9440 with --secure) Native port.
--user, -u - default User.
--password --ask-password - Password; --ask-password prompts.
--database, -d - default Database.
--secure, -s - - TLS; turned on automatically for port 9440 and ClickHouse Cloud hosts.

Common ClickHouse connection errors

Port 9000 is for clickhouse-client program. You must use port 8123 for HTTP.

Why: An HTTP client (browser, curl, JDBC, clickhouse-connect, .NET) was pointed at the native protocol port.

Fix: Use 8123, or 8443 for HTTPS.

Code: 516. DB::Exception: default: Authentication failed: password is incorrect, or there is no user with such name.

Why: Wrong user or password, or the user may not log in from your address.

Fix: Check the credentials and the user's allowed hosts in the server's users configuration.

Code: 81. DB::Exception: Database analytics does not exist. (UNKNOWN_DATABASE)

Why: The database in the string does not exist.

Fix: Check SHOW DATABASES and the spelling.

Unexpected packet / connection reset on the native port

Why: A native-protocol client (clickhouse-client, clickhouse-go) is talking to an HTTP port, or a plain client to the TLS port 9440.

Fix: Use 9000 without TLS or 9440 with --secure / secure=true.

ClickHouse connection string FAQ

Which port should I use for ClickHouse?

HTTP clients (JDBC, clickhouse-connect, .NET, curl) use 8123, or 8443 for HTTPS. Native clients (clickhouse-client, clickhouse-go native DSN) use 9000, or 9440 for TLS. ClickHouse Cloud serves 8443 and 9440.

What is the ClickHouse JDBC URL format?

jdbc:clickhouse:http://host:8123/database or jdbc:clickhouse:https://host:8443/database?ssl=true (driver 0.8+). The driver does not guess the protocol from the port, so write it.

Can I put the password in the HTTP URL?

Avoid it: URLs end up in logs. Send it in the X-ClickHouse-User and X-ClickHouse-Key headers, or with HTTP basic authentication.

// skip the strings entirely

Connect once. Then just write SQL.

SQLly is a native SQL workbench for macOS, Windows and Linux. Paste a connection string into its connection editor, keep passwords in your system keychain, and get schema-aware IntelliSense on ClickHouse and more.