Skip to content

Latest commit

 

History

History
89 lines (59 loc) · 3.9 KB

database.md

File metadata and controls

89 lines (59 loc) · 3.9 KB
Raw

DB Setup

We show how to create an Astra DB instance and set the connection details and secrets that all code examples can then use.

Astra DB is a serverless DBaaS by DataStax, built on Apache Cassandra, that offers a free tier with generous traffic and storage limits. Using Astra DB frees you from the hassle of running your own cluster while retaining all the advantages, such as the excellent data distribution and very high availability that make Cassandra a world-class NoSQL database.

!!! note "Self-managed Cassandra alternative"

Nothing prevents you from adapting the examples to any Cassandra cluster:
in most cases all you have to do is to build the database `Session` object
differently, and that's it. Inspect the code to find out: generally it's
just a couple of lines to change.

Create your Astra DB instance

Go to astra.datastax.com, sign up and create an Astra DB database in the Free Tier -- in the following we assume you called it cassio_db.

You will be asked for a "Keyspace name" when creating the database: you can call it something like cassio_tutorials for example.

Detailed explanations can be found at this page.

Get Token and Secure Connect Bundle, create .env file

In order to establish a connection to your Cloud Database, you need a secret string ("Token") and a "Secure Connect Bundle" zipfile, containing certificates/proxy/routing information.

The easiest way to do so is to first generate a database token with role "Database Administrator", then use the Astra CLI to automate the remaining part:

Now you can configure the CLI by running

astra setup

and providing the token (the string starting with AstraCS:...). Then, in the root directory of this repo, adjusting names if needed, launch

astra db create-dotenv cassio_db -k cassio_tutorials

This will download the bundle zipfile and create a .env file with all connection parameters you'll need later.

"Alternatives to Astra CLI"

If you prefer to proceed manually, you can download the Secure Connect Bundle somewhere on your machine, then create the .env file yourself, as long as it defines the same environment variables you see in the provided .env.template file (essentially, the full path to bundle file, the keyspace name and your database secret token string).

Import Schema and Sample data

Some of the provided code examples require pre-existing data on your database.

To populate the newly-created keyspace with the required data:

  • download the newest (vector-search-compatible) cqlsh utility from this link;
  • extract the archive to a location of your liking, e.g. /home/user/myCqlsh;
  • source the environment file you just prepared with . .env (make sure you are in this repo's root directory);
  • launch the script that populates the database with:
/home/user/myCqlsh/cqlsh-astra/bin/cqlsh \
    -b "$ASTRA_DB_SECURE_BUNDLE_PATH" \
    -u token \
    -p "$ASTRA_DB_APPLICATION_TOKEN" \
    -k "$ASTRA_DB_KEYSPACE" \
    -f setup/create_schema.cql

!!! note

If you target your own Cassandra cluster, make sure you `USE` your
keyspace before running the script above.

Your database is ready

The next step is to configure the necessary API Keys.