Skip to content

cql xrefs #55

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aimurphy merged 1 commit into from
Oct 15, 2026
Merged

cql xrefs #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 0 additions & 142 deletions in-progress/managing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2574,56 +2574,12 @@ OPTIONS
Database name (if unique) or Database identifier
----

[#cqlsh]
== Use `cqlsh`

`cqlsh` is an interface that you can use to issue xref:astra@cql:ROOT:index.adoc[{cql}] commands to your database.
The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wrapping the `cqlsh` utility.
This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh].

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 Python 3.6--3.11.
Python versions 3.12 and later are not supported.

Use the `astra db cqlsh` command to start `cqlsh` in interactive mode:

[source,bash,subs="+quotes"]
----
astra db cqlsh **DATABASE_ID**
----

.Result
[source,console]
----
[INFO] Downloading Cqlshell, please wait...
[INFO] Installing archive, please wait...
[INFO] Cqlsh is starting, please wait for connection establishment...
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>
----

Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`.

The first time you use the `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility to the {product} installation directory (`~/.astra/cqlsh-astra`).
The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory.

[TIP]
====
If the {product} reports `ModuleNotFoundError`, check that you have a supported version of Python available in your terminal:

[source,bash]
----
python -V
----

.Result
[source,console]
----
Python 3.11.10
----
====

=== `db cqlsh` options

Expand Down Expand Up @@ -2699,104 +2655,6 @@ OPTIONS
Database name (if unique) or Database identifier
----

Use the `-k` / `--keyspace` option to connect directly to a specific keyspace:

[source,bash,subs="+quotes"]
----
astra db cqlsh **DATABASE_ID** -k **KEYSPACE_NAME**
----

.Result
[source,console]
----
[INFO] Cqlsh is starting, please wait for connection establishment...
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:keyspace2>
----

Use the `-e` / `--execute` option to execute a CQL statement:

[source,bash,subs="+quotes"]
----
astra db cqlsh **DATABASE_ID** -e "describe keyspaces;"
----

.Result
[source,console]
----
[INFO] Cqlsh is starting, please wait for connection establishment...

system_auth data_endpoint_auth system_traces
datastax_sla default_keyspace system_virtual_schema
system_schema system system_views
----

Use the `-f` / `--file` option to execute a CQL file:

[source,bash,subs="+quotes"]
----
astra db cqlsh **DATABASE_ID** -f sample.cql
----

.sample.cql (Example CQL file)
[source,cql]
----
-- Use a specific keyspace
USE keyspace1;

-- 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
[source,console]
----
[INFO] Cqlsh is starting, please wait for connection establishment...

id | email | name
--------------------------------------+-------------------+-------
62a32f14-5432-4a28-add7-761d3626373e | bob@example.com | Bob
0a489e53-0eed-4385-81a6-081143c228f1 | alice@example.com | Alice

(2 rows)
----

[TIP]
====
You can also execute a CQL file using the `xref:astra@cql:cqlsh:cqlsh-commands/source.adoc[]` CQL command:

[source,bash,subs="+quotes"]
----
astra db cqlsh **DATABASE_ID** -e "SOURCE 'sample.cql'"
----

.Result
[source,cql]
----
[INFO] Cqlsh is starting, please wait for connection establishment...

id | email | name
--------------------------------------+-------------------+-------
62a32f14-5432-4a28-add7-761d3626373e | bob@example.com | Bob
0a489e53-0eed-4385-81a6-081143c228f1 | alice@example.com | Alice

(2 rows)
----
====

== Use {dsbulk}

The https://github.com/datastax/dsbulk[{dsbulk}] lets you load, unload, and count data in your database tables.
Expand Down
9 changes: 6 additions & 3 deletions modules/quickstarts/pages/cqlsh.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
= Issue CQL commands with {cql-shell} in the {product}
:navtitle: CQL quickstart

The {cql-shell} (`cqlsh`) is a utility that you can use to issue xref:astra@cql:reference:cql-quick-reference.adoc[{cql} commands] to your {astra-db} databases.
The {cql-shell} (`cqlsh`) is a utility that you can use to interact with your {astra-db} databases with xref:astra-db-serverless:cql:reference/cql-syntax.adoc[{cql} statements] and unique `cqlsh` commands like `DESCRIBE` and `TRACING`.

The {product} provides built-in `cqlsh` support by downloading and installing the `cqlsh` utility in the background, and then exposing it through the `xref:commands:astra-db-cqlsh.adoc[]` commands.
The {product} provides built-in `cqlsh` support by downloading and installing the `cqlsh` utility in the background, and then exposing it through the `xref:commands:astra-db-cqlsh.adoc[astra db cqlsh]` commands.
This is a command line-based alternative to the embedded {cql-console} in the {astra-ui}.

The `cqlsh` utility isn't installed by default with the {product}.
Expand All @@ -12,11 +12,12 @@ The first time you run an `astra db cqlsh` command, the {product} downloads and
All `astra db cqlsh` commands require a database name or ID.
The first time you connect to a specific database, {product} downloads the database's {scb} into the {product} home directory.

For more information about CQL for {astra-db}, see xref:astra-db-serverless:cql:develop-with-cql.adoc[].
For more information about CQL and {cql-shell} for {astra-db}, see xref:astra-db-serverless:cql:develop-with-cql.adoc[].

[#prerequisites]
== Prerequisites

//Might be up to 3.13?
The `cqlsh` commands require Python 3.8 to 3.11.

The supported Python version must be installed on your system _and_ available in your system's `PATH` for the {product} to use it with the `cqlsh` commands.
Expand Down Expand Up @@ -132,6 +133,8 @@ The result is printed to the terminal:
(2 rows)
----

You can also execute a CQL file using the {cql-shell} `xref:astra-db-serverless:cql:cqlsh/cqlsh-commands/source.adoc[SOURCE]` command.

== Connect to a specific keyspace

Use the `-k` / `--keyspace` option to connect directly to a specific keyspace:
Expand Down
Loading