Google Cloud Spanner Client for Java

Java idiomatic client for Cloud Spanner.

Quickstart

If you are using Maven with BOM, add this to your pom.xml file

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>20.8.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner</artifactId>
  </dependency>

If you are using Maven without BOM, add this to your dependencies:

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

If you are using Gradle 5.x or later, add this to your dependencies

implementation platform('com.google.cloud:libraries-bom:20.8.0')

compile 'com.google.cloud:google-cloud-spanner'

If you are using Gradle without BOM, add this to your dependencies

compile 'com.google.cloud:google-cloud-spanner:6.10.1'

If you are using SBT, add this to your dependencies

libraryDependencies += "com.google.cloud" % "google-cloud-spanner" % "6.10.1"

Authentication

See the Authentication section in the base directory's README.

Getting Started

Prerequisites

You will need a Google Cloud Platform Console project with the Cloud Spanner API enabled.
You will need to enable billing to use Google Cloud Spanner.
Follow these instructions to get your project set up. You will also need to set up the local development environment by
installing the Google Cloud SDK and running the following commands in command line:
gcloud auth login and gcloud config set project [YOUR PROJECT ID].

Installation and setup

You'll need to obtain the google-cloud-spanner library. See the Quickstart section
to add google-cloud-spanner as a dependency in your code.

About Cloud Spanner

Cloud Spanner is a fully managed, mission-critical,
relational database service that offers transactional consistency at global scale,
schemas, SQL (ANSI 2011 with extensions), and automatic, synchronous replication
for high availability.

Be sure to activate the Cloud Spanner API on the Developer's Console to
use Cloud Spanner from your project.

See the Cloud Spanner client library docs to learn how to
use this Cloud Spanner Client Library.

Calling Cloud Spanner

Here is a code snippet showing a simple usage example. Add the following imports
at the top of your file:

import com.google.cloud.spanner.DatabaseClient;
import com.google.cloud.spanner.DatabaseId;
import com.google.cloud.spanner.ResultSet;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.Statement;

Then, to make a query to Spanner, use the following code:

// Instantiates a client
SpannerOptions options = SpannerOptions.newBuilder().build();
Spanner spanner = options.getService();
String instance = "my-instance";
String database = "my-database";
try {
  // Creates a database client
  DatabaseClient dbClient = spanner.getDatabaseClient(
    DatabaseId.of(options.getProjectId(), instance, database));
  // Queries the database
  try (ResultSet resultSet = dbClient.singleUse().executeQuery(Statement.of("SELECT 1"))) {
    // Prints the results
    while (resultSet.next()) {
      System.out.printf("%d\n", resultSet.getLong(0));
    }
  }
} finally {
  // Closes the client which will free up the resources used
  spanner.close();
}

Complete source code

In DatabaseSelect.java we put together all the code shown above in a single program.

OpenCensus Metrics

Cloud Spanner client supports Opencensus Metrics,
which gives insight into the client internals and aids in debugging/troubleshooting
production issues. OpenCensus metrics will provide you with enough data to enable you to
spot, and investigate the cause of any unusual deviations from normal behavior.

All Cloud Spanner Metrics are prefixed with cloud.google.com/java/spanner/. The
metrics will be tagged with:

database: the target database name.
instance_id: the instance id of the target Spanner instance.
client_id: the user defined database client id.
library_version: the version of the library that you're using.

Note: RPC level metrics can be gleaned from gRPC’s metrics, which are prefixed
with grpc.io/client/.

Available client-side metrics:

cloud.google.com/java/spanner/max_in_use_sessions: This returns the maximum
number of sessions that have been in use during the last maintenance window
interval, so as to provide an indication of the amount of activity currently
in the database.
cloud.google.com/java/spanner/max_allowed_sessions: This shows the maximum
number of sessions allowed.
cloud.google.com/java/spanner/in_use_sessions: This metric allows users to
see instance-level and database-level data for the total number of sessions in
use (or checked out from the pool) at this very moment.
cloud.google.com/java/spanner/num_acquired_sessions: This metric allows
users to see the total number of acquired sessions.
cloud.google.com/java/spanner/num_released_sessions: This metric allows
users to see the total number of released (destroyed) sessions.
cloud.google.com/java/spanner/get_session_timeouts: This gives you an
indication of the total number of get session timed-out instead of being
granted (the thread that requested the session is placed in a wait queue where
it waits until a session is released into the pool by another thread) due to
pool exhaustion since the server process started.

If you are using Maven, add this to your pom.xml file

<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.26.0</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-stats-stackdriver</artifactId>
  <version>0.26.0</version>
</dependency>

If you are using Gradle, add this to your dependencies

compile 'io.opencensus:opencensus-impl:0.26.0'
compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.26.0'

At the start of your application configure the exporter:

import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter;
// Enable OpenCensus exporters to export metrics to Stackdriver Monitoring.
// Exporters use Application Default Credentials to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
// The minimum reporting period for Stackdriver is 1 minute.
StackdriverStatsExporter.createAndRegister();

By default, the functionality is disabled. You need to include opencensus-impl
dependency to collect the data and exporter dependency to export to backend.

Click here for more information.

Samples

Samples are in the samples/ directory. The samples' README.md
has instructions for running the samples.

Sample	Source Code	Try it
Add Numeric Column Sample	source code
Async Dml Example	source code
Async Query Example	source code
Async Query To List Async Example	source code
Async Read Example	source code
Async Read Only Transaction Example	source code
Async Read Row Example	source code
Async Read Using Index Example	source code
Async Runner Example	source code
Async Transaction Manager Example	source code
Batch Sample	source code
Create Backup With Encryption Key	source code
Create Database With Encryption Key	source code
Create Database With Version Retention Period Sample	source code
Create Instance Example	source code
Create Instance With Processing Units Example	source code
Custom Timeout And Retry Settings Example	source code
Get Commit Stats Sample	source code
Query With Numeric Parameter Sample	source code
Quickstart Sample	source code
Restore Backup With Encryption Key	source code
Spanner Sample	source code
Statement Timeout Example	source code
Tracing Sample	source code
Update Numeric Data Sample	source code

Troubleshooting

To get help, follow the instructions in the shared Troubleshooting document.

Transport

Cloud Spanner uses gRPC for the transport layer.

Supported Java Versions

Java 8 or above is required for using this client.

Google's Java client libraries,
Google Cloud Client Libraries
and
Google Cloud API Libraries,
follow the
Oracle Java SE support roadmap
(see the Oracle Java SE Product Releases section).

For new development

In general, new feature development occurs with support for the lowest Java
LTS version covered by Oracle's Premier Support (which typically lasts 5 years
from initial General Availability). If the minimum required JVM for a given
library is changed, it is accompanied by a semver major release.

Java 11 and (in September 2021) Java 17 are the best choices for new
development.

Keeping production systems current

Google tests its client libraries with all current LTS versions covered by
Oracle's Extended Support (which typically lasts 8 years from initial
General Availability).

Legacy support

Google's client libraries support legacy versions of Java runtimes with long
term stable libraries that don't receive feature updates on a best efforts basis
as it may not be possible to backport all patches.

Google provides updates on a best efforts basis to apps that continue to use
Java 7, though apps might need to upgrade to current versions of the library
that supports their JVM.

Where to find specific information

The latest versions and the supported Java versions are identified on
the individual GitHub repository github.com/GoogleAPIs/java-SERVICENAME
and on google-cloud-java.

Versioning

This library follows Semantic Versioning.

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in
this project you agree to abide by its terms. See Code of Conduct for more
information.

License

Apache 2.0 - See LICENSE for more information.

CI Status

Java Version	Status
Java 8
Java 8 OSX
Java 8 Windows
Java 11

Java is a registered trademark of Oracle and/or its affiliates.

stephaniewang526/java-spanner