Upgrade DSE 5.1 to 6.8

Improper upgrades can result in downtime, data loss, and other errors.

To minimize risk for an upgrade, review the entire upgrade guide before you begin, including warnings, restrictions, release notes, and all pre-upgrade, upgrade, and post-upgrade steps.

You must prepare all nodes in the cluster before upgrading any nodes. Failure to prepare all nodes can result in mismatched configurations, repair states, and schemas that can disrupt the upgrade process.

Follow these instructions to upgrade from DataStax Enterprise (DSE) 5.1 to 6.7 or 6.8. This guide assumes you are upgrading to 6.8 because 6.7 is EOL.

As an alternative to an in-place upgrade on a live cluster, you can use the Zero Downtime Migration (ZDM) tools to orchestrate live traffic while you prepare a new cluster with your desired DSE version, configuration, and data. After testing the new cluster, you can redirect your application traffic and safely decommission your current cluster. If you need to rollback, you can seamlessly discard the new cluster and continue using your existing cluster.

Upgrade path to avoid data loss

Data loss is possible when upgrading to DSE 6.8.

Tuple data will be lost if you upgrade directly to 6.8.36 or later without upgrading to 6.8.35 first.

If you use the tuple data type, you must follow this upgrade path:

Upgrade from DSE 5.1 to DSE 6.8.35, as explained in this guide.
Upgrade all SSTables with nodetool upgradesstables -a and run sstablescrub --fix.
Upgrade to the latest 6.8 patch release.

If you don’t have tuple data, you don’t need to stop at 6.8.35; you can upgrade directly from 5.1 to the latest 6.8 patch release.

Avoid certain operations during the upgrade

The upgrade process for DSE can be completed with minimal downtime (ideally zero) by upgrading nodes in a rolling fashion: upgrade and restart one node at a time while the other nodes continue to operate.

The moment that you install the new version on one node in a cluster, the cluster enters a partially upgraded state. In this state, the cluster continues to operate as though all nodes are running the earlier, pre-upgraded version. The cluster remains in this state until you have upgraded all nodes in the cluster.

You must avoid or block the following operations during the upgrade to maintain cluster stability and prevent errors:

Don’t enable new features.

This restriction includes net new features and existing features that you weren’t using previously. For example, don’t enable Change Data Capture (CDC) for the first time during an upgrade. Upgrade the entire cluster, and then enable the feature.
Don’t change credentials, permissions, or any other security settings unless explicitly instructed to do so.

To preserve your existing configuration, you will transfer your existing security settings from your current configuration files to the new configuration files during the upgrade process. The new files might use different settings due to enhancements, deprecations, and removals between versions. This mapping is required for a successful upgrade, and it isn’t the same as an extraneous change to the security configuration.

Examples of security changes to avoid include modifications to authenticators, authorizers, CQL roles, and CQL permissions. Postpone all such changes until after the upgrade.

If you aren’t already using Kerberos, don’t set up Kerberos authentication immediately before upgrading. First upgrade the cluster, and then set up Kerberos. If you are already using Kerberos, you can continue to use it during the upgrade.
Don’t run repairs manually or automatically:
- Disable all automated and scheduled repairs, including Reaper, crontab, and scripts that run nodetool repair.
- Don’t manually run commands like nodetool repair.
- Don’t repair SSTables while the cluster is in a partially upgraded state. Only repair SSTables before and after upgrading the entire cluster.
  
  If enabled, stop the DSE OpsCenter Repair Service.
You must complete the cluster-wide upgrade before the expiration of gc_grace_seconds (approximately 10 days by default) to ensure any post-upgrade repairs complete successfully.

Attempting to run repairs on partially upgraded clusters can cause performance issues, data inconsistencies, and repair failures. If you absolutely must run repairs on a partially upgraded cluster, determine which SSTable formats and streaming protocols are supported on each node, and then thoroughly test your intended repair operation on an isolated non-production cluster. Small incremental repairs are less risky but they aren’t risk free.
Don’t add (bootstrap) new nodes or decommission existing nodes.
Don’t issue DDL-related queries like TRUNCATE.

Depending on your infrastructure, workloads, and consistency levels, you might want to avoid other operations that could require excessive resources or coordination across mixed-version nodes. For example, BATCH operations can be resource intensive.
Don’t alter any schemas.

Schema versions must be consistent across the cluster before starting the upgrade.

Propagation of schema changes between mixed-version nodes can cause query failures, data consistency issues, and other errors. Take action to prevent schema changes from occurring during the upgrade process.

During the upgrade, it is normal for nodes on different versions to show schema disagreements. These disagreements should resolve after the entire cluster is upgraded.
Don’t rebuild indexes during the upgrade.
Disable services that can cause data inconsistencies and interfere with the upgrade process:
- Disable backup services, scheduled backups, and automated snapshots.
- Disable the NodeSync Service for major and minor releases. For patch releases, disabling the NodeSync Service is optional.
If you disabled the Performance Service before the upgrade, don’t reenable it during the upgrade.
DSE Analytics nodes: Don’t run analytics jobs until all nodes are upgraded.

When upgrading to a new major or minor version of DSE, all nodes in a DSE datacenter that run Spark must be on the same version of Spark, and the Spark jobs must be compiled for that version. To determine the Spark version, see the DSE release notes.

Before reinitiating Spark jobs, all datacenters comprising a Spark cluster must be on the same upgraded DSE version. If any Spark jobs run against Graph keyspaces, don’t reinitiate Spark jobs until you have upgraded all Analytics and non-Analytics nodes in the entire cluster. When Graph keyspaces are involved, Spark jobs fail due to mixed Spark and DSE versions across all nodes.

Driver compatibility and live application traffic

Incompatible drivers and unspecified protocol versions can cause connection failures and other issues during the upgrade.

To maintain live application traffic throughout the upgrade process, your Cassandra driver must be compatible with your current installation and your target DSE version. Additionally, you must configure protocol version negotiation to ensure backwards compatibility throughout the upgrade.

Find a mutually compatible driver version

Verify that your current Cassandra driver version is compatible with your target DSE version. For available drivers and compatibility information, see Cassandra driver compatibility.

If your current driver version isn’t compatible with your target DSE version, upgrade your driver to a mutually compatible version.

When upgrading your driver, check your driver’s release notes for breaking changes that might require code changes. Review all release notes from your current driver version through the new version. Recompile your client application code, if needed.

No mutually compatible version exists

If there is no mutually compatible driver version, you have two options:

Intermediate upgrade (recommended): Determine if your upgrade path requires (or supports) an intermediate upgrade before proceeding to your target DSE version. Find driver versions that are compatible with each segment of the upgrade path (current to intermediate and intermediate to target), and then upgrade your driver before each segment.
Delayed upgrade: Upgrade to the latest driver version that is compatible with your current installation, and then plan to upgrade your driver again when your cluster is on your target DSE version. This can require code or configuration changes to accommodate the temporary driver version, such as changing authentication methods or avoiding unsupported query patterns. Consider testing this approach in an isolated environment to identify potential compatibility issues before applying it to your production environment.

Configure protocol negotiation

When a cluster is in a partially upgraded state, upgraded nodes might support different Cassandra native protocol versions than non-upgraded nodes. By default, a driver negotiates the protocol version with the first host (node) that it connects to. The driver might select a protocol version that works across all nodes, but this isn’t guaranteed if the driver connects to a random node each time. It is better to prevent protocol incompatibility in one of two ways:

Set protocol version: Set a mutually compatible protocol version explicitly in your application at start up. After you upgrade all nodes in the cluster, you can switch your applications to the latest supported protocol version.
Set initial contact points: Specify a list of initial contact points that contains only hosts with the oldest database platform version or mutually compatible protocol version. You must upgrade these nodes last.

For more information about protocol version negotiation, see your driver’s documentation.

DSE-only drivers are unsupported

All DSE-only drivers have reached end-of-life (EOL); they are unsupported and unmaintained. If your applications use DSE-only drivers, you must upgrade to a recent version of a supported driver.

For legacy applications that require DSE-only drivers, compatibility with your target DSE version might be limited or nonexistent. For example, newer DSE, Cassandra, and CQL features might not be supported by the driver, or queries that use deprecated data types, functions, or syntax might fail. Consider modernizing or sunsetting legacy applications if possible, particularly because EOL drivers don’t receive any updates, including security updates.

Strict upgrade order for cluster stability

Don’t upgrade any nodes until you have completed the pre-upgrade steps on all nodes.

When upgrading nodes, always upgrade seed nodes before non-seed nodes.

To avoid cluster-wide downtime, you must upgrade and restart one node at a time in a specific order based on workload types and deployment architecture:

For multi-cluster deployments, upgrade one cluster at a time.
For multi-datacenter clusters, upgrade one datacenter at a time.
If using racks, upgrade one rack at a time within a datacenter.
Within a datacenter (or rack), upgrade one node at a time, starting with seed nodes.
If using advanced workloads (Analytics, Graph, Search), upgrade datacenters or nodes according to the following workload type hierarchy:
1. Upgrade DSE Analytics datacenters.
2. Upgrade transactional (Cassandra) and DSE Graph datacenters.
3. Upgrade DSE Search datacenters.
If each datacenter has only one workload type, upgrade your datacenters in the given order. Within each datacenter, proceed rack-by-rack (if applicable) and node-by-node, starting with the seed nodes.

If a datacenter has multiple workload types, upgrade nodes within that datacenter in the given order, starting with the seed nodes. If using racks, apply the hierarchy to each rack.
Repeat until you have upgraded all nodes in all racks, datacenters, and clusters.

Use an isolated deployment to test the upgrade.

For example, in multi-datacenter clusters with an active-passive configuration, you can complete the entire upgrade process (pre-upgrade, upgrade, and post-upgrade) on the passive datacenter first, run performance tests on that datacenter, and then upgrade the active datacenter if the tests are successful. If the tests fail, you can destroy the passive datacenter and rebuild it without impacting the active datacenter.

Similarly, if you have a test deployment with no connectivity to your production nodes, datacenters, or clusters, then you can safely perform the entire upgrade process in that isolated deployment before rolling out the upgrade to your production deployment.

Prepare to upgrade

Before upgrading any node, you must prepare all nodes for the upgrade. Complete the pre-upgrade steps on every node in the recommended order. Following the recommended order ensures that you don’t miss any nodes, although some steps aren’t applicable to every node.

Some pre-upgrade steps provide information about actions that you must take later in the upgrade process. This information is given in advance because it might impact your upgrade plan. Be sure to revisit these steps at the appropriate time.

If you installed DSE 5.1 with the DataStax Installer, you must migrate to a tarball or a package installation of the same version before you upgrade to DSE 6.8.

Support for the DataStax Installer ended with DSE 5.1.10 and 6.0.
Upgrade to the latest patch release for your current version.

Always upgrade to latest patch release for your current version before you upgrade to a new major or minor version. Patch releases help prepare your clusters for the upgrade by minimizing the differences between the current version and the target version.

Get your current DSE version with dse -v, and then compare it with the latest version available for your DSE release series. You can find the latest version in the DSE release notes.

If you need to apply a patch release, upgrade all nodes to the latest patch release before applying any further upgrades. Treat patch releases as you would any major or minor upgrade by carefully reviewing the release notes and following the recommended upgrade procedure. For specific instructions, see apply a DSE 5.1 patch release.
DSE Advanced Replication: If you used Advanced Replication v1 in an earlier DSE version, you must migrate to Advanced Replication v2 before upgrading to DSE 6.8.

DSE 6.8 support only Advanced Replication v2.

If you already migrated, or you never used v1, no action is needed.

If you need to migrate to v2, see Upgrade from DSE 5.0 to DSE 5.1: Post-upgrade steps for DSE Advanced Replication.
Familiarize yourself with the changes and features in the new release, reviewing all releases between your current version and the latest 6.8 patch release as well as the latest Apache Cassandra® 3.11 patch releases:
Upgrade DSE OpsCenter if necessary.

The minimum compatible DSE OpsCenter version for DSE 6.8 and 5.1 is DSE OpsCenter 6.8.4.
Compare your current operating system version to the supported platforms for DSE 6.8:
- If your current OS version is compatible with your new DSE version, no action is needed.
- If your current OS is compatible but outdated, plan to upgrade your OS before or after upgrading DSE to minimize complexity and risk.
- If you need to make significant system environment changes to support your new DSE version, an in-place upgrade might not be feasible or reasonable. Consider using platform migration tools, like the Zero Downtime Migration (ZDM) tools, to migrate to a new cluster with the required infrastructure rather than attempt an in-place upgrade. For assistance, contact IBM Support.
Check Java runtime compatibility and install a mutually supported Java runtime version if needed.

For upgrades from DSE 5.1 to DSE 6.8, install the latest build of OpenJDK 8 (recommended) or Oracle Java SE 8 (JRE or JDK) (supported). OpenJDK is recommended because DataStax does more extensive testing on OpenJDK.
1. Get your current Java version:
  
  java -version
2. Make sure the output shows a supported Java runtime. If not, install a supported Java runtime.
  
  For example, if OpenJDK 8 is installed:
  
  openjdk version "1.8.0_222" OpenJDK Runtime Environment (build 1.8.0_222-8u222-b10-1ubuntu1~18.04.1-b10) OpenJDK 64-Bit Server VM (build 25.222-b10, mixed mode)
3. If your environment has multiple Java versions installed, set the $JAVA_HOME environment variable to Java 8.
4. If you changed $JAVA_HOME, restart the node.
DSE 6.8 supports Java 11 for transactional (Cassandra) workloads. If you want to use Java 11, you can install it and change $JAVA_HOME after upgrading your clusters.
Install the libaio package:
RHEL
sudo yum install libaio
Debian
sudo apt-get install libaio1
Ubuntu 24.04 or later
sudo apt-get install libaio1t64
On Ubuntu 24.04 and later, the libaio library was renamed to libaio1t64. DSE requires a symlink from the old library name to the new one to detect it properly. Without this link, DSE issues a warning about the missing library and performance is significantly degraded.
sudo ln -s /lib/x86_64-linux-gnu/libaio.so.1t64 /lib/x86_64-linux-gnu/libaio.so.1
Make sure each node has adequate free disk space for the upgrade.

The required overhead depends on the compaction strategy. For more information, see Disk space.
1. Get the size of the DSE data directory:
  sudo du -sh /var/lib/cassandra/data/
2. Check available space on disk:
  sudo df -hT /
  The following output includes one disk named /dev/sda1. Your output depends on your disk configuration.
  Filesystem Type Size Used Avail Use% Mounted on /dev/sda1 ext4 59G 16G 41G 28% /
3. If necessary, make adjustments to your disks or data directory configuration to allow for more disk space.

Remove all ITriggers and custom interfaces that are unsupported in DSE 6.x.

DSE 6.x doesn’t support triggers. Don’t use triggers on upgraded nodes because this can introduce severe latency, reliability, and performance issues. Consider using internal APIs instead.

ITriggers and unsupported custom interfaces cannot be modified after upgrading.

Examples of custom implementations to find and remove include the following:

Triggers

The org.apache.cassandra.triggers.ITrigger interface was modified from augment to augmentNonBlocking for non-blocking internal architecture. Upgraded nodes must use the updated trigger implementations. If you’re unsure which implementations are used, drop all existing triggers before upgrading.

Find triggers:
```
SELECT * FROM system_schema.triggers;
```

Drop triggers:

DROP TRIGGER trigger_name ON keyspace_name.table_name;

Custom secondary indexes

The org.apache.cassandra.index.Index interface was modified to comply with the core storage engine changes. Upgraded nodes must use the updated implementations, and unsupported indexes must be dropped.

Unsupported indexes are those that use custom implementations like CREATE CUSTOM INDEX … USING 'com.acme.MyCustomIndexImplementation'.

Supported indexes don’t need to be removed. This includes DSE Search indexes, generic secondary indexes (CREATE INDEX), Solr indexes using built-in interfaces (CREATE CUSTOM INDEX … USING 'com.datastax.bdp.search.solr.Cql3SolrSecondaryIndex).

If you are unsure, drop all existing custom secondary indexes before upgrading.

Check for existing indexes:
```
SELECT * FROM system_schema.indexes;
```
Drop an index by index name:
```
DROP INDEX index_name;
```

Custom query handlers and payload implementations

org.apache.cassandra.cql3.QueryHandler, org.apache.cassandra.db.commitlog.CommitLogReadHandler, and other extension points have changed. You must find and remove custom query handlers and custom payload implementations. For more information, see the documentation for your Cassandra driver. If you need assistance, contact IBM Support.

Migrate all non-system tables that use COMPACT STORAGE to CQL table format.

Thrift-compatible tables (COMPACT STORAGE) aren’t supported in DSE 6.x.

Upgraded nodes won’t start if any non-system tables use COMPACT STORAGE.
1. Get the schema so you can check for tables using COMPACT STORAGE.
  
  The following command outputs the full schema to a file named schema_file:
  cqlsh -e 'DESCRIBE FULL SCHEMA;' > schema_file
2. If any non-system tables use COMPACT STORAGE, use ALTER TABLE to drop COMPACT STORAGE from those tables:
  ALTER TABLE keyspace_name.table_name DROP COMPACT STORAGE;
  If you have a lot of tables with COMPACT STORAGE, you can use a script to automate this process. The following example reads the schema_file from the previous step, uses grep to find lines containing COMPACT STORAGE, and then writes the required ALTER TABLE commands to a file named schema-drop-list:
  cat schema_file | while read -d $';\n' line ; do if echo "$line"|grep 'COMPACT STORAGE' 2>&1 > /dev/null ; then TBL="`echo $line|sed -e 's|^CREATE TABLE $[^ ]*$ .*$|\1|'`" if echo "$TBL"|egrep -v '^system' 2>&1 > /dev/null; then echo "ALTER TABLE $TBL DROP COMPACT STORAGE;" >> schema-drop-list fi fi done
  Then, you can run the ALTER TABLE commands individually by copying them from schema-drop-list, or you can pass the entire schema-drop-list file to cqlsh to run all of the ALTER TABLE commands:
  cqlsh -f schema-drop-list
Ensure that keyspace replication factors are correct for your environment.

Check user-defined, analytics, system_auth, and dse_security keyspaces.
1. Get the current replication factor:
  cqlsh --execute "DESCRIBE KEYSPACE keyspace-name;" | grep "replication"
2. If necessary, alter or recreate keyspaces with the correct replication factor:
  ALTER KEYSPACE keyspace-name WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3'} AND durable_writes = true;
  If you use NetworkTopologyStrategy, the replication factor is set for each datacenter in the form of 'DATACENTER_NAME': 'FACTOR'. Use commas to separate datacenter-factor pairs.
  
  For more information, see Setting the replication factor for analytics keyspaces and Configure the security keyspaces replication factors.
If audit logging is configured to use CassandraAuditWriter:
1. Run the following CQL commands with a superuser role on DSE 5.1 nodes:
  ALTER TABLE dse_audit.audit_log ADD authenticated text;
  ALTER TABLE dse_audit.audit_log ADD consistency text
2. Run nodetool describecluster to verify that the entire cluster has schema agreement.
  
  For example:
  Cluster Information: Name: Test Cluster Snitch: com.datastax.bdp.snitch.DynamicEndpointSnitch DynamicEndPointSnitch: enabled Partitioner: org.apache.cassandra.dht.Murmur3Partitioner Schema versions: 0fffd971-b7a4-33ae-859d-8ca792cd2852: [10.116.138.23]
3. If there are any schema discrepancies, restart the misaligned nodes and rerun nodetool describecluster until the output shows only one schema version.
In cassandra.yaml, set key_cache_save_period to 0.

You must do this before upgrading SSTables in the next step.

Upgraded nodes will fail if this parameter isn’t disabled (set to 0) because the key cache is deprecated in DSE 6.8.

Upgrade all SSTables on all nodes.

To avoid significant performance degradation and issues with incompatible SSTables formats, always upgrade SSTables before and after any database upgrade, including minor and patch releases.

This process is recommended for all upgrades, and it is critical for upgrades that involve a major underlying Cassandra version change.

On each node, run nodetool upgradesstables with the -a flag to ensure that all SSTables use the latest SSTable format and version for your current database version:

nodetool upgradesstables -a

DataStax recommends running the upgradesstables command on one node at a time or, when using racks, one rack at a time. Running the command on too many nodes at once can degrade performance.

You can use the --jobs option to set the number of SSTables that upgrade simultaneously. The default setting is 2, which minimizes the impact on the cluster. Set to 0 to use all available compaction threads.

If all SSTables are already on the latest version and format, the command returns immediately and takes no action.

For more information about this command, see nodetool upgradesstables.

Run nodetool repair to ensure that data on each replica is consistent with data on other nodes:
```
nodetool repair -pr
```
Repair nodes on a regular basis to minimize the overhead and time required for repair operations.

If you use DSE OpsCenter, you can repair nodes with the Repair Service but you must disable the Repair Service before upgrading any nodes.

Back up all DSE data and files, and then store the backups separately from your existing DSE installation.

Backup your existing installation before every upgrade, regardless of the extent of the upgrade.

To avoid data loss, you must store your backup configuration files in a separate directory from your DSE installation. The new version overwrites configuration files that are present in the installation directory, replacing all existing values with new default values.

Examples of data and files to back up include:

SSTable snapshots
Commit logs
Logs
Configuration files
Encrypted table recovery data:
- A snapshot of the entire dse_system keyspace with the encrypted_keys table
- All system keys

Some backup files are used during the upgrade process to align the new version with the previous version, and a complete backup is required if you need to rollback to the previous version or restore lost data.

If your upgrade requires significant pre-upgrade changes, consider creating a backup before making those changes and again immediately before upgrading the first node. Create the final backup as close to the beginning of your upgrade as possible to ensure your backup contains the most recent configuration files and data.

For instructions, see Back up and restore a DSE package installation or Back up and restore a DSE tarball installation.

Upgrades from 5.1.0 or 5.1.1: Restart the node with -Dcassandra.force_3_0_protocol_version=true to enforce a backwards-compatible protocol version:
```
installation_location/bin/dse cassandra -Dcassandra.force_3_0_protocol_version=true
```
After the upgrade is complete, you can remove this flag.

This step isn’t required if you are already running 5.1.2 or later.

While mixed versions exist during the upgrade, don’t add or remove columns from existing tables.

Additional preparation for DSE Search nodes

Complete these additional pre-upgrade steps on DSE Search nodes while DSE 5.1 is still running.

DataStax recommends running nodetool repair and creating a fresh backup after making these changes, even if you already did so during the pre-upgrade steps.

Schema changes might require a full reindex, and configuration changes require reloading the core.

Change all HTTP API writes to Cassandra Query Language (CQL) commands for updates and inserts.

See Search index config for valid options to change query behavior for search indexes.
In your search index configuration, remove the unsupported dataDir option.

You can still set the location of search indexes.

In your search index configuration, remove or replace mergePolicy, maxMergeDocs, and mergeFactor.

For example, if you have the following configuration:

<mergeFactor>25</mergeFactor>
<maxMergeDocs>...
<mergePolicy>...

Replace mergePolicy with mergePolicyFactory and add mergeScheduler:

<mergeScheduler class="org.apache.lucene.index.ConcurrentMergeScheduler">
    <int name="maxThreadCount">16</int>
    <int name="maxMergeCount">32</int>
</mergeScheduler>
...
<mergePolicyFactory class="org.apache.solr.index.TieredMergePolicyFactory">
  <int name="maxMergeAtOnce">10</int>
  <int name="segmentsPerTier">10</int>
</mergePolicyFactory>

In your search index configuration, remove any instance of ExtractingRequestHandler.

In your search index configuration, remove DSENRTCachingDirectoryFactory.

For example, if you have the following configuration:

<directoryFactory name="DirectoryFactory" class="com.datastax.bdp.search.solr.DSENRTCachingDirectoryFactory"/>

Replace it with the new configuration:

<directoryFactory name="DirectoryFactory" class="solr.StandardDirectoryFactory"/>

If you had a custom configuration for the Solr UI web.xml file:

Change the following configuration:

<filter-class>com.datastax.bdp.search.solr.auth.DseAuthenticationFilter</filter-class>

To the new configuration:

<filter-class>com.datastax.bdp.cassandra.auth.http.DseAuthenticationFilter</filter-class>

Be aware that the StallMetrics MBean is removed in DSE 6.8.
Be aware that DSE Search workloads might experience performance variability after upgrading from DSE 5.1 to DSE 6.x.

If you didn’t already plan to do so, DataStax strongly recommends that you test the upgrade on an isolated node, datacenter, or cluster so you can assess DSE Search performance before rolling out the upgrade in production.

The DSE Advanced Performance feature introduced in DSE 6.0 includes a fundamental architecture change. Performance is highly dependent on your data access patterns and workloads. This variability is most often observed in environments that don’t follow the DataStax hardware layout recommendations. For example, DataStax recommends 16 or more logical cores for Advanced Performance nodes, and tuning DSE Search for maximum indexing throughput.

In response to this scenario, DataStax extended DSE 5.1 EOL support to June 30, 2026, and DataStax investigates performance differences related to DSE Search that occur after some upgrades to DSE 6.x. Additional details are included in the DSE release notes.

Additional preparation for DSE Graph nodes

Names of edge labels and property keys must use only supported characters: a-z, A-Z, 0-9, underscores, hyphens, and periods.

In earlier versions, these names were nearly unrestricted. The upgrade process retains existing schemas with invalid names. However, schema elements with illegal names cannot be updated or added after the upgrade.

Use schema.describe() to get the entire schema, including illegal names, and then edit the schema to correct any illegal names.
Be aware that DSE Graph workloads might experience performance variability after upgrading from DSE 5.1 to DSE 6.x.

If you didn’t already plan to do so, DataStax strongly recommends that you test the upgrade on an isolated node, datacenter, or cluster so you can assess DSE Graph performance before rolling out the upgrade in production.

The DSE Advanced Performance feature introduced in DSE 6.0 includes a fundamental architecture change. Performance is highly dependent on your data access patterns and workloads. This variability is most often observed in environments that don’t follow the DataStax hardware layout recommendations. For example, DataStax recommends 16 or more logical cores for Advanced Performance nodes.

In response to this scenario, DataStax extended DSE 5.1 EOL support to June 30, 2026, and DataStax investigates performance differences related to DSE Graph that occur after some upgrades to DSE 6.x. Additional details are included in the DSE release notes.

Additional preparation for DSE Analytics nodes

Complete these additional pre-upgrade steps on DSE Analytics nodes while DSE 5.1 is still running.

DataStax recommends running nodetool repair and creating a fresh backup after making these changes, even if you already did so during the pre-upgrade steps.

If you programmatically set the shuffle parameter, you must change any application code that uses conf.set("spark.shuffle.service.port", port) to use dse spark-submit.

dse spark-submit automatically sets the correct service port based on the authentication state.
Switch from the Cassandra File System (CFS) to the DSE File System (DSEFS).

For more information, see Copying data from CFS to DSEFS.
1. Enable DSEFS in your DSE 5.1 installation.
2. Copy the CFS hivemetastore directory (if it exists) to DSEFS:
  INSTALL_DIRECTORY/bin/dse hadoop fs -cp cfs://NODE_HOSTNAME_OR_IP/user/spark/warehouse/ dsefs://NODE_HOSTNAME_OR_IP/user/spark/warehouse/
3. Verify that the data was copied:
  INSTALL_DIRECTORY/bin/dse hadoop fs -ls dsefs://NODE_HOSTNAME_OR_IP/user/spark/warehouse/
4. Now that you moved the CFS data to DSEFS, you can remove the cfs and cfs_archive keyspaces:
  DROP KEYSPACE cfs
  DROP KEYSPACE cfs_archive
Make sure all SPARK_LOCAL_DIRS and SPARK_EXECUTOR_DIRS environment variables match the intended use described in Set environment variables.
Migrate jobs that extend from SparkHiveJob or SparkSqlJob to SparkSessionJob.

This change is required to allow your applications to use the Spark Jobserver API version that is compatible with DSE 6.8.

For an example, see DemoSparkSessionJob in your DSE installation’s demos directory. The default location of the demos directory depends on the type of installation:
- Package installations: /usr/share/dse/demos
- Tarball installations: INSTALL_DIRECTORY/demos

Upgrade steps

Upgrade one node at a time in the recommended order. Following the recommended order minimizes downtime and ensures that you don’t miss any nodes.

DSE Analytics nodes: Kill all Spark worker processes:

for pid in $(jps | grep Worker | awk '{print $1}'); do kill -9 $pid; done

Flush the commit log of the current installation:
```
nodetool drain
```
Stop the node.

Install the new DSE version, but don’t start DSE.

Don’t start DSE yet. Before restarting the node, you must reconfigure DSE as explained in the next steps.

If you use DSE OpsCenter, you can use Lifecycle Manager (LCM) to clone a configuration profile and run an upgrade job on a datacenter or node. This approach can help streamline the install and reconfiguration process.

Use the same installation type as your current version. Mismatched installation types can cause problems with the upgrade.

Configure the new DSE version by comparing the new configuration files to your backup configuration files.

Specific modifications are described in the next steps. Additional changes depend on your workloads and previous configurations. For example:

Remove deprecated and removed settings.
Configure new settings.
Migrate previous custom configuration values to your new configuration files.
Modify previous configurations to account for changes described in the DSE release notes.

You must use the new configuration files included with your new installation. Copy values from your old configuration files into the new files. Don’t overwrite entire files with the old files.

For default configuration file locations in DSE 6.8, see Default file locations for package installations and Default file locations for tarball installations.

You can use the yaml_diff tool to compare your backup YAML files with the new YAML files:

cd /usr/share/dse/tools/yamls

./yaml_diff path/to/yaml-file-old path/to/yaml-file-new

The output is a diff between the specified YAML files. For example:

...
 CHANGES
=========
authenticator:
- AllowAllAuthenticator
+ com.datastax.bdp.cassandra.auth.DseAuthenticator

authorizer:
- AllowAllAuthorizer
+ com.datastax.bdp.cassandra.auth.DseAuthorizer

roles_validity_in_ms:
- 2000
+ 120000
...

Copy custom JVM options from your previous version’s jvm.options file to the new version’s jvm-server.options file, and then remove the previous jvm.options file from the installation directory.

DSE 6.8 uses jvm-server.options instead of jvm.options, and retaining the previous jvm.options file can cause errors in DSE functionality.

In cassandra.yaml, remove the following deprecated settings that have no replacement:

concurrent_counter_writes
concurrent_materialized_view_writes
concurrent_reads
concurrent_writes
max_client_wait_time_ms
max_threads
request_scheduler
request_scheduler_options
rpc_port
rpc_server_type
start_rpc
thrift_framed_transport_size_in_mb
thrift_prepared_statements_cache_size_mb

In cassandra.yaml, replace the deprecated RPC settings rpc_address and rpc_broadcast_address with the new settings native_transport_address and native_transport_broadcast_address.
In cassandra.yaml, replace the deprecated memtable settings memtable_heap_space_in_mb and memtable_offheap_space_in_mb with the new setting memtable_space_in_mb.
In cassandra.yaml, set memtable_allocation_type to offheap_objects:
```
memtable_allocation_type: offheap_objects
```
In cassandra.yaml, replace deprecated user-defined function (UDF) settings:
1. Remove the deprecated settings user_defined_function_warn_timeout and user_defined_function_fail_timeout.
2. Replace the removed settings with the following settings.
  
  The new timeouts are in microseconds, and they aren’t equivalent to the deprecated settings.
  user_defined_function_warn_micros: 500 user_defined_function_fail_micros: 10000 user_defined_function_warn_heap_mb: 200 user_defined_function_fail_heap_mb: 500 user_function_timeout_policy: die
In cassandra.yaml, replace the deprecated store_type setting in server_encryption_options and client_encryption_options with keystore_type and truststore_type:
```
server_encryption_options:
    keystore_type: JKS
    truststore_type: JKS

...

client_encryption_options:
    keystore_type: JKS
    truststore_type: JKS
```
Valid values for keystore_type are JKS, JCEKS, PKCS11, or PKCS12. Valid values for truststore_type are JKS, JCEKS, or PKCS12.
In cassandra.yaml, set the protocol setting to TLS in server_encryption_options and client_encryption_options.

For security reasons and the deprecation of SSLv3 in Oracle Java 8u31, DSE 6.8 allows only TLS for the encryption protocol.
```
server_encryption_options:
    ...
    protocol: TLS

...

client_encryption_options:
    ...
    protocol: TLS
```
In cassandra.yaml, remove deprecated credential cache settings that are no longer required for cache optimization in DSE 6.8:
```
credentials_validity_in_ms
credentials_update_interval_in_ms
```
In dse.yaml, replace deprecated Spark resource and encryption options:
1. Remove the following deprecated options:
  spark_ui_options: server_encryption_options: store_type: JKS
2. Replace the deprecated options with the new options:
  spark_ui_options_options: server_encryption_options: keystore_type: JKS truststore_type: JKS
  Valid values for keystore_type are JKS, JCEKS, PKCS11, or PKCS12. Valid values for truststore_type are JKS, JCEKS, or PKCS12.
In dse.yaml, remove the following deprecated DSE Search node settings that have no replacement.

DSE won’t start if these options are present.
```
cql_solr_query_executor_threads
enable_back_pressure_adaptive_nrt_commit
max_solr_concurrency_per_core
solr_indexing_error_log_options
```
Remove any previously installed Java Topology Suite (JTS) JAR files from the CLASSPATHS in your DSE installation.

JTS is distributed with DSE versions 6.8.
Upgrades to 6.7.0 through 6.7.3: If you are intentionally installing a version earlier than 6.7.4 and any tables use DSE Tiered Storage, then you must remove all txn_compaction log files from second-level tiers and lower.

At versions 6.7.0 to 6.7.3, data loss can occur if you don’t remove the txn_compaction log files before starting DSE. DataStax strongly recommends that you upgrade to 6.7.4 or later.

You can find the tiers and directories in the dse.yaml configuration file. For example, given the following tiered_storage_options configuration, you would remove txn_compaction log files from the /mnt2 and /mnt3 directories:
```
tiered_storage_options:
    strategy1:
        tiers:
            - paths:
                - /mnt1
            - paths:
                - /mnt2
            - paths:
                - /mnt3
```
The following example removes the files from the second and third tier directories using find commands:
```
find /mnt2 -name "*_txn_compaction_*.log" -type f -delete &&
find /mnt3 -name "*_txn_compaction_*.log" -type f -delete
```
Make sure the catalina.properties and context.xml files are present in the Apache Tomcat® conf directory.

DSE won’t start after the upgrade if these files are missing.

The default location of the Tomcat conf directory depends on the type of installation:
- Package installations: /etc/dse/tomcat/conf
- Tarball installations: INSTALL_DIRECTORY/resources/tomcat/conf
Start the node:
- Package installations: Start DataStax Enterprise as a service
- Tarball installations: Start DataStax Enterprise as a standalone process
Verify that the upgraded datacenter names match the datacenter names in the keyspace schema definition.

This is only relevant when using NetworkTopologyStrategy.
1. Get the node’s datacenter name:
  nodetool status | grep "Datacenter"
2. Get the replication configuration for a keyspace:
  cqlsh --execute "DESCRIBE KEYSPACE keyspace-name;" | grep "replication"
3. If the datacenter name in replication does not match the node’s datacenter name, alter or recreate the keyspace accordingly:
  ALTER KEYSPACE keyspace-name WITH replication = {'class': 'NetworkTopologyStrategy', 'datacenter-name': '3'};
Review the logs for warnings, errors, and exceptions:
```
grep -w 'WARN\|ERROR\|exception' /var/log/cassandra/*.log
```
If the default log location returns no results, check dse-env.sh for custom log locations.

Warnings, errors, and exceptions are frequently found in the logs when starting an upgraded node. Some messages provide information to help you complete specific upgrade steps, and some messages can be ignored while the cluster is in a partially upgraded state. If you find warnings, errors, or exceptions that are unexpected or persist after upgrading the entire cluster, contact IBM Support.

For DSE Graph nodes, warnings are logged for gremlin_server properties from earlier versions of DSE that are no longer required. For example:
```
WARN [main] 2017-08-31 12:25:30,523 GREMLIN DseWebSocketChannelizer.java:149 - Configuration for the org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV1d0 serializer in dse.yaml overrides the DSE default - typically it is best to allow DSE to configure these.
```
These warnings are generated if any such properties exist in dse.yaml. You can ignore these warnings, or you can modify dse.yaml to use only the required Gremlin server properties.
Repeat the upgrade process on each node in the cluster following the recommended order.

Post-upgrade steps

The post-upgrade steps include multi-node and cross-datacenter operations that can cause errors while a cluster is in a partially upgraded state. For example, repairs can propagate incompatible data between mixed-version nodes, and SSTable snapshots can be corrupted or unreadable due to mixed SSTable formats and versions.

Only start the post-upgrade steps after you upgrade all dependent nodes. Node dependencies are determined by your deployment architecture:

Architecture	Examples	Post-upgrade path
Isolated or non-production deployment	Upgrading a test deployment before rolling out the upgrade to production. Upgrading a passive datacenter in an active-passive multi-datacenter deployment.	Start the post-upgrade steps after upgrading all nodes in the test deployment or passive datacenter. For example, in a test deployment with two datacenters and cross-datacenter replication, you must upgrade all nodes in both datacenters before starting the post-upgrade steps. In contrast, in a test deployment with one datacenter and no cross-datacenter connections, you must upgrade all nodes in that datacenter before starting the post-upgrade steps.
Production deployment	Rolling out an upgrade to an entire production cluster. Upgrading a multi-datacenter deployment that has cross-datacenter replication.	Start the post-upgrade steps after upgrading all nodes included in the deployment. For example, in a multi-datacenter deployment with cross-datacenter replication, you must upgrade all nodes in all datacenters before starting the post-upgrade steps.

Architecture

Examples

Post-upgrade path

Isolated or non-production deployment

Upgrading a test deployment before rolling out the upgrade to production.
Upgrading a passive datacenter in an active-passive multi-datacenter deployment.

Start the post-upgrade steps after upgrading all nodes in the test deployment or passive datacenter.

For example, in a test deployment with two datacenters and cross-datacenter replication, you must upgrade all nodes in both datacenters before starting the post-upgrade steps.

In contrast, in a test deployment with one datacenter and no cross-datacenter connections, you must upgrade all nodes in that datacenter before starting the post-upgrade steps.

Production deployment

Rolling out an upgrade to an entire production cluster.
Upgrading a multi-datacenter deployment that has cross-datacenter replication.

Start the post-upgrade steps after upgrading all nodes included in the deployment.

For example, in a multi-datacenter deployment with cross-datacenter replication, you must upgrade all nodes in all datacenters before starting the post-upgrade steps.

Complete the post-upgrade steps progressively in the recommended order. Modify the recommended order as needed for your deployment architecture and workloads.

Upgrade all SSTables again.

Your database upgrade isn’t complete until you upgrade all SSTables.

To avoid significant performance degradation and issues with incompatible SSTables formats, always upgrade SSTables before and after any database upgrade, including minor and patch releases.

This process is recommended for all upgrades, and it is critical for upgrades that involve a major underlying Cassandra version change.

On each node, run nodetool upgradesstables with the -a flag to ensure that all SSTables use the latest SSTable format and version for your current database version:

nodetool upgradesstables -a

DataStax recommends running the upgradesstables command on one node at a time or, when using racks, one rack at a time. Running the command on too many nodes at once can degrade performance.

If all SSTables are already on the latest version and format, the command returns immediately and takes no action.

Review your security configuration.

To use security, enable and configure DSE Unified Authentication.

In cassandra.yaml, the default authenticator is DseAuthenticator and the default authorizer is DseAuthorizer. Security is disabled in dse.yaml by default.
Update commands and scripts that query system.local or system.peers to use the metadata_directory:

Starting in DSE 6.8, the metadata_directory property that holds information about the local node and all peers. This metadata_directory stores the same information as system.local and system.peers in earlier versions.
Restart any services or automated operations that you disabled before starting the upgrade.

For more information, see Avoid certain operations during the upgrade.
Optional: Reconfigure or disable the DSE Metrics Collector, depending on your preference.

This tool is a diagnostics information aggregator used to help facilitate DSE problem resolution.

In DSE 6.8, the DSE Metrics Collector is enabled by default.
Migrate off of DSE In-Memory, Tiered Storage, and Multi-Instance.

These services are deprecated in DSE 6.8 and will be removed in a future release.

Post-upgrade steps for DSE Search nodes

Learn how DSE 6.8 limits queries by time to prevent excess resource consumption.

Starting in DSE 6.8.0, the Solr timeAllowed parameter is enabled by default to prevent long running shard queries, such as complex facets and Boolean queries, from using system resources after they have timed out from the DSE Search coordinator.
In logback.xml, you can remove the unused appender SolrValidationErrorAppender and the unused logger SolrValidationErrorLogger.
Recommended: If you previously used a custom value for back_pressure_threshold_per_core in dse.yaml, use the default value of 1024 unless you have a specific reason to use a non-default value.

For more information, see Tuning search for maximum indexing throughput.
Migrate encrypted tables and indexes.

Encrypted tables and indexes must be migrated after upgrading DSE.

Post-upgrade steps for DSE Analytics nodes

Because the Spark Jobserver uses a custom version for DSE, make sure your applications use the compatible Spark Jobserver API from the DataStax Jobserver repository.

You can check the Spark Jobserver version in the DSE release notes.
Check the replication factor for the dse_analytics keyspace.

Starting in DSE 6.0, this keyspace stores all DSE Analytics internal system data.
1. Check the replication settings for the dse_analytics keyspace:
  cqlsh --execute "DESCRIBE KEYSPACE dse_analytics;" | grep "replication"
2. If needed, alter the keyspace.
  
  DataStax recommends setting the replication strategy to NetworkTopologyStrategy (NTS) with a minimum replication factor of 3 in each of your DSE Analytics datacenters. If a datacenter has more nodes, consider setting a larger replication factor.
  ALTER KEYSPACE dse_analytics WITH replication = {'class': 'NetworkTopologyStrategy', 'datacenter-name': '3'};
  With NetworkTopologyStrategy, the replication factor is set for each datacenter in the form of 'DATACENTER_NAME': 'FACTOR'. Use commas to separate datacenter-factor pairs.
If you are using Spark SQL tables, migrate them to the new Hive metastore format:
```
dse client-tool spark metastore migrate --from 5.1.0 --to 6.8.0
```
Configure authorization for the Spark web UI if security is enabled.

In DSE 6.8, the default behavior for the Spark web UI can prevent non-superuser DSE users from accessing the Spark web UI. To grant Spark web UI authorization to non-superusers, edit spark-daemon-defaults.conf in your installation’s Spark configuration directory, and set spark.ui.filters to com.datastax.bdp.auth.SparkUIAuthFilter or com.datastax.bdp.auth.SparkUIAuth*z*Filter.

Lock DSE package versions

After upgrading a DSE package installation, you can prevent unintended upgrades by locking the package version:

Yum

Install yum-versionlock if it isn’t already installed:
```
sudo yum install yum-versionlock
```
Lock the current DSE version:
```
sudo yum versionlock dse-*
```
When you need to allow an upgrade, clear the version lock:
```
sudo yum versionlock clear
```

APT

Use apt-mark to hold the dse package at the current version:
```
sudo apt-mark hold dse-*
```
When you need to allow an upgrade, remove the hold:
```
sudo apt-mark unhold dse-*
```