cqlsh: Usage, Options & Common CI Errors
cqlsh runs CQL against an Apache Cassandra or ScyllaDB cluster.
cqlsh seeds keyspaces and runs schema for Cassandra in CI. The hard part is that Cassandra takes a while to accept CQL after the container starts, so naive runs fail with connection-refused.
What it does
cqlsh connects to a Cassandra node over the native CQL protocol and runs CQL statements interactively, from -e, or from a -f file. It is the standard tool for creating keyspaces and tables and loading fixtures.
Common usage
cqlsh 127.0.0.1 9042 -e 'DESCRIBE KEYSPACES'
cqlsh 127.0.0.1 -u cassandra -p cassandra -f schema.cql
until cqlsh 127.0.0.1 -e 'SELECT now() FROM system.local'; do sleep 2; done
cqlsh 127.0.0.1 --cqlversion=3.4.5 -e 'DESCRIBE CLUSTER'Options
| Flag | What it does |
|---|---|
| <host> <port> | Node host and native port (default 9042) |
| -e "CQL" | Run one statement and exit |
| -f <file> | Run CQL from a file |
| -u / -p | Username / password (if auth enabled) |
| -k <keyspace> | Use this keyspace by default |
| --cqlversion <v> | Force a CQL protocol version |
Common errors in CI
Connection error: ... Connection refused - Cassandra is slow to start; the CQL port opens well after the container does, so loop on a trivial cqlsh query until it succeeds (often 30-60s). "Unable to connect to any servers ... ProtocolError" is a client/server CQL-version mismatch; pin --cqlversion. "AuthenticationFailed" means auth is enabled and -u/-p are needed. cqlsh requires a Python runtime in the image.