Cassandra Knowledge Patch

Apache Cassandra Knowledge Patch

Purpose

Load this skill when designing, upgrading, operating, or debugging Apache Cassandra. It concentrates compatibility details that affect CQL, schema, indexes, storage, repair, topology, configuration, security, observability, clients, and command-line tooling.

Start from the deployed cluster and application reality:

1. Determine the Cassandra version on every node involved in the change.
2. Check whether the cluster is mixed-version or fully upgraded.
3. Identify the storage format, index implementations, compaction strategy, and repair mode in use.
4. Read the topic reference that matches the operation.
5. Validate changes on representative data and with the same management path used in production.

Do not infer behavior from configuration templates alone. Runtime state, JMX, virtual tables, nodetool, schema output, and logs may each expose a different part of the operational picture.

Reference index

High-impact compatibility checks

Tightened security boundaries

• Expect authorization that older maintenance releases accidentally permitted on data centers, authorizer paths, or system keyspaces to be rejected.
• A regular user cannot bind an identity to a superuser. Run that provisioning step with appropriately privileged credentials.
• Password changes are rate-limited. Rotation automation needs bounded retry behavior rather than rapid repeated requests.
• Audit logging configuration is validated during startup. Treat a startup rejection as a configuration error instead of assuming the logger will ignore malformed settings.
• Grants are supported on the system_views and system_virtual_schema virtual keyspaces when monitoring roles need them.

See Configuration, Security, and Observability for the complete set of authorization, redaction, and obfuscation changes.

Automation and CLI changes

• Use nodetool import -cd as the short form of --copy-data; -p conflicts and is no longer the short option.
• Do not make tool wrappers depend on incidental sourcing of cassandra-env.sh; tools skip it when it is unnecessary.
• Treat invalid or filesystem-unsafe table and snapshot names as DDL or command validation failures.
• cqlsh can disable persistent history, and supported Python runtimes include Python 3.12 and 3.13.
• nodetool getguardrailsconfig and setguardrailsconfig expose guardrail configuration through their simplified interfaces.
• Use nodetool checktokenmetadata when comparing token metadata with gossip endpoint state.

See CQL, Schema, Clients, and Tools for exact tool and client compatibility notes.

Virtual settings consumers

Consumers of system_views.settings must:

• parse complex values as JSON;
• tolerate settings whose keys are not strings;
• expect security-sensitive values to be redacted; and
• handle the restored, broader set of configuration rows.

Do not use the view as a secret-retrieval mechanism. See Configuration, Security, and Observability for JMX and metrics changes that often affect the same inventory systems.

AutoRepair operations

Built-in AutoRepair provides an in-process scheduler with minimum task-duration control, preview_repaired support, disk protection for full repair, and expected-versus-actual progress reporting for bytes and keyspaces.

Operational constraints matter:

• the scheduler stops when two major Cassandra versions are detected;
• full repair observes disk-protection conditions; and
• parallel_repair_count values greater than one are supported without the previous ongoing-repair assertion failure.

During a mixed-major upgrade, retain external repair planning because the built-in scheduler does not continue. See Repair, Topology, and Coordination.

SAI and query correctness

When investigating a query result, distinguish index availability from node availability and distinguish local correctness from distributed reconciliation:

• built SAI indexes are queryable when a restarted node is marked UP;
• writer switches flush active SAI segment builders;
• repair flushes correctly mark non-empty index state;
• static-column queries and their range tombstones reconcile correctly;
• intersection queries preserve repaired and non-indexed matches;
• segmented index components use segment-aware checksum boundaries; and
• ANN execution uses score-ordered iterators.

Legacy secondary indexes take priority when they coexist with SAI on a column. Empty values remain invalid for non-literal or otherwise incompatible indexed types. See Indexing and Query Correctness.

Deletions and reconciliation

Correctness fixes cover several distinct deletion paths:

• mutation serialization preserves complex deletions across multiple collections;
• RowFilter retains deletions needed for result reconciliation;
• Full Query Logging batches support null-value tombstones;
• reading a partition after a column deletion no longer fails with an index bounds exception; and
• secondary indexes are notified about rows in fully expired SSTables.

Do not paper over a suspected deletion bug by changing consistency levels or rebuilding an unrelated index. Identify the affected serialization, filtering, logging, or compaction path first.

Storage and recovery safety

• Direct I/O commitlog flushes preserve data safely.
• Commitlog recovery skips sync blocks correctly after CRC errors.
• A corrupt SSTable found during compaction is marked suspected and associated buffer-pool resources are released.
• Runtime failures while writing the TOC remain runtime failures rather than being reclassified as filesystem errors.
• Memory-mapped trie indexes larger than 2 GiB are readable.
• Early-open BTI range queries return correct results.
• Legacy SSTables with the old Bloom-filter format automatically fall back from zero-copy streaming.

See Storage, SSTables, and Recovery before changing compaction, streaming, snapshot, or recovery procedures.

Upgrade and incident workflow

Before an upgrade

1. Inventory node versions, Java runtime, SSTable formats, indexes, and repair scheduling.
2. Review tightened authorization, schema compatibility, configuration validation, and tool option changes.
3. Confirm monitoring parsers handle JSON and redacted virtual settings and corrected metric values.
4. Exercise mixed-version Paxos, streaming fallback, hints, and repair behavior in a staging topology.
5. Verify disk limits against a first-boot node and compaction space estimates against compressed table sizes.

After a restart or bootstrap

1. Confirm gossip endpoint state includes DC, rack, and host ID for bootstrapping or gossip-only nodes.
2. Check token metadata consistency with nodetool checktokenmetadata.
3. Confirm SAI queryability rather than relying only on node UP state.
4. Use the bootstrap-available StorageService JMX MBean when automation needs management visibility before the node reaches normal state.
5. Check the corrected failure-detector timing if defaults are in use.

During a correctness incident

1. Record whether the query uses SAI, legacy 2i, static columns, composite map filters, numeric ranges, or descending clustering columns.
2. Determine whether repair, reconciliation, tombstones, an early-open SSTable, or an SSTable-writer boundary is involved.
3. Preserve evidence from logs, nodetool tablestats, schema descriptions, and relevant virtual tables.
4. For storage faults, distinguish corruption, checksum, commitlog CRC, and TOC write paths before choosing remediation.
5. Do not expect a heap dump for an exception Cassandra handled internally.

Authoring and review guidance

When proposing Cassandra code or automation:

• keep examples explicit about keyspace, table, consistency, and topology;
• prefer long CLI options in scripts unless the short form is documented;
• treat redacted values as intentionally unavailable;
• account for mixed-version behavior during rolling upgrades;
• avoid assuming node liveness implies index readiness;
• validate CQL type compatibility, especially vectors, UDT clustering keys, and BytesType schema evolution; and
• test deletion and tombstone semantics with reconciliation and repair in mind.

Use the references as compatibility constraints, then verify the final behavior against the target cluster, its schema, and its operational configuration.