Java idiomatic client for Cloud Spanner.
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>16.4.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>3.3.2</version>
</dependency>
If you are using Gradle 5.x or later, add this to your dependencies
implementation platform('com.google.cloud:libraries-bom:16.4.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:3.3.2'If you are using SBT, add this to your dependencies
libraryDependencies += "com.google.cloud" % "google-cloud-spanner" % "3.3.2"See the Authentication section in the base directory's README.
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].
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.
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/.
-
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.
To use OpenTelemetry with the Cloud Spanner client, set up the OpenTelemetry pipeline, and add the OpenCensus shim to your project. Follow the README instructions to set up traces and metrics.
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 Instance Example | source code | |
| Custom Timeout And Retry Settings Example | source code | |
| Query With Numeric Parameter Sample | source code | |
| Quickstart Sample | source code | |
| Spanner Sample | source code | |
| Statement Timeout Example | source code | |
| Tracing Sample | source code | |
| Update Numeric Data Sample | source code | |
To get help, follow the instructions in the shared Troubleshooting document.
Cloud Spanner uses gRPC for the transport layer.
Java 7 or above is required for using this client.
This library follows Semantic Versioning.
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.
Apache 2.0 - See LICENSE for more information.
| Java Version | Status |
|---|---|
| Java 7 |  |
| Java 8 |  |
| Java 8 OSX |  |
| Java 8 Windows |  |
| Java 11 |  |
Java is a registered trademark of Oracle and/or its affiliates.