google-cloud-spanner

Google Cloud Java Client for Spanner

Java idiomatic client for Cloud Spanner.

• Product Documentation
• Client Library Documentation

Note: This client is a work-in-progress, and may occasionally make backwards-incompatible changes.

Quickstart

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

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

If you are using Gradle, add this to your dependencies

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

If you are using SBT, add this to your dependencies

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

Authentication

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

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 Spanner client lib docs to learn how to interact with Cloud Spanner using this Client Library.

Getting Started

Prerequisites

Please refer to the getting started guide.

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.

Troubleshooting

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

Transport

Spanner uses gRPC for the transport layer.

Java Versions

Java 7 or above is required for using this client.

Testing

This library has tools to help make tests for code using Cloud Spanner.

See TESTING to read more about testing.

Versioning

This library follows Semantic Versioning.

It is currently in major version zero (0.y.z), which means that anything may change at any time and the public API should not be considered stable.

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information on how to get started.

License

Apache 2.0 - See LICENSE for more information.