cqlsh

Common errors

• Connection refused

  cause The Cassandra cluster is not running or is not accessible on the specified host/port.
  fix Start your Cassandra cluster. Verify Cassandra's listening address and port (e.g., `netstat -tulnp | grep 9042` on Linux). Use `cqlsh <host> <port>` if Cassandra is not on the default `localhost:9042`.

• cqlsh: command not found

  cause The `cqlsh` executable is not in your system's PATH environment variable.
  fix Ensure `cqlsh` is installed (`pip install cqlsh`). Locate the installation directory for Python scripts (e.g., `~/.local/bin` or `C:\Python\Scripts`) and add it to your system's PATH. Restart your terminal.

• AuthenticationFailed: Failed to authenticate to <ip-address>:9042

  cause The Cassandra cluster requires authentication, but `cqlsh` was run without correct credentials, or with no credentials.
  fix Provide a valid username and password using `cqlsh --username <user> --password <pass>` or configure credentials in your `~/.cqlshrc` file.

• ServerError: code=2000 [Syntax error in CQL query] message="line 1:XX no viable alternative at input '...'"

  cause The CQL statement provided to `cqlsh` has a syntax error.
  fix Carefully review the CQL query for typos, missing keywords, incorrect punctuation, or features not supported by your specific Cassandra version. Consult the Apache Cassandra CQL documentation.

Warnings

• breaking cqlsh version compatibility with Cassandra server versions. Using an cqlsh version significantly different from your Cassandra cluster can lead to missing features, unexpected behavior, or connection errors due to protocol mismatches.
  Fix: Always try to use a `cqlsh` version that is compatible with your Cassandra cluster version. Generally, `cqlsh` from the same major Cassandra distribution is recommended. For example, use cqlsh 6.x for Cassandra 4.x.
• gotcha Connection refused or NoHostAvailable error. `cqlsh` requires a running Cassandra cluster to connect to. If the cluster is down, inaccessible, or on a different host/port, connection attempts will fail.
  Fix: Ensure your Cassandra cluster is running and listening on the expected host and port (default is localhost:9042). Verify network connectivity. Use `cqlsh <host> <port>` to specify the connection details if not default.
• gotcha Authentication failures (`AuthenticationFailed`). If your Cassandra cluster is configured to require authentication, `cqlsh` will fail to connect without valid credentials.
  Fix: Provide the necessary username and password using the `--username` and `--password` command-line options, or configure them in your `cqlshrc` file.
• gotcha `cqlsh` is a command-line tool, not a Python library for direct import. Attempting to `import cqlsh` for programmatic interaction with Cassandra will not work as expected.
  Fix: For programmatic interaction with Cassandra from Python, use the `cassandra-driver` library (e.g., `from cassandra.cluster import Cluster`). To execute `cqlsh` commands from Python, use `subprocess`.

Install

• pip install cqlsh Install cqlsh

Imports

• cqlsh functionality
  wrong:

  import cqlsh

  correct:

  from cassandra.cluster import Cluster

  The `cqlsh` package provides a command-line client. It is not designed for direct programmatic import as a library. For programmatic interaction with Cassandra from Python, use the `cassandra-driver` library (e.g., `from cassandra.cluster import Cluster`), which `cqlsh` itself depends on.

Quickstart

This quickstart demonstrates how to invoke the `cqlsh` command-line tool from Python using the `subprocess` module to execute a CQL query. It checks for the Cassandra release version. Ensure a Cassandra cluster is running and accessible (e.g., on localhost:9042) before running this code.

import subprocess
import os

# Ensure Cassandra is running, e.g., via Docker:
# docker run --name my-cassandra -p 9042:9042 -d cassandra:latest

# Execute a simple CQL command using cqlsh via subprocess
try:
    # -e for executing a single command
    # You can specify host/port if not localhost:9042
    # e.g., ['cqlsh', 'your_host_ip', 'your_port', '-e', ...]
    # If authentication is needed: ['cqlsh', '--username', 'user', '--password', 'pass', '-e', ...]
    result = subprocess.run(
        ['cqlsh', '-e', 'SELECT release_version FROM system.local;'],
        capture_output=True,
        text=True,
        check=True # Raise an error for non-zero exit codes
    )
    print("cqlsh Output (Cassandra Release Version):")
    print(result.stdout.strip())
    print("\nSuccessfully connected and executed query.")
except FileNotFoundError:
    print("Error: 'cqlsh' command not found. Make sure cqlsh is installed and in your system PATH.")
except subprocess.CalledProcessError as e:
    print(f"Error executing cqlsh: {e.returncode}")
    print(f"Stderr: {e.stderr.strip()}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")