Upgrading DataStax Enterprise 5.0 to 5.1

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 DSE version or protocol version. For example, the initial contact points contain only protocol version 2.

Change HTTP API queries to CQL queries:

If any Solr core was created on DSE 4.6 or earlier and never reindexed after being upgraded to DSE 4.7 or later, you must reindex on DSE 5.0 before upgrading to DSE 5.1:

dsetool reload_core keyspace_name.table_name schema=filepath solrconfig=filepath reindex=true deleteAll=true distributed=false

If you are using Apache Solr SolrJ, the minimum required Solr version is 6.0.0. To find the current Solr version:

installation_directory/bin/solr status

For SpatialRecursivePrefixTreeFieldType (RPT) in search schemas, you must adjust your queries for these changes:

Edit the solrconfig.xml file and make these changes, as needed:

The Circle syntax is no longer a part of Well-Known-Text (WKT); therefore, Spatial Search queries such as:

Intersects(Circle(10 10 d=2))

Intersects(BUFFER(POINT(10 10), 2)

Upgrading DSE search nodes requires replacing unsupported Solr types with supported types.

Update the schema and configuration for the Solr field types that are removed from Solr 5.5 and later.

Remove these unsupported Solr requestHandlers:

Remove <unlockOnStartup>.

Reload the core:

dsetool reload_core keyspace_name.table_name reindex=false

DSE versions earlier than 5.1 use an older version of Spark and applications written using that version (1.6) may not be compatible with Spark 2.2. You must recompile all DSE 5.0 Scala Spark applications against Scala 2.11 and use only Scala 2.11 third-party libraries.

Spark applications should use dse:// URLs instead of spark://spark_master_IP:Spark_RPC_port_number URLs, as described in Specifying Spark URLs.

Modify calls to setMaster and setAppName.

val conf = new SparkConf(true)
.setMaster("spark://192.168.123.10:7077")
.setAppName("cassandra-demo")
.set("cassandra.connection.host" , "192.168.123.10") // initial contact
.set("cassandra.username", "cassandra")
.set("cassandra.password", "cassandra")
val sc = new SparkContext(conf)

val conf = new SparkConf(true)
**.appName**("cassandra-demo")
**.master**("dse://192.168.123.10:7077")
.set("cassandra.connection.host" , "192.168.123.10") // initial contact
.set("cassandra.username", "cassandra")
.set("cassandra.password", "cassandra")
val sc = new SparkContext(conf)

Upgrade to the latest patch release on your current version. Fixes included in the latest patch release can simplify the upgrade process.

bin/dse -v
current_dse_version

Familiarize yourself with the changes and features in the new release:

Before upgrading, be sure that each node has adequate free disk space.

sudo du -sh /var/lib/cassandra/data/
3.9G	/var/lib/cassandra/data/

sudo df -hT /
Filesystem     Type  Size  Used Avail Use% Mounted on
/dev/sda1      ext4   59G   16G   41G  28% /

Upgrade the SSTables on each node to ensure that all SSTables are on the current version:

nodetool upgradesstables

Ensure that keyspace replication factors are correct for your environment:

cqlsh --execute "DESCRIBE KEYSPACE keyspace-name;" | grep "replication"
CREATE KEYSPACE keyspace-name WITH replication = {'class': 'NetworkTopologyStrategy, 'replication_factor': '3'}  AND durable_writes = true;

Verify the Java runtime version and upgrade to the recommended version.

java -version
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)

Run nodetool repair to ensure that data on each replica is consistent with data on other nodes:

nodetool repair -pr

Install the libaio package for optimal performance.

sudo yum install libaio

sudo apt-get install libaio1

Back up any customized configuration files since they may be overwritten with default values during installation of the new version.

Upgrades from 5.0.0 to 5.0.8 and from DSE 5.1.0 and 5.1.1 to DSE 5.1.2 and later releases:

-Dcassandra.force_3_0_protocol_version=true

installation_location/bin/dse cassandra -Dcassandra.force_3_0_protocol_version=true

Flush the commit log of the current installation:

nodetool drain

DSE Analytics nodes only: Kill all Spark worker processes:

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

Stop the node:

Use the appropriate method to install the new product version on a supported platform:

To configure the new product version:

When upgrading DSE to versions earlier than 5.1.16, 6.0.8, or 6.7.4 inclusive, if any tables are using DSE Tiered Storage, remove all txn_compaction log files from second-level tiers and lower. For example, given the following dse.yaml configuration, remove txn_compaction log files from /mnt2 and /mnt3 directories:

tiered_storage_options:
    strategy1:
        tiers:
            - paths:
                - /mnt1
            - paths:
                - /mnt2
            - paths:
                - /mnt3

find /mnt2 -name "*_txn_compaction_*.log" -type f -delete &&
find /mnt3 -name "*_txn_compaction_*.log" -type f -delete

DSE Analytics nodes only: If your DSE 5.0 clusters had any datacenters running in Analytics Hadoop mode and if the DseSimpleSnitch was used, you must use one of these options for starting nodes in your cluster. Select the option that works best for your environment:

Start the node.

Verify that the upgraded datacenter names match the datacenter names in the keyspace schema definition:

Review the logs for warnings, errors, and exceptions:

grep -w 'WARNING\|ERROR\|exception' /var/log/cassandra/*.log

Repeat the upgrade process on each node in the cluster following the recommended order.

After the entire cluster upgrade is complete: upgrade the SSTables on one node at a time or, when using racks, one rack at a time.

nodetool upgradesstables

If you use the OpsCenter Repair Service, turn on the Repair Service.

If you encounter serialization-header errors, stop the node and repair them using the sstablescrub -e option:

sstablescrub -e fix-only keyspace table

Review your security configuration. To use security, enable and configure DSE Unified Authentication.

TimeWindowCompactionStrategy (TWCS (6.7) | TWCS (6.8)) is set only on new dse_perf and dse_audit_log tables. Manually change dse_perf and dse_audit_log tables that were created in earlier releases to use TWCS. For example:

ALTER TABLE dse_perf.read_latency_histograms WITH COMPACTION={'class':'TimeWindowCompactionStrategy'};

ALTER TABLE dse_audit_log.audit_log WITH COMPACTION={'class':'TimeWindowCompactionStrategy'};

Index time boost support is removed in DSE 5.1.1 and later. Use query time boosting instead. Delete any _docBoost columns in backing CQL tables:

DELETE _docBoost FROM table-name IF EXISTS;
DELETE _docBoost FROM table-name IF EXISTS;

If SpatialRecursivePrefixTreeFieldType (RPT) is used in the search schema, replace the units field type with a suitable (degrees, kilometers, or miles) distanceUnits, and then verify that spatial queries behave as expected.

For optimal indexing of multipolygon shapes, you must set useJtsMulti="false". For example:

<fieldType autoIndex="true" useJtsMulti="false"
                class="solr.SpatialRecursivePrefixTreeFieldType" distErrPct="0.0125"
                distanceUnits="kilometers" geo="true" name="WktField" spatialContextFactory="org.locationtech.
                spatial4j.context.jts.JtsSpatialContextFactory"/>

If you are using HTTP API writes with JSON documents (deprecated), a known issue may cause the auto-generated solrconfig.xml to have an invalid requestHandler for JSON core creations. If necessary, change the auto-generated solrconfig.xml:

<requestHandler name="/update/json" class="solr.UpdateUpdateRequestHandler" startup="lazy"/>

<requestHandler name="/update/json" class="solr.UpdateRequestHandler" startup="lazy"/>

Do a full reindex of all encrypted search indexes on each node in your cluster:

dsetool reload_core keyspace_name.table_name distributed=false reindex=true deleteAll=true

Stop the node:

Clear the dsefs data directories on each node.

dsefs_options:
     ...
     data_directories:
         - dir: /var/lib/dsefs/data

rm -r /var/lib/dsefs/data/*

In the dsefs_options section of dse.yaml, change the keyspace_name parameter to a different name:

##########################
# DSE File System options
dsefs_options:
    ...
    **keyspace-name: new_keyspace_name**

Start the node.

If you backed up existing DSEFS data before the upgrade, copy the data back into DSEFS from local storage.

dse hadoop fs -cp /local_backup_location/* /dsefs_data_directory/

OPTIONAL: Drop the old dsefs keyspace:

DROP KEYSPACE dsefs

Create a V2 destination for the hub configured in V1:

dse advrep destination create --name dest_name --addresses ip_address --transmission-enabled false

Create a V2 channel for each V1 channel:

dse advrep channel create --source-keyspace keyspace_name --source-table table_name --destination dest_name --source-id source_id --source-id-column source_column_id --priority 1

Resume collection and transmission:

dse advrep channel resume --source-keyspace keyspace_name --source-table table_name --collection-enabled true --transmission-enabled true

Make sure the V2 is running and replicating, then disable collection on the V1 channels:

dse advrep --v1 edge channel pause --keyspace keyspace_name --table table_name

Wait for V1 to drain the V1 replication log, checking for a zero count:

dse advrep --v1 edge rl-count

Delete V1 channels and disable V1 hub:

for f in `dse advrep --v1 edge list-conf|cut -f1 -d' '|sed 1,2d | sed s/_/-/g`; do dse advrep --v1 edge remove-conf --$f; done;

Install yum-versionlock (one-time operation):

sudo yum install yum-versionlock

Lock the current DSE version:

sudo yum versionlock dse-*