gocqlastra

README

gocql for Astra

⚠️ Version Notice

This is version 1.x of gocql-astra. If you are looking to use gocql 2.x, please use the v2 module:

go get github.com/datastax/gocql-astra/v2

Documentation: https://pkg.go.dev/github.com/datastax/gocql-astra/v2

The v2 README documentation contains an upgrade guide to help you migrate from v1.x to v2.x.

---

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 it:

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)

// ...

Also, look at the example for more information.

Running the example:

cd example
go build

# Using a bundle
./example --astra-bundle /path/to/bundle.zip --username <username> --password <password>

# Using a token
./example --astra-token <astra-token> --astra-database-id <astra-database-id> \
  [--astra-api-url <astra-api-url>]

Documentation

Overview

Package gocqlastra provides a custom gocql.HostDialer that enables gocql to connect to DataStax Astra.

Version Notice

This is version 1.x of gocql-astra. If you are looking to use gocql 2.x, please use the v2 module:

go get github.com/datastax/gocql-astra/v2

Documentation: https://pkg.go.dev/github.com/datastax/gocql-astra/v2

The v2 documentation contains an upgrade guide to help you migrate from v1.x to v2.x.

Getting Started

For quickstart tips, usage examples, and detailed information, please see the README above.

Index

• Constants
• func NewCluster(dialer gocql.HostDialer, username, password string) *gocql.ClusterConfig
• func NewClusterFromBundle(path, username, password string, timeout time.Duration) (*gocql.ClusterConfig, error)
• func NewClusterFromURL(url, databaseID, token string, timeout time.Duration) (*gocql.ClusterConfig, error)
• func NewDialer(b *astra.Bundle, timeout time.Duration) (gocql.HostDialer, error)
• func NewDialerFromBundle(path string, timeout time.Duration) (gocql.HostDialer, error)
• func NewDialerFromURL(url, databaseID, token string, timeout time.Duration) (gocql.HostDialer, error)

Constants

const AstraAPIURL = "https://api.astra.datastax.com"

Functions

func NewCluster

func NewCluster(dialer gocql.HostDialer, username, password string) *gocql.ClusterConfig

func NewClusterFromBundle

func NewClusterFromBundle(path, username, password string, timeout time.Duration) (*gocql.ClusterConfig, error)

func NewClusterFromURL

func NewClusterFromURL(url, databaseID, token string, timeout time.Duration) (*gocql.ClusterConfig, error)

func NewDialer

func NewDialer(b *astra.Bundle, timeout time.Duration) (gocql.HostDialer, error)

func NewDialerFromBundle

func NewDialerFromBundle(path string, timeout time.Duration) (gocql.HostDialer, error)

func NewDialerFromURL

func NewDialerFromURL(url, databaseID, token string, timeout time.Duration) (gocql.HostDialer, error)