Install the CQL shell
The CQL shell (cqlsh) is a Python-based command-line shell you can use to issue Cassandra Query Language (CQL) statements to your Hyper-Converged Database (HCD) databases.
The CQL shell also provides unique cqlsh commands like DESCRIBE KEYSPACE.
There are several ways to access the CQL shell, depending on your environment:
| Environment | CQL shell | Notes |
|---|---|---|
HCD tarball installation |
A supported Python version is required |
|
HCD package installation |
A supported Python version is required |
|
HCD not installed |
A supported Python version is required |
|
HCD Docker container |
A supported Python version is required |
|
Mission Control |
No additional software is required, but you must have access to the Mission Control UI. For programmatic access, use the other methods. |
Install Python
CQL shell requires Python.
HCD 1.2 supports Python 3.8 to 3.13. HCD 1.2.6 or later is required for Python 3.12 or 3.13.
If you have multiple Python versions installed, run cqlsh in a virtual environment that uses a supported Python version.
To verify your Python version, run python -V.
Use the bundled CQL shell
Your HCD installation automatically includes cqlsh:
-
Package installations:
cqlshis installed automatically with HCD. You can runcqlshfrom your system’s command line if it is in your system’sPATH. Otherwise, run it from thebindirectory of your HCD installation. -
Tarball installations:
cqlshis installed automatically with HCD. You can runcqlshfrom thebindirectory of your HCD installation directory. -
HCD container:
cqlshis included with the container image. You can runcqlshfrom the HCDbindirectory inside the container, or start CQL shell withdocker exec. For an example, see Connect to an HCD container.
Install the standalone CQL shell
To install cqlsh without HCD, you need a cqlsh binary tarball.
This tarball is included with HCD tarball installation files on IBM Passport Advantage.
The cqlsh binary cannot be extracted from HCD DEB/RPM packages.
Separate cqlsh binary tarballs are no longer provided; you must download the HCD tarball installation files, and then extract the standalone cqlsh binary tarball.
If you installed HCD from a tarball, you can use the cqlsh binary from your original tarball installation files.
-
Get access to IBM Passport Advantage:
-
IBMid: An IBMid account with MFA enabled is required. If you don’t have one, create an IBMid account. If your organization uses Enterprise Federation (EF) for authentication with corporate credentials, see the IBMid EF documentation.
-
Site number: You must be authorized by your Site Primary or Secondary Contact.
-
Entitlement: You must have an active watsonx.data Premium Software Subscription and an HCD entitlement.
-
Temporary passcode (primary contact, initial setup only): If you are a primary contact, you need a temporary passcode from your welcome letter to initially connect your IBMid to your site number.
-
-
Download the HCD tarball installation files from IBM Passport Advantage:
-
Go to the Passport Advantage Online for Customers website and click Sign in to your PAO site.
-
Log in with your IBMid.
-
Select Software download from the top menu or the quick links list.
-
Search for the product by name or part number, or use the Find downloads & media tool to view your entitled products.
For the best search results, try one of the following:
-
Search by product name: Include the word
Versionin your search. For example, Hyper-Converged Database Version. -
Search by part number: Find part numbers for each release in the release notes.
If results show only eAssemblies, switch to the Images tab to find HCD under Analytics - Platform.
-
-
Select the version you need.
-
Select the files you need, agree to the terms and conditions, and then click Download now.
The download file is named
HCD_VERSION_NUMBER_EN.zip.
-
-
Unzip the downloaded file to access the included
cqlshbinary tarball (cqlsh-VERSION-bin.tar.gz). -
Extract the
cqlshdistribution into the directory where you want to installcqlsh:tar -xzvf cqlsh-VERSION-bin.tar.gz -C /PATH/TO/INSTALL/DIRECTORY -
Optional: Validate the signatures (
cqlsh-VERSION-bin.tar.gz.ascandcqlsh-VERSION-bin.tar.gz.cosign.sig), as explained in Validate tarball signatures.
