Upgrading from Apache Cassandra to DDAC

Upgrade instructions from Apache Cassandra™ to DDAC.

Upgrade order

Upgrade nodes in this order:
  • In multiple datacenter clusters, upgrade every node in one datacenter before upgrading another datacenter.
  • Upgrade the seed nodes within a datacenter first.
  • Upgrade nodes in this order:
    1. DSE Analytics datacenters
    2. Transactional/DSE Graph datacenters
    3. DSE Search datacenters

DataStax Enterprise and Apache Cassandra™ configuration files

Configuration file Installer-Services and package installations Installer-No Services and tarball installations
DataStax Enterprise configuration files
byoh-env.sh /etc/dse/byoh-env.sh install_location/bin/byoh-env.sh
dse.yaml /etc/dse/dse.yaml install_location/resources/dse/conf/dse.yaml
logback.xml /etc/dse/cassandra/logback.xml install_location/resources/logback.xml
spark-env.sh /etc/dse/spark/spark-env.sh install_location/resources/spark/conf/spark-env.sh
spark-defaults.conf /etc/dse/spark/spark-defaults.conf install_location/resources/spark/conf/spark-defaults.conf
Cassandra configuration files
cassandra.yaml /etc/cassandra/cassandra.yaml install_location/conf/cassandra.yaml
cassandra.in.sh /usr/share/cassandra/cassandra.in.sh install_location/bin/cassandra.in.sh
cassandra-env.sh /etc/cassandra/cassandra-env.sh install_location/conf/cassandra-env.sh
cassandra-rackdc.properties /etc/cassandra/cassandra-rackdc.properties install_location/conf/cassandra-rackdc.properties
cassandra-topology.properties /etc/cassandra/cassandra-topology.properties install_location/conf/cassandra-topology.properties
jmxremote.password /etc/cassandra/jmxremote.password install_location/conf/jmxremote.password
Tomcat server configuration file
server.xml /etc/dse/resources/tomcat/conf/server.xml install_location/resources/tomcat/conf/server.xml

DataStax driver changes

DataStax drivers come in two types:

  • DataStax drivers for DataStax Enterprise — for use by DSE 4.8 and later
  • DataStax drivers for Apache Cassandra™ — for use by Apache Cassandra™ and DSE 4.7 and earlier
Note: While the DataStax drivers for Apache Cassandra drivers can connect to DSE 5.0 and later clusters, DataStax strongly recommends upgrading to the DSE drivers. The DSE drivers provide functionality for all DataStax Enterprise features.

cassandra-env.sh

The location of the cassandra-env.sh file depends on the type of installation:
Package installations /etc/dse/cassandra/cassandra-env.sh
Tarball installations installation_location/resources/cassandra/conf/cassandra-env.sh
Attention: Read and understand these instructions before upgrading. Carefully reviewing the planning and upgrade instructions can prevent errors and data loss.

Before you upgrade

Review this section before starting the Cassandra to DataStax Distribution of Apache Cassandra™ (DDAC) upgrade process.

Upgrade paths

The greater the gap between your current Cassandra version and the required base Cassandra version, the more required interim Cassandra upgrades:
Upgrade from Apache Cassandra™ Required Cassandra interim upgrade version
Cassandra 3.0 and 3.11 None
Cassandra 2.2 Upgrade to the latest version of 2.2 before upgrading to DDAC
Cassandra 2.1 and 2.0 Upgrade to the latest version of 2.1 before upgrading to DDAC
Cassandra 1.2 and earlier Upgrade to the latest 1.2 version, then to the latest version of 2.0, and then to the latest version of 2.1 before upgrading to DDAC
Tip: Contact DataStax Support with any questions.

Upgrade order

Upgrade order matters. Upgrade nodes in this order:

  • In multiple datacenter clusters, upgrade every node in one datacenter before moving on to another datacenter.
  • Upgrade the seed nodes within a datacenter first.

General upgrade restrictions during an upgrade

  • Do not enable new features.
  • During the upgrade, do not bootstrap or decommission nodes.
  • Do not issue TRUNCATE queries during a rolling restart.
  • Do not make schema changes.

Restrictions for nodes using any kind of security

Do not change security credentials or permissions until after the upgrade is complete.

Upgrading drivers

Be sure to check driver compatibility. Depending on the driver version, you might need to recompile your client application code. See DataStax driver changes.

During upgrades, you might experience driver-specific impact when clusters have mixed versions of drivers. If your cluster has mixed versions, the protocol version is negotiated with the first host to which the driver connects. To avoid driver version incompatibility during upgrades, use one of these workarounds:
  • Protocol version: Set the protocol version explicitly in your application at start up. Switch to the Java driver to the new protocol version only after the upgrade is complete on all nodes in the cluster.
  • Initial contact points: Ensure that the list of initial contact points contains only hosts with the oldest driver version. For example, the initial contact points contain only Java driver v2.
For details on protocol version negotiation, see protocol versions with mixed clusters in the Java driver version you're using, for example, Java driver.

Upgrade steps

Follow these steps on each node beginning with seed nodes:

  1. Before upgrading to DDAC from any Apache Cassandra™ version, DataStax recommends backing up your data prior to any version upgrade, including logs and custom configurations. A backup provides the ability to revert and restore all the data used in the previous version if necessary. See Backing up and restoring DSE.
    Tip: The general backup and restore operations are identical between Cassandra and DSE. Change the directory names and any DSE specific commands as required.
  2. Familiarize yourself with the changes and features in the release:
    • DDAC release notes for 5.1 (equivalent to Cassandra 3.11).
    • General upgrade advice and Cassandra features in NEWS.txt.
    • Cassandra changes in CHANGES.txt.
  3. Upgrade the SSTables on each node to ensure that all SSTables are on the current version.
    nodetool upgradesstables
    If the SSTables are already on the current version, the command returns immediately and no action is taken.
    Warning: Failure to upgrade SSTables results in a significant performance impact and increased disk usage.
  4. Run nodetool drain to flush the commit log of the old installation:
    nodetool drain
  5. Stop the node. (2.1, 2.2, 3.0)
  6. Back up your Cassandra configuration files.
  7. Uninstall Cassandra.
    Note: If you installed Cassandra from packages in APT or RPM repositories, you must remove the packages before setting up and installing DDAC.
    • For packages installed from APT repositories:
      sudo apt-get autoremove "dsc*" "cassandra*" "apache-cassandra*"

      This action shuts down Cassandra if it is still running.

    • For packages installed from Yum repositories:
      sudo yum remove "dsc*" "cassandra*" "apache-cassandra*"

      The old Cassandra configuration file might be renamed to cassandra.yaml.rpmsave, for example:

      warning: /etc/cassandra/default.conf/cassandra.yaml
      saved as /etc/cassandra/default.conf/cassandra.yaml.rpmsave
    • If Cassandra was installed with a binary tarball:
      ps auwx | grep cassandra
      sudo  kill cassandra_pid

      And then remove the Cassandra installation directory.

  8. Install DDAC.
  9. To configure the product, use your backup configuration files to merge any necessary modifications into the new configuration files.
    Warning: Do not simply replace the DDAC version of cassandra-env.sh with your old Cassandra version. Instead, merge any required changes from the old file to the new file manually.
  10. If upgrading from Cassandra 3.11.2 or later, comment out the following parameters in cassandra.yaml if they exist:
    • enable_materialized_views
    • enable_sasi_indexes
    Tip: See configuration for the location of Cassandra configuration files.
  11. Start the node:
    sudo bin/cassandra
  12. To ensure optimal performance, upgrade the SSTables on each node:
    bin/nodetool upgradesstables
  13. Run nodetool repair:
    bin/nodetool repair -pr
    Important: Be sure to run nodetool repair on each node in the datacenter.
  14. Review the logs for warnings, errors, and exceptions.
    Note: Warnings, errors, and exceptions are frequently found in the logs when starting up an upgraded node. Some of these log entries are informational to help you execute specific upgrade-related steps. If you find unexpected warnings, errors, or exceptions, contact DataStax Support.
  15. Verify that the upgraded datacenter names still match the datacenter names that are used in the keyspace schema definition:
    bin/nodetool status
  16. Repeat the upgrade on each node in the cluster following the recommended order.