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 Astra DB Serverless cluster in Phase 4.
In this final phase, you connect your client applications directly and exclusively to your target Astra 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 Astra 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 Astra cluster and the Astra features that you want to use. If the driver is incompatible, connection failures and other errors can occur.
For Astra-compatible drivers, see Cassandra driver compatibility.
Connect to Astra
Connections to Astra are different from connections to self-managed Cassandra clusters.
In addition to updating the connection strings, you might need to make the following other code changes in your client applications:
-
Go applications must replace
gocqlwithgocql-astra. This package includesgocqland additional support for connections to Astra. For the required import statements and connection details, see Get started with the Go driver. -
Changes to CQL statement and logic for feature disparity between your origin and target clusters.
For example, after migrating to Astra, your drivers cannot create keyspaces because CQL for Astra DB doesn’t support
CREATE KEYSPACE. Similarly, Astra DB Serverless doesn’t support DSE-specific features like DSE Insights Monitoring and DSE Advanced Workloads. -
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.
Get Astra credentials
To connect a driver to Astra, you need the following:
-
An Astra application token that has a role with sufficient permissions to execute the required operations, such as the Database Administrator role.
In your driver connection strings, set the
usernameto the literal stringtoken, and set thepasswordto the actual application token value (AstraCS:…).For connections to early Astra DB databases with long-lived tokens created prior to the unified
tokenapproach, you can set theusernameto the token’sclientIdand thepasswordto the token’ssecret. -
Your Astra 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 Astra databases and Astra organizations that use custom domains, your database will have more than one SCB. Your driver connections must be updated to use the appropriate SCB for the desired region or domain when connecting to your databases. For more information, see Connection pools and initial contact points..
Update connection strings
The following example demonstrates how the Cassandra Python driver connects to Astra using an application token and SCB. For more information and examples of Astra connections, see Compare driver connection parameters and the documentation for your Cassandra driver.
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()Unsupported drivers
Supported drivers for Astra have built-in support for the SCB. These drivers can automatically extract the necessary connection information, such as contact points, SSL context, and local datacenter, from the SCB zip file.
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 cannot upgrade your driver, you must do one of the following:
-
Use
cql-proxy. -
Extract the SCB archive and manually provide the required values to enable mTLS in your driver’s configuration. For an example, see DataStax Ruby and PHP drivers (Maintenance).
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)Switch to the Data API
After migrating to Astra, 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.
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.
