Cassandra Workshop Series are an interactive experience. Datastax Developer Advocates share some knowledge about Apache Cassandra™ NoSQL database and how you build Cloud Native applications. You interact with them through chats (youtube and discord), quizzes (menti.com), and exercises.
In this repository, you'll find everything you need related to week 4 of the Cassandra Worskhop Series. For simplicity all exercise instructions will be listed in a single README for each language: Java, Javascript, Python, CSharp. We recommended you to have some previous experience with the language you choose.
Now if you are NOT familiar with any of those, we recommended to use Python, the is the simplest. Ready ? go !
| Materials | Description and Links |
|---|---|
| Slidedeck | SLIDEDECK |
| Chat with us on Discord | DISCORD |
| Ask Question during week | COMMUNITY |
| Recording LIVESTREAM NA, LATAM | 📅 July 22th 12EDT |
| Recording LIVESTREAM APAC, EMEA | 📅 July 23th 12:30 IST |
| Homework | here |
| Exercises | Description and Links |
|---|---|
| Prerequisites - Create your Astra instance | Create your Astra instance |
| Prerequisites : Create the Data model | Create the Data model |
| Exercise : Start backend and API | Start JAVA Backend |
| Exercise : Start backend and API | Start PYTHON Backend |
| Exercise : Start backend and API | Start CSHARP Backend |
| Exercise : Start UI and demo | Start User Interface |
- Create your Astra instance (reminders)
- Create the Data Model (reminders)
🔥 If you intend to use the python or C# backend please jump to that section using Start PYTHON Backend OR Start CSHARP Backend. You only need ONE backend at a time. 🔥
This provides an example REST backend built in Java using Spring Boot. This application serves as the connection between the UI website and an underlying Astra database. It has Swagger installed.
Creation of CqlSession objects within an application is an expensive process as they take awhile to initialize and become aware of the clusters topology. Due to this it is a best practice to create a CqlSession object once per application and reuse it throughout the entire lifetime of that application.
SessionManager implements the Singleton pattern to handle a single instance of the CqlSession object. Note that this is the only bean not initialized by Spring at startup. This is only when you have provided the secure credential bundle that we can initiate a connection.
@@ ONLINE in GITPOD @@ ✅ Open gitpod : Gitpod is an IDE 100% online based on Eclipse Theia. To initialize your environment simply click on the button below (CTRL + Click to open in new tab)
Target url looks like https://<your_uid>.<your_region>.gitpod.io/#/workspace/cassandra-workshop-series. These URL's are dynamic and we cannot provide clickable links in advance. You will need to copy-paste <your_uid>.<your_region> as we will insert them in each URL during the exercises.
⚠️⚠️⚠️
By default Autosave is not enabled in Gitpod. Don't forget to save your modifications with CTRL+S
⚠️⚠️⚠️
👁️ Expected output
That's it. Gitpod provides all tools we will need today including maven,pip,npm. At initialization of the workspace we schedule a command to download dependencies.
✅ Start SpringBoot
Move to folder week4-AppDev-api to get the exercises of the week and getting-started-with-astra-java to work with JAVA.
cd week4-AppDev-api/getting-started-with-astra-java
mvn spring-boot:run
👁️ Expected output
___ _
/ _ \ | |
/ /_\ \ ___ | |_ _ __ __ _
| _ |/ __|| __|| '__| / _` |
| | | |\__ \| |_ | | | (_| |
\_| |_/|___/ \__||_| \__,_|
Getting Started with Astra
08:53:58.334 INFO com.datastax.astra.GettingStartedWithAstra : Starting GettingStartedWithAstra on ws-5cea4c69-c849-40fe-9b27-0b6673a93e90 with PID 3322 (/workspace/cassandra-workshop-series/week4-AppDev-api/getting-started-with-astra-java/target/classes started by gitpod in /workspace/cassandra-workshop-series/week4-AppDev-api/getting-started-with-astra-java)
08:53:58.337 INFO com.datastax.astra.GettingStartedWithAstra : No active profile set, falling back to default profiles: default
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by org.codehaus.groovy.vmplugin.v7.Java7$1 (file:/workspace/m2-repository/org/codehaus/groovy/groovy/2.5.7/groovy-2.5.7-indy.jar) to constructor java.lang.invoke.MethodHandles$Lookup(java.lang.Class,int)
WARNING: Please consider reporting this to the maintainers of org.codehaus.groovy.vmplugin.v7.Java7$1
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release
08:54:02.282 INFO com.datastax.astra.GettingStartedWithAstra : Started GettingStartedWithAstra in 4.58 seconds (JVM running for 14.049)
Click the "Open Browser" button and GitPod will generate a URL that you should be able to access to the UI with. Note that the 8080 port has been redirected to port 80 but changing the URL with a 8080 prefix and enforcing HTTPS. With the UI (swagger) you can start executing some requests against the REST API. Just paste "/swagger-ui.html" to the end of YOUR generated URL.
https://8080-<your_uid>.<your_region>.gitpod.io/swagger-ui.html
@@ ONLINE in GITPOD END @@ ! LOCAL on YOUR MACHINE✅ Prerequisites
- Java 11+
- An Astra compatible Java driver, instructions may be found here to install this locally.
- An Astra database with the CQL schema located in schema.cql already added.
- The username, password, keyspace name, and secure connect bundle downloaded from your Astra Database. For information on how to obtain these credentials please read the documentation found here.
✅ Start SpringBoot
This application is a Spring Boot web application. This sample can be run from the root directory using:
cd week4-AppDev-api/getting-started-with-astra-java
mvn spring-boot:run
This will startup the application running on http://localhost:8080
You will know that you are up and working when you get the following in your terminal window:
16:23:01.569 INFO com.datastax.astra.GettingStartedWithAstra : Started GettingStartedWithAstra in 1.851 seconds (JVM running for 2.39)
✅ Access the API from a browser
Note: If you want to change the listening port of the application, locate the file src/main/resources/application.yml and change key server.port
! LOCAL on YOUR MACHINE END🔥 If you intend to use the Java or C# backend please jump to that section using Start JAVA Backend OR Start CSHARP Backend. You only need ONE backend at a time. 🔥
This sample Python backend provides a REST API service that is used with the Getting Started with Astra UI to show a simple example of how to connect to and query DataStax Astra databases. This application serves as the connection between the UI website and an underlying Astra database.
Objectives
- How to connect to Astra using the Secure Connect Bundle
- How to manage a Cassandra Session within a Python web application
Project Layout
- getting_started_with_astra.py - entrypoint for the backend, registers controller blueprints with Flask app
- schema.cql - database schema used by the application
- service - acts as the middle-man to take requests from the controllers and calls the corresponding dao methods. Note how this and session_manager.py are used to share a single DataStax Driver Session across API requests, this is a best practice.
- model - defines the Python objects that correspond to the database tables
- dao - methods for accessing the database, contains the DataStax Driver API calls
- controller - defines the API endpoints using Flask decorators
How this works This project is built in Python and uses Flask to expose a REST API backend for use with the Getting Started with Astra UI.
This application is the middle man that receives requests from the UI web page and serves data from the underlying DataStax Astra database.
! LOCAL on YOUR MACHINE✅ Prerequisites
- Python 3.6 or newer
- An Astra compactible python driver, instructions may be found here
- An Astra database with the CQL schema located in schema.cql already added.
- The username, password, keyspace name, and secure connect bundle downloaded from your Astra Database. For information on how to obtain these credentials please read the documentation found here.
This appliation uses the Flask framework. This sample can be run from the root directory.
✅ Installation procedure
- Setup environment
We advise that you set up a virtual python environment with Python 3 first (e.g with pyenv or venv). To setup a virtual environment with venv
python3 -m venv astra-venv
cd astra-venv
source bin/activate
The activation will prepend your command prompt with (astra-venv), indicating that you are operating in your virtual environment. All dependencies will be installed into this environment only.
- Install dependencies
pip install Flask flask-cors cassandra-driver
- Clone this repository
git clone https://github.com/DataStax-Academy/cassandra-workshop-series
✅ Starting procedure
Go to the directory that you just cloned this repo into
cd cassandra-workshop-series/week4-AppDev-api/getting-started-with-astra-python
python getting_started_with_astra.py
This will start the application running on http://127.0.0.1:5000
You should see the following output:
$ python getting_started_with_astra.py
* Serving Flask app "getting_started_with_astra" (lazy loading)
* Environment: production
WARNING: This is a development server. Do not use it in a production deployment.
Use a production WSGI server instead.
* Debug mode: off
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
- Access the API documentation from a browser
It's open, but there is nothing to see:
Not Found
The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.
This is OK and is expected. What's important is that our API is ready to go for the front end UI in the next section.
Note: If you want to change the listening port of the application, change it in the app.run() call in getting-started-with-astra.py, eg
app.run(port=5001)
! LOCAL on YOUR MACHINE END@@ ONLINE in GITPOD @@✅ Open gitpod : Gitpod is an IDE 100% online based on Eclipse Theia. To initialize your environment simply click on the button below (CTRL + Click to open in new tab)
Target url looks like https://<your_uid>.<your_region>.gitpod.io/#/workspace/cassandra-workshop-series. These URL's are dynamic and we cannot provide clickable links in advance. You will need to copy-paste <your_uid>.<your_region> as we will insert them in each URL during the exercises.
⚠️⚠️⚠️
By default Autosave is not enabled in Gitpod. Don't forget to save your modifications with CTRL+S
⚠️⚠️⚠️
👁️ Expected output
⚠️ By default Autosave is not enabled in Gitpod. Don't forget to save your modifications with CTRL+S
✅ Installation procedure
pip install Flask flask-cors cassandra-driver
✅ Starting the Flask application procedure
Move to folder week4-AppDev-api to get the exercises of the week and getting-started-with-astra-python to work with PYTHON.
cd week4-AppDev-api/getting-started-with-astra-python
python getting_started_with_astra.py
Click the "Open Browser" button and GitPod will generate a URL that you should be able to access to the UI with.
https://5000-<your_uid>.<your_region>.gitpod.io
It's open, but there is nothing to see:
Nothing to see here... 🦗
Port 5000 didn't respond
Please make sure this port is exposed and your app is running.
This is OK and is expected. What's important is that our API is ready to go for the front end UI in the next section.
You will see an Open Ports tab in the gitpod terminal window, where you can check on the status of the ports and access previews and browsers.
Note: If you want to change the listening port of the application, change it in the app.run() call in getting-started-with-astra.py, eg
app.run(port=5001)
@@ ONLINE in GITPOD END @@ 🔥 If you intend to use the Java or python backend please jump to that section using Start JAVA Backend OR Start PYTHON Backend. You only need ONE backend at a time. 🔥
Objectives
- How to connect to Astra via the Secure Connect Bundle
- How to manage a Cassandra Session within a .NET web application
Project Layout
This sample also contains several interesting files that worth noting specifically:
- Services/AstraService.cs - This file contains all the logic for connecting to the Astra database using the secure connect bundle.
- Startup.cs - This file contains the logic for adding a singleton for the Session object for reuse across our application.
See here for additional details on how the session object in Cassandra works and why it is best practice to only have a single Session object per application
-
schema.cql - The database schema required for the Astra keyspace
-
Controllers/InstrumentController.cs - If you would like to see how to implement paging in C# then this would be the place to look. Paging in Cassandra is different than what you are likely used to so it is beneficial to read this article describing how paging works with Cassandra.
How this Sample Works
This is am example .NET Core Web API backend for use with the Astra Getting Started UI which is found here.
This application serves as the connection between the UI website and an underlying Astra database.
It has Swagger installed so once it is running you can look at the Swagger UI here:
http://localhost:5000/swagger/index.html#/
Connecting to Astra with a Secure Connect Bundle
To see how to connect to Astra using the Secure Connect Bundle you can look at the ConnectToAstra() method in Services/AstraService.cs. In this method you will find the code which:
-
Creates a
Clusterinstance using the builder.var session = Cluster.Builder() -
Specifies the local file path to the Secure Connect Bundle ZIP file that has been downloaded from your Astra Database.
.WithCloudSecureConnectionBundle(secureConnectBundlePath) -
Set the username and password for your Astra Database
.WithCredentials(username, password) -
Set the default Consistency Level to
LOCAL_QUORUM.LOCAL_QUORUMis the only supported consistency level for Astra queries..WithQueryOptions(new QueryOptions().SetConsistencyLevel(ConsistencyLevel.LocalQuorum)) -
Build the
Clusterobject then connect to your Astra database specifying the keyspace to use..Build().Connect(keyspace);
Once you have completed all these steps you will now have a fully configured, connected, and ready to run CQL queries.
Managing Cassandra Session Within a .NET Web Application
Creation of Session objects within an application is an expensive process as they take awhile to initialize and become aware of the clusters topology. Due to this it is a best practice to create a Session object once per application and reuse it throughout the entire lifetime of that application. When building an ASP.NET Core application as shown this is easily supported through the use of singleton and .NET Core's built in Dependency Injection mechanisms.
For our Web API endpoints we created a singleton instance of our AstraService object inside the ConfigureServices() method in Startup.cs using the following code:
services.AddSingleton(typeof(Interfaces.IDataStaxService), typeof(Services.AstraService));
This code specifies that we are adding a singleton instance of AstraService for any dependency requiring an object instantiating the Interfaces.IDataStaxService interface.
To use this within our controllers, we need to specify a property on the constructor of the controller that requires the Interfaces.IDataStaxService interface as shown below.
public CredentialsController(IDataStaxService service) { Service = service; }
! LOCAL on YOUR MACHINEWith each call to the CredentialsController the AstraService singleton we created at startup will be passed to the constructor. This mechanism of dependency injection allows us a simple mechanism to use a single Session object throughout the entirety of the application lifecycle.
✅ Installation procedure
- .NET Core 2.1
- An Astra compatible C# driver, instructions may be found here to install this locally.
- An Astra database with the CQL schema located in schema.cql already added.
- The username, password, keyspace name, and secure connect bundle downloaded from your Astra Database. For information on how to obtain these credentials please read the documentation found here.
✅ Starting procedure
This application is a .NET 2.1 web application configured to serve it's web application via the Kestrel web server. This sample can be run from the root directory using:
dotnet run
This will startup the application running on http://localhost:5000
You will know that you are up and working when you get the following in your terminal window:
Hosting environment: Development
Content root path: /Users/dave.bechberger/Documents/projects/bechbd/getting-started-with-astra-csharp
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.
! LOCAL on YOUR MACHINE ENDN/A as of now, we did not setup gitpod to work with dotnet.
🔥 This provides the front end for the Astra Getting Started application. This is meant to be used with one of the following backends (java, python, csharp)🔥
Objectives
- Connect a web application to one of four backends to demonstrate an end to end full stack application
- Demonstrate how to properly page results for an Astra Service
! LOCAL on YOUR MACHINEPrerequisites
- node v8.1.0
Running
A .env file is required before you can build the application. This file needs to be added to the root of the project and called .env. This file contains all the environment variables required for the application. Currently there is only one required entry:
This value is where you put the relative address of the api.
- Java
BASE_ADDRESS=http://localhost:8080/api
- Python
BASE_ADDRESS=http://localhost:5000/api
- CSharp
BASE_ADDRESS=http://localhost:5001/api
In order to start this application you need to run:
npm install
and then
npm run start
You will know that this is correctly running when you see this message in your terminal:
ℹ ｢wds｣: Project is running at http://localhost:3000/
ℹ ｢wds｣: webpack output is served from /
ℹ ｢wds｣: Content not from webpack is served from /Users/dave.bechberger/Documents/projects/bechbd/getting-started-with-astra-ui
ℹ ｢wds｣: 404s will fallback to /index.html
If you would like to build this for deployment then this can be accomplished using:
npm run build
! LOCAL on YOUR MACHINE END@@ ONLINE in GITPOD @@Locate the folder and install the dependencies:
cd week4-AppDev-api/getting-started-with-astra-ui
npm install
A .env file is required before you can build the application. This file needs to be added to the root of the project and called .env. This file contains all the environment variables required for the application. Currently there is only one required entry:
echo 'BASE_ADDRESS=https://<your_port>-<your_id>.<your_region>.gitpod.io/api' > .env
cat .env
- <your_port>: Will be
8080is you pick the Java Backend,5000if you pick the python backend and5001if you pick the CSharp backend.
npm run start
Your should be able to access
https://3000-<your_uid>.<>your_region.gitpod.io/
@@ ONLINE in GITPOD END@@ THE END.