gocqlastra

README

gocql for Astra (v2)

This is version 2.x of gocql-astra, compatible with the Apache Cassandra GoCQL Driver v2.

📌 Looking for version 1.x? See Version 1.x
🔄 Upgrading from v1? See Migration Guide

---

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. Use version >= 2.1.1 of the Apache Cassandra GoCQL Driver (github.com/apache/cassandra-gocql-driver/v2).

Issues

• There is a bit of weirdness around contact points. The driver is using a few place holders "0.0.0.1,0.0.0.2,0.0.0.3" (some valid IP address) then the HostDialer provides a host ID from the metadata service when the host ID in the HostInfo is empty. Using multiple placeholder contact points instead of a single one enables the driver to retry if the initial connection fails.

How to use it:

Using an Astra bundle:

import (
	gocqlastra "github.com/datastax/gocql-astra/v2"
	gocql "github.com/apache/cassandra-gocql-driver/v2"
)

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:

import (
	gocqlastra "github.com/datastax/gocql-astra/v2"
	gocql "github.com/apache/cassandra-gocql-driver/v2"
)

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>]

---

Version 1.x

If you need version 1.x (compatible with github.com/gocql/gocql 1.x), see: https://pkg.go.dev/github.com/datastax/gocql-astra

Note: GoCQL 1.x (github.com/gocql/gocql) is no longer maintained. We recommend migrating to version 2.x.

Migration from v1 to v2

Version 2.0.0 of gocql-astra introduces breaking changes due to the migration of the underlying gocql driver to the Apache Software Foundation. The gocql project was donated to the ASF and, as part of version 2, changed its module path from github.com/gocql/gocql to github.com/apache/cassandra-gocql-driver/v2.

If you're upgrading from v1, follow these steps:

1. Update your go.mod

Change your module dependency from:

require github.com/datastax/gocql-astra v1.x.x

To:

require github.com/datastax/gocql-astra/v2 v2.0.0

2. Update your imports

Change your import statements from:

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

To:

import (
    gocqlastra "github.com/datastax/gocql-astra/v2"
    gocql "github.com/apache/cassandra-gocql-driver/v2"
)

3. Update your dependencies

Run the following commands to update your dependencies:

go get github.com/datastax/gocql-astra/v2@latest
go get github.com/apache/cassandra-gocql-driver/v2@latest
go mod tidy

4. Review API changes

The core API of gocql-astra remains the same, but you should review any code that directly uses the Apache Cassandra GoCQL Driver API, as it has undergone changes in v2. Refer to the Apache Cassandra GoCQL Driver Upgrade Guide for details on driver-specific changes.

Documentation

Overview

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

This is version 2.x of gocql-astra, compatible with the Apache Cassandra GoCQL Driver v2 (github.com/apache/cassandra-gocql-driver/v2).

Version 1.x

If you need version 1.x (compatible with github.com/gocql/gocql 1.x), see: https://pkg.go.dev/github.com/datastax/gocql-astra

Note: GoCQL 1.x (github.com/gocql/gocql) is no longer maintained. We recommend migrating to version 2.x.

Migration Guide

For detailed instructions on migrating from v1.x to v2.x, including import changes and API updates, please see the "Migration from v1 to v2" section in the README above.

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 NewClusterFromBundleWithLogger(path, username, password string, timeout time.Duration, ...) (*gocql.ClusterConfig, error)
• func NewClusterFromURL(url, databaseID, token string, timeout time.Duration) (*gocql.ClusterConfig, error)
• func NewClusterFromURLWithLogger(url, databaseID, token string, timeout time.Duration, ...) (*gocql.ClusterConfig, error)
• func NewClusterWithLogger(dialer gocql.HostDialer, username, password string, ...) *gocql.ClusterConfig
• func NewDialer(b *astra.Bundle, timeout time.Duration) (gocql.HostDialer, error)
• func NewDialerFromBundle(path string, timeout time.Duration) (gocql.HostDialer, error)
• func NewDialerFromBundleWithLogger(path string, timeout time.Duration, logger gocql.StructuredLogger) (gocql.HostDialer, error)
• func NewDialerFromURL(url, databaseID, token string, timeout time.Duration) (gocql.HostDialer, error)
• func NewDialerFromURLWithLogger(url, databaseID, token string, timeout time.Duration, ...) (gocql.HostDialer, error)
• func NewDialerWithLogger(b *astra.Bundle, timeout time.Duration, logger gocql.StructuredLogger) (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 NewClusterFromBundleWithLogger

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

func NewClusterFromURL

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

func NewClusterFromURLWithLogger

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

func NewClusterWithLogger

func NewClusterWithLogger(dialer gocql.HostDialer, username, password string, logger gocql.StructuredLogger) *gocql.ClusterConfig

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 NewDialerFromBundleWithLogger

func NewDialerFromBundleWithLogger(path string, timeout time.Duration, logger gocql.StructuredLogger) (gocql.HostDialer, error)

func NewDialerFromURL

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

func NewDialerFromURLWithLogger

func NewDialerFromURLWithLogger(url, databaseID, token string, timeout time.Duration, logger gocql.StructuredLogger) (gocql.HostDialer, error)

func NewDialerWithLogger

func NewDialerWithLogger(b *astra.Bundle, timeout time.Duration, logger gocql.StructuredLogger) (gocql.HostDialer, error)