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.

In Phase 5, your applications no longer use the proxy and, instead, connect directly to the target cluster

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. Parts of this page assume 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.

Verify driver compatibility

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.

Upgrade your driver version if necessary. When upgrading your driver, review the driver’s release notes for enhancements, deprecations, and removals that might impact your application code.

For DSE-compatible drivers, see Cassandra driver compatibility.

Identify feature disparity

If necessary, change your application code to account for feature disparity between your origin and target clusters. A feature supported by your origin cluster might not be supported by your target cluster.

For example, because Astra DB is a managed service, some functionality that is available to self-managed clusters is restricted in Astra DB. These restrictions can require additional code changes outside the connection strings when migrating to or from Astra DB. Some specific examples include the following:

After migrating to Astra DB, drivers cannot create keyspaces because CQL for Astra DB doesn’t support CREATE KEYSPACE.
The Astra DB DevOps API isn’t available to self-managed clusters.

The timing of code changes based on feature disparity depends on your application’s requirements. A frequently used feature must be replaced immediately to avoid errors after connecting to the target cluster. In contrast, a rarely used feature that won’t cause an error can be replaced after connecting to the target cluster.

GoCQL support

Go applications might require a different GoCQL driver package, depending on the origin and target cluster connection types.

For self-managed clusters, the required GoCQL driver package depends on Mission Control CQL gateway usage.

GoCQL package required for self-managed cluster connections
Origin cluster connection type	Target cluster connection type	Required GoCQL driver package
DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Continue using `gocql-astra`, which was already required for the origin cluster’s CQL gateway connection.
Any self-managed cluster without a CQL gateway	DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Replace `gocql` with `gocql-astra`. The `gocql-astra` package includes `gocql` and additional support for Mission Control CQL gateway connections. For the required import statements and connection details, see Get started with the Go driver.
DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Any self-managed cluster without a CQL gateway	Replace `gocql-astra` with `gocql`. The extra connection support provided by `gocql-astra` isn’t required for connections to self-managed clusters without a Mission Control CQL gateway.
Any self-managed cluster without a CQL gateway	Any self-managed cluster without a CQL gateway	Continue using `gocql`, which was already required for the origin cluster’s connection.
Astra DB	DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Continue using `gocql-astra`, which was already required for the Astra DB connection.
Astra DB	Any self-managed cluster without a CQL gateway	Replace `gocql-astra` with `gocql`. The extra connection support provided by `gocql-astra` isn’t required for connections to self-managed clusters without a Mission Control CQL gateway.

Update Cassandra driver connection strings

If your origin and target clusters are both self-managed Cassandra-based clusters, then the driver connection strings might be extremely similar. It’s possible that your code requires only minor changes to connect to the target cluster.

At minimum, you must update your driver configuration to use the appropriate contact details for your target cluster.

The extent of the required changes depends on cluster architecture, authentication and encryption settings, and Mission Control CQL gateway usage. A change in CQL gateway usage has the most significant impact on the connection strings, and potentially other parts of your application code, as summarized in the following table. This table isn’t exhaustive; it is intended to provide an overview to help you conceptualize possible changes for your own driver connections and application code. For more information about connection string changes, see Compare driver connection parameters.

Connection string changes based on Mission Control CQL gateway usage
Origin cluster connection type	Target cluster connection type	Required connection strings
DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Minimal changes. Update the existing connection strings with new values for the target cluster.
Any self-managed cluster without a CQL gateway	DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Significant changes. Replace the existing connection strings with CQL gateway connection strings that use the target cluster’s username, password, and gateway SCB. Don’t use a load balancing policy that sets a different local datacenter than the one specified in the SCB. Applications that connect to multi-datacenter clusters must have access to the gateway SCB for each datacenter.
DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Any self-managed cluster without a CQL gateway	Moderate changes. Replace the existing CQL gateway connection strings with traditional driver connection strings that set the target cluster’s contact point, authentication credentials, and SSL context (if applicable). Set a local datacenter for the load balancing policy, if needed. Applications that connect to multi-datacenter clusters must be updated to use the contact points for each datacenter instead of a SCB.
Any self-managed cluster without a CQL gateway	Any self-managed cluster without a CQL gateway	Minimal changes. Update the existing connection strings with new values for the target cluster.
Astra DB	DSE 6.9, HCD, or OSS Cassandra cluster with a CQL gateway	Minimal changes to connection strings. Update the existing connection strings with new values for the target cluster: Replace the Astra DB username and password (`token`, `AstraCS:…`) with a valid CQL role name and password for your target cluster. Replace the Astra DB SCB with the target cluster’s gateway SCB. Other code changes are likely to be more significant because Astra DB and self-managed clusters have different feature sets.
Astra DB	Any self-managed cluster without a CQL gateway	Significant changes. Replace the existing connection strings with traditional driver connection strings that set the target cluster’s contact point, authentication credentials, and SSL context (if applicable). Set a local datacenter for the load balancing policy, if needed. Applications that connect to multi-datacenter clusters must be updated to use the contact points for each datacenter instead of a SCB. Other code changes due to differences in features supported by Astra DB and self-managed clusters.

Compare driver connection parameters

Use the following table to compare required driver connection parameters and understand potential changes for your driver connection strings, depending on your origin and target cluster connection types:

Parameter Self-managed without Mission Control CQL gateway Self-managed with CQL gateway Astra DB

Parameter	Self-managed without Mission Control CQL gateway	Self-managed with CQL gateway	Astra DB
Contact points	Required, set manually	Automatically set by the SCB	Automatically set by the SCB
Secure Connect Bundle (SCB)	Not applicable	Required	Required
SSL context	Optional, set manually	Automatically set by the SCB	Automatically set by the SCB
Local datacenter	Required, set manually	Automatically set by the SCB	Automatically set by the SCB
Database username	Requirement depends on cluster configuration. If required, set to the relevant user name for authentication.	Required. Must be a valid CQL role name for the target cluster.	Required. Token-only authentication (Recommended): Set to the literal string `token`. Client ID and secret authentication (Legacy): Set to the `clientId` generated with your token.
Database password	Requirement depends on cluster configuration. If required, set to the relevant password for authentication.	Required. Provide the password that corresponds with the given database username (CQL role name).	Required. Token-only authentication (Recommended): Set to your application token (`AstraCS:…`). Client ID and secret authentication (Legacy): Set to the `secret` generated with your token.

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. Must be a valid CQL role name for the target cluster.

Required.

Token-only authentication (Recommended): Set to the literal string token.
Client ID and secret authentication (Legacy): Set to the clientId generated with your token.

Database password

Requirement depends on cluster configuration. If required, set to the relevant password for authentication.

Required. Provide the password that corresponds with the given database username (CQL role name).

Required.

Token-only authentication (Recommended): Set to your application token (AstraCS:…).
Client ID and secret authentication (Legacy): Set to the secret generated with your token.

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 without a CQL gateway, 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 self-managed cluster with a CQL gateway, the contact points and SSL context are set by the gateway SCB automatically. A CQL role name and password are used for authentication.
For Astra DB, the contact points and SSL context are set by the database’s SCB automatically. An Astra application token is used for authentication. The username is the literal string token because the application token provides all authentication context, including role information.

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 a self-managed cluster with a CQL gateway
Cluster my_cluster = Cluster.build_new_cluster(
    username="cluster_username",
    password="cluster_password",
    secure_connect_bundle="/path/to/scb.zip"
)

// 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)

Driver connection examples for DSE

For more information and examples, see the documentation for your driver. To get started, 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.

Phase 5: Connect client applications to the target cluster

Verify driver compatibility

Identify feature disparity

GoCQL support

Update Cassandra driver connection strings

Compare driver connection parameters

Compare driver pseudocode

Driver connection examples for DSE

Migration complete

Was this helpful?

Give Feedback