cqlsh CONSISTENCY, TRACING, DESCRIBE, COPY Boundaries, and Scripting

Learning outcomes

AtlasMart's support engineer uses cqlsh COPY to move a small incident fixture and then proposes the same method for a multi-terabyte migration. The command is useful—but the operational contract changes completely with scale, concurrency, failure recovery and observability.

Terms and configuration-provenance mental model

Configuration provenance is the chain from an intended baseline to the value a Cassandra process is actually running. cassandra.yaml holds most server settings; cassandra-env.sh, jvm*.options, environment variables, Java system properties, container orchestration and package defaults can also influence startup. A startup-only/static setting requires process restart to take effect. A runtime/dynamic setting can be changed through a supported JMX or nodetool surface, but that change may be node-local and non-persistent unless the deployment baseline is also updated.

A seed is a discovery/contact point used during startup and gossip; it is not a leader, primary, quorum authority or special replica. listen_address identifies the interface/address used for internode traffic, while rpc_address is the bind address for native client transport; broadcast_address and broadcast_rpc_address are addresses advertised to peers/drivers when binding differs from reachability. JMX is the Java management plane used by nodetool; it has a different security boundary from CQL. A virtual table, such as system_views.settings, exposes node-local runtime information through CQL but is not replicated and ignores consistency level. A guardrail warns about or rejects risky operations/values. Configuration drift means nodes or deployment artifacts no longer share the intended settings. Rolling change means applying a compatible change one node/failure domain at a time while verifying service and rollback between steps.

1. cqlsh changes its client session, not cassandra.yaml

docker exec atlasmart-cass-1 nodetool version -vdocker exec atlasmart-cass-1 java -versiondocker exec atlasmart-cass-1 cqlsh --versiondocker exec atlasmart-cass-1 nodetool statusdocker exec atlasmart-cass-1 nodetool statusbinarydocker exec atlasmart-cass-1 nodetool getseeds# Repeat from another node because nodetool/JMX observations are node-local.docker exec atlasmart-cass-2 nodetool status

CREATE KEYSPACE IF NOT EXISTS atlasmart_opsWITH replication = {'class':'NetworkTopologyStrategy','dc1':3};CREATE TABLE IF NOT EXISTS atlasmart_ops.config_probe (  probe_id text PRIMARY KEY,  status text,  owner text,  note text,  updated_at timestamp) WITH compaction = {'class':'UnifiedCompactionStrategy'};CONSISTENCY LOCAL_QUORUM;INSERT INTO atlasmart_ops.config_probe (probe_id,status,owner,note,updated_at)VALUES ('probe-1','READY','platform','chapter22',toTimestamp(now()));INSERT INTO atlasmart_ops.config_probe (probe_id,status,owner,note,updated_at)VALUES ('probe-2','READY','orders','copy-fixture',toTimestamp(now()));SELECT * FROM atlasmart_ops.config_probe WHERE probe_id='probe-1';

CONSISTENCY LOCAL_QUORUM;SERIAL CONSISTENCY LOCAL_SERIAL;PAGING 20;DESCRIBE CLUSTER;DESCRIBE KEYSPACE atlasmart_ops;TRACING ON;SELECT * FROM atlasmart_ops.config_probe WHERE probe_id='probe-1';TRACING OFF;CONSISTENCY;

CONSISTENCY, SERIAL CONSISTENCY, TRACING, PAGING and DESCRIBE are cqlsh special commands. They affect how the shell issues/prints requests; they do not rewrite server configuration. Trace event names/timing depend on version and topology, and tracing itself adds work, so use it selectively.

2. DESCRIBE is schema evidence and a migration aid—not a backup

docker exec atlasmart-cass-1 cqlsh -e "DESCRIBE KEYSPACE atlasmart_ops;" > atlasmart_ops_schema.cql# Inspect before applying elsewhere. Schema text does not include table data, repair state, snapshots or credentials.cat atlasmart_ops_schema.cql

A schema dump is valuable for drift review and rebuild automation, but a recoverable backup also needs data snapshots/incrementals, schema/version metadata, topology/configuration and a tested restore procedure.

3. COPY is appropriate for bounded local exchange

COPY atlasmart_ops.config_probe TO '/tmp/config_probe.csv' WITH HEADER = TRUE;CREATE TABLE IF NOT EXISTS atlasmart_ops.config_probe_import (  probe_id text PRIMARY KEY,  status text,  owner text,  note text,  updated_at timestamp) WITH compaction = {'class':'UnifiedCompactionStrategy'};COPY atlasmart_ops.config_probe_import FROM '/tmp/config_probe.csv' WITH HEADER = TRUE;SELECT * FROM atlasmart_ops.config_probe_import;

docker exec atlasmart-cass-1 sh -lc "wc -l /tmp/config_probe.csv && sed -n '1,8p' /tmp/config_probe.csv"docker exec atlasmart-cass-1 rm -f /tmp/config_probe.csv

4. Script cqlsh idempotently

CONSISTENCY LOCAL_QUORUM;DESCRIBE KEYSPACE atlasmart_ops;SELECT probe_id,status,owner,note,updated_atFROM atlasmart_ops.config_probeWHERE probe_id='probe-1';

# Save chapter22_verify.cql on the host first.docker cp chapter22_verify.cql atlasmart-cass-1:/tmp/chapter22_verify.cqldocker exec atlasmart-cass-1 cqlsh -f /tmp/chapter22_verify.cqldocker exec atlasmart-cass-1 rm -f /tmp/chapter22_verify.cql

For automation, make scripts deterministic and stop/alert on failures. Destructive schema changes, conditional operations and data migrations need explicit rollback/reconciliation, not just “run cqlsh again.”

5. Verification and boundaries

Production judgment

Operational configuration is part of the database design. Record the Cassandra patch/JDK/container or package, topology and failure domains, RF/consistency levels, compaction, repair and backup schedules, TTL/gc_grace_seconds, SAI/vector dependencies, disk/memory/network/JVM limits, auth/TLS/JMX boundaries, native transport exposure, guardrails, driver retry/idempotency behavior, observability endpoints, and managed-service overrides. A syntactically valid setting can still be wrong for workload cardinality, retention, tail latency, disk headroom or failure behavior. Likewise, a healthy-looking nodetool status does not prove repair freshness, query SLOs, disk latency, compaction health, application correctness or backup recoverability.

Make every change with an owner, compatibility check, blast-radius estimate, pre/post evidence, rollback path and version-controlled intent. Avoid copying tuning values from another cluster without workload evidence. Security-sensitive files, passwords and keystores belong in secret-management systems, not source control. Lesson 4 changes actual runtime configuration in a reversible way and demonstrates why a successful one-node nodetool command is configuration drift until the intended value is rolled, verified and persisted.

Summary and next bridge

cqlsh is a precise interactive/scripting client, not a replacement for configuration management, production drivers or bulk-migration engineering. Its special commands make consistency, tracing, paging and schema evidence visible. Next, change a runtime guardrail safely and watch node-local drift appear in real time.

Authoritative references

Re-check these version-sensitive references when regenerating the course. Tool availability, defaults, guardrails and configuration names evolve across Cassandra releases and managed services.

• Apache Cassandra downloads / current 5.0 patch
• cassandra.yaml configuration reference
• Unit-aware cassandra.yaml parameters
• Virtual tables and system_views.settings
• nodetool command reference
• cqlsh special commands and COPY
• Cassandra security / JMX access
• Cassandra FAQ / seed semantics
• Docker Official Cassandra 5.0 image