go-spanner-cassandra

README

Spanner Cassandra Go Client

[!NOTE] Spanner Cassandra Go Client is currently in public preview.

Introduction

The Spanner Cassandra Go Client is a tool designed to bridge applications written for the Apache Cassandra® database with Google Spanner. With Spanner's native support for the Cassandra v4 wire protocol, this client allows Go applications using the gocql driver, or even non-Go applications and tools like cqlsh, to connect seamlessly to a Spanner database.

This client acts as a local tcp proxy, intercepting the raw Cassandra protocol bytes sent by a driver or client tool. It then wraps these bytes along with necessary metadata into gRPC messages for communication with Spanner. Responses from Spanner are translated back into the Cassandra wire format and sent back to the originating driver or tool.

Table of Contents

• When to use spanner-cassandra?
• Prerequisites
• Spanner Instructions
• Getting started
  • In-Process Dependency
  • Sidecar Proxy
• Options
• Supported Cassandra Versions
• Unsupported Features
• License

When to Use Spanner Cassandra Go Client?

This client is useful but not limited to the following scenarios:

• Leveraging Spanner with Minimal Refactoring: You want to use Spanner as the backend for your Go application but prefer to keep using the familiar gocql API for data access.
• Using Non-Go Cassandra Tools: You want to connect to Spanner using standard Cassandra tools like cqlsh or applications written in other languages that use Cassandra drivers.

Prerequisites

You will need a Google Cloud Platform Console project with the Spanner API enabled. You will need to enable billing to use Google Spanner. Follow these instructions to get your project set up.

Ensure that you run

gcloud auth application-default login

to set up your local development environment with authentication credentials.

Set the GCLOUD_PROJECT environment variable to your Google Cloud project ID:

gcloud config set project [MY_PROJECT_NAME]

Spanner Instructions

• Database and all the tables should be created in advance before executing the queries against Spanner Cassandra Go Client.
• To migrate existing Cassandra schema to corresponding Spanner schema, refer to spanner-cassandra-schema-tool to automate this process.

Getting Started

You can use spanner-cassandra in two main ways: as an in-process dependency within your Go application, or as a standalone sidecar proxy for other applications and tools.

• In-Process Dependency: Choose this method if you have a Go application already using gocql and want the spanner-cassandra client to run within the same process, providing a seamless switch to Spanner with minimal code modifications.
• Sidecar Proxy: Choose this method if your application is not written in Go, or if you want to use external Cassandra tools (like cqlsh) without modifying the application's code. The spanner-cassandra client runs as a separate process, intercepting network traffic.

In-Process Dependency (Recommended)

For Go applications already using the gocql library, integrating the Spanner Cassandra Go Client requires only minor changes to the cluster initialization.

Steps:

• Import the spanner package in your go applcation:

  import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"
  

• Modify your cluster creation code. Instead of using gocql.NewCluster, use spanner.NewCluster and provide the Spanner database URI:

  func main() {
    opts := &spanner.Options{
        // Required: Specify the Spanner database URI
        DatabaseUri: "projects/your_gcp_project/instances/your_spanner_instance/databases/your_spanner_database",
    }
    // Optional: Configure other gocql cluster settings as needed
    cluster := spanner.NewCluster(opts)
    cluster.Timeout = 5 * time.Second
    // Your Spanner database schema is mapped to a keyspace
    cluster.Keyspace = "your_spanner_database"
    // Important to close the resources
    defer spanner.CloseCluster(cluster)
    // Rest of your business logic
    session, err := cluster.CreateSession()
    if err != nil {
      fmt.Printf("Failed to create session: %v\n", err)
      return
    }
    defer session.Close()
    // Rest of your business logic such as session.Query(SELECT * FROM ...)
  }
  

• Run your Go application as usual. The client will now route traffic to your Spanner database.

Sidecar Proxy

For non-Go applications or tools like cqlsh, you can run the Spanner Cassandra Go Client as a standalone proxy.

Method 1: Run locally with go run

• Clone the repository:

  git clone https://github.com/googleapis/go-spanner-cassandra.git
  cd go-spanner-cassandra
  

• Run the cassandra_launcher.go with the required -db flag:

  go run cassandra_launcher.go -db "projects/your_gcp_project/instances/your_spanner_instance/databases/your_spanner_database" -tcp ":9042" -grpc-channels 4
  

  • Replace the value of -db with your Spanner database URI.
  • You can omit the -tcp to use the default :9042 and omit -grpc-channels to use the default 4.

  See Options for an explanation of all further options.

Method 2: Run with pre-built docker image

• Pull from official registry repo:

  docker pull gcr.io/cloud-spanner-adapter/cassandra-adapter
  

• Start the Spanner Cassandra Adapter Docker container:

  export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
  docker run -d -p 9042:9042 \
  -e GOOGLE_APPLICATION_CREDENTIALS \
  -v ${GOOGLE_APPLICATION_CREDENTIALS}:${GOOGLE_APPLICATION_CREDENTIALS}:ro \
  gcr.io/cloud-spanner-adapter/cassandra-adapter \
  -db projects/your-project/instances/your-instance/databases/your-database
  

  See Options for an explanation of all further options.

Options

The following list contains the most frequently used startup options for Spanner Cassandra Client.

-db <DatabaseUri>
  * The Spanner database URI (required). This specifies the Spanner database that the client will connect to.
  * Example: projects/your-project/instances/your-instance/databases/your-database

-tcp <TCPEndpoint>
  * The client proxy listener address. This defines the TCP endpoint where the client will listen for incoming Cassandra client connections.
  * Default:
    * When running in-process inside Golang applicaion: localhost:9042
    * When running as a sidecar proxy: :9042 to bind all network interfaces, suitable for Docker forwarding.

-grpc-channels <NumGrpcChannels>
  * The number of gRPC channels to use when connecting to Spanner.
  * Default: 4

-log <LogLevel>
  * Log level used by the global zap logger.
  * Default: info

-max_commit_delay <MaxCommitDelay>
  * The maximum commit delay in milliseconds. The valid range is 0-500.
  * If you don't set a commit delay time, Spanner might set a small delay for you if it thinks that will amortize the cost of your writes.
  * You can disable commit delays for applications that are highly latency sensitive by setting the maximum commit delay time to 0.
  * Default: 0 (disabled)

Supported Cassandra Versions

By default, Spanner Cassandra client communicates using the Cassandra 4.0 protocol and is fully tested and verified with Cassandra 4.x, providing complete support. For Cassandra 3.x, the client is designed to be compatible and should work seamlessly, though we recommend thorough testing within your specific setup.

Unsupported Features

• named parameters
• pagination
• ScanCAS

License

Apache License 2.0