About upgrading Apache Cassandra
Upgrading an Apache Cassandra® cluster is accomplished by upgrading the version of Cassandra running on each of the cluster’s constituent nodes. For example, a cluster whose nodes are running Cassandra 3.11.15 is considered fully upgraded once all of its nodes have been successfully upgraded to Cassandra 4.1.2. With only a few exceptions, the cluster as a whole continues to work as though it were on the earlier version of Cassandra until all of the nodes in the cluster are upgraded.
Upgrades can be performed with the cluster either offline or online. One of the many benefits of Cassandra’s distributed architecture is that a cluster needn’t incur downtime while it’s being upgraded. Nodes can be upgraded and restarted one at a time while other nodes continue to operate online, serving replica data.
Upgrading Cassandra involves careful planning and preparations at the cluster-level to ensure minimal disruption to ongoing operations. The appropriate upgrade procedure depends on whether the cluster is required to continue serving data during the course of the upgrade.
The following pages outline the requirements for upgrading a Cassandra cluster:
- Plan your upgrade
-
Create an upgrade plan that’s tailored to your specific environment.
- Learn about the new release
-
Familiarize yourself with new features and changes, and understand how they may impact the upgrade process.
Cassandra 4.x - Review the prerequisites
-
Certain prerequisites are required in order upgrade to a new version of Cassandra.
- Upgrade your cluster
-
Follow the step-by-step process for upgrading your cluster.
Supported upgrade paths
Cassandra version increments follow a traditional versioning scheme of MAJOR.MINOR.PATCH (X.Y.Z):
- Major (X)
-
Backward-incompatible changes can be introduced.
- Minor (Y)
-
New functionality can be introduced, but in a backward-compatible manner.
- Patch (Z)
-
Bugs are fixed in a backward-compatible manner.
Unless documented otherwise, Cassandra can be upgraded to any release in the next major version increment. For example, a cluster running any 3.x release can be upgraded to any 4.x release.
However, upgrades to non-adjacent major versions are not supported. To upgrade by more than one major version increment, you’ll need to upgrade to an intermediate major version first. For example, to upgrade from a 2.x release to a 4.x release, the entire cluster must be upgraded twice; first to 3.x (preferably the latest release: 3.11.15), then again to 4.x (preferably the latest release: 4.1.2).
| Starting version | Path to current version |
|---|---|
Cassandra 2.x |
Supported: 2.x → 3.x → 4.x Recommended: 2.x → 2.2.19 (if not already running) → 3.11.15 → 4.1.2 |
Cassandra 3.x |
Supported: 3.x → 4.x Recommended: 3.x → 3.11.15 (if not already running) → 4.1.2 |
When upgrading to a new major version, it’s recommended that you first upgrade the cluster to the latest patch release on your current version. Fixes included in the latest patch release can help avoid issues and reduce the overall level of risk associated with the upgrade process. For this reason, it’s a general best practice to have a continual upgrade strategy that keeps the cluster on the latest patch release of the current major version.
No matter what version increment you’re upgrading to — whether it’s a major release or a patch release — the node-level upgrade procedures remain largely the same. However, there may be significant differences in the steps required before and after upgrading a major version versus a minor version.
Migrate as an alternative to an in-place upgrade
For significant upgrades across multiple major versions or involving critical breaking changes, consider migrating to a new cluster using the Zero Downtime Migration (ZDM) tools.
ZDM Proxy orchestrates traffic between two independent clusters, allowing you to migrate data from your existing source cluster to your new target cluster without taking either cluster offline or managing the complexities of a rolling upgrade.
You can configure your new cluster with the desired Cassandra version without changing the configuration of your existing cluster.
ZDM Proxy supports the following migration paths to Cassandra:
-
Cassandra 2.1.6 or later to any later Cassandra version.
-
Cassandra 2.0 to Cassandra 2.1 or 2.2.
ZDM Proxy requires that the origin and target clusters share a common Apache Cassandra Native Protocol version, and Cassandra 2.0 supports only
v2. After migrating to 2.1.6 or later, you can migrate to any other Cassandra version.
Migrate from another platform
You can use the Zero Downtime Migration (ZDM) tools to migrate to Cassandra from another Cassandra-based database. ZDM Proxy supports the following migration paths to Cassandra:
-
Astra DB Serverless to Cassandra 2.1.6 or later (latest or LTS versions recommended).
-
Astra Managed Clusters (Astra DB Classic) to Cassandra 2.1.6 or later (latest or LTS versions recommended).
If you have Tier E Astra Managed Clusters databases that use DSE advanced workloads, you cannot migrate data or CQL statements related to these workloads. You must adjust your data model and application logic to remove dependencies on these workloads before starting the migration.
-
Any Hyper-Converged Database (HCD) version to Cassandra 2.1.6 or later (3.11 or later recommended).
-
DataStax Enterprise (DSE) version 4.7.1 or later to Cassandra 2.1.6 or later.
For DSE 5.1, 6.8, or 6.9, Cassandra 3.11 or later is recommended.
-
Other Cassandra-based or CQL-compatible databases, such as ScyllaDB and Yugabyte, that share a common Apache Cassandra Native Protocol version with your target Cassandra version. A common protocol version is required for ZDM Proxy to function successfully.
DataStax tests ZDM Proxy compatibility with Astra DB, DSE, HCD, and open-source Cassandra. DataStax doesn’t guarantee support for any untested cluster aside from the platforms and versions listed here. As with any migration, DataStax recommends that you run isolated tests before attempting a full-scale production migration.
Migrate to another platform
If you’re using the open source version of Cassandra, you can migrate your clusters to DSE, HCD, or Astra DB. This can be done as an in-place upgrade or with the Zero Downtime Migration (ZDM) tools. For more information, see the following:
Downgrade Cassandra
Cassandra doesn’t have a direct mechanism for downgrading to a previous version once it has been upgraded to a newer version.
However, if issues occur during the course of a cluster upgrade, nodes can be rolled back to the previous version of Cassandra and restored from a snapshot backup.
Another option is to create an entirely new cluster running a lower version of Cassandra and migrate the data from the newly upgraded cluster.
