Connect via CQL¶

Authentication setup¶

For security, always enable authentication and authorization. Create a ConfigMap with the ScyllaDB configuration before deploying your cluster:

apiVersion: v1
kind: ConfigMap
metadata:
  name: scylladb-config
data:
  scylla.yaml: |
    authenticator: PasswordAuthenticator
    authorizer: CassandraAuthorizer

Reference this ConfigMap from your ScyllaCluster via scyllaConfig on each rack:

apiVersion: scylla.scylladb.com/v1
kind: ScyllaCluster
metadata:
  name: scylladb
spec:
  datacenter:
    racks:
    - name: us-east-1a
      scyllaConfig: scylladb-config
      # ...

After deployment, follow the Creating a Custom Superuser guide in the ScyllaDB documentation to replace the default cassandra superuser with a dedicated role.

Embedded cqlsh¶

Every ScyllaDB Pod includes a built-in cqlsh. This is the simplest way to run queries:

kubectl exec -it service/<cluster-name>-client -c scylla -- cqlsh -u <user>

kubectl exec -it pod/<cluster-name>-<datacenter>-<rack>-<ordinal> -c scylla -- cqlsh -u <user>

Password:
Connected to scylla at 0.0.0.0:9042
[cqlsh 6.0.32 | Scylla 2026.1.0-0.20260309.9190d42863d4 | CQL spec 3.3.1 | Native protocol v4]
Use HELP for help.
<user>@cqlsh>

Remote cqlsh with TLS¶

ScyllaDB Operator configures TLS certificates automatically. The encrypted CQL port 9142 works by default.

kubectl -n scylla get configmap <cluster-name>-local-serving-ca \
  --template='{{ index .data "ca-bundle.crt" }}' > ca.crt
kubectl -n scylla get secret <cluster-name>-local-user-admin \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > client.crt
kubectl -n scylla get secret <cluster-name>-local-user-admin \
  -o jsonpath='{.data.tls\.key}' | base64 -d > client.key

export SCYLLADB_CONFIG=/path/to/scylladb-config
mkdir -p "${SCYLLADB_CONFIG}"
cp ca.crt client.crt client.key "${SCYLLADB_CONFIG}/"
cat > "${SCYLLADB_CONFIG}/cqlshrc" <<EOF
[connection]
hostname = <cluster-name>-client.<namespace>.svc
port = 9142
ssl = true

[ssl]
certfile = ${SCYLLADB_CONFIG}/ca.crt
usercert = ${SCYLLADB_CONFIG}/client.crt
userkey = ${SCYLLADB_CONFIG}/client.key
validate = true

[authentication]
username = cassandra
password = <password>
EOF

cqlsh --cqlshrc="${SCYLLADB_CONFIG}/cqlshrc"

podman run -it --rm --entrypoint=cqlsh \
  -v="${SCYLLADB_CONFIG}:${SCYLLADB_CONFIG}:ro,Z" \
  -v="${SCYLLADB_CONFIG}/cqlshrc:/root/.cassandra/cqlshrc:ro,Z" \
  docker.io/scylladb/scylla:2026.1.3

docker run -it --rm --entrypoint=cqlsh \
  -v="${SCYLLADB_CONFIG}:${SCYLLADB_CONFIG}:ro" \
  -v="${SCYLLADB_CONFIG}/cqlshrc:/root/.cassandra/cqlshrc:ro" \
  docker.io/scylladb/scylla:2026.1.3

Driver configuration tips¶

When using a ScyllaDB or Cassandra driver in your application:

Related pages¶

• Discovery endpoint — how the client Service works and how to expose it.

• Alternator (DynamoDB API) — connecting via the DynamoDB-compatible API.

• Configure external access — connecting from outside the Kubernetes cluster.

• Security — TLS certificate management.