Astra DB Go Client

The official Go client for Astra DB, DataStax's cloud-native database. It provides access to both the Astra DB Data API (collections and tables) and the Astra DevOps API (database administration).

Note: This client is in active development. Until it reaches a stable v1.0, it will contain breaking changes.

Requirements

• Go 1.24 or higher. Download it here.
• An Astra DB account with an Application Token. Don't have an account? Create one.

Quickstart

In a folder with a Go module, use go get to add the client to your project:

go get github.com/datastax/astra-db-go

Usage

You will need a token to test with. From the Astra Console, go to Settings > Tokens. Select a role, and click "Generate token". In these contrived examples, the token is represented as a string. Never check the token in to source control or share it. Use a secret manager to expose the token to your client.

Check out ./examples for runnable examples and instructions on how to run them.

Creating a Client

Import the package and create a client with your Application Token:

import (
    astradb "github.com/datastax/astra-db-go"
    "github.com/datastax/astra-db-go/options"
)

client := astradb.NewClient(
    options.WithToken("AstraCS:..."),
)

Get a handle to a database using its API endpoint:

db := client.Database("https://<ASTRA_DB_ID>-<REGION>.apps.astra.datastax.com")

Collections (Document API)

Collections store schema-flexible JSON documents, similar to MongoDB.

Creating a Collection

ctx := context.Background()

coll, err := db.CreateCollection(ctx, "my_collection")
if err != nil {
    log.Fatal(err)
}

Inserting Documents

type Book struct {
    ID     string `json:"_id"`
    Title  string `json:"title"`
    Author string `json:"author"`
    Year   int    `json:"year"`
}

// Insert a single document
_, err = coll.InsertOne(ctx, Book{
    ID:     "1",
    Title:  "The Go Programming Language",
    Author: "Alan Donovan",
    Year:   2015,
})

// Insert multiple documents
_, err = coll.InsertMany(ctx, []Book{
    {ID: "2", Title: "Go in Action", Author: "William Kennedy", Year: 2015},
    {ID: "3", Title: "Concurrency in Go", Author: "Katherine Cox-Buday", Year: 2017},
})

Finding Documents

Use FindOne to retrieve a single document:

import "github.com/datastax/astra-db-go/filter"

var result Book
err = coll.FindOne(ctx, filter.Eq("_id", "1")).Decode(&result)
if err != nil {
    log.Fatal(err)
}

Use Find to retrieve multiple documents and iterate with a cursor:

cursor := coll.Find(ctx, filter.F{"author": "Alan Donovan"})
defer cursor.Close(ctx)

var books []Book
if err = cursor.All(ctx, &books); err != nil {
    log.Fatal(err)
}

Or iterate document by document:

cursor := coll.Find(ctx, filter.F{"year": filter.F{"$gte": 2016}})
defer cursor.Close(ctx)

for cursor.Next(ctx) {
    var book Book
    if err := cursor.Decode(&book); err != nil {
        log.Fatal(err)
    }
    fmt.Println(book.Title)
}
if err := cursor.Err(); err != nil {
    log.Fatal(err)
}

Counting Documents

count, err := coll.CountDocuments(ctx, filter.F{}, 1000)

Filtering

The filter package provides a composable set of operators for querying collections and tables.

import "github.com/datastax/astra-db-go/filter"

// Equality
filter.Eq("status", "active")

// Comparison
filter.Lt("year", 2020)
filter.Gte("rating", 4.5)

// Membership
filter.In("genre", "fiction", "mystery", "sci-fi")

// Logical composition
filter.And(
    filter.Eq("status", "active"),
    filter.Gte("year", 2000),
)

filter.Or(
    filter.Eq("genre", "fiction"),
    filter.Eq("genre", "mystery"),
)

// Raw map syntax
filter.F{"title": "The Go Programming Language"}

Tables (Table API)

Tables provide a structured, schema-enforced data model backed by Cassandra's CQL engine.

Defining and Creating a Table

import (
    "github.com/datastax/astra-db-go/table"
)

definition := table.Definition{
    Columns: map[string]table.Column{
        "id":     table.Text(),
        "title":  table.Text(),
        "author": table.Text(),
        "year":   table.Int(),
    },
    PrimaryKey: table.PrimaryKey{
        PartitionBy:   []string{"id"},
        PartitionSort: map[string]int{"year": -1},
    },
}

tbl, err := db.CreateTable(ctx, "books", definition, nil)
if err != nil {
    log.Fatal(err)
}

Inserting Rows

type BookRow struct {
    ID     string `json:"id"`
    Title  string `json:"title"`
    Author string `json:"author"`
    Year   int    `json:"year"`
}

_, err = tbl.InsertOne(ctx, BookRow{
    ID: "1", Title: "The Go Programming Language", Author: "Alan Donovan", Year: 2015,
})

Finding Rows

var row BookRow
err = tbl.FindOne(ctx, filter.Eq("id", "1")).Decode(&row)

cursor := tbl.Find(ctx, filter.F{"author": "Alan Donovan"})
defer cursor.Close(ctx)

var rows []BookRow
if err = cursor.All(ctx, &rows); err != nil {
    log.Fatal(err)
}

Creating Indexes

// Standard index on a column
err = tbl.CreateIndex(ctx, "author_idx", "author")

// Vector index for similarity search
err = tbl.CreateVectorIndex(ctx, "embedding_idx", "embedding")

// List existing indexes
indexes, err := tbl.ListIndexes(ctx)

Admin Operations

Astra Admin

admin, err := client.Admin()
if err != nil {
    log.Fatal(err)
}

// List all databases
databases, err := admin.ListDatabases(ctx)

// Get a specific database
db, err := admin.GetDatabase(ctx, "my-database-id")

// Find available regions
regions, err := admin.FindAvailableRegions(ctx)

Database Admin

dbAdmin := admin.DbAdmin("my-database-id")

// Manage keyspaces
keyspaces, err := dbAdmin.ListKeyspaces(ctx)
err = dbAdmin.CreateKeyspace(ctx, "my_keyspace")
err = dbAdmin.DropKeyspace(ctx, "old_keyspace")

// Database info and lifecycle
info, err := dbAdmin.Info(ctx)
err = dbAdmin.Drop(ctx)

You can also get a DatabaseAdmin from an existing Db handle:

db := client.Database("https://...")
dbAdmin, err := db.DatabaseAdmin()

Options and Configuration

Options can be specified at the client, database, collection, or table level. More specific options override broader ones.

import "github.com/datastax/astra-db-go/options"

// Client-level defaults
client := astradb.NewClient(
    options.WithToken("AstraCS:..."),
    options.WithTimeout(30 * time.Second),
    options.WithKeyspace("my_keyspace"),
)

// Override at the database level
db := client.Database(endpoint,
    options.WithKeyspace("another_keyspace"),
)

// Custom HTTP client
httpClient := &http.Client{Timeout: 60 * time.Second}
client := astradb.NewClient(
    options.WithToken("AstraCS:..."),
    options.WithHTTPClient(httpClient),
)

// Warning handler
client := astradb.NewClient(
    options.WithToken("AstraCS:..."),
    options.WithWarningHandler(func(warnings results.Warnings) {
        for _, w := range warnings {
            log.Printf("warning: %s", w.Message)
        }
    }),
)

Development and Testing

Unit Tests

Run the standard Go test suite:

go test ./...

If your changes need to change generated code:

go generate ./...

Integration Tests

Integration tests run against a live Astra DB instance. See the Integration Tests README for full setup instructions.

Other Astra DB Clients

• Python
• TypeScript
• .NET
• Java