Migrating an application from Apache Cassandra® to Astra DB can be a difficult task. In this post, we’ll discuss some of these challenges, and tools to help you get around them. In our last post, “Moving Data Between Apache Cassandra® and DataStax Astra DB,” we talked about migrating data with the Cassandra Data Migrator (CDM) and the DataStax Bulk Loader (DSBulk). Here we pick-up where that post left off, lighting the way for the rest of the migration journey.

The ZDM Proxy

As a refresher, we’ll discuss the ZDM Proxy and its role in the overall migration process (shown in the illustration below). The ZDM Proxy is a tool which bridges operational database traffic between Cassandra, Astra DB, and an application.

An overview of the Zero Downtime Migration process.

 

Several instances of the ZDM Proxy are brought up to handle application traffic meant for the origin (Cassandra) database. The ZDM Proxy is configured with credentials that enable it to communicate with both the origin cluster and the target (Astra DB) database. Once the application instances are configured to point to the ZDM Proxy, all read traffic is sent to the origin cluster, while write traffic is sent to both databases. This enables data to be moved between the databases in an offline, at-will manner. Thus, the Zero Downtime Migration process enables an existing Cassandra-based application to be migrated to Astra DB without incurring any interruption to the application users.

For production migrations, it’s recommended to be running at least three instances of the ZDM Proxy. Depending on the application throughput, more might be required.

Connecting from the application

Connecting the application to the ZDM Proxy is simple, as it responds similarly to how a Cassandra node would respond. The primary difference is that the ZDM Proxy enables connections on port 14002, instead of the default Cassandra CQL port of 9042.

Remember that the application will also need to use the Astra token to connect to the proxy. This can be done by passing the literal string “token” as a username, and then the Astra DB API token as a password. In this case, we wouldn’t need to worry about the Astra secure connect bundle (SCB) as the ZDM Proxy configuration requires it.

Connecting from cqlsh

For connecting to the proxy with cqlsh, remember to specify the ZDM Proxy’s IP address along with port 14002. Sometimes it can be helpful to remember that cqlsh checks the CQLSH_PORT environment variable, which can be set with the following command:

export CQLSH_PORT=14002

Application changes

Generally, an application that is currently backed by Cassandra shouldn’t change much as it moves to Astra DB. The drivers have been updated over the last few years to include Astra-specific connection properties. While older versions of the drivers required several items of information about the specific Astra database, newer versions really only require a few. To make things easier, most drivers are capable of downloading the Astra SCB themselves, eliminating the need for it to be specified.

Popular enterprise frameworks such as (Java) Spring Data do have different configuration properties between Cassandra and Astra DB. The required Spring Data connection properties for Cassandra and Astra DB are contrasted in this table:

Spring - Cassandra	value	Spring - Astra DB	value
spring.cassandra .contact-points	IP addresses: 1.2.3.4, 1.2.3.5	astra.api .application-token	AstraCS:23kj4h:88y3 3k2l34j324j
spring.cassandra .port	9042	astra.api .database-id	UUID: 2dc14047- ff24-4b78-841d- aa2ab94e5b8c
spring.cassandra .username	Text user/role name	astra.api .database-region	Cloud region name:  us-west-2
spring.cassandra .password	Text password	astra.cql.enabled	Boolean: true/false
spring.cassandra .keyspace-name	Text name of keyspace	astra.cql.driver-config .basic .session-keyspace	Text name of keyspace

 

A comparison of various Spring Data connection properties required between Cassandra and Astra DB.

Cutover

The last part of the migration is the cutover of the application from the ZDM Proxy to DataStax Astra DB. After this process, the migration will be mostly complete (short of any cleanup steps). Before cutting over, be sure to verify the following:

• A window of time has been communicated and approved.
• All data has been migrated over to Astra DB.

It's a good idea to ensure that the cutover is targeted for a time window when it’s projected to experience low levels of traffic. While the ZDM process aims to ensure no interruptions, it should be understood that an application in a migration state is certainly more fragile than usual.

The actual process of cutting over is relatively straightforward:

• Verify that: 
  • The application is functioning normally
  • All ZDM Proxies are running
  • Astra DB can be reached and responds to CRUD operations
• Stop the application instance
• Change the connection properties
• Restart the application instance
• Verify that the application instance is running and connected to Astra DB
• Repeat for all other application instances

Conclusion

Executing a migration from Cassandra to Astra DB requires some careful planning. The process has a lot of moving parts, and it can be tricky. But there are also many great tools and resources that can help ease the process.

Some points to remember:

• In production, it's recommended to run at least 3 instances of ZDM Proxy
• It’s not uncommon to run more than 3 instances of the ZDM Proxy to adequately support operational throughput
• When connecting to the ZDM Proxy with cqlsh, you might have to adjust the CQLSH_PORT environment variable.
• Understand the required Cassandra driver properties for connecting to Astra DB
• In a large enterprise, be sure to adequately communicate all migration activities

Looking to migrate your Cassandra cluster into Astra DB, but not sure where to start? Check out our Modernize Apache Cassandra Workloads page for more information!