ClickHouse: Native clickhouse-client vs HTTP (curl 8123)
clickhouse-client speaks the native binary protocol on port 9000; the HTTP interface accepts plain queries over curl on port 8123. CI uses whichever the image and step allow.
A frequent CI confusion is pointing the native client at 8123 or curl at 9000. They are different protocols on different ports.
What it does
ClickHouse exposes two query interfaces. The native protocol (default 9000) is used by clickhouse-client and native drivers; it is binary and efficient. The HTTP interface (default 8123) accepts a query in the request body or a URL parameter, so any HTTP client, including curl, can run SQL without the CLI installed.
Common usage
# native client, port 9000
clickhouse-client --host localhost --port 9000 --query "SELECT 1"
# HTTP interface, port 8123, via curl
curl -s 'http://localhost:8123/' --data-binary 'SELECT 1'
# HTTP with auth and a database
curl -s 'http://localhost:8123/?database=app' \
-H 'X-ClickHouse-User: default' --data-binary 'SELECT count() FROM events'Options
| Interface | Detail |
|---|---|
| Native (clickhouse-client) | Port 9000, binary protocol, lowest overhead |
| HTTP (curl) | Port 8123, query in body or ?query= parameter |
| HTTP auth | X-ClickHouse-User / X-ClickHouse-Key headers or user:pass in URL |
| HTTP format | Append FORMAT to the query or use ?default_format= |
| HTTPS | Port 8443 when TLS is enabled |
In CI
Use HTTP via curl when the runner image does not ship clickhouse-client; it needs no extra install and is handy for a quick health check. Use the native client for bulk loads and scripts where its formats and performance matter. Whichever you pick, match the port: 9000 native, 8123 HTTP.
Common errors in CI
"Connection refused (localhost:9000)" from clickhouse-client often means the container only exposed 8123, or you targeted the HTTP port by mistake. From curl, "Port 9000 is for clickhouse-client program ... You must use port 8123 for HTTP" is the server telling you the native port was hit over HTTP. A 516 from HTTP means auth headers are missing or wrong.