• GoLang

1. Overview¶

Astra provides multiple services such as; Database and Streaming, with multiple Apis and interfaces. There are different frameworks and tools to connect to Astra depending on the Api interface you choose.

Pick the interface below to get relevant instructions. In most cases, you will download a working sample. There are standalone examples designed to be as simple as possible.

If you have issues or requests about these code samples, please open a ticket under Awesome-Astra.

📦 Prerequisites [ASTRA]

You should have an Astra account
You should Have an Astra Token with "Database Administrator" permissions
You should Install the Astra CLI

You will need to have a recent (1.17+) version of Go. Visit the official download page, and select the appropriate version for your machine architecture. To verify that Go is installed, run the following command:

go version

You want to have a go version of at least 1.17.

📦 Prerequisites [Development Environment]

To get started you need to Install the Astra CLI. Create a directory you want to use and change into that directory.

Using the token you created with the "Database Administrator" permission, use the CLI to setup your environment.

astra setup

Create a database and keyspace to work with.

astra db create workshops -k library --if-not-exist

2. Interfaces List¶

3. CQL¶

3.1 The gocql-astra driver¶

ℹ️ Overview

These instructions are aimed at helping people connect to Astra DB programmatically using the custom Astra Gocql driver.

Basic driver instructions Basic instructions can be found at the home page for gocql-astra. You can use these instructions, or scroll down to find some ready-made code for you to use.

README from gocql-astra

This provides a custom gocql.HostDialer that can be used to allow gocql to connect to DataStax Astra. The goal is to provide native support for gocql on Astra.

This library relies on the following features of gocql:

The ability to customize connection features via the HostDialer interface
Querying system.peers if system.peers_v2 should be used but isn't available

You must use a version of gocql which supports both of these features. Both features have been merged into master as of version 1.2.1 so any release >= 1.2.1 should work.

Issues¶

Need to verify that topology/status events correctly update the driver when using Astra.
This seems to work correctly and was tested by removing Astra coordinators
There is a bit of weirdness around contact points. I'm just using a place holder "0.0.0.0" (some valid IP address) then the HostDialer provides a host ID from the metadata service when the host ID in the HostInfo is empty.

How to use gocql-astra

Using an Astra bundle:

cluster, err := gocqlastra.NewClusterFromBundle("/path/to/your/bundle.zip", 
    "<username>", "<password>", 10 * time.Second)

if err != nil {
    panic("unable to load the bundle")
}

session, err := gocql.NewSession(*cluster)

// ...

Using an Astra token:

cluster, err = gocqlastra.NewClusterFromURL(gocqlastra.AstraAPIURL, 
    "<astra-database-id>", "<astra-token>", 10 * time.Second)

if err != nil {
panic("unable to load the bundle")
}

session, err := gocql.NewSession(*cluster)

// ...

Environment variable version

To use this library with environment variables, you can follow these steps.

🖥️ Sample Code

The best way to use this sample is to clone it from the repository.

Follow the prerequisites above.

Clone the repository and change into the 'gocql-astra' directory in that repository.

git clone https://github.com/awesome-astra/go-sample-code
cd go-sample-code/gocql-astra/envvars

Create .env with astra CLI

astra db create-dotenv workshops -k gotest

Build the environment variable example.

go build envvars.go

Run the code in your environment.

./envvars

Envvars example
    package main

    import (
        "fmt"
        "log"
        "os"
        "time"

        gocqlastra "github.com/datastax/gocql-astra"
        "github.com/gocql/gocql"
    )

    func main() {

        var err error

        var cluster *gocql.ClusterConfig

        if len(os.Getenv("ASTRA_DB_APPLICATION_TOKEN")) > 0 {
            if len(os.Getenv("ASTRA_DB_ID")) == 0 {
                panic("database ID is required when using a token")
            }
        }

        fmt.Println("Creating the cluster now")
        fmt.Println(os.Getenv("ASTRA_DB_ID"))
        fmt.Print(os.Getenv("ASTRA_DB_APPLICATION_TOKEN"))
        fmt.Println(os.Getenv("ASTRA_DB_REGION"))
        fmt.Println(cluster)

        cluster, err = gocqlastra.NewClusterFromURL("https://api.astra.datastax.com", os.Getenv("ASTRA_DB_ID"), os.Getenv("ASTRA_DB_APPLICATION_TOKEN"), 10*time.Second)
        fmt.Println(cluster)

        if err != nil {
            fmt.Errorf("unable to load cluster %s from astra: %v", os.Getenv("ASTRA_DB_APPLICATION_TOKEN"), err)
        }

        start := time.Now()
        session, err := gocql.NewSession(*cluster)
        elapsed := time.Now().Sub(start)

        if err != nil {
            log.Fatalf("unable to connect session: %v", err)
        }

        fmt.Println("Making the query now")

        iter := session.Query("SELECT release_version FROM system.local").Iter()

        var version string

        for iter.Scan(&version) {
            fmt.Println(version)
        }

        if err = iter.Close(); err != nil {
            log.Printf("error running query: %v", err)
        }

        fmt.Printf("Connection process took %s\n", elapsed)

    }

Sample code details

If you want to use this sample without cloning the repository, you will need to have the following:

github.com/datastax/astra-client-go/v2 v2.2.9
github.com/datastax/cql-proxy v0.1.3

package main

import (
    "fmt"
    "log"
    "os"
    "time"

    gocqlastra "github.com/datastax/gocql-astra"
    "github.com/gocql/gocql"
    "github.com/joho/godotenv"
)

func main() {

    var err error

    err = godotenv.Load()

    var cluster *gocql.ClusterConfig
    if len(os.Getenv("ASTRA_DB_SECURE_BUNDLE_PATH")) > 0 {
        cluster, err = gocqlastra.NewClusterFromBundle(os.Getenv("ASTRA_DB_SECURE_BUNDLE_PATH"), "token", os.Getenv("ASTRA_DB_APPLICATION_TOKEN"), 10*time.Second)
        if err != nil {
            err = fmt.Errorf("unable to open bundle %s from file: %v", os.Getenv("ASTRA_DB_SECURE_BUNDLE_PATH"), err)
            panic(err)
        }
    } else if len(os.Getenv("ASTRA_DB_APPLICATION_TOKEN")) > 0 {
        if len(os.Getenv("ASTRA_DB_ID")) == 0 {
            panic("database ID is required when using a token")
        }
        cluster, err = gocqlastra.NewClusterFromURL("https://api.astra.datastax.com", os.Getenv("ASTRA_DB_ID"), os.Getenv("ASTRA_DB_APPLICATION_TOKEN"), 10*time.Second)
        fmt.Println(cluster)
        if err != nil {
            fmt.Errorf("unable to load cluster %s from astra: %v", os.Getenv("ASTRA_DB_APPLICATION_TOKEN"), err)
        }
    } else {
        fmt.Errorf("must provide either bundle path or token")
    }

    start := time.Now()
    session, err := gocql.NewSession(*cluster)
    elapsed := time.Now().Sub(start)
    if err != nil {
        log.Fatalf("unable to connect session: %v", err)
    }

    fmt.Println("Making the query now")

    iter := session.Query("SELECT release_version FROM system.local").Iter()

    var version string
    for iter.Scan(&version) {
        fmt.Println(version)
    }

    if err = iter.Close(); err != nil {
        log.Printf("error running query: %v", err)
    }

    fmt.Printf("Connection process took %s\n", elapsed)
}

To get this to work, you will need to pull the dependencies:

go mod init gocql
go mod tidy
go build envvars.go
./envvars

3.2 Other Astra CQL Interfaces¶

cql-proxy This proxy sidecar is not Go-specific, but it works with the existing Go drivers to provide an interface into Astra.

4. The Stargate API Signing Library¶

4.1 Using the Stargate API Signing Library¶

ℹ️ Overview

These instructions are aimed at helping people connect to Astra DB programmatically using Stargate's API interface

🖥️ Sample Code

To use the signing library, you simply include it in your code and then create a client for making calls.

package main

import (
    "fmt"
    "log"
    "os"
    "time"

    gocqlastra "github.com/datastax/gocql-astra"
    "github.com/gocql/gocql"
)

func main() {

    var err error

    var cluster *gocql.ClusterConfig

    if len(os.Getenv("ASTRA_DB_APPLICATION_TOKEN")) > 0 {
        if len(os.Getenv("ASTRA_DB_ID")) == 0 {
            panic("database ID is required when using a token")
        }
    }

    fmt.Println("Creating the cluster now")
    fmt.Println(os.Getenv("ASTRA_DB_ID"))
    fmt.Print(os.Getenv("ASTRA_DB_APPLICATION_TOKEN"))
    fmt.Println(os.Getenv("ASTRA_DB_REGION"))
    fmt.Println(cluster)

    cluster, err = gocqlastra.NewClusterFromURL("https://api.astra.datastax.com", os.Getenv("ASTRA_DB_ID"), os.Getenv("ASTRA_DB_APPLICATION_TOKEN"), 10*time.Second)
    fmt.Println(cluster)

    if err != nil {
        fmt.Errorf("unable to load cluster %s from astra: %v", os.Getenv("ASTRA_DB_APPLICATION_TOKEN"), err)
    }

    start := time.Now()
    session, err := gocql.NewSession(*cluster)
    elapsed := time.Now().Sub(start)

    if err != nil {
        log.Fatalf("unable to connect session: %v", err)
    }

    fmt.Println("Making the query now")

    iter := session.Query("SELECT release_version FROM system.local").Iter()

    var version string

    for iter.Scan(&version) {
        fmt.Println(version)
    }

    if err = iter.Close(); err != nil {
        log.Printf("error running query: %v", err)
    }

    fmt.Printf("Connection process took %s\n", elapsed)

}

5. Stargate REST API¶

While the basic code is shown above, you can interact with a more extensive REST example by following these instructions.

Follow the prerequisites above.

Clone the repository and change into the 'gocql-astra' directory in that repository.

git clone https://github.com/awesome-astra/go-sample-code
cd go-sample-code/gocql-astra/astra_stargate_rest

Create .env with astra CLI

astra db create-dotenv workshops -k gotest

Run the code in your environment.

go build astra_stargate_rest_example.go
./astra_stargate_rest_example

6. Stargate GraphQL API¶

While the basic code is shown above, you can interact with a more extensive REST example by following these instructions.

Follow the prerequisites above.

Clone the repository into your directory, then change into the astra_stargate_rest directory.

git clone https://github.com/awesome-astra/go-sample-code
cd astra_stargate_graphql

Create .env with astra CLI

astra db create-dotenv workshops -k library

Run the code in your environment.

go build astra_stargate_graphql.go
./astra_stargate_graphql

7. Stargate Document API¶

While the basic code is shown above, you can interact with a more extensive REST example by following these instructions.

📦 Prerequisites [Development Environment]

To get started you need to Install the Astra CLI. Create a directory you want to use and change into that directory.

Follow the prerequisites above.

Clone the repository into your directory, then change into the astra_stargate_rest directory.

git clone https://github.com/awesome-astra/go-sample-code
cd astra_stargate_document

Create .env with astra CLI

astra db create-dotenv workshops -k library

Run the code in your environment.

go build astra_stargate_document.go
./astra_stargate_document

8. CQL API GRPC¶

8.1 The Gocql GRPC Cassandra Astra Driver¶

ℹ️ Overview

These instructions are aimed at helping people connect to Astra DB programmatically using the Astra specific Golang driver

Follow the prerequisites above.

🖥️ Sample Code

Clone the repository into your directory, then change into the astra-gprc directory.

Create .env with astra CLI

astra db create-dotenv workshops -k library

git clone https://github.com/awesome-astra/go-sample-code
cd astra-grpc

Run the code in your environment.

go build AstraGRPCQuickStart.go
./AstraGRPCQuickStart

Last update: 2023-09-13