cloud

Connecting to Astra (Cloud)

Using the Java Driver to connect to a DataStax Astra database is almost identical to using the driver to connect to any normal Apache Cassandra® database. The only differences are in how the driver is configured in an application and that you will need to obtain a secure connect bundle.

Prerequisites

1. Download and install Maven.
2. Create an Astra database on AWS/Azure/GCP; alternatively, have a team member provide access to their Astra database (instructions for AWS/Azure/GCP to obtain database connection details.
3. Download the secure connect bundle (instructions for AWS/Azure/GCP, that contains connection information such as contact points and certificates.

Procedure

Create a minimal project structure as explained here. Then modify Main.java using one of the following approaches:

Programmatic configuration

You can pass the connection information directly to CqlSession.builder():

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 Main {
  
    public static void main(String[] args) {
        try (CqlSession session = CqlSession.builder()
            // make sure you change the path to the secure connect bundle below
            .withCloudSecureConnectBundle(Paths.get("/path/to/secure-connect-database_name.zip"))
            .withAuthCredentials("user_name","password")
            .withKeyspace("keyspace_name")
            .build()) {

                // For the sake of example, run a simple query and print the results
                ResultSet rs = session.execute("select release_version from system.local");
                Row row = rs.one();
                if (row != null) {
                    System.out.println(row.getString("release_version"));
                } else {
                    System.out.println("An error occurred.");
                }
           }
        }
    }

The path to the secure connect bundle for your Astra database is specified with withCloudSecureConnectBundle(). The authentication credentials must be specified separately with withAuthCredentials(), and match the username and password that were configured when creating the Astra database.

Note the following:

• an SSL connection will be established automatically. Manual SSL configuration is not allowed, any settings in the driver configuration (advanced.ssl-engine-factory) will be ignored;
• the secure connect bundle contains all of the necessary contact information. Specifying contact points manually is not allowed, and will result in an error;
• if the driver configuration does not specify an explicit consistency level, it will default to LOCAL_QUORUM (instead of LOCAL_ONE when connecting to a normal Cassandra database).

File-based configuration

Alternatively, the connection information can be specified in the driver's configuration file (application.conf). Merge the following options with any content already present:

datastax-java-driver {
  basic {
    # change this to match the target keyspace
    session-keyspace = keyspace_name
    cloud {
      # change this to match bundle's location; can be either a path on the local filesystem
      # or a valid URL, e.g. http://acme.com/path/to/secure-connect-database_name.zip
      secure-connect-bundle = /path/to/secure-connect-database_name.zip
    }
  }
  advanced {
    auth-provider {
      class = PlainTextAuthProvider
      # change below to match the appropriate credentials
      username = user_name 
      password = password
    }
  }
}

For more information about the driver configuration mechanism, refer to the driver documentation.

With the above configuration, your main Java class can be simplified as shown below:

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;
    
public class Main {
    
  public static void main(String[] args) {
    // Create the CqlSession object; it will read the configuration file and pick the right
    // values to connect to the Astra database.
    try (CqlSession session = CqlSession.builder().build()) {

      ResultSet rs = session.execute("select release_version from system.local");
      Row row = rs.one();
      if (row != null) {
        System.out.println(row.getString("release_version"));
      } else {
        System.out.println("An error occurred.");
      }
    }
  }
}