How to Use Cassandra SSTable Utilities: sstableloader, sstableverify, and sstablescrub

The Cassandra SSTable utilities sstableloader, sstableverify, and sstablescrub provide command-line interfaces for bulk-loading data, verifying file integrity, and repairing corrupted SSTables by operating directly on immutable storage files.

The apache/cassandra repository provides three essential command-line tools for managing SSTable files outside of normal database operations. These Cassandra SSTable utilities allow administrators to import snapshot data, detect disk corruption, and recover from damaged files without executing CQL commands. Each tool operates directly on the physical SSTable files located in the data directory, bypassing the standard Cassandra RPC layer.

What Are Cassandra SSTable Utilities?

Cassandra stores data on disk in immutable SSTable files. When you need to import, verify, or repair these files, the database provides specialized utilities that work offline:

• sstableloader: Bulk-loads SSTables into a live cluster by streaming them to target nodes, creating new SSTables on the destination while preserving compaction and repair semantics.
• sstableverify: Scans SSTables for corruption or checksum errors, offering both quick validation and deep value-level verification.
• sstablescrub: Rewrites corrupted SSTables locally, skipping unreadable rows and creating snapshots of the original files.

All three tools assume Cassandra is stopped on the node where they run because they require exclusive access to raw SSTable files in directories like $CASSANDRA_DATA/keyspace/table-<uuid>/.

Prerequisites and Safety Considerations

Before running any Cassandra SSTable utility, ensure the database instance on the target node is stopped. These tools open *-Data.db and companion *-Index.db files directly without coordinating with a running server.

Both sstableverify and sstablescrub require a force flag (-f) to acknowledge the risk of marking tables as unrepaired, as documented in CASSANDRA-17017. This safety mechanism prevents accidental metadata changes during maintenance operations.

sstableloader: Bulk Loading SSTables

The sstableloader utility streams SSTables into a live cluster over the native transport port (9042) and internode storage ports (7000/7001). Unlike other utilities, it does not require the local Cassandra instance to be stopped, but it reads from snapshot directories or exported data sets.

Key architectural points:

• Creates new SSTables on destination nodes rather than copying files directly
• Supports SSL authentication and throttling to prevent cluster overload
• Operates on the physical directory layout of snapshots

Command-line example:

sstableloader \
  --nodes 10.0.0.5,10.0.0.6 \
  --throttle-mib 64 \
  --connections-per-host 8 \
  /var/lib/cassandra/snapshots/keyspace1/standard1/

This example loads data from a snapshot directory into the cluster at 10.0.0.5 and 10.0.0.6, limiting bandwidth to 64 MiB/s and using eight concurrent connections per host.

sstableverify: Detecting Corruption

Use sstableverify to scan for corruption before running repairs or after detecting possible disk issues. The tool offers two verification depths:

• Quick mode (default): Validates checksums only
• Extended mode (-e): Reads every column value to detect subtle corruption

Usage examples:

# Quick checksum verification

sstableverify keyspace1 mytable

# Deep value-level verification

sstableverify -e keyspace1 mytable

In bin/sstableverify, the tool implements safety checks that require the -f flag to proceed when the operation might affect repair metadata.

sstablescrub: Repairing Corrupted Files

When sstableverify reports corrupted files, sstablescrub attempts to recover as much data as possible. The utility rewrites SSTables locally, producing new files while taking a snapshot of the original corrupted data.

Key options:

• --no-validate: Skips validation, useful for resolving type-mismatches
• --skip-corrupted: Ignores corrupted rows during rewrite, essential for counter tables
• -f or --force: Acknowledges the risk of marking tables as unrepaired

Command examples:

# Standard scrub with snapshot backup

sstablescrub keyspace1 corrupted_table

# Skip validation for type-mismatch recovery

sstablescrub --no-validate keyspace1 mytable

# Recover counter table data while skipping corrupted rows

sstablescrub --skip-corrupted keyspace1 counter_table

The tool is implemented in bin/sstablescrub and interacts directly with the SSTable API to rewrite *-Data.db files while preserving the companion index structures.

Key Source Files and Implementation

According to the apache/cassandra source code, these utilities are thin wrappers around internal Java classes:

• tools/bin/sstableloader: The shell script entry point for bulk loading, documented in doc/modules/cassandra/pages/managing/tools/sstable/sstableloader.adoc.
• bin/sstableverify: The verification utility implementation, documented in doc/modules/cassandra/pages/managing/tools/sstable/sstableverify.adoc.
• bin/sstablescrub: The scrubbing tool implementation, documented in doc/modules/cassandra/pages/managing/tools/sstable/sstablescrub.adoc.

These files contain the command-line option definitions, usage examples, and entry points that parse arguments and establish connections (for sstableloader) or perform safety checks before manipulating SSTable data.

Summary

• Cassandra SSTable utilities require the local database to be stopped (except sstableloader) because they access raw *-Data.db and *-Index.db files directly.
• Use sstableloader to stream SSTables from snapshots into live clusters with configurable throttling and parallel connections.
• Use sstableverify with the -e flag for deep corruption detection or run without flags for quick checksum validation.
• Use sstablescrub to rewrite damaged files locally, employing --skip-corrupted for counter tables and --no-validate for type-mismatch recovery.
• Always include the -f flag when prompted to acknowledge risks to repair metadata.

Frequently Asked Questions

Can I run SSTable utilities while Cassandra is running?

No. Except for sstableloader, which streams data to remote nodes, utilities like sstableverify and sstablescrub require Cassandra to be stopped on the local node. They obtain exclusive locks on SSTable files in the data directory and do not coordinate with the running database process.

What is the difference between sstableverify and sstablescrub?

sstableverify is a read-only diagnostic tool that detects corruption through checksum validation or deep value inspection. sstablescrub is a write operation that creates new SSTables by rewriting existing files and skipping corrupted sections. Run sstableverify first to assess damage, then use sstablescrub to recover data when corruption is confirmed.

How does sstableloader handle concurrent connections?

The sstableloader utility supports the --connections-per-host parameter to control parallelism and the --throttle-mib option to limit bandwidth. By default, it streams data over port 9042 (native transport) and storage ports 7000/7001, creating new SSTables on destination nodes rather than copying raw files.

When should I use the --force flag with sstablescrub?

Use the -f or --force flag when the utility warns that the operation will mark tables as unrepaired. This safety mechanism, introduced in CASSANDRA-17017, requires explicit acknowledgment because scrubbing modifies SSTable metadata and may require subsequent repair operations to restore consistency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}