{"id":8913,"library":"cqlsh","title":"cqlsh","description":"cqlsh is a Python-based command-line client for running CQL commands on an Apache Cassandra cluster. It provides an interactive shell for executing CQL statements, managing data, and administering Cassandra. It is part of the Apache Cassandra project and is actively maintained with releases tied to Cassandra versions. The current PyPI version is 6.2.1.","status":"active","version":"6.2.1","language":"en","source_language":"en","source_url":"https://github.com/apache/cassandra","tags":["cassandra","database","cli","shell","apache"],"install":[{"cmd":"pip install cqlsh","lang":"bash","label":"Install cqlsh"}],"dependencies":[{"reason":"cqlsh uses the official DataStax Python Driver for Apache Cassandra internally to connect and interact with Cassandra clusters.","package":"cassandra-driver"},{"reason":"Used for handling geographic data types within CQL, particularly for geospatial functions.","package":"geomet","optional":true}],"imports":[{"note":"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.","wrong":"import cqlsh","symbol":"cqlsh functionality","correct":"from cassandra.cluster import Cluster"}],"quickstart":{"code":"import subprocess\nimport os\n\n# Ensure Cassandra is running, e.g., via Docker:\n# docker run --name my-cassandra -p 9042:9042 -d cassandra:latest\n\n# Execute a simple CQL command using cqlsh via subprocess\ntry:\n    # -e for executing a single command\n    # You can specify host/port if not localhost:9042\n    # e.g., ['cqlsh', 'your_host_ip', 'your_port', '-e', ...]\n    # If authentication is needed: ['cqlsh', '--username', 'user', '--password', 'pass', '-e', ...]\n    result = subprocess.run(\n        ['cqlsh', '-e', 'SELECT release_version FROM system.local;'],\n        capture_output=True,\n        text=True,\n        check=True # Raise an error for non-zero exit codes\n    )\n    print(\"cqlsh Output (Cassandra Release Version):\")\n    print(result.stdout.strip())\n    print(\"\\nSuccessfully connected and executed query.\")\nexcept FileNotFoundError:\n    print(\"Error: 'cqlsh' command not found. Make sure cqlsh is installed and in your system PATH.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error executing cqlsh: {e.returncode}\")\n    print(f\"Stderr: {e.stderr.strip()}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"< 6.0.0 (for Cassandra 4.x), general mismatch across major Cassandra versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Provide the necessary username and password using the `--username` and `--password` command-line options, or configure them in your `cqlshrc` file.","message":"Authentication failures (`AuthenticationFailed`). If your Cassandra cluster is configured to require authentication, `cqlsh` will fail to connect without valid credentials.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"The Cassandra cluster is not running or is not accessible on the specified host/port.","error":"Connection refused"},{"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.","cause":"The `cqlsh` executable is not in your system's PATH environment variable.","error":"cqlsh: command not found"},{"fix":"Provide a valid username and password using `cqlsh --username <user> --password <pass>` or configure credentials in your `~/.cqlshrc` file.","cause":"The Cassandra cluster requires authentication, but `cqlsh` was run without correct credentials, or with no credentials.","error":"AuthenticationFailed: Failed to authenticate to <ip-address>:9042"},{"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.","cause":"The CQL statement provided to `cqlsh` has a syntax error.","error":"ServerError: code=2000 [Syntax error in CQL query] message=\"line 1:XX no viable alternative at input '...'\""}]}