Connect client applications to ZDM Proxy

ZDM Proxy is designed to mimic communication with a Apache Cassandra® cluster with no discernable difference to the client application. This means that your client applications connect to ZDM Proxy in the same way that they already connect to your existing clusters.

ZDM Proxy understands Cassandra messaging protocols, and it can process the Cassandra Query Language (CQL) statements currently used in your existing client applications. As a result, most client applications cannot distinguish between connections to ZDM Proxy and direct cluster connections.

This guide assumes your origin cluster is a Cassandra-based cluster, and your client applications use Cassandra drivers or the CQL shell to connect to the cluster.

This page explains how to reconfigure your applications to connect through ZDM Proxy, rather than directly to your origin cluster. At minimum, you must edit the connection strings. Additional changes might be required to handle certain operations or support dual writes to both clusters.

This page covers both Cassandra driver and CQL shell connections. The CQL shell is used during the migration process for certain validation tasks.

The configuration on this page is for your client applications only. Don’t use this information to modify your ZDM Proxy configuration files.

The cluster credentials used by your client application are significantly different from the credentials set in the ZDM Proxy configuration.

Connect applications to ZDM Proxy with Cassandra drivers

By design, ZDM Proxy is meant to 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.

Review your client application’s code to understand how it connects to your origin cluster without ZDM Proxy. Then, proceed through the following sections to learn how to modify that code to connect to ZDM Proxy instead.

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

In your client application’s code, edit the driver connection strings to connect to ZDM Proxy instead of your origin cluster.

You need the IP addresses or hostnames and port numbers for your ZDM Proxy instances. These values are determined by your ZDM Proxy infrastructure.

Self-managed clusters: If your origin cluster is a self-managed cluster, replace the cluster contact points with the IP addresses, hostnames, or port numbers for your local ZDM Proxy instances.

Astra DB: If your origin cluster is an Astra DB database, you must change the entire connection object to a self-managed cluster connection, and then set the IP addresses, hostnames, and port numbers for your local ZDM Proxy instances.

Don’t use 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.

The following pseudocode provides an example of a driver’s Cluster object with ZDM Proxy contact points. The exact syntax depends on your driver language and version. For specific options and examples, see the documentation for your driver.

// Replace contact points with ZDM Proxy IP addresses or hostnames
// This example uses the default port 9042
Cluster my_cluster = Cluster.build_new_cluster(
    contact_points = "10.20.30.40",
    // Credentials TBD
)

Provide authentication credentials

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.

Your client application must pass authentication credentials to ZDM Proxy in the driver connection strings. The required credentials depend on the authentication requirements for your origin and target clusters:

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, the actual credentials depend on the cluster type:

Self-managed clusters: In your driver connection strings, 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.

The following pseudocode provides an example of a driver’s Cluster object with ZDM Proxy contact points and self-managed cluster credentials. The exact syntax depends on your driver language and version. For specific options and examples, see the documentation for your driver.
```
// This example uses plaintext credentials
// In your applications, always use secure references to credentials
// For example, use environment variables or a secrets manager
Cluster my_cluster = Cluster.build_new_cluster(
    contact_points = "10.20.30.40",
    username="cluster_username",
    password="cluster_password"
)
```
Astra DB: Generate an Astra application token with a role that has sufficient permissions to perform the operations requested by the client application during the migration. Then, in your driver connection strings, set the username to the literal string token, and set the password to the actual application token value (AstraCS:…).

The following pseudocode provides an example of a driver’s Cluster object with ZDM Proxy contact points and self-managed cluster credentials. The exact syntax depends on your driver language and version. For specific options and examples, see the documentation for your driver.
```
// This example uses plaintext credentials
// In your applications, always use secure references to credentials
// For example, use environment variables or a secrets manager
Cluster my_cluster = Cluster.build_new_cluster(
    contact_points = "10.20.30.40",
    username="token",
    password="AstraCS:..."
)
```
For connections to early Astra DB 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.

ZDM Proxy global control connections

In addition to authenticated connections for read/write requests, ZDM Proxy maintains a global control connections to both clusters. These are similar to driver control connections, and they are used for ZDM Proxy monitoring and other internal operations. ZDM Proxy control connections always use the credentials defined in zdm_proxy_cluster_config.yml, regardless of the credentials provided in the driver connection strings.

Connect the CQL shell to ZDM Proxy

The CQL shell (cqlsh) is a command-line tool that you can use to send CQL and cqlsh commands to your Cassandra-based clusters. When issuing these commands directly to a cluster, you can use your database’s included version of cqlsh, or you can download and run a standalone cqlsh installation. With ZDM Proxy, you must use a standalone cqlsh installation to issue commands to both clusters through ZDM Proxy.

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

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

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

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: The same cluster authentication credentials that you used for your driver connection strings.

If no authentication is required by either cluster, omit the -u and -p arguments.

If your migration includes an Astra DB database, don’t use an SCB when you connect cqlsh to ZDM Proxy. If you include the SCB, cqlsh ignores all other connection arguments and connects exclusively to your Astra DB database instead of ZDM Proxy.

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 orchestrates read and write requests as expected between the origin cluster, target cluster, and 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.

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.

DataStax recommends that you review Manage ZDM Proxy instances to understand how to perform common operations that you will need during the remaining migration phases.