DataStax Enterprise 3.0 Documentation

Preparing to upgrade

This documentation corresponds to an earlier product version. Make sure this document corresponds to your version.

Latest DSE documentation | Earlier DSE documentation

You can upgrade from these releases to DataStax Enterprise 3.0.x:

  • A previous release of DataStax Enterprise
  • Cassandra 0.7.10, 0.8.10, or 1.0.x - 1.1.x

You can upgrade to DataStax Enterprise 3.0 from a version of DataStax Community or Cassandra that is earlier, but not later, than the one included in DataStax Enterprise 3.0.x. See the release notes for version information.

Upgrade one data center at a time.

To start the upgrade process, perform the pre-upgrade steps, and then follow the link in step 4 for the particular version you are upgrading.

Limitations on use during the upgrade

During an upgrade, limit activity on the node:

  • Do not update schemas.
  • Do not re-index Solr unless you are following an instruction in these upgrade procedures to re-index.
  • Do not run nodetool repair.
  • Do not use new features.
  • Do not issue these types of queries during a rolling restart: DDL, TRUNCATE, and Solr queries
  • Do not issue Solr queries after upgrading from DataStax Enterprise 2.1.x or earlier until all nodes are upgraded and schema disagreements are resolved.
  • Do not attempt to set up Kerberos authentication. First upgrade the cluster, and then set up Kerberos.

Pre-upgrade steps

  1. Make a backup of the data by taking a snapshot of the node to be upgraded.

  2. Run nodetool drain to flush the commit log of the old installation:

    nodetool drain –h <hostname>
    

    If you are upgrading a DSE Search/Solr node, this step is mandatory. This step is highly recommended for upgrading other nodes because, in the event of a power failure during the upgrade, data loss could occur.

  3. On Debian/Ubuntu, save the cassandra.yaml (and cassandra-topology.properties file if you use the PropertyFileSnitch) from the old installation in a safe location.

    On RHEL-based platforms, RPM saves the file automatically during the upgrade process instead of overwriting it. RPM output looks something like this:

    warning: /etc/cassandra/default.conf/cassandra.yaml
    saved as /etc/cassandra/default.conf/cassandra.yaml.rpmsave
    

    On tarball platforms, you install the new release in a different location, so the old files are not overwritten.

    Regardless of the platform, if you customized any other files, copy the files from the old installation to a safe location before performing an in-place upgrade that overwrites customized files.

  4. Upgrade your installation according to these instructions:

Order of upgrading nodes

Observe the following order for upgrading nodes in a mixed workload cluster:

  1. Analytics: Jobtracker, remaining seeds, remaining task trackers
  2. Cassandra: Seeds, then remaining nodes
  3. Solr: Seeds, then remaining nodes

DSE Search/Solr nodes are upgraded last because they are more sensitive to schema disagreements.

Component version changes

The versions of components that changed for each DataStax release are listed in the Release notes for that version. The cassandra.yaml file included in DSE 3.0.x contains security options that are not included in the Apache Cassandra 1.1.9 file.

For a complete list of Cassandra changes and new features, see:

https://github.com/apache/cassandra/blob/cassandra-1.1.9/CHANGES.txt.

Upgrading data on disk

Upgrading SSTables is highly recommended under any one of these conditions:

  • If you use counter columns
  • If you are upgrading from Cassandra 1.0.x or earlier
  • If you are upgrading from a DataStax Enterprise version having Cassandra 1.0.x or earlier

Upgrade SSTables before doing these operations:

  • move
  • repair
  • bootstrap

Because these operations copy SSTables within the cluster and the on-disk format sometimes changes between major versions, upgrade SSTables now to prevent possible SSTable incompatibilities. Follow upgrade procedures in this document to upgrade SSTables at the end of the process.

  • Tarball: <install_location>/bin/nodetool -h upgradesstables
  • Package or AMI: nodetool -h upgradesstables

About expected schema disagreements

Between the time the first node in a cluster begins the upgrade process until the last node completes the process, a schema disagreement condition exists. Cassandra throws a SchemaDisagreementException when a schema disagreement occurs. This is expected behavior. Upgrade procedures include steps for resolving schema disagreements.

When the schema disagreement exists, client interfaces block the following operations:

  • DDL
  • TRUNCATE
  • Solr queries

DDL, TRUNCATE, and Solr queries are not supported during a rolling restart. For example, during a rolling restart, these are the CQL commands that are and are not supported:

OK to Run Do Not Run Do Not Run (continued)
DELETE ALTER TABLE DROP TABLE
INSERT CREATE TABLE DROP INDEX
SELECT CREATE INDEX DROP KEYSPACE
UPDATE CREATE KEYSPACE TRUNCATE

Exception: After upgrading from DataStax Enterprise 2.1.x or earlier, Solr queries are not supported until all nodes are upgraded and schema disagreements are resolved.

Tapping NEWS.txt for upgrading information

NEWS.txt contains late-breaking information about upgrading from previous versions of Cassandra.

A NEWS.txt or a NEWS.txt archive is installed in the following locations:

  • Tarball: <install_location>/resources/cassandra
  • Package: /usr/share/doc/dse-libcassandra*

NEWS.txt is also posted on the Apache Cassandra project web site.

Unpack NEWS.txt.gz if it is an archive. For example:

cd /usr/share/doc/dse-libcassandra-3.0.
sudo gunzip NEWS.txt.gz

Take at look at the information that is pertinent to your old version if there is any. For example, if you upgrade from some early versions, it might be necessary to upgrade SSTables.