Phase 5: Connect your client applications directly to the target
Phase 5 is the last phase of the migration process. In this phase, you configure your client applications to connect directly and exclusively to the target cluster. This removes the dependency on ZDM Proxy and completes the migration.
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 (Cassandra, DSE, or HCD), then the driver connection strings can be similar, requiring 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 for earlier drivers:
-
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.
|
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 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 by extracting the SCB archive and using the individual files to enable mTLS in your driver’s configuration.
If your driver has built-in support for the Astra DB SCB, the changes to enable your application to connect to Astra DB are minimal. The following example demonstrates an Astra DB connection through the Python driver using an SCB and application token. For more information and examples, see Compare driver connection parameters for self-managed Cassandra clusters and Astra DB and Connect Cassandra drivers to your databases.
import os
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
import json
cloud_config= {
'secure_connect_bundle': '/path/to/scb.zip'
}
auth_provider = PlainTextAuthProvider("token", os.environ["APPLICATION_TOKEN"])
cluster = Cluster(cloud=cloud_config, auth_provider=auth_provider)
session = cluster.connect()Driver pseudocode to connect to Astra DB
The following pseudocode provides guidance on how you might change your driver’s code to connect directly to Astra DB. This is for illustration purposes only; the exact syntax depends on your driver and programming language.
// Create an object to represent a Cassandra cluster
// Note: there is no need to 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="my_AstraDB_client_ID", password="my_AstraDB_client_secret", secure_connect_bundle="/path/to/scb.zip")
// Connect our Cluster object to our 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 the "release_version" column from the first row of our result set
String release_version = my_result_set.first_row().get_column("release_version")
// Close our Session and Cluster
my_session.close()
my_cluster.close()
// Display the release version to the user
print(release_version)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, and 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, as these are no longer needed and clean rollback is no longer possible.
If you need to revert to the origin cluster after this point, you must perform a full migration with your previous origin cluster as the target to ensure that all data is rewritten and synchronized back to the origin.
