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.
Open this connection in SQLly
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.
| Keyword | Synonyms | Default | What 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.
| Keyword | Synonyms | Default | What 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.
| Keyword | Synonyms | Default | What 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].
| Keyword | Synonyms | Default | What 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.
Other engines
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.