DataStax Java driver

To use the DataStax Java driver, you need to add the driver dependency to your pom.xml, use the ConnectDatabase class to initialize the driver, and then connect the driver to your Astra DB Classic database. Once connected, your scripts can use the driver to run commands against your database.

Prerequisites

Create a database.
Set the following environment variables:
- ASTRA_DB_ID: The database ID
- ASTRA_DB_REGION: A region where your database is deployed and where you want to connect to the database, such as us-east-2
- ASTRA_DB_KEYSPACE: A keyspace in your database, such as default_keyspace
- ASTRA_DB_APPLICATION_TOKEN: An application token with the Database Administrator role.
  
  The token.json has the following format:
  { "clientId": "CLIENT_ID", "secret": "CLIENT_SECRET", "token": "APPLICATION_TOKEN" }
  For driver authentication, you can use either clientId and secret or the literal string token and the AstraCS token value. If you are on an older driver version that doesn’t support the token option, then you might need to use clientId and secret. For more information, see Token details.
Download your database’s Secure Connect Bundle (SCB).
Install Maven.

Add the Java driver dependency

Add the latest DataStax Java driver Maven Central dependency to your project’s pom.xml file:

<!--Use the latest version from https://search.maven.org/artifact/com.datastax.oss/java-driver-core -->
<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>LATEST_VERSION</version>
</dependency>

Make sure you use a driver version that is compatible with Astra DB. For more information, see DataStax driver matrix.

Example pom.xml

The following pom.xml file includes DataStax Java driver dependencies. If you already have a pom.xml file for your Java project, you only need the Java driver repository and dependencies.

Replace VERSION with the current Java driver version Maven Central .

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>net.techne.web</groupId>
    <artifactId>cloudTest</artifactId>
    <version>1.0</version>
    <packaging>jar</packaging>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <!--Use the latest version from https://search.maven.org/artifact/com.datastax.oss/java-driver-core -->
        <java.driver.version>VERSION</java.driver.version>
    </properties>
    <dependencies>
        <!-- START-javaDriverDependencyCore -->
        <dependency>
            <groupId>com.datastax.oss</groupId>
            <artifactId>java-driver-core</artifactId>
            <version>$VERSION</version>
        </dependency>
        <!-- END-javaDriverDependencyCore -->
        <!-- START-javaDriverDependencyQuery -->
        <dependency>
            <groupId>com.datastax.oss</groupId>
            <artifactId>java-driver-query-builder</artifactId>
            <version>$VERSION</version>
        </dependency>
        <!-- END-javaDriverDependencyQuery -->
        <!-- START-javaDriverDependencyMapper -->
        <dependency>
            <groupId>com.datastax.oss</groupId>
            <artifactId>java-driver-mapper-runtime</artifactId>
            <version>$VERSION</version>
        </dependency>
        <!-- END-javaDriverDependencyMapper -->
    </dependencies>
</project>

Initialize and 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
```

Copy the following code into ConnectDatabase.java, and then replace PATH_TO_SCB with the absolute path to your database’s Secure Connect Bundle (SCB) (secure-connect-DATABASE_NAME.zip):

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 java.nio.file.Paths;

public class ConnectDatabase {

   public static void main(String[] args) {
       // Create the CqlSession object:
       try (CqlSession session = CqlSession.builder()
           .withCloudSecureConnectBundle(Paths.get("PATH_TO_SCB"))
           .withAuthCredentials("token", System.getenv("ASTRA_DB_APPLICATION_TOKEN"))
           .withKeyspace(System.getenv("ASTRA_DB_KEYSPACE"))
           .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.");
           }
       }
       System.exit(0);
   }
}

This code imports dependencies, initializes the Java driver, implements the ConnectDatabase class to connect to your Astra DB database, runs a CQL query, and then prints the output to the console.

Save ConnectDatabase.java and then build your Maven project.

The console output prints the release_version value from the system.local table in your Astra DB database.
Extend or modify this script to run other commands against your database or connect to other databases. For more information, see Java driver documentation and Developing applications with DataStax drivers.

Connect the Java Cloud driver (deprecated)

The legacy Stargate APIs and their associated drivers are deprecated for Astra DB Classic as of September 2024, and end-of-life (EOL) is scheduled for the end of 2025. As EOL approaches, DataStax will provide migration information to support your transition to other options.

If you have questions or concerns, contact your account representative or DataStax Support.

Generate a Bearer Token and select Database Administrator for the role.
Install a Java Development Kit (SDK) and Maven.
Create a keyspace.
Create a table for your keyspace.

Add the Java Cloud driver dependencies to your pom.xml file. Make sure the dependency names correspond to the installed versions.

Replace PROTO_VERSION with the current gRPC proto version Maven Central , and replace NETTY_VERSION with the current gRPC netty version .

<dependencies>
  <dependency>
    <groupId>io.stargate.grpc</groupId>
    <artifactId>grpc-proto</artifactId>
    <version>PROTO_VERSION</version>
  </dependency>
  <dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>NETTY_VERSION</version>
  </dependency>
</dependencies>

While running Stargate on Astra DB, create a connection. To connect to your Stargate instance, create the client. For example, for a local Stargate instance, the following client code fetches an authentication token with a REST call:

private static final String ASTRA_DB_ID      = "DATABASE_ID";
private static final String ASTRA_DB_REGION  = "REGION_NAME";
private static final String ASTRA_TOKEN      = "APPLICATION_TOKEN";
private static final String ASTRA_KEYSPACE   = "KEYSPACE_NAME";

public static void main(String[] args)
throws Exception {
  //-------------------------------------
  // 1. Initializing Connectivity
  //-------------------------------------
  ManagedChannel channel = ManagedChannelBuilder
          .forAddress(ASTRA_DB_ID + "-" + ASTRA_DB_REGION + ".apps.astra.datastax.com", 443)
          .useTransportSecurity()
          .build();

  // blocking stub version
  StargateGrpc.StargateBlockingStub blockingStub =
      StargateGrpc.newBlockingStub(channel)
          .withDeadlineAfter(10, TimeUnit.SECONDS)
          .withCallCredentials(new StargateBearerToken(ASTRA_TOKEN));
}

Perform a query by passing a CQL query to the client using the ExecuteQuery() function for standard query execution:

QueryOuterClass.Response queryString = blockingStub.executeQuery(QueryOuterClass
  .Query.newBuilder()
  .setCql("SELECT firstname, lastname FROM " + ASTRA_KEYSPACE + ".users")
  .build());

To use a batch statement, provide an ExecuteBatch() function to execute a batch query:

blockingStub.executeBatch(
  QueryOuterClass.Batch.newBuilder()
      .addQueries(
          QueryOuterClass.BatchQuery.newBuilder()
              .setCql("INSERT INTO " + ASTRA_KEYSPACE + ".users (firstname, lastname) VALUES('Jane', 'Doe')")
              .build())
      .addQueries(
          QueryOuterClass.BatchQuery.newBuilder()
              .setCql("INSERT INTO " + ASTRA_KEYSPACE + ".users (firstname, lastname) VALUES('Serge', 'Provencio')")
              .build())
      .build());
System.out.println("2 rows have been inserted in table users.");

DataStax Java driver

Prerequisites

Add the Java driver dependency

Initialize and connect the Java driver

Connect the Java Cloud driver (deprecated)

See also

Was this helpful?

Give Feedback