Spanner Cassandra Java Client

Current Released Version

Version 1.1.0

Introduction

The Spanner Cassandra Java 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 Java applications or even non-Java applications and tools such as cqlsh, to connect seamlessly to a Cloud 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 java-spanner-cassandra?
• Prerequisites
• Spanner Instructions
• Getting started
  • In-Process Dependency
  • Sidecar Proxy (or Standalone Process)
• Supported Cassandra Versions
• Client-side Metrics
• Custom Retry Policy
• Unsupported Features
• License

When to Use Spanner Cassandra Java 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 Java application but prefer to keep using the familiar cassandra-java-driver API for data access.
• Using Non-Java 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. Java Development Kit (JDK) 8 or later. Maven or Gradle for dependency management.

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 using the adapter.
• To migrate existing Cassandra schema to corresponding Spanner schema, refer to our official Cassandra to Spanner migration tool to automate this process.

Getting Started

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

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

In-Process Dependency (Recommended)

For Java applications already using the cassandra-java-driver library, integrating the Spanner Cassandra Java Client requires only minor changes to the CqlSession initialization.

Steps:

• Add the dependency to your project's build file:

  Maven:

  <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-spanner-cassandra</artifactId>
      <version>1.1.0</version>
  </dependency>

  Gradle:

  dependencies {
      implementation 'com.google.cloud:google-cloud-spanner-cassandra:1.1.0'
  }

• Modify your CqlSession creation code. Instead of using CqlSessionBuilder, use SpannerCqlSessionBuilder and provide the Spanner database URI:

  CqlSession session =
      SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
          .setDatabaseUri("projects/your_gcp_project/instances/your_spanner_instance/databases/your_spanner_database") // Required: Specify the Spanner database URI
          .withConfigLoader(
              DriverConfigLoader.programmaticBuilder()
                  .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                  .withDuration(
                      DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                      Duration.ofSeconds(5))
                  .build())
          .build();
  
  // Rest of your business logic such as session.Query(SELECT * FROM ...)
  
  session.close();

• Run your Java application as usual. The adapter will now route traffic to your Spanner database.

Sidecar Proxy (or Standalone Process)

For non-Java applications or tools like cqlsh, you can run the Spanner Cassandra Java Client as a standalone proxy or process (with locally built jar file).

Steps:

• Clone the repository:

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

• Build the project by running:

  mvn clean install

  This will create an executable jar file spanner-cassandra-launcher.jar inside the folder google-cloud-spanner-cassandra/target.

• Run the jar using one of the following methods:

  1. Using a YAML Configuration File (Recommended for Production)

  For production setups, it is recommended to use a YAML file to configure the adapter. This method supports multiple listeners and global settings. See the Configuration Options for a complete list of all supported options. An example config.yaml file can be found here.

  Then, run the launcher with the -DconfigFilePath system property:

  java -DconfigFilePath=/path/to/config.yaml -jar path/to/your/spanner-cassandra-launcher.jar

  2. Using System Properties (for a single listener)

  For simpler setups or quick testing, you can provide the configuration via system properties. This method only supports a single adapter listener.

  java -DdatabaseUri=projects/my-project/instances/my-instance/databases/my-database \
  -Dhost=127.0.0.1 \
  -Dport=9042 \
  -DnumGrpcChannels=4 \
  -DhealthCheckPort=8080 \
  -jar path/to/your/spanner-cassandra-launcher.jar

  Configuration Notes:

  • Database URI: You must specify the Spanner database URI. This is done via the databaseUri property in YAML or the -DdatabaseUri system property.
  • Host: The default host is 0.0.0.0. This can be overridden with the host property in YAML or -Dhost.
  • Port: The default port is 9042. This can be overridden with the port property in YAML or -Dport.
  • gRPC Channels: The default number of gRPC channels is 4. This can be overridden with numGrpcChannels in YAML or -DnumGrpcChannels.
  • Health Check: You can optionally enable a health check endpoint.
    • In YAML, set healthCheckEndpoint to a host:port value (e.g., "127.0.0.1:8080").
    • With system properties, use -DhealthCheckPort and specify a port. The host will default to the adapter's host.
    • When enabled, the endpoint is available at /debug/health and returns HTTP 200 OK if the client is running, or 503 Service Unavailable otherwise. The health check is disabled by default.

View and manage client-side metrics

The Spanner Cassandra client provides client-side metrics that you can use along with server-side metrics to optimize performance and troubleshoot any performance issues, please see the View and manage client-side metrics documentation.

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
• unset parameter value

Custom Retry Policy

The Spanner Cassandra Java Client includes a custom retry policy that is tailored for Spanner Server. For more details on how to use and configure this policy, please see the Custom Retry Policy documentation.

License

Apache License 2.0