Get started with the Java driver

Because DataStax Enterprise (DSE) is based on Apache Cassandra®, you can use Cassandra drivers to connect to your DSE databases.

This quickstart explains how to install a driver, connect it to your DSE database, and then send some CQL statements to the database.

To use the Java driver, you need to choose a compatible version, add the driver dependency to your pom.xml, use the ConnectDatabase class to initialize the driver, and then connect the driver to your DSE database. Once connected, you can write scripts that use the driver to run commands against your database.

Java driver ownership, groupId, and artifact naming conventions

Starting with versions 4.18 and 3.12, the Java driver is maintained by the Apache Software Foundation (ASF). Prior versions were maintained by DataStax.

In version 4.18 and later, the groupId is org.apache.cassandra. This is a breaking change from earlier versions that used com.datastax.cassandra. Make sure you update this value in your Java project dependencies. For examples, see Add the Java driver dependency.

DataStax recommends that you upgrade to the 4.x series if you are on any earlier version. When upgrading from the 3.x series, be aware that the artifact naming convention for the 4.x series is java-driver-*, not cassandra-driver-*.

Java driver compatibility

DataStax officially supports the latest 12 months of releases, and DataStax recommends using the latest driver version whenever possible. Compatibility isn’t guaranteed for earlier versions. For upgrade guides and compatibility information for earlier versions, see Unsupported drivers.

New features and bug fixes are developed on the latest minor version of the driver, and users are encouraged to stay current with those minor releases. APIs are maintained stable according to semantic versioning conventions, and upgrades should be trivial.

Unless otherwise specified, compatibility version ranges include all patch versions. For example, a range of 4.0 to 4.3 includes all versions from 4.0.0 to the last 4.3.z release.

Java driver 4.x series compatibility
Driver version	DSE 6.9	DSE 6.8	DSE 5.1	Comments
4.16 and later	Fully compatible	Fully compatible	Fully compatible	Starting with version 4.18, this driver is maintained by the Apache Software Foundation (ASF).
4.5 to 4.15	Partially compatible	Fully compatible	Fully compatible	Doesn’t support the vector type.
4.4	Partially compatible	Partially compatible	Fully compatible	Doesn’t support the vector type. The Java driver unified with the DSE-only driver in version 4.4, with support for additional DSE features added in subsequent releases. For information about a specific version, see the Java driver releases.
4.0 to 4.3	Partially compatible	Partially compatible	Partially compatible	Doesn’t support the vector type. The Java driver unified with the DSE-only driver in version 4.4, with support for additional DSE features added in subsequent releases. Pre-unification versions might not include support for any DSE features. For information about a specific version, see the Java driver releases.

For Java driver 3.x series compatibility, see Unsupported drivers.

Prepare the environment and database

To use this driver, you need the following:

A running DSE cluster
A keyspace
Java installed

For specific Java version requirements, see the Java driver documentation.
Apache Maven™ (or similar) installed

Authentication methods for drivers

The DSE-compatible drivers ship with built-in authentication providers that provide the necessary utilities to connect to secure DSE clusters. However, DSE clusters have no authentication service enabled by default. This simplifies initial setup, but it isn’t intended for production deployments. You must configure your preferred authentication method, security schemes, users, and roles in your clusters before attempting to use a non-default authentication method through a driver. The required credentials for the driver connection depend on your cluster and authentication method.

DSE unified authentication provides a single, flexible security model. One DSE server can accept multiple forms of authentication, and clients with different levels of access can use varying authentication schemes to connect to the same server.

Supported authentication methods include internal usernames and passwords, LDAP/Active Directory usernames and passwords, and Kerberos authentication. All of these features are supported directly in most DSE-compatible drivers with built-in classes to enable the desired security configuration. Some drivers include support for custom authentication provider classes if your desired authentication method isn’t supported by the built-in providers.

Internal username and password authentication

Always use this method in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.

Drivers use a plain text authentication provider to perform internal username and password authentication. For DSE, the driver sends a plain text username and password to the server that authenticates to the underlying Authentication scheme.

To authenticate with a username and password, provide the username and password in the driver configuration. For example, in a test environment, you could use superuser credentials. In production, use narrowly scoped user roles for better security.

In addition to traditional role-based access control (RBAC), DSE supports proxy authentication (authorization through proxy roles). With proxy authentication, the driver authenticates with a fixed set of credentials that authorize access to a cluster in lieu of direct role assignment. The driver uses the credentials to connect to the cluster and execute requests (with proxy execute) within the context of the proxy roles.

This guide uses username and password authentication for simplicity. For examples of other authentication methods, including proxy authentication, see your driver’s documentation.

LDAP/Active Directory authentication

Always use this method in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.

Drivers use a plain text authentication provider to perform LDAP/Active Directory username and password authentication. For DSE, the driver sends a plain text username and password to the server that authenticates to the underlying LDAP scheme.

For usage instructions and examples, see your driver’s documentation.

Kerberos authentication

Most DSE-compatible drivers extend authentication providers to support Kerberos authentication for DSE either directly or through custom provider implementations.

Kerberos authentication uses keytabs, ticket caches, and Kerberos configuration files:

Kerberos keytabs: A keytab can be used to authenticate with Kerberos without requiring any additional credentials or a password. Keytab files must have their permissions set properly to restrict access. The permissions must be set to allow the application user to access the keytab.
Kerberos ticket cache: To use the Kerberos ticket cache, use the kinit command to authenticate with the Kerberos server and obtain a ticket. Then, verify the ticket cache contains a ticket for the successful authentication with the klist command. Once you verify there is a ticket in the ticket cache, you can run an application that is configured to use the Kerberos authentication provider. If multiple principals have valid tickets in the ticket cache, and no principal was specified in the application, then the driver arbitrarily chooses one and uses that ticket.
Kerberos configuration file: Driver authentication against a Kerberos-enabled DSE cluster requires a krb5.conf file containing the Kerberos configuration settings. If this file isn’t in the node’s /etc directory, contact your Kerberos system administrator to locate the file. To reference a krb5.conf file in a non-default location, set the KRB5_CONFIG environment variable to the location of your krb5.conf. Kerberos command line tools such as kinit, klist, and kdestroy respect this variable, as well as drivers with support for Kerberos authentication with krb5.conf. For the Java driver, you must set the java.security.krb5.conf system property to the path to the krb5.conf file at startup.

For more information, see the documentation for your version of the Java driver:

SSL-encrypted connections for drivers

Cassandra drivers support SSL-encrypted connections between the driver and server. Encrypted driver connections follow a typical SSL workflow:

The client opens a TCP connection to the server on the configured SSL port.
An SSL handshake is initialized by the server, sending its public key (or certificate) to the client.
The client uses that public key certificate to generate an encrypted session key and sends it back to the server.
The server decrypts the message using its private key and retrieves the session key.
All communication from that point on is encrypted using that session key.

SSL isn’t required, but it is recommended for production deployments, especially those with clients communicating over the public internet.

To use SSL-encrypted connections, you must do the following:

Select an identity verification method:

No identity verification (Not recommended)

As a best practice for secure driver communication, never use SSL without identity verification. Always use either client-to-server or server-to-client identity verification.

While most drivers support creating SSL connections to the server without identity verification, DataStax doesn’t recommend this for production deployments. When a secure browser contacts a web server, the browser verifies the identity of the server before sending it requests in case an attacker is masquerading as the web server. A secure communication to a bad actor defeats the purpose of configuring secure communication between the browser and web server in the first place.

Client verifies server

To verify the identity of a server, the driver must be configured with a list of trusted certificate authorities (CAs). When the driver receives the server’s SSL certificate during the SSL handshake, it checks that the certificate was signed by one of the registered CAs. If the certificate wasn’t signed by a registered CA, the client checks that the signer was signed by one of the registered CAs. It continues through the signers until it finds one that is in the client’s list of trusted CAs. If the client doesn’t find a registered CA, then identity verification fails.

Server verifies client

To configure a server to verify the identity of a client, edit cassandra.yaml, find client_encryption_options, and then set require_client_auth to true. This scenario requires that clients have their own certificates to send to the server upon request during the SSL handshake. For more information, see Configure SSL for client-to-node connections in DSE.
Configure SSL in your DSE cluster.

By default DSE clusters are configured to communicate with clients using an unencrypted binary protocol. This is convenient for getting started but it isn’t suitable for production environments.

To enable SSL in a DSE cluster, you need access to your cluster’s cassandra.yaml file. The location of the cassandra.yaml file depends on your DSE installation method. For information about editing cassandra.yaml and configuring SSL, see Configure SSL for DataStax Enterprise.
Configure your driver to use the SSL certificates and the SSL-encrypted connection based on your preferred identity verification method. For instructions, see the documentation for your version of the Java driver:
- Apache Cassandra Java driver 4.18 and later: SSL
- DataStax Java driver 4.17 and earlier: SSL

Add the Java driver dependency

In your project’s pom.xml file, add a dependency for the Apache Cassandra Java driver :

If you install an earlier version of the driver, make sure your version is compatible with DSE and your application’s CQL statements. For example, if you need to query vector data, make sure your driver version supports the vector type.

The groupId depends on the driver version:

Version 4.18 and later

<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>VERSION</version>
</dependency>

Version 4.17 and earlier

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>VERSION</version>
</dependency>

For Java driver 3.x series, see Unsupported drivers.

Connect the Java driver

In your Java project, navigate to /src/main/java, and then create a ConnectDatabase.java file:
```
cd JAVA_PROJECT_DIRECTORY/src/main/java
touch ConnectDatabase.java
```

Add the following code to the ConnectDatabase.java file.

This code imports dependencies, initializes the Java driver, and implements the ConnectDatabase class to connect to your DSE database. For more information, see Best practices: Session and cluster handling and Connection pools and initial contact points.

This example includes imports that you might not need for your project. For example, CqlVector is only necessary for the vector data type.

ConnectDatabase.java

import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;
import com.datastax.oss.driver.api.core.CqlSessionBuilder;
import com.datastax.oss.driver.api.core.cql.PreparedStatement;
import com.datastax.oss.driver.api.core.data.CqlVector;
import com.datastax.oss.driver.api.core.type.codec.TypeCodecs;

import java.nio.file.Paths;
import java.util.Arrays;
import java.util.List;

public class DriverExample {
    public static void main(String[] args) {
        // Initialize the Java driver
        String keyspace = "default_keyspace";
        CqlSessionBuilder builder = CqlSession.builder();
        builder.withAuthCredentials("username","password");
        builder.withKeyspace(keyspace);

        try (CqlSession session = builder.build()) {
            //CQL queries and query execution logic...
        }

        System.exit(0);
    }
}

To test the connection, add a simple query to the script.

The following example SELECT statement runs against the system.local table. You can replace this statement with any CQL statement on any keyspace or table in your database. Edit the variable that stores the keyspace name, if necessary.

        try (CqlSession session = builder.build()) {
            // Select the release_version from the system.local table:
            ResultSet rs = session.execute("select release_version from system.local");
            Row row = rs.one();
            //Print the results of the CQL query to the console:
            if (row != null) {
                System.out.println(row.getString("release_version"));
            } else {
                System.out.println("An error occurred.");
            }
        }

Save ConnectDatabase.java, and then build your Maven project.

If you ran the example SELECT statement on the system.local table, then the release_version value from the system.local table is printed to the console if the script runs successfully.

Next, you can extend or modify this script to run other commands against your database or connect to other databases. For more information, see the documentation for your version of the Java driver:

Use DSE advanced workloads

If you have enabled DSE advanced workloads, you must configure your driver to connect to compatible nodes when sending DSE Search or Graph queries. For more information, see DSE advanced workloads in Cassandra drivers.

Reconnect the Java driver after a migration

If you migrate your data from one Cassandra database platform to another, you must update your client applications to connect to your new databases.

At minimum, you must update the driver connection strings. Additional changes might be required if you upgraded to a new major driver version or migrated to a database platform with a different feature set. For example, if you migrate to Astra, your drivers cannot create keyspaces because CQL for Astra doesn’t support CREATE KEYSPACE.

For information about updating driver connections after a migration, see the DataStax migration documentation on Connecting client applications to your new target database. Although the referenced documentation is in the context of zero downtime migration, the information applies to most Cassandra-to-Cassandra migrations where you need to update Cassandra driver connection strings.

Get started with the Java driver

Java driver ownership, groupId, and artifact naming conventions

Java driver compatibility

Prepare the environment and database

Authentication methods for drivers

SSL-encrypted connections for drivers

Add the Java driver dependency

Connect the Java driver

Use DSE advanced workloads

Reconnect the Java driver after a migration

Documentation and release notes

Was this helpful?

Give Feedback