Upgrading Cassandra¶

Best practices for upgrading Cassandra¶

Follow these best practices before upgrading Cassandra:

• Take a snapshot before the upgrade. This allows you to rollback to the previous version if necessary. Cassandra is able to read data files created by the previous version, but the inverse is not always true.

  Taking a snapshot is fast, especially if you have JNA installed, and takes effectively zero disk space until you start compacting the live data files again.

• Check https://github.com/apache/cassandra/blob/trunk/NEWS.txt for any new information about upgrading.

• Familiarize yourself with the list of fixes and new features in https://github.com/apache/cassandra/blob/trunk/CHANGES.txt.

Prerequisites¶

1. Date strings (and timestamps) are no longer accepted as valid timeuuid values. This change requires modifying queries that use these values. New methods have been added for working with timeuuid values.

2. Cassandra 1.2.4 is not network-compatible with versions older than 1.0. If you want to perform a rolling restart, first upgrade the cluster to 1.0.x or 1.1.x, and then to 1.2.4, as described in the Cassandra 1.1 documentation.

   Data files from Cassandra 0.6 and later are compatible with Cassandra 1.2 and later. If it's practical to shut down cluster instead of performing a rolling restart, you can skip upgrading to an interim release and upgrade from Cassandra 0.6 or later to 1.2.4.

3. Do not upgrade if nodes in the cluster are down. The hints schema changed from 1.1 to 1.2.4. Cassandra automatically snapshots and then truncates the hints column family as part of starting up 1.2.4 for the first time. Additionally, upgraded nodes will not store new hints destined for older (pre-1.2) nodes. Use the nodetool removenode command, which was called nodetool removetoken in earlier releases, to remove dead nodes.

Other Cassandra changes that affect upgrades¶

Noteworthy changes are:

• The nodetool upgradesstables command now only upgrades/rewrites sstables that are not on the current version, which is usually what you want. Use the -a flag to recover the old behavior of rewriting all sstables.

• Tables using LeveledCompactionStrategy do not create a row-level bloom filter by default. In versions of Cassandra before 1.2.2 the default value differs from the current value; manually set the false positive rate to 1.0 (to disable) or 0.01 (to enable, if you make many requests for rows that do not exist).

• The default version of CQL (and cqlsh) is CQL 3.0. CQL 2 is still available but you will have to use the thrift set_cql_version method that is already supported in 1.1 to use CQL 2.

• In CQL 3, the DROP behavior has been removed temporarily from ALTER TABLE because it was not correctly implemented.

• In earlier releases, CQL3 property map keys used in ALTER and CREATE statements were case-insensitive. For example, CLASS or class and REPLICATION_FACTOR or replication_factor were permitted. The case-sensitivity of the property map keys was inconsistent with the treatment of other string literals and incompatible with formatting of NetworkTopologyStrategy property maps, which have case-sensitive data center names. In this release property map keys, such as class and replication_factor are case-sensitive. Use lowercase property map keys as shown in this example:

  CREATE KEYSPACE test WITH replication =
    { 'class' : 'SimpleStrategy', 'replication_factor' : '1' };
  

• You might need to fix queries having loose type validation of CQL 3 constants that now have strong validation. See the changelog section of Apache docs. Using blobs as strings constants is now deprecated in favor of blob constants.