Step 5: Connect your client applications directly to Target

At this point in our migration phases, we’ve completed:

  • Phase 1: Connected client applications to ZDM Proxy, which included setting up Ansible playbooks with the ZDM Utility, and deploying the ZDM Proxy instances via the Docker container with ZDM Proxy Automation.

  • Phase 2: Migrated and validated our data with Cassandra Data Migrator and/or DSBulk Migrator.

  • Phase 3: Enabled async data reads (an optional step) to check that Target can handle the read/write traffic.

  • Phase 4: Changed read routing to Target.

Now we’re ready to perform Phase 5, in which we will configure our client applications to connect directly to Target. The way you do this varies based on whether your Target is Astra DB or a regular Apache Cassandra® or DataStax Enterprise cluster.

Phase 5 diagram shows apps no longer using proxy and instead connected directly to Target.

Configuring your driver to connect to a generic CQL cluster

If your Target is a generic CQL cluster (such as Apache Cassandra or DataStax Enterprise), you can connect your client application to it in a similar way as you previously connected it to Origin, but with the appropriate contact points and any additional configuration that your Target may require. For further information, please refer to the documentation of the driver language and version that you are using.

Configuring your driver to connect to Astra DB

To connect to your Astra DB cluster, you will need:

  • A valid set of credentials (ClientID and Client Secret) for the Astra DB organization to which your cluster belongs:

    • Note: You will already have used these credentials when you configured the ZDM Proxy to connect to your Astra DB cluster as Target.

    • For more information on creating credentials (tokens), see here.

  • The Secure Connect Bundle (SCB) for your Astra DB cluster:

    • This is a zip archive containing connection metadata and files to automatically enable Mutual TLS encryption between your client application and Astra DB.

    • There is one SCB for each Astra DB cluster (or one for each region of an Astra DB Multi-region cluster).

    • The SCB does not contain your DB credentials.

The SCB can be downloaded from the Astra Portal as follows:

  1. In the Astra Portal, go to the Dashboard and select the serverless database that you created in the prior step. Ensure it is in Active state.

  2. Click on Connect.

  3. Select the Java driver, choosing the driver based on the CQL APIs.

  4. Click on Download bundle (choosing a region if prompted to do so).

For more information on the SCB and how to retrieve it, see the Astra DB Serverless documentation.

You will also need to check whether the driver used by your client application has native support for the Astra DB Secure Connect Bundle. To do so, please refer to the documentation for your driver language and version, and check the per-language driver compatibility matrix for details (look for the support status in the Astra / Cloud column for your driver version).

You do not need to upgrade your client application driver to enable it to connect to Astra DB.

If your client application uses an old version of the driver without built-in SCB support, upgrading it would make the configuration easier, but it is not required and can be also done at a later time if desired.

Drivers with built-in support for the Secure Connect Bundle

The great news is that, if your driver has built-in support for the Astra DB Secure Connect Bundle (SCB), the changes to enable your application to connect to Astra DB are minimal.

Recalling the pseudocode to enable your client application to connect to the proxy, here it is how it needs to change to connect directly to Astra DB:

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

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

// Display the release version to the user

As noted before, this pseudocode is just a guideline to illustrate the changes that are needed. For the specific syntax that applies to your driver, please refer to the documentation for your driver language and version:

That’s it! Your client application is now able to connect directly to your Astra DB cluster.

Drivers without support for the Secure Connect Bundle

It is possible to configure older or community-contributed drivers to connect to Astra DB even if they lack built-in SCB support.

To do so, you will need to extract the files from the SCB and use them to enable Mutual TLS in the configuration of your driver. Please see here for detailed instructions for each driver.

Alternatively, you could also consider using CQL Proxy, which is an open-source lightweight proxy that abstracts away all Astra-specific connection configuration from your client application.

A word on the cloud-native drivers

Now that your client application is running on Astra DB, you can take advantage of many additional features and APIs that Astra DB offers such as gRPC, GraphQL, Document REST APIs and many more. To access these features, you may wish to consider moving to a cloud-native driver. This can be done at any time, as part of the future development and evolution of your client application.

Here are the cloud-native drivers currently available:

Phase 5 of migration completed

Until this point, in case of any issues, you could have abandoned the migration and rolled back to connect directly to Origin at any time. From this point onward, the clusters will diverge, and Target is the source of truth for your client applications and data.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000,