## Connecting to Astra (Cloud)

Using the DataStax 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][Download Maven] and [install][Install Maven] Maven.
2. Create an Astra database on [AWS/Azure/GCP][Create an Astra database - AWS/Azure/GCP];
   alternatively, have a team member provide access to their
   Astra database (instructions for [AWS/Azure/GCP][Access an Astra database - AWS/Azure/GCP] to
   obtain database connection details.
3. Download the secure connect bundle (instructions for 
   [AWS/Azure/GCP][Download the secure connect bundle - AWS/Azure/GCP], that contains connection
   information such as contact points and certificates.

### Procedure

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

#### Programmatic configuration

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

```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 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:
      
```properties
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:
    
```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;
    
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.");
      }
    }
  }
}
```

[Download Maven]: https://maven.apache.org/download.cgi
[Install Maven]: https://maven.apache.org/install.html
[Create an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/creating-your-astra-database.html
[Access an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html#_sharing_your_secure_connect_bundle
[Download the secure connect bundle - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html
[minimal project structure]: ../core/integration/#minimal-project-structure
[driver documentation]: ../core/configuration/
