Skip to content
AxonOps Documentation

AxonOps — AI-Native Control Plane for Open Source Data Platforms

Phase 3: DSE to Cassandra Data Migration (CDM & ZDM)

This phase performs the actual data migration. It assumes ZDM Proxy and CDM Setup has been read and the migration infrastructure prepared.

The approach described here is the CDM + ZDM Proxy path, which works for all DSE versions and is the recommended path for DSE 6.0+. Operators on DSE 5.1 or earlier who prefer to add an open-source datacenter to the existing ring rather than stand up a separate cluster may use the Second Datacenter Migration path instead.

DSE 6.0+: this is the safest path

DSE 6.0+ uses the proprietary BTI SSTable format and EverywhereStrategy system keyspaces, which make adding an open-source datacenter to the existing ring highly nuanced and expert-only (see Second Datacenter Migration). For DSE 6.0+, migrating to a separate target cluster with CDM + ZDM Proxy is the safest and recommended approach.

Why a data migration is required for all versions

Section titled “Why a data migration is required for all versions”

Even DSE 4.x and 5.x, whose SSTables are compatible with their underlying Cassandra versions (2.0 to 3.11), cannot be migrated in-place to a current Apache Cassandra release. Those versions are several major releases behind, and Cassandra does not support skipping major versions. A data migration to a new open-source Apache Cassandra cluster sidesteps the version gap entirely, and because the proxy handles traffic, it does so with no downtime.

For a 6-node cluster, a typical migration runs 1 to 5 days depending on data volume, network bandwidth, and compaction load. There is no service downtime, because the proxy routes traffic throughout.

Provision the target cluster

Section titled “Provision the target cluster”

Stand up a new open-source Apache Cassandra cluster with the same topology as the source (node count, datacenters, replication factors). Configure cassandra.yaml to match the source where appropriate (cluster name, snitch, partitioner, seeds). Install the monitoring agent on each node. Confirm every node reports UN (Up/Normal). Do not start application traffic yet.

The install should be automated rather than building nodes by hand; automation makes the cluster repeatable and consistent, removes a whole class of human error, and makes scaling, rebuilding, or standing up matching test and production environments a routine operation. AxonOps publishes ready-to-use configuration management for this purpose: the AxonOps Ansible collection and the AxonOps Chef cookbook install and configure Apache Cassandra together with the axon-agent that connects to AxonOps Cloud or to a self-hosted axon-server. For other approaches, such as baking golden machine images, AxonOps can help adopt one that fits how the organisation operates. See why Ansible is recommended for Cassandra in the installation guide to get started.

In all Cassandra versions, conflicting writes are resolved by their timestamp (last write wins) and TTL expiry is timestamp-driven, so the nodes in a cluster must have closely synchronised clocks. If clocks drift, writes can appear lost, deleted data can reappear, and reads may differ depending on which node answers. Configure a reliable time service (for example, chrony) on every node, point all nodes at the same time source, and monitor clock offset on an ongoing basis. AxonOps surfaces per-node NTP offset to confirm the cluster's clocks are in sync and alerts if a node starts to drift. See AxonOps for Cassandra.

Steps

Section titled “Steps”
  1. Create the target schema, roles, and credentials. Recreate all keyspaces, tables, roles, permissions, and user passwords on the target before deploying the proxy. CDM does not migrate system tables, so credentials must be created manually. See the pre-deployment requirement.
  2. Deploy the ZDM Proxy between the application and both clusters. Reads go to the source (DSE); writes are dual-written to both clusters. Dual-writes begin immediately, which keeps new data in sync from this point forward.
  3. Review the CDM caveats for collections, UDTs, and TTLs before running it. See Operational Caveats.
  4. Run CDM to copy existing data from DSE to the target. Redirect output to a log file so issues can be investigated. CDM copies user-table data only and validates row-level consistency. For assistance running CDM, contact AxonOps.
  5. Review the CDM logs. Confirm the error set is acceptable. If not, re-run CDM, as subsequent passes reduce the error count.
  6. Enable asynchronous dual reads via the proxy configuration so that reads are served against both clusters and the target's read path is exercised under real load ahead of cutover.

CDM is the recommended tool for this migration, but Apache Spark can also perform the bulk copy for teams who already run Spark or have existing ETL pipelines. A Spark job using the open-source spark-cassandra-connector (or Apache Cassandra Analytics for SSTable-level bulk I/O) reads from the source cluster and writes to the target. The trade-off is that the copy logic must be built and validated separately, whereas CDM provides the data migration and row-level validation out of the box. The ZDM Proxy dual-write setup is the same in either case; only the bulk-backfill tool changes.

Preserve write timestamps and TTLs during the bulk copy

Problem: The bulk-copy tool must preserve the original write timestamp and TTL on every copied row. Copying rows without the original timestamp assigns migration time as the write timestamp; omitting TTLs treats data as non-expiring.

Symptoms: TTL-based expiry breaks (data lives too long or expires at the wrong time); last-write-wins conflict resolution against concurrent dual-writes produces incorrect results; expired data reappears or survives past its intended lifetime.

Instead: Use a tool that carries the original timestamp and TTL on every row. CDM preserves both by default. Tools that do not, such as DataStax Bulk Loader (DSBulk) or Apache Spark, must be explicitly configured to carry the original timestamp and TTL on each row.

If the data has short TTLs (days or weeks), the bulk copy may be skippable. Deploy the ZDM Proxy with dual-writes enabled and leave it running until all pre-existing data on the source has expired naturally. Once the TTL window has passed, the target holds a complete dataset from dual-writes alone. This trades migration time for simplicity.

Counter tables need special handling

Section titled “Counter tables need special handling”

Counter tables do not fit the standard dual-write and bulk-copy flow, and getting them wrong produces silently incorrect totals. Plan for them separately.

The problem is that counter updates are increments, not absolute values, and they are not idempotent. During the migration the proxy dual-writes each new increment to both clusters, while the bulk copy carries the existing counter total from the source to the target. Any increment that lands during the copy window is then applied to the target twice (once in the copied total and once through the dual-write), or missed entirely, depending on ordering. Either way the target ends up with the wrong value. For this reason CDM does not copy counter tables when missing by default.

The safe approach is to take counter tables out of the main flow and migrate them in a dedicated step:

  1. Exclude counter tables from the bulk copy used for the rest of the data.
  2. Migrate each counter table once, with no concurrent increments to double-count. In practice this means copying the authoritative counter values during a short window in which updates to those specific tables are paused or quiesced, so nothing is counted twice.
  3. Direct counter traffic to the target as part of cutover, so increments resume against the migrated values.

The right sequencing depends on how the application uses counters, for example whether increments can be paused briefly, and whether the values are derived from data that can be recomputed. If counters are central to the workload, talk to AxonOps so the approach can be designed and tested before migration begins.

Go / No-Go

Section titled “Go / No-Go”

Go: no dropped read or write requests on either cluster.

Rollback: reconfigure the ZDM Proxy to route all traffic back to the DSE cluster, and remove the new Cassandra nodes. Because reads have not yet been switched to the target, this is a clean rollback.

Watch both clusters and the proxy throughout this phase. Cluster monitoring shows streaming, compaction, and latency on each side, while the AxonOps ZDM Proxy fork exposes proxy-layer metrics (primary reads, dual reads, target reads) that catch issues invisible to cluster-level monitoring. See AxonOps for Cassandra.

Next: Phase 4: Validate the Cassandra migration.