Scylla and cqlsh

About cqlsh

The cqlsh command is the standard way of connecting to Scylla databases.

Installing cqlsh

There are a number of ways of installing cqlsh. As it is a Python application, running pip install cqlsh will install the latest version of the command. As of writing, cqlsh is a Python 2.7 program and does not run with Python 3.

It is also possible to get cqlsh from a full distribution of Cassandra. This can be obtained from http://cassandra.apache.org/download/ which offers binary, source and instructions on how to install Cassandra on Debian (apt) and Red Hat (RPM) Linux distributions. Download a binary release and unpack the file into a directory. Then cd into that directory and you'll find cqlsh in the bin directory.

About cqlshrc files

When it is run the cqlsh command loads a file, $HOME/.cassandra/cqlshrc by default, which can set many parameters which are not settable in the command line. An Apache sample of cqlshrc. You can edit the default file to set parameters. These will apply to all sessions unless overridden on the command line.

If you are running multiple instances of Scylla in different environments, you can create a separate cqlshrc file and make cqlsh use it by adding --cqlshrc=[filename] to your command.

TLSv1.2

cqlsh does not default to TLSv1.2 when negotiating an encrypted connection. In order to successfully connect to a Compose Scylla deployment, the TLS version has to be specified in the environment running cqlsh. To get the most compatibility (and a bit of future-proofing for TLSv1.3) Set SSL_VERSION in the environment to SSLv23 using:
export SSL_VERSION=SSLv23
or place SSL_VERSION=SSLv23 before the cqlsh connection command.

You can also set the version specifically to TLSv1.2 using:
export SSL_VERSION=TLSv1_2
or place SSL_VERSION=TLSv1_2 before the cqlsh connection command.

Connecting Without Validating

The simplest way to connect to Scylla with TLS/SSL is without validating the remote host. This is not recommended for production. By default, validation is enabled. Validation is controlled by the environment variable SSL_VALIDATE or by SSL settings in the cqlshrc file. Set SSL_VALIDATE to false in your environment to disable validation:
export SSL_VALIDATE=false

Or you may add the following to your cqlshrc file.

[ssl]  
validate = false

If you want to only disable it for a single cqlsh command, place SSL_VALIDATE=false before the cqlsh connection command.

You do still have to tell cqlsh to use TLSv1.2, even when not validating the certificate. If you haven't set the ssl version in the environment and don't want to validate the connection should look like this example:

SSL_VERSION=SSLv23 SSL_VALIDATE=false cqlsh --ssl portal1204-7.sally-scylla.composedb.com 24981 -u scylla -p [password] --cqlversion=3.3.1

Obtaining and Using the Certificate

If you want to use cqlsh and verify the remote host you will need to obtain the certificate, save it somewhere accessible, and then provide the path to the certificate to cqlsh. A copy of the certificate lives in the Scylla and certificates page, as well as details about its contents and their source. Make a certificate file or save a copy locally.

Set the environment variable SSL_CERTFILE to the path and filename of your saved certificate to enable it for all subsequent invocations of cqlsh.

Alternatively, you could add the following to your cqlshrc file.

[ssl]
certfile = ~/path_to_your/lechain.pem
validate = true

If you only want to use a particular certificate for a single cqlsh command place SSL_CERTFILE = ~/path_to_your/lechain.pem at the start of your cqlsh connection command. For example:

SSL_VERSION=SSLv23 SSL_CERTFILE='~/path_to_your/lechain.pem' cqlsh --ssl portal1204-7.sally-scylla.composedb.com 24981 -u scylla -p [password] --cqlversion=3.3.1

cqlshrc for Compose

This is the minimal cqlshrc file when connecting to a Compose Scylla deployment:

[authentication]
username = scylla
password = [password]

[connection]
hostname = [hostname.composedb.com]
port = [portnumber]
factory = cqlshlib.ssl.ssl_transport_factory

[ssl]
version=SSLv23
certfile = ~/.cassandra/lechain.pem
validate = true

Running cqlsh --ssl --cqlshrc=example.cqlshrc and you will be logged into your Scylla database. Note that even though cqlshrc has an option for specifying ssl=true it appears to be ignored so the --ssl flag must be used.

Using cqlsh

The cqlsh shell offers a wide range of cql and its own commands. Information on these commands can be obtained through the help command:

For example, we can create a keyspace, use it and create a table in that space. Here's the interaction with the shell:

[email protected]> CREATE KEYSPACE example_keyspace WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3 };
[email protected]> use example_keyspace ;
[email protected]:example_keyspace> create table names (
                    ... name_id uuid,
                    ... last_name text,
                    ... first_name text,
                    ... PRIMARY KEY(name_id)
                    ... );
[email protected]:example_keyspace>

It is worth noting that cqlsh has extensive autocompletion. Pressing [TAB] will invoke it. Taking the "Create Keyspace" command, we actually typed

CR[TAB] K[TAB] example_keys [TAB]S[TAB][TAB]3 };

Still Need Help?

If this article didn't solve things, summon a human and get some help!