Phase 5: Connect client applications to the target cluster
Phase 5 is the last phase of the migration process, after you route all read requests to the target cluster in Phase 4.
In this final phase, you connect your client applications directly and exclusively to the target cluster. This removes the dependency on ZDM Proxy and the origin cluster, thereby completing the migration process.
The minimum requirements for reconfiguring these connections depend on whether your target cluster is Astra DB or a generic CQL cluster, such as Apache Cassandra®, DataStax Enterprise (DSE), or Hyper-Converged Database (HCD).
|
Once you switch your client applications to connect directly to the target cluster, you can no longer cleanly roll back to the origin cluster. From this point onward, the clusters will diverge, and the target cluster becomes the source of truth for your client applications and data. Be sure that you have thoroughly validated your data (Phase 2), tested your target cluster’s performance (Phase 3), and routed all reads to the target (Phase 4) before permanently switching the connection. |
Connect a driver to a generic CQL cluster
If your origin and target clusters are both generic CQL clusters, such as Cassandra, DSE, or HCD, then the driver connection strings can be extremely similar. It’s possible that your code requires only minor changes to connect to the target cluster.
-
At minimum, update your driver configuration to use the appropriate contact points for your target cluster.
You might need to make additional configuration changes depending on your target cluster’s setup, such as authentication and encryption. For example, if you have execution profiles with unique datacenter-aware load balancing policies, you must update the profiles to use the target datacenters.
For information about driver connections for different Cassandra-compatible clusters, see Connect Cassandra drivers to your databases.
-
Verify that your driver version is compatible with your target cluster and supports the features that you want to use on your new cluster. For example, if you want to use the vector data type on an HCD cluster, you must use a driver version that supports both HCD and the vector type.
When upgrading from an earlier driver version, you might need to make additional code changes to account for enhancements, deprecations, removals, and differences in platform features. Depending on your application’s requirements, you might need to make these changes immediately, or you might make them after switching the connection.
For more information on supported drivers, see Cassandra drivers supported by DataStax.
Connect a driver to Astra DB
Connections to Astra DB are different from connections to generic CQL clusters.
Get Astra DB credentials
To connect a driver to Astra DB, you need the following:
-
An application token with sufficient permissions to execute the required operations, such as the Database Administrator role.
You must specify one of the following sets of credentials in your driver configuration:
-
Token-only authentication (Recommended):
-
Set
usernameto the literal stringtoken. -
Set
passwordto the actual application token value (AstraCS:…).
-
-
Legacy authentication (Earlier drivers only):
-
Set
usernameto theclientIdvalue generated with the token. -
Set
passwordto thesecretvalue generated with the token.
-
-
-
Your Astra DB database’s Secure Connect Bundle (SCB).
The SCB contains sensitive information that establishes a connection to your database, including key pairs and certificates. Treat it as you would any other sensitive values, such as passwords or tokens.
For multi-region databases and Astra organizations that use custom domains, your databases will have more than one SCB. After making these changes in Astra, your driver connections will need to be updated to use the appropriate SCB for the desired region or domain when connecting to your databases.
Compare driver connection parameters for self-managed Cassandra clusters and Astra DB
To help you understand the required changes for your driver connection strings, the following table compares driver connection parameters for self-managed Cassandra clusters and Astra DB databases:
| Parameter | Self-managed clusters | Astra DB databases |
|---|---|---|
Contact points |
Required, set manually |
Automatically set by the SCB |
Secure Connect Bundle (SCB) |
Not applicable |
Required |
SSL context |
Optional, set manually |
Automatically set by the SCB |
Local datacenter |
Required, set manually |
Automatically set by the SCB |
Database username |
Requirement depends on cluster configuration. If required, set to the relevant user name for authentication. |
Required.
|
Database password |
Requirement depends on cluster configuration. If required, set to the relevant password for authentication. |
Required.
|
Driver pseudocode comparison
The two pseudocode examples provide a simplified comparison of the way a Cassandra driver interacts with Astra DB and self-managed Cassandra clusters. This pseudocode is for illustration purposes only; the exact syntax depends on your driver language and version.
The first pseudocode example illustrates the connection to a self-managed Cassandra cluster. This should be somewhat familiar to you based on your current Cassandra driver.
// Create an object to represent a Cassandra cluster
// This example listens for connections at 10.20.30.40 on the default port 9042
// Username and password are required only if authentication is enabled on the cluster
Cluster my_cluster = Cluster.build_new_cluster(
contact_points = "10.20.30.40",
username="cluster_username",
password="cluster_password"
)
// Connect the Cluster object to the Cassandra cluster, returning a Session
Session my_session = my_cluster.connect()
// Execute a query, returning a ResultSet
ResultSet my_result_set = my_session.execute("select release_version from system.local")
// Retrieve a specific column from the first row of the result set
String release_version = my_result_set.first_row().get_column("release_version")
// Close the Session and Cluster
my_session.close()
my_cluster.close()
// Print the data retrieved from the result set
print(release_version)The second example modifies the same pseudocode to connect to Astra DB.
The primary difference lies in the initial connection string.
After that point, the interaction through the root object (Cluster/Session) is typical.
// Create an object to represent a Cassandra cluster (an Astra database)
// Don't specify contact points when connecting to Astra DB
// All connection information is implicitly passed in the SCB
Cluster my_cluster = Cluster.build_new_cluster(
username="token",
password="AstraCS:...",
secure_connect_bundle="/path/to/scb.zip"
)
// For legacy applications that must use client ID and secret authentication:
// Cluster my_cluster = Cluster.build_new_cluster(
// username="my_AstraDB_client_ID",
// password="my_AstraDB_client_secret",
// secure_connect_bundle="/path/to/scb.zip"]
// )
// Connect the Cluster object to the database, returning a Session
Session my_session = my_cluster.connect()
// Execute a query, returning a ResultSet
ResultSet my_result_set = my_session.execute("select release_version from system.local")
// Retrieve a specific column from the first row of the result set
String release_version = my_result_set.first_row().get_column("release_version")
// Close the Session and Cluster
my_session.close()
my_cluster.close()
// Print the data retrieved from the result set
print(release_version)Verify driver compatibility and update connection strings
Verify that your driver version is compatible with Astra DB and the features that you want to use in Astra DB, such as the vector data type. For more information, see Cassandra drivers supported by DataStax.
If your driver version is fully compatible with Astra DB, then it has built-in support for the Astra DB SCB. The changes required to connect your application to Astra DB are minimal.
If your client application uses an earlier driver version without built-in SCB support, DataStax strongly recommends upgrading to a compatible driver to simplify configuration and get the latest features and bug fixes. If you prefer to make this change after the migration, or you must support a legacy application that relies on an earlier driver, you can connect to Astra DB with CQL Proxy, or you must extract the SCB archive and provide the individual files to enable mTLS in your driver’s configuration.
The following example demonstrates how the Cassandra Python driver connects to Astra DB using an application token and SCB:
import os
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
import json
# Provide the path to the SCB
cloud_config= {
'secure_connect_bundle': '/path/to/scb.zip'
}
# The username is 'token' and the password is the application token value
auth_provider = PlainTextAuthProvider("token", os.environ["APPLICATION_TOKEN"])
# Create the Cluster and Session objects with Astra credentials
cluster = Cluster(cloud=cloud_config, auth_provider=auth_provider)
session = cluster.connect()For more information and examples of Astra DB connections, see Compare driver connection parameters for self-managed Cassandra clusters and Astra DB and Connect Cassandra drivers to your databases.
Other code changes for Astra DB
In addition to updating connection strings, you might also need to make the following code changes:
-
Feature compatibility between your previous and current database platform.
For example, after migrating to Astra DB, your drivers cannot create keyspaces because CQL for Astra DB doesn’t support
CREATE KEYSPACE.Similarly, Astra DB doesn’t support DSE-specific features like DSE Insights Monitoring.
-
Enhancements, deprecations, and removals when upgrading from an earlier driver version.
Depending on your application’s requirements, you might need to make these changes immediately, or you might make them after switching the connection.
Switch to the Data API
If you migrated to Astra DB or HCD, you have the option of using the Data API instead of, or in addition to, a Cassandra driver.
Although the Data API can read and write to CQL tables, it is significantly different from driver code. To use the Data API, you must rewrite your application code or create a new application.
For more information, see the following:
Migration complete
Your migration is now complete, and your target cluster is the source of truth for your client applications and data.
When you are ready, you can decommission your origin cluster and ZDM Proxy because these are no longer needed and seamless rollback is no longer possible.
If you need to revert to the origin cluster after this point, you must perform a full migration in the opposite direction, with your previous origin cluster as the target, to ensure that all data is rewritten and synchronized back to the origin.
