nodetool upgradesstables

Rewrites SSTables to the SSTable format version supported by the running Cassandra instance.

Synopsis

nodetool [connection_options] upgradesstables [options] [--] [keyspace [table ...]]

See connection options for connection options.

Description

nodetool upgradesstables rewrites SSTables that were created by older Cassandra versions into the SSTable format corresponding to the currently running Cassandra version. The target format is determined automatically by the Cassandra instance—each major Cassandra release introduces a new SSTable format version with improvements to encoding, compression, and metadata storage.

This operation is recommended after upgrading Cassandra to ensure all SSTables benefit from the latest format's features and optimizations. SSTables already in the current format are skipped unless the -a flag is specified.

Arguments

Argument	Description
`keyspace`	Keyspace to upgrade. If omitted, upgrades all keyspaces
`table`	Specific table(s) to upgrade

Options

Option	Description
`-a, --include-all-sstables`	Upgrade all SSTables, even if already current version
`-j, --jobs <jobs>`	Number of concurrent upgrade jobs (default: 2). Use `0` to use all available compaction threads.
`-t, --max-timestamp <timestamp>`	Only upgrade SSTables with max timestamp older than the specified value (epoch time in seconds)

When to Run

After Cassandra Upgrade

# After upgrading from 4.0 to 4.1
nodetool upgradesstables

Check SSTable Versions First

# See which versions exist
ls /var/lib/cassandra/data/my_keyspace/my_table-*/
# Look for version prefixes: mc-, nb-, etc.

Prefix	Cassandra Version
`mc-`	3.0+
`nb-`	4.0+
`nc-`	5.0+

Examples

Upgrade All SSTables

nodetool upgradesstables

Upgrade Specific Keyspace

nodetool upgradesstables my_keyspace

Upgrade Specific Table

nodetool upgradesstables my_keyspace my_table

Force Upgrade All (Including Current)

nodetool upgradesstables -a my_keyspace

Parallel Upgrade

nodetool upgradesstables -j 4 my_keyspace

Use All Available Compaction Threads

nodetool upgradesstables -j 0 my_keyspace

Upgrade Only Old SSTables

# Upgrade SSTables older than 30 days (timestamp in epoch seconds)
nodetool upgradesstables -t $(date -d '30 days ago' +%s) my_keyspace

Process

Identify SSTables with older format version
Read data from old SSTable
Write data to new SSTable in current format
Replace old SSTable with new one
Remove old SSTable files

Disk Space Requirements

Space Needed

Like compaction, upgradesstables needs temporary space:

Space needed ≈ Size of largest SSTable being upgraded

Check available space:

df -h /var/lib/cassandra/data

Monitoring Progress

Check Running Upgrades

nodetool compactionstats

Upgrade appears as a compaction operation with type "Upgrade".

Watch Progress

watch -n 5 'nodetool compactionstats | grep -i upgrade'

Performance Impact

I/O Intensive

Reads all qualifying SSTables
Writes new SSTables
Similar to major compaction
Run during low-traffic periods

Recommended Approach

# 1. Run on one node at a time
# 2. Start with smaller keyspaces
nodetool upgradesstables system_schema
nodetool upgradesstables system

# 3. Then production keyspaces
nodetool upgradesstables production_ks

Upgrade Order After Version Upgrade

# 1. System keyspaces first
nodetool upgradesstables system_schema
nodetool upgradesstables system
nodetool upgradesstables system_auth
nodetool upgradesstables system_distributed
nodetool upgradesstables system_traces

# 2. Application keyspaces
nodetool upgradesstables my_app_keyspace

Common Issues

Upgrade Takes Too Long

Large tables take significant time:

# Check progress
nodetool compactionstats

# Consider upgrading table by table
nodetool upgradesstables my_keyspace small_table
nodetool upgradesstables my_keyspace medium_table
nodetool upgradesstables my_keyspace large_table

Not Enough Disk Space

# Free space first
nodetool clearsnapshot

# Or upgrade one table at a time
nodetool upgradesstables my_keyspace table1
# Wait for completion
nodetool upgradesstables my_keyspace table2

SSTables Already Current

If all SSTables are already current version:

Nothing to upgrade for my_keyspace.my_table

This is expected and not an error.

Skipping Upgradesstables

Not Recommended

Skipping upgradesstables after a major version upgrade may cause:

Reduced performance (old format not optimized)
Compatibility issues
Problems during repair
Issues with new features

Automation Script

#!/bin/bash
LOG="/var/log/cassandra/upgrade_sstables_$(date +%Y%m%d).log"

echo "Starting SSTable upgrade at $(date)" >> $LOG

# System keyspaces first
for ks in system_schema system system_auth system_distributed system_traces; do
    echo "Upgrading $ks..." >> $LOG
    nodetool upgradesstables $ks >> $LOG 2>&1
done

# Then all user keyspaces
for ks in $(nodetool tablestats 2>/dev/null | grep "Keyspace:" | awk '{print $2}' | grep -v "^system"); do
    echo "Upgrading $ks..." >> $LOG
    nodetool upgradesstables $ks >> $LOG 2>&1
done

echo "Completed at $(date)" >> $LOG

Best Practices

Upgrade Guidelines

Run after every major upgrade - Essential for compatibility
System keyspaces first - They're smaller and critical
One node at a time - Reduce cluster impact
Check disk space - Ensure sufficient room
Monitor progress - Watch compactionstats
Run during maintenance window - High I/O impact

Command	Relationship
compactionstats	Monitor upgrade progress
scrub	Rewrite SSTables (for corruption)
compact	Force compaction
tablestats	View SSTable counts