Issue CQL commands with cqlsh in the Astra CLI
The Cassandra Query Language Shell (cqlsh) is a utility that you can use to issue CQL commands to your Astra DB databases.
The Astra CLI provides embedded cqlsh support by downloading and installing the cqlsh utility in the background and exposing it through the astra db cqlsh commands.
This can act as a convenient alternative to installing and configuring a standalone cqlsh.
The cqlsh utility isn’t installed by default with the Astra CLI.
The first time you run an astra db cqlsh command, the Astra CLI downloads and installs the cqlsh utility into the Astra CLI home directory (~/.astra).
All astra db cqlsh commands require a database name or ID.
The first time you connect to a specific database, Astra CLI downloads the database’s Secure Connect Bundle (SCB) into the Astra CLI home directory.
Prerequisites
The cqlsh commands require one of the following supported versions of Python with SSL/TLS:
-
Python 3.6 to 3.11
-
Python 2.7.12 or later
All other versions aren’t supported.
Any supported Python version must be installed on your system and available in your system’s PATH for the Astra CLI to use it with the cqlsh commands.
This version doesn’t need to be your system’s default Python version as long as it’s available in the PATH.
Troubleshoot ModuleNotFoundError and Python installation errors
If the Astra CLI reports ModuleNotFoundError after running any of the astra db cqlsh commands, make sure you have a supported Python version available in your system’s PATH.
The error A Python installation with SSL is required to connect to a cloud cluster means that the detected Python version doesn’t support TLS.
This typically happens with Python versions earlier than 2.7.12, which don’t support TLS.
Verify TLS support
To verify whether your current Python version supports TLS, run the following command:
python -c 'from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED'If TLS isn’t supported, the following error is returned:
Traceback (most recent call last):
File "<string>", line 1, in <module>
ImportError: cannot import name PROTOCOL_TLSStart an interactive cqlsh session
Use the astra db cqlsh start command to start cqlsh in interactive mode:
astra db cqlsh start DB_IDResult
[INFO] Patched cqlsh script to try known supported Python versions first
Connected to cndb at 127.0.0.1:9042.
[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4]
Use HELP for help.
token@cqlsh>To exit cqlsh, type exit or quit; and then press Enter.
Issue a CQL statement directly
Use the astra db cqlsh exec command to issue a CQL statement directly from your terminal without starting an interactive cqlsh session:
astra db cqlsh exec DB_ID "describe keyspaces;"Result
system_auth data_endpoint_auth default_keyspace system_views
my_keyspace system system_traces system_virtual_schema
system_schema datastax_sla my_keyspace2CQL statements must be enclosed in double quotes ("").
Execute a CQL file
Use the -f / --file option with the astra db cqlsh exec command to execute a CQL file:
astra db cqlsh exec DB_ID -f sample.cqlExample CQL file
-- Use a specific keyspace
USE default_keyspace;
-- Create a table
CREATE TABLE IF NOT EXISTS users (
id UUID PRIMARY KEY,
name TEXT,
email TEXT
);
-- Insert some data
INSERT INTO users (id, name, email) VALUES (uuid(), 'Alice', 'alice@example.com');
INSERT INTO users (id, name, email) VALUES (uuid(), 'Bob', 'bob@example.com');
-- Query the data
SELECT * FROM users;Result
id | email | name
--------------------------------------+-------------------+-------
8b901d74-ac31-48e2-a403-dbcee8efe935 | bob@example.com | Bob
0d712e1e-b764-4bbd-b587-579b75f29f32 | alice@example.com | Alice
(2 rows)Connect to a specific keyspace
Use the -k / --keyspace option with the astra db cqlsh start and astra db cqlsh exec commands to connect directly to a specific keyspace:
astra db cqlsh start DB_ID -k KEYSPACE_NAMEResult
Connected to cndb at 127.0.0.1:9042.
[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4]
Use HELP for help.
token@cqlsh:my_keyspace>astra db cqlsh exec DB_ID -k KEYSPACE_NAME "DESC TABLES"Result
repairs view_builds_in_progress paxos transferred_ranges
available_ranges peers size_estimates
batches compaction_history built_views
prepared_statements sstable_activity range_xfers
"IndexInfo" peer_events local