Using cqlsh to connect to Amazon Keyspaces - Amazon Keyspaces (for Apache Cassandra)

Using cqlsh to connect to Amazon Keyspaces

The following sections describe how to use cqlsh to connect to Amazon Keyspaces (for Apache Cassandra). First, you must get a digital certificate to encrypt your connections using Transport Layer Security (TLS). You can use the Starfield digital certificate to connect to Amazon Keyspaces.

Note

You can also use the Amazon digital certificate to connect to Amazon Keyspaces and can continue to do so if your client is connecting to Amazon Keyspaces successfully. The Starfield certificate provides additional backwards compatibility for clients using older certificate authorities.

For information about cqlsh, see cqlsh: the CQL shell.

Installing and Using cqlsh to Connect to Amazon Keyspaces (for Apache Cassandra)

To install and use cqlsh, you must do the following:

Note

To make cqlsh connections to Amazon Keyspaces for functional testing, light operations, and migrations you can use a preconfigured docker container that includes all prerequisites and configuration settings optimized for Amazon Keyspaces, and is available from https://github.com/aws-samples/amazon-keyspaces-toolkit.

Install Python 2.7

To determine whether you have Python installed on your computer and which version, run the following operation.

python --version

If you have Python 2.7 installed, you should see something like the following for output.

Python 2.7.16

If you need to install Python 2.7, follow the instructions at Python Downloads.

Install and Configure the CQL Client

Cqlsh is bundled with Apache Cassandra. To get it, install Apache Cassandra by following the instructions in Downloading and Installing Apache Cassandra. Amazon Keyspaces supports drivers and clients that are compatible with Apache Cassandra 3.11.2. The currently recommended version of cqlsh can be downloaded from Apache.

After installing Cassandra, verify that cqlsh is installed by running the following command.

cqlsh --version

You should see something like the following for output.

cqlsh 5.0.1

If you are using Windows, replace all instances of cqlsh with cqlsh.bat. For example, to check the version of cqlsh in Windows, run the following command.

cqlsh.bat --version

Download the configuration file cqlshrc optimized for Amazon Keyspaces from Github. Save the downloaded cqlshrc file to the Cassandra directory.

${HOME}/.cassandra/cqlshrc

Encrypting cqlsh Connections Using TLS

Amazon Keyspaces only accepts secure connections using Transport Layer Security (TLS).

Before you can connect using SSL/TLS, you must do the following:

  1. Download the Starfield digital certificate using the following command and save it to the path_to_file/ directory.

    Note

    You can also use the Amazon digital certificate to connect to Amazon Keyspaces and can continue to do so if your client is connecting to Amazon Keyspaces successfully. The Starfield certificate provides additional backwards compatibility for clients using older certificate authorities.

    curl https://certs.secureserver.net/repository/sf-class2-root.crt -O
  2. Connect to Amazon Keyspaces with the following command.

    Important

    The ServiceUserName and ServicePassword should match the ones obtained when you generated the service-specific credentials by following the steps in Generate Service-Specific Credentials.

    You can also manage Amazon Keyspaces cqlsh access through AWS IAM users and roles by using the AWS authentication plugin expansion for cqlsh. To learn more, see Amazon Keyspaces (for Apache Cassandra) developer toolkit on Github.

    cqlsh host 9142 -u ServiceUserName -p ServicePassword --ssl

    Note that 9142 is the secure port.

    The following is an example.

    cqlsh cassandra.us-east-2.amazonaws.com 9142 -u "alice-at-111122223333" -p "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" --ssl

    After connecting, you see something like the following for output. The currently supported version of Apache Cassandra is 3.11.2.

    Connected to Amazon Keyspaces at cassandra.us-east-2.amazonaws.com:9142. [cqlsh 5.0.1 | Cassandra 3.11.2 | CQL spec 3.4.4 | Native protocol v4] Use HELP for help. alice-at-111122223333@cqlsh>

Updating an existing configuration file for cqlsh connections

If you want to edit an existing configuration file to support TLS connections, open the configuration file in the Cassandra home directory, for example ${HOME}/.cassandra/cqlshrc and add the following lines.

[connection] port = 9142 factory = cqlshlib.ssl.ssl_transport_factory [ssl] validate = true certfile = path_to_file/sf-class2-root.crt

You can configure cqlsh COPY settings to ensure cqlsh stays within the Amazon Keyspaces CQL Query Throughput Tuning guidelines.

Modify the default for the COPY FROM option in the configuration file ${HOME}/.cassandra/cqlshrc and add the following lines.

[copy-from] CHUNKSIZE=50

This setting for CHUNKSIZE works well to get started with a newly created table and should be changed to support larger workloads. For more information on how to optimize cqlsh COPY configuration settings for Amazon Keyspaces, see Step 4: Configure cqlsh COPY FROM Settings in the data migration tutorial.