CockroachDB "connection refused" on port 26257 in CI

By Daniel Zoghalchali·Latchkey

CockroachDB serves SQL on port 26257. A single-node CI container must finish starting (and, for a fresh cluster, be initialized) before it accepts connections. Connecting too early returns "connection refused".

What this error means

A psql or driver connection to 26257 fails with "connection refused" or "dial tcp 127.0.0.1:26257: connect: connection refused" right after the container starts.

psql: error: connection to server at "127.0.0.1", port 26257 failed:
Connection refused
	Is the server running on that host and accepting TCP/IP connections?

Common causes

The node has not finished starting

Cockroach logs "CockroachDB node starting" and then "nodeID:" once ready; before that, the SQL port is not accepting connections.

A single-node cluster was never initialized

Using cockroach start without cockroach init (or without start-single-node) leaves the cluster uninitialized and not serving SQL.

How to fix it

Use start-single-node and wait for readiness

1. Start the node with start-single-node --insecure so it self-initializes.
2. Poll the SQL port until a query succeeds.
3. Run migrations only after the probe passes.

until cockroach sql --insecure --host=127.0.0.1:26257 -e "SELECT 1" >/dev/null 2>&1; do
  echo "waiting for cockroachdb"; sleep 3
done

Add a health check on the HTTP endpoint

CockroachDB exposes a health endpoint on the admin port; gate dependent steps on it.

services:
  crdb:
    image: cockroachdb/cockroach:latest-v24.1
    ports: ['26257:26257', '8080:8080']
    options: --health-cmd "curl -f http://localhost:8080/health?ready=1" --health-retries 12

How to prevent it

• Prefer start-single-node for CI so no separate init is needed.
• Gate on a real SQL probe or the readiness endpoint.
• Pin the Cockroach image tag for consistent startup.

Frequently asked questions

Related guides

References

• GitHub Actions documentation