cqlsh -e: Run a CQL Statement in CI
cqlsh -e "<CQL>" connects to Cassandra, runs one CQL statement, prints the result, and exits.
cqlsh is the CQL shell for Cassandra (and ScyllaDB). The -e flag is how a pipeline runs a query or DDL without dropping into the interactive prompt.
What it does
cqlsh -e executes the given CQL string against the connected node and exits with a status that reflects success or failure. It takes the contact host and port as positional arguments after the flags, defaulting to 127.0.0.1:9042.
Common usage
cqlsh -e "SELECT release_version FROM system.local" 127.0.0.1 9042
# create a keyspace
cqlsh -e "CREATE KEYSPACE IF NOT EXISTS app WITH replication = \
{'class':'SimpleStrategy','replication_factor':1}"
# with auth
cqlsh -u cassandra -p cassandra -e "DESCRIBE KEYSPACES"Options
| Flag | What it does |
|---|---|
| -e <cql> | Execute one CQL statement and exit |
| <host> <port> | Positional contact point (default 127.0.0.1 9042) |
| -u / -p | Username and password for authentication |
| -k <keyspace> | Use this keyspace for the session |
| --connect-timeout <s> | Seconds to wait when connecting |
| --request-timeout <s> | Seconds to wait for a request to complete |
In CI
Cassandra is slow to start, so a single cqlsh -e at job start often fails; wrap it in a retry loop or use a health check first. Pass an explicit --request-timeout for heavy DDL on a cold node, since the default can be too short while the cluster is still initializing.
Common errors in CI
"Connection error: ('Unable to connect to any servers', ...)" with "Connection refused" means the node is not listening yet. "Unable to connect to any servers ... ProtocolError" can mean a CQL native protocol version mismatch between cqlsh and the server; pin a version with --protocol-version. "AuthenticationFailed" means -u/-p are wrong or the authenticator is PasswordAuthenticator with default creds not yet set.