ClickHouse "Connection refused" on 8123/9000 (service not ready) in CI

ClickHouse serves HTTP on 8123 and the native protocol on 9000. It binds those ports only after loading metadata and databases at startup. A job that connects immediately hits "Connection refused" until the server is ready.

What this error means

A client fails with "Connection refused" (HTTP curl to 8123, or "Code: 210. DB::NetException ... Connection refused" on 9000) right after the container starts.

clickhouse-client

Code: 210. DB::NetException: Connection refused (localhost:9000).
(NETWORK_ERROR)

Common causes

The server has not bound its ports yet

ClickHouse logs "Ready for connections" only after startup completes; before that, both 8123 and 9000 refuse connections.

No readiness probe before the query step

The workflow queries the server as soon as the container exists, before it finishes loading.

How to fix it

Poll the HTTP ping endpoint until ready

Curl /ping on 8123 until it returns "Ok.".
Then run a real query to confirm the native port too.
Start tests only after both succeed.

Terminal

until curl -fs http://127.0.0.1:8123/ping | grep -q Ok; do
  echo "waiting for clickhouse"; sleep 2
done
clickhouse-client --host 127.0.0.1 --query "SELECT 1"

Add a container health check on /ping

Gate dependent steps on the HTTP ping so they only run once ClickHouse is ready.

.github/workflows/ci.yml

services:
  clickhouse:
    image: clickhouse/clickhouse-server:24.8
    ports: ['8123:8123', '9000:9000']
    options: --health-cmd "wget -qO- http://localhost:8123/ping" --health-retries 12

How to prevent it

Gate on /ping returning Ok before querying.
Probe both the HTTP and native ports if you use both.
Pin the server image tag for predictable startup.