Note on Cassandra 5.x memory usage

Cassandra 5.x needs ~25% more system RAM compared to Cassandra 4.x. While the heap size for Cassandra 5.x remains identical to Cassandra 4.x, Cassandra 5.x uses more direct memory for file caching, buffers, and so on. This requires the system to have more RAM as compared to the previous version. For example, if a system had 64GB of RAM, it is now recommended to have at least 80GB of RAM.

Preparing to upgrade Cassandra

To prepare for the Cassandra upgrade

  1. Ensure that all Cassandra nodes are ready. Run the following command and verify that all nodes are Up and Normal:
    nodetool status
    BASH
  2. Leave the Cassandra service running but stop all Teamwork Cloud services.
  3. Back up your current database before upgrading.
  4. Upgrade all Cassandra data tables to current version by running the following command:
    nodetool upgradesstables
    BASH

    This process can take a long time for large databases. Use the jobs option to use more threads for the operation (0 for maximum threads available, default is 2). Also, use the nohup command to run the upgrade process in the background.

    nohup nodetool upgradesstables --jobs 0 &
    BASH

    Make sure this process is completed before proceeding!

Upgrading Cassandra

To upgrade Cassandra

  1. IMPORTANT! Flush memtables to the disk by executing the following command:

    nodetool drain
    BASH

  2. Stop the Cassandra service.

  3. Make a note of the existing cluster name and token count with the following command:

    grep -E 'num_tokens:|cluster_name:' cassandra.yaml
    BASH

  4. Uninstall/remove Cassandra (example with yum package manager)

    sudo yum remove -y cassandra
    BASH

    Cassandra configuration files are saved with .rpmsave extension after uninstallation (default path: /etc/cassandra/default.conf). Archive these files for future reference.

  5. Install new version of Cassandra (for installation instructions, see Installing Cassandra on Linux).

  6. Check the cluster name and token count in cassandra.yaml. If needed, replace the default values with the values set in the previous version. The example below shows the default values for a Cassandra installation.

    Example

    cluster_name: 'Test Cluster'
num_tokens: 16
    BASH

    The cluster name and token count must match those values set in the previous version of Cassandra. If the server is new (has no database), leave the default value.

  7. Start the Cassandra service.

  8. Check if the service is running smoothly:

    • Check the log file for startup errors.

    • Verify that all nodes have a status of Up and Normal with this command:

      nodetool status
      BASH
  9. Upgrade all Cassandra data tables to current version by running the following command:
    nodetool upgradesstables
    BASH

    This process can take a long time for large databases. Use the jobs option to use more threads for the operation (0 for maximum threads available, default is 2). Also, use the nohup command to run the upgrade process in the background.

    nohup nodetool upgradesstables --jobs 0 &
    BASH

    Make sure this process is completed before proceeding!


Additional resources

For more information about upgrading Apache Cassandra, see https://www.datastax.com/learn/whats-new-for-cassandra-4/migrating-cassandra-4x.