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 your target DataStax Enterprise (DSE) cluster in Phase 4.
In this final phase, you connect your client applications directly and exclusively to your target DSE 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 the differences between your origin and target clusters as well as the APIs and libraries you use in your client applications. This page assumes you are migrating to a target DSE cluster. If this is not the case, see the ZDM documentation for your actual target cluster.
|
Once your client applications connect directly to the target cluster, you can no longer seamlessly roll back to the origin cluster. From this point onward, the clusters are no longer be synchronized, and the target cluster becomes the source of truth for all reads and writes. 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. |
Supported drivers
Make sure your Cassandra driver is compatible with your target DSE cluster and the DSE features that you want to use. If the driver is incompatible, connection failures and other errors can occur.
For DSE-compatible drivers, see Cassandra driver compatibility.
Connect to DSE
If your origin and target clusters are both self-managed Cassandra-based clusters, 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.
-
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 in your target DSE cluster, you must use a driver version that supports both DSE 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.
Compare driver connection parameters
For migrations between an Astra DB cluster and a self-managed cluster, your driver connection strings will change significantly. Use the following table to compare driver connection parameters and understand the required changes for your driver connection strings.
| Parameter | Self-managed | Astra DB |
|---|---|---|
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.
|
Compare driver pseudocode
The following pseudocode example provides a simplified comparison of the way a Cassandra driver interacts with Astra DB and self-managed clusters. This pseudocode is for illustration purposes only; the exact syntax depends on your driver language and version.
The primary difference is the initial Cluster configuration:
-
For self-managed clusters, the contact points are set explicitly, and the authentication credentials depend on the cluster’s configuration.
This example uses plain username and password authentication with no SSL encryption. Other authentication methods can use other classes or options.
To enable SSL encryption, certificates and keyfiles must be provided explicitly to the driver. For these classes and options, see the documentation for your driver.
-
For Astra DB, the contact points, certificates, and keyfiles are provided in the SCB, and an Astra application token is used for authentication.
After instantiating the Cluster, the interactions through the Cluster object are the same.
// Create an object to represent a self-managed cluster
Cluster my_cluster = Cluster.build_new_cluster(
contact_points = "10.20.30.40",
username="cluster_username",
password="cluster_password"
)
// Or create an object to represent an Astra database
Cluster my_cluster = Cluster.build_new_cluster(
username="token",
password="AstraCS:...",
secure_connect_bundle="/path/to/scb.zip"
)
// 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)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.
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. This ensures that all data is rewritten and synchronized back to the origin cluster.
