Java idiomatic client for Cloud Spanner.

• Product Documentation
• Client Library Documentation

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>26.62.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 the BOM, add this to your dependencies:

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

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

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

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

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

implementation 'com.google.cloud:google-cloud-spanner:6.100.0'

If you are using SBT, add this to your dependencies:

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

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

The client application making API calls must be granted authorization scopes required for the desired Cloud Spanner APIs, and the authenticated principal must have the IAM role(s) required to access GCP resources using the Cloud Spanner API calls.

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 Command Line Interface and running the following commands in command line: gcloud auth login and gcloud config set project [YOUR PROJECT ID].

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.

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.

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();
}

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

The Cloud Spanner client maintains a session pool, as sessions are expensive to create and are intended to be long-lived. The client automatically takes a session from the pool and uses this executing queries and transactions. See Session Pool and Channel Pool Configuration for in-depth background information about sessions and gRPC channels and how these are handled in the Cloud Spanner Java client.

• 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.

• spanner/max_allowed_sessions: This shows the maximum number of sessions allowed.

• spanner/num_sessions_in_pool: This metric allows users to see instance-level and database-level data for the total number of sessions in the pool at this very moment.

• spanner/num_acquired_sessions: This metric allows users to see the total number of acquired sessions.

• spanner/num_released_sessions: This metric allows users to see the total number of released (destroyed) sessions.

• 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.

• spanner/gfe_latency: This metric shows latency between Google's network receiving an RPC and reading back the first byte of the response.

• spanner/gfe_header_missing_count: This metric shows the number of RPC responses received without the server-timing header, most likely indicating that the RPC never reached Google's network.

Cloud Spanner client supports OpenTelemetry Metrics, which gives insight into the client internals and aids in debugging/troubleshooting production issues. OpenTelemetry 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 spanner/ and uses cloud.google.com/java as Instrumentation Scope. 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.

By default, the functionality is disabled. You need to add OpenTelemetry dependencies, enable OpenTelemetry metrics and must configure the OpenTelemetry with appropriate exporters at the startup of your application: