nodetool upgradesstables¶

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

Synopsis¶

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

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)

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

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
# upgrade_all_sstables.sh

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