Connect your client applications to ZDM Proxy

ZDM Proxy is designed to be similar to a conventional Apache Cassandra® cluster. You communicate with it using the CQL query language used in your existing client applications. It understands the same messaging protocols used by Cassandra, DataStax Enterprise (DSE), and Astra DB. As a result, most of your client applications won’t be able to distinguish between connecting to ZDM Proxy and connecting directly to your Cassandra cluster.

On this page, we explain how to connect your client applications to a Cassandra cluster. We then move on to discuss how this process changes when connecting to a ZDM Proxy. We conclude by describing two sample client applications that serve as real-world examples of how to build a client application that works effectively with ZDM Proxy.

You can use the provided sample client applications, in addition to your own, as a quick way to validate that the deployed ZDM Proxy is reading and writing data from the expected origin and target clusters.

This topic also explains how to connect CQL shell (cqlsh) to ZDM Proxy.

DataStax-compatible drivers

You can use Cassandra drivers to connect your client applications to Cassandra, DSE, HCD, and Astra DB. With drivers, you can allow execute queries, iterate through results, access metadata about your cluster, and perform other related activities.

For available drivers and driver documentation, see Cassandra drivers supported by DataStax.

Connect drivers to Cassandra

Perhaps the simplest way to demonstrate how to use the drivers to connect your client application to a Cassandra cluster is an example in the form of some sample code. But there’s a bit of a problem: the drivers are independent projects implemented natively in the relevant programming language.

This approach offers the benefit of allowing each project to provide an API that makes the most sense for the language or platform on which it’s implemented. Unfortunately it also means there is some variation between languages. With that in mind, the following pseudocode provides reasonable guidance for understanding how a client application might use one of the drivers.

// Create an object to represent a Cassandra cluster listening for connections at
// 10.20.30.40 on the default port (9042).  The username and password are necessary
// only if your Cassandra cluster has authentication enabled.
Cluster my_cluster = Cluster.build_new_cluster(contact_points = "10.20.30.40", username="myusername", password="mypassword")

// 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
my_session.close()
my_cluster.close()

// Display the release version to the user
print(release_version)

As noted, you’ll see some differences in individual drivers:

New versions of the Java driver no longer define a Cluster object. Client programs create a Session directly.
The Node.js driver has no notion of a Cluster or Session at all, instead using a Client object to represent this functionality.

The details may vary but you’ll still see the same general pattern described in the pseudocode in each of the drivers.

This topic does not describe details or APIs for any of the drivers mentioned above. All the drivers come with a complete set of documentation for exactly this task. The following links provide some good starting points for learning about the interfaces for each specific driver:

The core driver section of the Java driver manual.
The getting started guide for the Python driver.
The basic usage section of the C# driver documentation.
The getting started section of the C/C++ driver documentation.
The basic usage section of the Node.js driver documentation.

Connect applications to ZDM Proxy

We mentioned above that connecting to a ZDM Proxy should be almost indistinguishable from connecting directly to your Cassandra cluster. This design decision means there isn’t much to say here; everything we discussed in the section above also applies when connecting your driver to ZDM Proxy. There are a few extra considerations to keep in mind, though, when using the proxy.

Client application credentials

Client applications provide cluster credentials to authenticate requests.

Client applications connect to ZDM Proxy in the same way that they connect to a cluster: by providing a set of credentials.

Clients have no awareness of the ZDM Proxy architecture or the existence of the two separate clusters (the origin and target). Therefore, a client only provides a single set of credentials when connecting to ZDM Proxy, the same as it would when connecting directly to a cluster.

ZDM Proxy uses the credentials provided by the client to forward requests to the cluster that corresponds with those credentials, which is usually the target cluster. If necessary, ZDM Proxy uses the credentials defined in zdm_proxy_cluster_config.yml to forward requests to the other cluster, which is usually the origin cluster.

ZDM Proxy credentials usage when authentication is required for both clusters

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

Determine which credentials to provide

The credentials your client must provide depend on the authentication requirements of the 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.

Expected authentication credentials for self-managed clusters

For a self-managed clusters that require authentication, your client application must provide valid username and password values to access the cluster.

For information about self-managed cluster credentials in your ZDM Proxy configuration, see Cluster and core configuration.

Expected authentication credentials for Astra DB

For Astra DB databases, your client application can provide either application token credentials or a Secure Connect Bundle (SCB).

Application token
SCB

For token-based authentication, do the following:

Generate an application token with the Organization Administrator role.

The token has three values: clientId, secret, and token.
Specify one of the following sets of credentials in your client application:
- Recommended: Set username to the literal string token, and set password to the Astra DB token value (AstraCS:…).
- Legacy applications and older drivers: Set username to the clientId value, and set password to the secret value.

For information about downloading the SCB, see Download and use a Secure Connect Bundle (SCB) with Astra DB Serverless.

For information about using a SCB with a driver, see your driver’s documentation.

For information about Astra DB credentials in your ZDM Proxy configuration, see Cluster and core configuration.

Disable client-side compression with ZDM Proxy

Client applications must not enable client-side compression when connecting through ZDM Proxy, as this is not currently supported. This is disabled by default in all drivers, but if it was enabled in your client application configuration, it will have to be temporarily disabled when connecting to ZDM Proxy.

ZDM Proxy ignores token-aware routing

Token-aware routing isn’t enforced when connecting through ZDM Proxy because these instances don’t hold actual token ranges in the same way as database nodes. Instead, each ZDM Proxy instance has a unique, non-overlapping set of synthetic tokens that simulate token ownership and enable balanced load distribution across the instances.

Upon receiving a request, a ZDM Proxy instance routes the request to appropriate source and target database nodes, independent of token ownership.

If your clients have token-aware routing enabled, you don’t need to disable this behavior while using ZDM Proxy. Clients can continue to operate with token-aware routing enabled without negative impacts to functionality or performance.

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.

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 any utility as a validation tool, Themis also serves as an example of a larger client application which uses the Java driver to connect to a ZDM Proxy — as well as directly to Cassandra clusters or Astra DB — and perform operations. The configuration logic as well as the cluster and session management code have been cleanly separated into distinct packages to make them easy to understand.

Connect the CQL shell to ZDM Proxy

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

You can use your database’s included version of CQL shell, or you can download and run the standalone CQL shell.

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, CQL shell won’t be able to connect to ZDM Proxy.

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

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

Any version of CQL shell can connect to ZDM Proxy, but some clusters require a specific CQL shell version.
Install CQL shell by extracting the downloaded archive:
```
tar -xvf CQLSH_ARCHIVE
```
Replace CQLSH_ARCHIVE with the file name of the downloaded CQL shell archive, such as cqlsh-astra-20210304-bin.tar.gz.
Change to the bin directory in your CQL shell installation directory. For example, if you installed CQL shell for Astra DB, you would run cd cqlsh-astra/bin.

Launch CQL shell:

./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 client connection 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.

If you need to provide credentials for an Astra DB database, don’t use the SCB when attempting to connect CQL shell to ZDM Proxy. Instead, use the token-based authentication option explained in Expected authentication credentials for Astra DB.

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