cockroach sql: Usage, Options & Common CI Errors
cockroach sql opens a Postgres-wire SQL client to a CockroachDB cluster.
cockroach sql runs schema and queries against a CockroachDB node in CI. Because Cockroach defaults to TLS, the first failures are usually about certificates or forgetting --insecure on a dev cluster.
What it does
cockroach sql connects to a CockroachDB node (which speaks the PostgreSQL wire protocol) and runs SQL interactively, from -e, or from a piped file. It uses TLS by default, so connections need either certificates or an explicit insecure flag.
Common usage
cockroach sql --insecure --host=localhost:26257 -e 'SELECT 1'
cockroach sql --url='postgresql://root@localhost:26257/app?sslmode=disable' -e 'SELECT 1'
cockroach sql --certs-dir=certs --host=db:26257 -e 'SHOW DATABASES'
cockroach sql --insecure --host=localhost:26257 < schema.sqlOptions
| Flag | What it does |
|---|---|
| --url "postgresql://..." | Full connection URL |
| --host <host:port> | Node host and port (default 26257) |
| --insecure | Disable TLS (dev/test clusters) |
| --certs-dir <dir> | Directory of client/CA certificates |
| -e "SQL" | Execute SQL and exit |
| -d / --database | Default database |
Common errors in CI
ERROR: cannot dial server ... connection refused means the node is not up yet or the port is wrong (Cockroach SQL is 26257, not 5432). On a secure cluster, "problem using security settings ... no certificates found" means --certs-dir is missing the client cert; for a dev container start it with --insecure and connect with --insecure (or sslmode=disable). A node that is still joining returns "node is not ready" - wait for it to become live.