cqlsh-rs

cqlsh-rs is a ground-up Rust re-implementation of the Python cqlsh — the official interactive CQL shell for Apache Cassandra and compatible databases (ScyllaDB, Amazon Keyspaces, Astra DB).

Why cqlsh-rs?

• Single static binary — no Python runtime, no pip, no virtualenv
• Fast startup — launches in milliseconds, not seconds
• 100% CLI compatible — drop-in replacement for the Python cqlsh
• Modern terminal experience — syntax highlighting, tab completion, pager integration
• Cross-platform — Linux, macOS, Windows

How to use this documentation

• New users: Start with Getting Started
• Installing: See Installation for all platforms
• Migrating from Python cqlsh: Read the Migration Guide
• Reference: Browse CLI Reference, Command Reference, and Configuration Reference
• Having issues?: Check Troubleshooting

Getting Started

This guide walks you through installing cqlsh-rs and connecting to your first Cassandra cluster.

Prerequisites

• A running Apache Cassandra, ScyllaDB, or compatible database
• Network access to the database’s native transport port (default: 9042)

Quick install

The fastest way to get started:

cargo install --git https://github.com/fruch/cqlsh-rs.git

See Installation for more options (Homebrew, Docker, pre-built binaries).

Connect to a cluster

# Connect to localhost:9042
cqlsh-rs

# Connect to a specific host
cqlsh-rs 10.0.0.1

# Connect to a specific host and port
cqlsh-rs 10.0.0.1 9043

Run your first query

Once connected, you’ll see the interactive prompt:

cqlsh>

Try a few commands:

-- Show cluster info
DESCRIBE CLUSTER;

-- List keyspaces
DESCRIBE KEYSPACES;

-- Query system tables
SELECT cluster_name, release_version FROM system.local;

Execute a single statement

Use -e to run a statement and exit:

cqlsh-rs -e "SELECT * FROM system.local"

Execute a CQL file

Use -f to run statements from a file:

cqlsh-rs -f schema.cql

Connect with authentication

cqlsh-rs -u cassandra -p cassandra

Connect with SSL/TLS

cqlsh-rs --ssl

See Configuration Reference for full SSL setup.

Use a specific keyspace

cqlsh-rs -k my_keyspace

Or switch keyspaces inside the shell:

USE my_keyspace;

Next steps

• CLI Reference — all command-line flags
• Command Reference — shell commands (DESCRIBE, COPY, etc.)
• Configuration Reference — cqlshrc file format
• Migration Guide — moving from Python cqlsh

Installation

From source (cargo)

Requires Rust 1.70+.

# Install from the repository
cargo install --git https://github.com/fruch/cqlsh-rs.git

# Or clone and install locally
git clone https://github.com/fruch/cqlsh-rs.git
cd cqlsh-rs
cargo install --path .

The binary is installed to ~/.cargo/bin/cqlsh-rs.

Pre-built binaries

Download pre-built binaries from GitHub Releases:

# Example: Linux x86_64
curl -LO https://github.com/fruch/cqlsh-rs/releases/latest/download/cqlsh-rs-x86_64-unknown-linux-gnu.tar.gz
tar xzf cqlsh-rs-x86_64-unknown-linux-gnu.tar.gz
sudo mv cqlsh-rs /usr/local/bin/

Homebrew (macOS/Linux)

brew install fruch/tap/cqlsh-rs

Docker

# Run interactively
docker run --rm -it ghcr.io/fruch/cqlsh-rs:latest

# Connect to a specific host
docker run --rm -it ghcr.io/fruch/cqlsh-rs:latest 10.0.0.1

# Execute a statement
docker run --rm ghcr.io/fruch/cqlsh-rs:latest -e "SELECT * FROM system.local" 10.0.0.1

Building from source

git clone https://github.com/fruch/cqlsh-rs.git
cd cqlsh-rs
cargo build --release

The binary is at target/release/cqlsh-rs.

Shell completions

Generate shell completion scripts for your shell:

# Bash
cqlsh-rs --completions bash > /etc/bash_completion.d/cqlsh-rs

# Zsh
cqlsh-rs --completions zsh > ~/.zfunc/_cqlsh-rs

# Fish
cqlsh-rs --completions fish > ~/.config/fish/completions/cqlsh-rs.fish

# PowerShell
cqlsh-rs --completions powershell > cqlsh-rs.ps1

# Elvish
cqlsh-rs --completions elvish > cqlsh-rs.elv

Verifying the installation

cqlsh-rs --version

Configuration Reference

cqlsh-rs reads configuration from ~/.cassandra/cqlshrc by default. Override the path with --cqlshrc.

This is the same INI-format configuration file used by the Python cqlsh. All sections and keys are fully compatible.

File format

The cqlshrc file uses standard INI format:

[section]
key = value

Example cqlshrc

[authentication]
username = cassandra
password = cassandra

[connection]
hostname = 127.0.0.1
port = 9042
connect_timeout = 5
request_timeout = 10

[ssl]
certfile = /path/to/ca-cert.pem
validate = true

[ui]
color = on
datetimeformat = %Y-%m-%d %H:%M:%S%z
float_precision = 5
encoding = utf-8

[csv]
field_size_limit = 131072

[copy]
numprocesses = 4
maxattempts = 5

[copy-to]
pagesize = 1000
pagetimeout = 10

[copy-from]
chunksize = 1000
ingestrate = 100000

[tracing]
max_trace_wait = 10.0

Sections

Precedence

Configuration values are resolved in this order (highest priority first):

1. CLI flags
2. Environment variables
3. cqlshrc file values
4. Built-in defaults

[authentication]

Credentials for connecting to the cluster.

[authentication]
username = cassandra
password = cassandra
credentials = /path/to/credentials
keyspace = my_keyspace

Keys

Notes

• CLI flags (-u, -p, -k) take precedence over cqlshrc values.
• The credentials file is read if username/password are not set directly.

[connection]

Network and timeout settings.

[connection]
hostname = 127.0.0.1
port = 9042
factory = cqlshlib.ssl.ssl_transport_factory
timeout = 10
connect_timeout = 5
request_timeout = 10
client_timeout = 120

Keys

[ssl]

SSL/TLS certificate and validation settings.

[ssl]
certfile = /path/to/ca-cert.pem
validate = true
userkey = /path/to/client-key.pem
usercert = /path/to/client-cert.pem
version = TLSv1_2

Keys

[certfiles] section

Map per-host certificate files:

[certfiles]
10.0.0.1 = /path/to/cert-host1.pem
10.0.0.2 = /path/to/cert-host2.pem

Enabling SSL

1. Set --ssl on the command line, or
2. Set factory = cqlshlib.ssl.ssl_transport_factory in [connection]

Example: mutual TLS

[connection]
factory = cqlshlib.ssl.ssl_transport_factory

[ssl]
certfile = /etc/cassandra/ssl/ca-cert.pem
userkey = /etc/cassandra/ssl/client-key.pem
usercert = /etc/cassandra/ssl/client-cert.pem
validate = true

cqlsh-rs --ssl 10.0.0.1

[ui]

Display and formatting settings.

[ui]
color = on
datetimeformat = %Y-%m-%d %H:%M:%S%z
timezone = UTC
float_precision = 5
double_precision = 12
max_trace_wait = 10.0
encoding = utf-8
completekey = tab
browser = open %s

Keys

[cql]

CQL protocol settings.

[cql]
version = 3.4.5

Keys

[csv]

CSV parsing settings for COPY operations.

[csv]
field_size_limit = 131072

Keys

[copy] / [copy-to] / [copy-from]

Default options for COPY TO and COPY FROM operations. Values here can be overridden with WITH clauses in the COPY command.

[copy] — shared defaults

[copy]
numprocesses = 4
maxattempts = 5
reportfrequency = 0.25

[copy-to] — export defaults

[copy-to]
pagesize = 1000
pagetimeout = 10
maxrequests = 6
maxoutputsize = -1
floatprecision = 5
doubleprecision = 12

[copy-from] — import defaults

[copy-from]
chunksize = 1000
ingestrate = 100000
maxbatchsize = 20
minbatchsize = 2
maxparseerrors = -1
maxinserterrors = -1
preparedstatements = true
ttl = -1

[tracing]

Request tracing settings.

[tracing]
max_trace_wait = 10.0

Keys

Usage

Enable tracing in the shell with:

TRACING ON

Then each CQL statement will show trace output. View a specific trace with:

SHOW SESSION <trace-uuid>

CLI Reference

Complete reference for all cqlsh-rs command-line flags and arguments.

Synopsis

cqlsh-rs [OPTIONS] [host] [port]

Positional arguments

Options

Connection

Authentication

Execution

Note: --execute and --file are mutually exclusive.

Display

Note: --color and --no-color are mutually exclusive.

Configuration

Behavior

Utility

Environment variables

Precedence

Configuration values are resolved in this order (highest priority first):

1. CLI flags
2. Environment variables
3. cqlshrc file
4. Built-in defaults

Command Reference

Shell commands available in the cqlsh-rs interactive prompt. These are distinct from CQL statements — they control the shell itself.

Quick reference

CQL statements

All standard CQL statements (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, etc.) are sent directly to the database for execution. Terminate statements with a semicolon (;).

CAPTURE

Capture query output to a file (tee-style — output is shown and saved).

Syntax

CAPTURE '<filename>'
CAPTURE OFF
CAPTURE

Usage

cqlsh> CAPTURE '/tmp/output.txt'
Now capturing query output to '/tmp/output.txt'.

cqlsh> SELECT * FROM system.local;
-- output shown AND written to file --

cqlsh> CAPTURE
Currently capturing to '/tmp/output.txt'.

cqlsh> CAPTURE OFF
Stopped capture. Output saved to '/tmp/output.txt'.

Notes

• Disabled when --no-file-io is used.
• The file is created (or truncated) when CAPTURE is started.
• Tilde (~) in paths is expanded to the home directory.

CLEAR

Clear the terminal screen.

Syntax

CLEAR
CLS

Usage

cqlsh> CLEAR

Both CLEAR and CLS are accepted.

CONSISTENCY

Get or set the consistency level for subsequent CQL statements.

Syntax

CONSISTENCY
CONSISTENCY <level>

Levels

ANY, ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM, LOCAL_ONE

Usage

cqlsh> CONSISTENCY
Current consistency level is ONE.

cqlsh> CONSISTENCY QUORUM
Consistency level set to QUORUM.

Notes

• The default consistency level is ONE.
• Can be set at startup with --consistency-level.
• For lightweight transactions, see SERIAL CONSISTENCY.

COPY TO

Export table data to a CSV file or stdout.

Syntax

COPY [keyspace.]table [(column1, column2, ...)] TO 'filename'|STDOUT [WITH option = value [AND ...]]

Options

Examples

-- Export entire table
COPY users TO '/tmp/users.csv';

-- Export specific columns with headers
COPY users (id, name, email) TO '/tmp/users.csv' WITH HEADER = true;

-- Export to stdout
COPY users TO STDOUT;

-- Export with custom delimiter
COPY users TO '/tmp/users.tsv' WITH DELIMITER = '\t' AND HEADER = true;

Notes

• Disabled when --no-file-io is used (except TO STDOUT).
• See the COPY Guide for detailed usage and performance tips.

COPY FROM

Import CSV data into a table.

Syntax

COPY [keyspace.]table [(column1, column2, ...)] FROM 'filename'|STDIN [WITH option = value [AND ...]]

Options

Examples

-- Import from file
COPY users FROM '/tmp/users.csv';

-- Import with headers
COPY users FROM '/tmp/users.csv' WITH HEADER = true;

-- Import specific columns
COPY users (id, name) FROM '/tmp/users.csv' WITH HEADER = true;

-- Import from stdin
COPY users FROM STDIN;

Notes

• Disabled when --no-file-io is used (except FROM STDIN).
• See the COPY Guide for detailed usage and performance tips.

DEBUG

Toggle debug output mode.

Syntax

DEBUG
DEBUG ON
DEBUG OFF

Usage

cqlsh> DEBUG
Debug output is currently disabled. Use DEBUG ON to enable.

cqlsh> DEBUG ON
Now printing debug output.

Notes

• Can also be enabled at startup with --debug.
• When enabled, additional diagnostic information is printed for each query.

DESCRIBE

Schema introspection commands. DESC is accepted as a shorthand.

Syntax

DESCRIBE CLUSTER
DESCRIBE KEYSPACES
DESCRIBE KEYSPACE [name]
DESCRIBE TABLES
DESCRIBE TABLE <name>
DESCRIBE SCHEMA
DESCRIBE FULL SCHEMA
DESCRIBE INDEX <name>
DESCRIBE MATERIALIZED VIEW <name>
DESCRIBE TYPES
DESCRIBE TYPE <name>
DESCRIBE FUNCTIONS
DESCRIBE FUNCTION <name>
DESCRIBE AGGREGATES
DESCRIBE AGGREGATE <name>

Subcommands

Examples

cqlsh> DESCRIBE KEYSPACES;
system    system_auth    system_distributed    my_app

cqlsh> DESC TABLE my_app.users;
CREATE TABLE my_app.users (
    id uuid PRIMARY KEY,
    name text,
    email text
) WITH ...

EXIT / QUIT

Exit the cqlsh-rs shell.

Syntax

EXIT
QUIT

You can also press Ctrl-D to exit.

EXPAND

Toggle expanded (vertical) output mode. In expanded mode, each row is displayed as a vertical list of column-value pairs instead of a horizontal table.

Syntax

EXPAND
EXPAND ON
EXPAND OFF

Usage

cqlsh> EXPAND ON
Now printing expanded output.

cqlsh> SELECT * FROM system.local;
@ Row 1
-----------+---------------------------
 key       | local
 ...

cqlsh> EXPAND OFF
Disabled expanded output.

Notes

• Useful for tables with many columns that don’t fit horizontally.
• Similar to \x in PostgreSQL’s psql.

HELP

Show help information.

Syntax

HELP
HELP <topic>
?

Usage

cqlsh> HELP
Documented shell commands:
  CAPTURE       Capture output to file
  CLEAR         Clear the terminal screen
  CONSISTENCY   Get/set consistency level
  ...

cqlsh> HELP COPY

Topics

Shell command topics: CAPTURE, CLEAR, CONSISTENCY, COPY, DESCRIBE, EXIT, EXPAND, LOGIN, PAGING, QUIT, SERIAL, SHOW, SOURCE, TRACING, UNICODE, DEBUG, USE

CQL topics: SELECT, INSERT, UPDATE, DELETE, CREATE_KEYSPACE, CREATE_TABLE, ALTER_TABLE, DROP_TABLE, USE, TRUNCATE, GRANT, REVOKE, and more.

LOGIN

Re-authenticate with new credentials without restarting the shell.

Syntax

LOGIN <username> [<password>]

If the password is omitted, you will be prompted to enter it.

Usage

cqlsh> LOGIN admin
Password: ****
Login successful.

cqlsh> LOGIN admin secretpass
Login successful.

Notes

• Creates a new connection to the cluster with the provided credentials.
• The current session state (keyspace, consistency level, etc.) may be reset.

PAGING

Configure automatic output paging through the built-in pager.

Syntax

PAGING
PAGING ON
PAGING OFF
PAGING <page_size>

Usage

cqlsh> PAGING
Query paging is currently enabled. Use PAGING OFF to disable.

cqlsh> PAGING OFF
Disabled paging.

cqlsh> PAGING ON
Now query paging is enabled.

cqlsh> PAGING 100
Now query paging is enabled.

Notes

• When enabled, large result sets are automatically piped through the pager.
• Paging is automatically disabled when output is not a TTY.
• PAGING <N> enables paging (the page size value is accepted for compatibility with Python cqlsh).

SERIAL CONSISTENCY

Get or set the serial consistency level for lightweight transactions (IF NOT EXISTS, IF conditions).

Syntax

SERIAL CONSISTENCY
SERIAL CONSISTENCY <level>

Levels

SERIAL, LOCAL_SERIAL

Usage

cqlsh> SERIAL CONSISTENCY
Current serial consistency level is SERIAL.

cqlsh> SERIAL CONSISTENCY LOCAL_SERIAL
Serial consistency level set to LOCAL_SERIAL.

Notes

• The default serial consistency level is SERIAL.
• Can be set at startup with --serial-consistency-level.
• Only applies to statements using lightweight transactions.

SHOW

Display version, host, or session trace information.

Syntax

SHOW VERSION
SHOW HOST
SHOW SESSION <trace-uuid>

Subcommands

Usage

cqlsh> SHOW VERSION
cqlsh-rs 0.1.0 | Cassandra 4.1.0 | CQL spec 3.4.6

cqlsh> SHOW HOST
Connected to Test Cluster at 127.0.0.1:9042

cqlsh> SHOW SESSION 12345678-1234-1234-1234-123456789abc
-- trace output --

Notes

• SHOW SESSION requires a valid trace UUID from a previously traced request (enable with TRACING ON).

SOURCE

Execute CQL statements from a file.

Syntax

SOURCE '<filename>'

Usage

cqlsh> SOURCE '/tmp/schema.cql'

Notes

• Each statement in the file must be terminated with a semicolon (;).
• Disabled when --no-file-io is used.
• Tilde (~) in paths is expanded to the home directory.
• Similar to using -f on the command line, but can be run interactively.

TRACING

Toggle request tracing for subsequent CQL statements.

Syntax

TRACING ON
TRACING OFF
TRACING

Usage

cqlsh> TRACING ON
Now tracing requests.

cqlsh> SELECT * FROM system.local;
-- query results --
-- trace output --
Tracing session: 12345678-1234-1234-1234-123456789abc

cqlsh> TRACING OFF
Disabled tracing.

Notes

• TRACING with no argument disables tracing (same as TRACING OFF).
• Trace output is displayed after each query result.
• To view a trace later, use SHOW SESSION <trace-uuid>.
• The maximum wait time for trace data is controlled by [tracing] max_trace_wait in cqlshrc.

UNICODE

Show Unicode character handling and encoding information.

Syntax

UNICODE

Usage

cqlsh> UNICODE
Encoding: utf-8
Default encoding: utf-8

Notes

• Displays the current output encoding (set via --encoding or [ui] encoding in cqlshrc).

USE

Switch the current keyspace. This is a CQL statement handled by the database, but cqlsh-rs also updates the prompt and tab completion context.

Syntax

USE <keyspace>;

Usage

cqlsh> USE my_keyspace;
cqlsh:my_keyspace>

Notes

• The prompt updates to show the current keyspace.
• Tab completion for table names will use the current keyspace context.
• Can also be set at startup with -k / --keyspace.

COPY Guide

Comprehensive guide to importing and exporting data with COPY TO and COPY FROM.

Exporting data with COPY TO

Basic export

COPY my_keyspace.users TO '/tmp/users.csv';

Export with headers

COPY users TO '/tmp/users.csv' WITH HEADER = true;

Export specific columns

COPY users (id, name, email) TO '/tmp/users.csv' WITH HEADER = true;

Export to stdout

Useful for piping to other tools:

COPY users TO STDOUT WITH HEADER = true;

Tab-separated values

COPY users TO '/tmp/users.tsv' WITH DELIMITER = '\t';

Custom NULL representation

COPY users TO '/tmp/users.csv' WITH NULL = 'N/A';

Importing data with COPY FROM

Basic import

COPY my_keyspace.users FROM '/tmp/users.csv';

Import with headers

If the CSV has a header row:

COPY users FROM '/tmp/users.csv' WITH HEADER = true;

Import specific columns

Map CSV columns to table columns:

COPY users (id, name) FROM '/tmp/users.csv' WITH HEADER = true;

Import from stdin

COPY users FROM STDIN;

Set TTL on imported rows

COPY users FROM '/tmp/users.csv' WITH TTL = 86400;

Performance tuning

COPY TO performance

• PAGESIZE: Increase for faster exports on large tables. Default: 1000.
• MAXOUTPUTSIZE: Limit the number of exported rows for sampling.

COPY users TO '/tmp/users.csv' WITH PAGESIZE = 5000;

COPY FROM performance

• CHUNKSIZE: Number of rows per batch. Increase for faster imports, decrease if hitting timeouts.
• INGESTRATE: Target rows per second. Reduce if the cluster is under load.
• MAXBATCHSIZE: Maximum rows per batch statement. Smaller batches are safer.
• PREPAREDSTATEMENTS: Keep true for better performance.

COPY users FROM '/tmp/users.csv' WITH CHUNKSIZE = 5000 AND INGESTRATE = 50000;

Error handling

• MAXPARSEERRORS: Maximum CSV parse errors before aborting (-1 = unlimited).
• MAXINSERTERRORS: Maximum insert errors before aborting (-1 = unlimited).

COPY users FROM '/tmp/users.csv' WITH MAXPARSEERRORS = 100 AND MAXINSERTERRORS = 50;

Configuration defaults

Default COPY options can be set in the cqlshrc file. See Configuration: copy.

Common issues

Large text/blob fields

If you get errors with large fields, increase the CSV field size limit:

[csv]
field_size_limit = 1048576

Timeout errors

Reduce batch size and ingest rate:

COPY users FROM '/tmp/users.csv' WITH CHUNKSIZE = 100 AND INGESTRATE = 10000;

Encoding issues

Specify the encoding explicitly:

COPY users TO '/tmp/users.csv' WITH ENCODING = 'utf-8';

Migration Guide

Step-by-step guide for migrating from Python cqlsh to cqlsh-rs.

Overview

cqlsh-rs is designed as a drop-in replacement for Python cqlsh. The same CLI flags, configuration files, and shell commands work in both versions.

Step 1: Install cqlsh-rs

See Installation for your platform.

Step 2: Verify your cqlshrc

cqlsh-rs reads the same ~/.cassandra/cqlshrc file. No changes needed.

# Test with your existing config
cqlsh-rs --cqlshrc ~/.cassandra/cqlshrc

Step 3: Test your connection

# Same flags as Python cqlsh
cqlsh-rs 10.0.0.1 9042 -u cassandra -p cassandra --ssl

Step 4: Test your scripts

If you use cqlsh in scripts with -e or -f, test them:

# These should work identically
cqlsh-rs -e "SELECT * FROM system.local"
cqlsh-rs -f schema.cql

Step 5: Create an alias (optional)

Once confident, alias cqlsh to cqlsh-rs:

# In ~/.bashrc or ~/.zshrc
alias cqlsh='cqlsh-rs'

What stays the same

• All CLI flags (-e, -f, -u, -p, -k, --ssl, etc.)
• The ~/.cassandra/cqlshrc config file format and all sections
• Shell commands (DESCRIBE, COPY, CONSISTENCY, EXPAND, TRACING, etc.)
• The prompt format (username@cqlsh:keyspace>)
• History file location (~/.cassandra/cql_history)
• Environment variables (CQLSH_HOST, CQLSH_PORT, SSL_CERTFILE, etc.)
• Multi-line input with ; termination
• Ctrl-C to cancel, Ctrl-D to exit

What’s different

See Known Divergences for a complete list. Key differences:

SSL/TLS migration

Python cqlsh uses Python’s ssl module. cqlsh-rs uses rustls. The cqlshrc SSL configuration is compatible:

[ssl]
certfile = /path/to/ca-cert.pem
validate = true
userkey = /path/to/client-key.pem
usercert = /path/to/client-cert.pem

Note: rustls does not support SSLv3 or TLSv1.0/1.1. If your cluster requires these, you’ll need to upgrade your TLS configuration.

COPY migration

COPY TO/FROM syntax and options are identical. Performance characteristics differ because cqlsh-rs uses async I/O instead of Python multiprocessing.

Rollback

To switch back to Python cqlsh:

# Remove the alias
unalias cqlsh

# Or use the Python version explicitly
python -m cqlshlib.cqlsh

Known Divergences

Intentional and unintentional differences between cqlsh-rs and Python cqlsh.

Intentional differences

TLS/SSL

• cqlsh-rs uses rustls, which does not support SSLv3, TLSv1.0, or TLSv1.1.
• The [ssl] version config key accepts TLSv1_2 and TLSv1_3 only.

Driver

• cqlsh-rs uses the scylla-rust-driver instead of the Python cassandra-driver.
• Token-aware routing and connection pooling behavior may differ.
• Protocol version negotiation may select a different version in edge cases.

COPY implementation

• Python cqlsh uses multiprocessing for COPY operations.
• cqlsh-rs uses async I/O (tokio), which may behave differently under heavy load.
• Error messages during COPY operations may differ in format.

Pager

• cqlsh-rs uses a built-in pager (sapling-streampager) instead of shelling out to less.
• The PAGING <N> command accepts a page size for compatibility but uses the built-in pager.

Minor formatting differences

• Floating-point formatting may show trailing zeros differently in edge cases.
• Timestamp formatting uses chrono instead of Python’s datetime, which may produce slightly different results for edge-case timezone handling.
• Blob values are displayed identically (0x...) but internal formatting may differ for very large blobs.

Missing features (planned)

These features from Python cqlsh are not yet implemented but are planned:

• COPY FROM (partially implemented)
• Per-topic HELP text (stub implementation)
• CQL type-specific formatting customization

Reporting divergences

If you find a behavior difference not listed here, please open an issue.

Troubleshooting

Common issues and their solutions.

Connection issues

“Connection refused” or “Connection timed out”

• Verify the host and port are correct: cqlsh-rs 10.0.0.1 9042
• Check that Cassandra is running and listening on the native transport port
• Check firewall rules allow connections to port 9042
• Increase the connect timeout: --connect-timeout 30

“Authentication failed”

• Verify username and password: cqlsh-rs -u cassandra -p cassandra
• Check that the authenticator is configured in cassandra.yaml
• Try credentials from your cqlshrc: cat ~/.cassandra/cqlshrc

SSL/TLS errors

• Verify the certificate file exists and is readable
• Check certificate validity: openssl x509 -in cert.pem -text -noout
• Ensure TLS 1.2+ is supported (cqlsh-rs doesn’t support older protocols)
• For self-signed certs, set validate = false in [ssl] (not recommended for production)

[ssl]
certfile = /path/to/ca-cert.pem
validate = true

“Protocol version mismatch”

• Try specifying a protocol version: --protocol-version 4
• Cassandra 2.x supports protocol v1-v3
• Cassandra 3.x supports protocol v1-v4
• Cassandra 4.x+ supports protocol v4-v5

Shell issues

Tab completion not working

• Tab completion requires an active connection to fetch schema metadata
• Try reconnecting or running DESCRIBE KEYSPACES to refresh the schema cache

History not saving

• Check that ~/.cassandra/ directory exists and is writable
• Verify --disable-history is not set
• Check CQL_HISTORY environment variable isn’t set to an invalid path

Pager not working

• Paging is automatically disabled when output is not a TTY
• Check with: PAGING (shows current state)
• Enable with: PAGING ON

COPY issues

“File I/O is disabled”

• Remove the --no-file-io flag to enable COPY, SOURCE, and CAPTURE commands

COPY TO produces empty file

• Verify the table has data: SELECT COUNT(*) FROM table;
• Check the keyspace is correct (fully qualify: COPY keyspace.table TO ...)

COPY FROM timeout errors

• Reduce batch size: WITH CHUNKSIZE = 100
• Reduce ingest rate: WITH INGESTRATE = 10000
• Increase request timeout: --request-timeout 60

Configuration issues

cqlshrc not being read

• Default location: ~/.cassandra/cqlshrc
• Override with: --cqlshrc /path/to/cqlshrc
• Verify the file is valid INI format

Settings not taking effect

Remember the precedence order:

1. CLI flags (highest)
2. Environment variables
3. cqlshrc file
4. Built-in defaults (lowest)

A CLI flag always overrides a cqlshrc value.

Getting help

• File an issue: github.com/fruch/cqlsh-rs/issues
• Check existing issues for known problems
• Include cqlsh-rs --version output and --debug output when reporting issues

Performance

cqlsh-rs is significantly faster than Python cqlsh in startup time and query throughput.

Startup time

cqlsh-rs starts in milliseconds compared to seconds for Python cqlsh:

Measured with hyperfine on Linux x86_64.

Benchmarks

Performance is tracked continuously via CI. See the live results:

• Historical Dashboard — Interactive commit-over-commit charts
• Benchmark Workflow Runs — Grouped tables and Criterion artifacts

Running benchmarks locally

# All Criterion micro-benchmarks
cargo bench

# Individual benchmarks
cargo bench --bench startup
cargo bench --bench parser
cargo bench --bench format
cargo bench --bench formatter
cargo bench --bench completion

# Rust vs Python startup comparison (requires hyperfine + pip install cqlsh)
cargo build --release
scripts/bench_comparison.sh

Binary size

Memory usage

cqlsh-rs uses significantly less memory than Python cqlsh due to Rust’s lack of a garbage collector and runtime overhead.