Connect client applications to ZDM Proxy

ZDM Proxy is designed to mimic communication with a typical cluster based on Apache Cassandra®. This means that your client applications connect to ZDM Proxy in the same way that they already connect to your existing Cassandra-based clusters.

You can communicate with ZDM Proxy using the same CQL statements used in your existing client applications. It understands the same messaging protocols used by Cassandra, DSE, HCD, and Astra DB. As a result, most client applications cannot distinguish between connections to ZDM Proxy and direct connections to a Cassandra-based cluster.

This page explains how to connect client applications to a Cassandra-based cluster using Cassandra drivers, and then describes the how you need to modify your client applications to connect to ZDM Proxy. It also explains how to connect cqlsh to ZDM Proxy, which is often used in conjunction with Cassandra drivers and during the migration process for certain validation tasks.

Connect applications to Cassandra clusters

A common way to connect client applications to Cassandra clusters is with Cassandra drivers. These drivers can connect to Cassandra-based clusters, execute queries, iterate through results, access metadata about the clusters, and perform other related activities. For available drivers and driver documentation, see Cassandra drivers supported by DataStax.

The following pseudocode provides simplified examples of the way a Cassandra driver interacts with Cassandra clusters. Specifically, these examples are for Astra DB and self-managed DSE, HCD, and open-source Cassandra clusters.

This pseudocode is for illustration purposes only; the exact syntax depends on your driver language and version. For specific instructions and examples, see Connect Cassandra drivers to your databases.

Self-managed Cassandra clusters
Astra DB

// Create an object to represent a Cassandra cluster
// This example listens for connections at 10.20.30.40 on the default port 9042
// Username and password are required only if authentication is enabled on the cluster
Cluster my_cluster = Cluster.build_new_cluster(
    contact_points = "10.20.30.40",
    username="cluster_username",
    password="cluster_password"
)

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

// Create an object to represent a Cassandra cluster (an Astra database)
// Don't 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="token",
    password="AstraCS:...",
    secure_connect_bundle="/path/to/scb.zip"
)

// For legacy applications that must use client ID and secret authentication:
// 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 the Cluster object to the database, 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)

Review your client application’s code to understand how it connects to your existing Cassandra-based clusters. Then, proceed to Connect applications to ZDM Proxy to learn how to modify that code to connect to ZDM Proxy instead.

Connect applications to ZDM Proxy

By design, ZDM Proxy should be transparent to your client application. This means that connecting your client application to ZDM Proxy should be seamless and nearly identical to the direct cluster connection. However, there are some considerations and adjustments you might need to make for ZDM Proxy.

Understand how ZDM Proxy handles certain client behaviors

If you haven’t done so already, thoroughly review the compatibility requirements for ZDM Proxy. This ensures that your client application’s code is compatible with ZDM Proxy, and you understand how certain operations and behaviors are handled by ZDM Proxy. For example:

Set connection points

Connect your client application to ZDM Proxy instead of directly to the origin cluster by modifying the client’s connection points.

Typically, this involves setting the client’s connection points to the IP addresses or hostnames of the local ZDM Proxy instances. The specific connection points for your migration depend on where and how you configured your ZDM Proxy infrastructure.

Provide authentication credentials

Make sure ZDM Proxy receives the correct authentication credentials from your client application. You might need to change the credentials set in your client application depending on your origin and target cluster configuration.

With or without ZDM Proxy, client applications must provide cluster credentials to authenticate requests. When a client connects directly to a cluster, it provides the authentication credentials for that cluster. When a client connects to ZDM Proxy, the client still provides only one set of credentials because ZDM Proxy is designed to be invisible to the client application.

ZDM Proxy uses the credentials provided by the client to forward requests to one of the clusters. To forward requests to the other cluster, ZDM Proxy uses the credentials defined in zdm_proxy_cluster_config.yml.

ZDM Proxy credentials usage when authentication is required for both clusters

Credential usage by ZDM Proxy when authentication is required for both clusters

The credentials that ZDM Proxy expects to receive from the client depend on the authentication requirements of the origin and target clusters. Make sure the client passes the correct credentials for your cluster configuration:

Authentication required for both clusters: Your client application must supply credentials for the target cluster.
Authentication required for target cluster only: Your client application must supply credentials for the target cluster.
Authentication required for origin cluster only: Your client application must supply credentials for the origin cluster.
No authentication required for either cluster: Your client application doesn’t need to supply any cluster credentials.

After you determine which cluster’s credentials are required, set the appropriate credentials in your client application:

Self-managed clusters: Provide a valid username and password to access the cluster.

Make sure the user has the appropriate permissions to perform the operations requested by the client application during the migration.

Astra DB: Generate an application token with a role that has sufficient permissions to perform the operations requested by the client application during the migration. Then, in your client application, set the username to the literal string token, and set the password to the actual application token value (AstraCS:…).

Don’t provide a Secure Connect Bundle (SCB) when connecting your client application to ZDM Proxy.

If you include the SCB, the driver ignores the ZDM Proxy connection points and connects exclusively to your Astra DB database instead of ZDM Proxy.

For connections to early Astra databases with long-lived tokens created prior to the unified token approach, you can set the username to the token’s clientId and the password to the token’s secret.

For more information about cluster credentials for ZDM Proxy, see Cluster and core configuration.

Sample client applications

These sample applications are for demonstration purposes only. They are not intended for production use or for production-scale performance testing.

To test your target cluster’s ability to handle production workloads, you can enable asynchronous dual reads.

To assess the performance of ZDM Proxy, DataStax recommends NoSQLBench.

The following sample client applications demonstrate how to use the Java driver with ZDM Proxy and the origin and target for that proxy.

See your driver’s documentation for code samples that are specific to your chosen driver, including cluster connection examples and statement execution examples.

You can use the provided sample client applications, in addition to your own client applications, to validate that your ZDM Proxy deployment is orchestrating read and write requests as expected between the origin cluster, target cluster, and your client applications.

ZDM Demo Client: ZDM Demo Client is a minimal Java web application which provides a simple, stripped-down example of an application built to work with ZDM Proxy. After updating connection information you can compile and run the application locally and interact with it using HTTP clients such as curl or wget.

You can find the details of building and running ZDM Demo Client in the README.

Themis client: Themis is a Java command-line client application that allows you to write randomly generated data directly to the origin cluster, directly to the target cluster, or indirectly to both clusters through ZDM Proxy. Then, you can use the client application to query the data and confirm that ZDM Proxy is reading and writing data from the expected sources.

Configuration details for the clusters and ZDM Proxy are defined in a YAML file. For more information, see the Themis README.

In addition to being a validation tool, Themis also provides an example of a larger client application that uses the Java driver to connect to ZDM Proxy, or directly to a Cassandra cluster, and perform operations. The configuration logic, as well as the cluster and session management code, are separated into distinct packages to make them easy to understand.

Connect cqlsh to ZDM Proxy

cqlsh is a command-line tool that you can use to send CQL statements and cqlsh-specific commands to your Cassandra-based clusters, including Astra DB, DSE, HCD, and Apache Cassandra databases.

You can use your database’s included version of cqlsh, or you can download and run a standalone cqlsh.

Your origin and target clusters must have a common cql_version between them. If there is no CQL version that is compatible with both clusters, cqlsh won’t be able to connect to ZDM Proxy.

To connect cqlsh to a ZDM Proxy instance, do the following:

On a machine that can connect to your ZDM Proxy instance, download and install cqlsh.

Any version of cqlsh can connect to ZDM Proxy, but some clusters require a specific cqlsh version.

Start cqlsh with your ZDM Proxy connection details:

./cqlsh ZDM_PROXY_IP PORT -u USERNAME -p PASSWORD

Replace the following:

ZDM_PROXY_IP: The IP address of your ZDM Proxy instance.
PORT: The port on which the ZDM Proxy instance listens for client connections. If you are using the default port, 9042, you can omit this argument.
USERNAME and PASSWORD: Valid cluster authentication credentials, depending on the authentication requirements for your origin and target clusters:
- Authentication required for both clusters: Provide credentials for the target cluster.
- Authentication required for target cluster only: Provide credentials for the target cluster.
- Authentication required for origin cluster only: Provide credentials for the origin cluster.
- No authentication required for either cluster: Omit the -u and -p arguments.

For a self-managed cluster, provide a valid username and password to access the cluster.

For Astra DB, the username is the literal string token, and the password is an Astra application token, such as -u token -p AstraCS:….

For Astra DB, don’t use the SCB to connect cqlsh to ZDM Proxy. Only use an application token.

If you include the SCB, cqlsh ignores all other connection arguments and connects exclusively to your Astra DB database instead of ZDM Proxy.

Next steps

After you connect your client applications to ZDM Proxy, you can begin Phase 2 of the migration, which is the data migration phase.