cockroach sql: The CockroachDB SQL Client
cockroach sql --url "postgresql://..." -e "SQL" runs a statement against a CockroachDB cluster.
CockroachDB speaks the PostgreSQL wire protocol, and its built-in client is cockroach sql. In CI you connect with a --url or discrete flags, run statements with -e or a file with --file, and decide between secure (certs) and --insecure mode.
What it does
cockroach sql opens a SQL shell to a CockroachDB node. It accepts a full connection --url (the same postgresql:// form psql uses) or discrete --host/--user/--database flags. -e runs one statement and exits; --file runs a script. Because Cockroach is secure by default, you either supply client certs or pass --insecure for a dev cluster.
Common usage
# insecure dev cluster, one statement
cockroach sql --insecure --host=db:26257 -e "SELECT 1"
# via a connection URL
cockroach sql --url "postgresql://root@db:26257/appdb?sslmode=disable" -e "SHOW TABLES"
# run a migration file securely
cockroach sql --certs-dir=certs --host=db:26257 --file=migrate.sqlOptions
| Flag | What it does |
|---|---|
| --url <uri> | Full postgresql:// connection string |
| --host <host:port> | Node address (default port 26257) |
| --user / --database | User and database (discrete form) |
| -e "<sql>" | Execute one statement and exit |
| --file <file> | Run SQL from a file |
| --insecure | Connect without TLS (dev only) |
| --certs-dir <dir> | Directory of client certificates (secure mode) |
In CI
A single-node dev cluster started with cockroach start-single-node --insecure pairs with cockroach sql --insecure for tests. Note the default port is 26257, not 5432. Because Cockroach is Postgres-compatible, generic psql and libpq drivers also connect, but cockroach sql bundles cluster-aware helpers. Wait for the node to be ready before the first query.
Common errors in CI
"ERROR: connection refused" or "failed to connect to ... dial tcp: connect: connection refused" means the node is not up or the port is wrong (26257). "problem using security settings ... no certificates found" means secure mode without --certs-dir; add the certs or use --insecure for dev. "password authentication failed" mirrors Postgres and means wrong credentials in the --url.