Astra SDK Reference Configuration

This page will cover the different options and configurations available to work with Astra SDK. To get more information regarding one API in particular please refer to the proper chapter in the menu on the left.

In the following tutorial we expect you to already have a database running and a token. If you need to create them have a look to the quickstart

📋 Table of content

1. Architecture
2. SDK design principles
3. Reference configuration
4. Sample Code
5. Load-Balancing and Failover
6. Working with AstraRC

1. Architecture

Datastax ASTRA is a the cloud platform of Datastax. It provides AstraDB and Astra Streaming services.

• AstraDB is a DBAAS (database as a service) for Apache Cassandra™. You can start and run instances with a few clicks. The platform provides the databases nodes but also Stargate nodes with the tools to use the apis (swagger and graphQL playground).

• Astra Streaming is a SAAS (software as a service) for Apache Pulsar™. You can create tenants with a few clicks and use all components of the message broker: namespaces, topics, subscriptions, functions....

📘 An Astra Database contains:

• One to multiple region(s).
• Each region will have 3 Cassandra nodes, 3 Stargate nodes, the CQL Console, Swagger-UI, GraphQL Playground and the load balancer to distribute the requests across the nodes.

As such, with Astra, there is no need to perform any load balancing at client side. You can eventually perform a failover across astra regions.

2. SDK Design Principles

The Astra SDK library leverage on the Stargate SDK. As such it will reuse the same technologies for Cql, Http, gRPC, and graphQL, those are detailed here.

The Astra SDK adds some Http clients for the Devops Apis (databases, organization, streaming) reusing the same Http Component but also the pulsar-client and pulsar-admin needed to interact with Astra Streaming.

3. Reference configuration

4. Sample Code

5. Load-Balancing and Failover

6. Working with AstraRc

To setup the SDK you can provide values using the builder as listed above but not only you can save them locally in some configuration file (.astrarc).

📘 (a) Understanding configuration file ~/.astrarc

This file uses the ini configuration formatting. A key ASTRA_DB_APPLICATION_TOKEN is associated to its value. Values are grouped in sections identified by a [name].

Sample File with 2 sections:

[default]
ASTRA_DB_APPLICATION_TOKEN=AstraCS:GmSdU.....
ASTRA_DB_CLIENT_ID=GmSdUgw....
ASTRA_DB_CLIENT_SECRET=pL7QcZgN....
ASTRA_DB_ID=33a7527a-aaf9-4f9f-9758-96216efff3d5
ASTRA_DB_KEYSPACE=ks1
ASTRA_DB_REGION=eu-central-1
ASTRA_DB_SECURE_BUNDLE=

[sandbox]
ASTRA_DB_APPLICATION_TOKEN=AstraCS:GmSdU.....
ASTRA_DB_CLIENT_ID=GmSdUgw....
ASTRA_DB_CLIENT_SECRET=pL7QcZgN....
ASTRA_DB_ID=33a7527a-aaf9-4f9f-9758-96216efff3d5
ASTRA_DB_KEYSPACE=ks1
ASTRA_DB_REGION=eu-central-1
ASTRA_DB_SECURE_BUNDLE=

The file starts with a [default] section. If nothing name is provided it will be the one to load. In the SDK this file will be associated with the class com.datastax.astra.sdk.utils.AstraRc

📘 (b) Generate an ~/.astrarc

// Generate the file in default location user home (~/.astrarc) 
AstraRc.create("<your_token>");
        
// Generate the file in a defined location
AstraRc.create("<your_token>", new File("/tmp/astracrc"));

📘 (c) Load an ~/.astrarc file

// Load default file (~/.astrarc) 
AstraRc confAstraRc1 = AstraRc.load()
        
// Load a file in defined location
AstraRc confAstraRc2 = AstraRc.load("/tmp/astracrc");

📘 (d) Update an ~/.astrarc file

confAstraRc1.save("sectionName", "keyName", "keyValue");

Working with environment variables

The SDK can be and will be used in Docker and Kubernetes contextes. For those you provide parameters through environment variables. The SDK is ready for that here is the list of environment variables than you can provide:

Environment Variable	Definition
STARGATE_USERNAME	User identifier to login to Stargate
STARGATE_PASSWORD	User password to login to Stargate
STARGATE_ENDPOINT_AUTH	Authentication endpoint to get a Token
STARGATE_ENDPOINT_REST	Endpoint for Data and Document APIs
STARGATE_ENDPOINT_GRAPHQL	Endpoint for GraphQL APIs
STARGATE_ENDPOINT_CQL	Contact Point adresse ip:port
STARGATE_LOCAL_DC	Local DataCenter name
STARGATE_KEYSPACE	Keyspace selected
STARGATE_ENABLE_CQL	Even with user/[assword you can disable CQL to stay stateless
ASTRA_DB_ID	Astra database identifier
ASTRA_DB_REGION	Main region for the database
ASTRA_DB_APPLICATION_TOKEN	Your Token AstraCS:...
ASTRA_DB_CLIENT_ID	ClientId part of your token
ASTRA_DB_CLIENT_SECRET	ClientSecret part of your token
ASTRA_DB_KEYSPACE	Keyspace to use in ASTRA
ASTRA_DB_SECURE_BUNDLE	Location where to find the secure connect bundle

The same variables can be provided as Java parameter using the syntax -DKEY=VALUE

java -jar myapp.jar -DSTARGATE_USERNAME=cassandra -DSTARGATE_PASSWORD=cassandra