Develop applications with Quarkus and Astra DB Serverless

query_builder 15 min

Quarkus is a modern Kubernetes-based Java framework tailored for GraalVM and HotSpot to create modern, cloud-based applications with responsive microservices.

With DataStax Apache Cassandra® Quarkus extension, your REST services can communicate with Cassandra-based databases, including Astra DB Serverless databases.

This guide demonstrates how to connect Quarkus to Astra with the cassandra-quarkus extension.

To install the extension in an existing project using Maven, Gradle, or the Quarkus CLI, see the DataStax Apache Cassandra client extension in the Quarkus extension catalog.

Prerequisites

Familiarity with CQL and Quarkus
JDK 17 or later
Apache Maven 3.8.2 or later (3.9.9 or later recommended)
An Astra DB Serverless database
An application token with the Database Administrator role
Your database’s Secure Connect Bundle (SCB)

The SCB and application token are required to connect to your database. Treat them as you would any other sensitive credentials: store them securely and use secure references in your code.

This guide uses a pre-existing Java project as an example. To build and run the project successfully, you must create the expected keyspace and table. If you change any part of this schema, you must also modify the quickstart project’s code to match your changes.

In your Astra DB Serverless database, create a keyspace named k1.

Because CQL for Astra DB doesn’t allow CREATE KEYSPACE, you must use cqlsh or the DevOps API to create the keyspace before building the project.
In your k1 keyspace, create a table named Fruit with two text columns, name and description, and set the name column as the primary key.
- cqlsh
- Data API
- Apache Cassandra Java driver (advanced)
CREATE TABLE k1.Fruit ( name text PRIMARY KEY, description text);
For Serverless (Vector) databases, you can use the Data API to read, write, and alter CQL tables.

The following command creates the required table for the quickstart project:
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/k1" \ --header "Token: APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "createTable": { "name": "Fruit", "definition": { "columns": { "name": { "type": "text" }, "description": { "type": "text" } }, "primaryKey": "name" } } }'
For more information about this command, see Create a table with the Data API. If you are new to the Data API, see Get started with the Data API.
As an alternative to pre-creating the table, you can use the Java driver to create the table in Astra at runtime. For example:
// ... session.execute(String.format( "CREATE TABLE IF NOT EXISTS k1.Fruit (name TEXT PRIMARY KEY, description TEXT);", ) ); // ...
Although this logic isn’t included in the cassandra-quarkus quickstart project or this guide, you might want to try this approach in your own projects.

Set up the quickstart project

The cassandra-quarkus repository provides a quickstart project that you can use to learn about the Cassandra Quarkus extension. This project works with Astra, DSE, and open-source Apache Cassandra. The following steps explain how to modify the quickstart project to connect to Astra. For more information about the quickstart project, see Next steps.

Clone the cassandra-quarkus repository. The quickstart project files are in the quickstart directory.
Review the dependencies specified in cassandra-quarkus/quickstart/pom.xml. Many dependencies are specific to this quickstart; your own projects might not require all of the given dependencies.

cassandra-quarkus-client is the primary dependency for the Cassandra Quarkus extension.

If you want to use a different version of the Apache Cassandra Java driver , modify the java-driver-* dependencies:
- For versions 4.18 and later, you only need to modify the java-driver.version property.
- For versions 4.17 and earlier, you must modify the java-driver.version property, and you must change the groupId for all java-driver-* artifacts to com.datastax.oss. For more information, see Java driver ownership.
Open /src/main/resources/application.properties, and then edit the connection and authentication properties for Astra:
1. Comment out or delete quarkus.cassandra.contact-points and quarkus.cassandra.local-datacenter. These properties are automatically provided by the SCB when connecting to Astra.
2. Set quarkus.cassandra.keyspace to k1, the keyspace where you created the quickstart table.
3. Uncomment quarkus.cassandra.cloud.secure-connect-bundle, and then set it to the path to your database’s SCB.
4. Uncomment quarkus.cassandra.auth.username, and then set it to the literal string token.
5. Uncomment quarkus.cassandra.auth.password, and then set it to your application token (prefixed by AstraCS:).
application.properties
```
# Connecting to Apache Cassandra (R) or DataStax Enterprise (DSE)
#quarkus.cassandra.contact-points=127.0.0.1:9042
#quarkus.cassandra.local-datacenter=datacenter1
quarkus.cassandra.keyspace=k1

# Connecting to DataStax Astra
quarkus.cassandra.cloud.secure-connect-bundle=/path/to/secure-connect-bundle.zip

# Authentication
quarkus.cassandra.auth.username=token
quarkus.cassandra.auth.password=AstraCS:...
```

Build and run the quickstart project

To test the connection to your database, build and run the quickstart project. The following is a minimal, local build. For other build options, including a frontend UI, see Next steps.

Package the application:
```
mvn clean package
```

Run the application:

java -jar target/cassandra-quarkus-quickstart-*-runner.jar

Check that the REST endpoints are available:
```
curl http://localhost:8080/fruits
```

Add an entry to the list:

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name":"apple","description":"red and tasty"}' \
  http://localhost:8080/fruits

To verify the change, get the fruits list again:

curl http://localhost:8080/fruits

You can also check that the data is present in the Fruit table in Astra.

The following examples read all rows in the table. This is suitable for small tables only because it can be resource intensive. In a production scenario, use specific filters to read table data.

cqlsh
Data API

Read the Fruit table:

select * from k1.Fruit;

Result

 name  | description
-------+---------------
 apple | red and tasty

(1 rows)

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/k1/Fruit" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {}
  }
}'

For more information about this command, see Find rows with the Data API.

Next steps

For a complete walkthrough of the quickstart project and advanced features, such as metrics and mappers, see the Quarkus Cassandra client guide or the cassandra-quarkus quickstart README.

Develop applications with Quarkus and Astra DB Serverless

Prerequisites

Create a data model

Set up the quickstart project

Build and run the quickstart project

Next steps

Was this helpful?

Give Feedback