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 database.
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
To use cqlsh commands, you must have a supported version of Python installed on your system.
The underlying cqlsh utility requires Python 2.7 with TLS support, or any version of Python from 3.6 through 3.11.
Python versions 3.12 and later are not supported.
For more details, see this support article
Any supported version of Python must be available in your system’s PATH for the Astra CLI to use it.
It does not require that the supported version be your system’s default version of Python.
If the Astra CLI reports ModuleNotFoundError after running any of the astra db cqlsh commands, you might not have a supported version of Python available in your system’s PATH.
Start 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