Repository files navigation

Java idiomatic client forGoogle Cloud Spanner JDBC.

• Product Documentation
• Client Library Documentation

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

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

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

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

If you are using SBT, add this to your dependencies

libraryDependencies+="com.google.cloud"%"google-cloud-spanner-jdbc"%"2.34.0"

See theAuthentication section in the base directory's README.

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

You will need aGoogle Cloud Platform Console project with the Google Cloud Spanner JDBC [API enabled][enable-api].

Follow these instructions to get your project set up. You will also need to set up the local development environment byinstalling the Google Cloud SDK and running the following commands in command line:gcloud auth login andgcloud config set project [YOUR PROJECT ID].

You'll need to obtain thegoogle-cloud-spanner-jdbc library. See theQuickstart sectionto addgoogle-cloud-spanner-jdbc as a dependency in your code.

Google Cloud Spanner JDBC

See theGoogle Cloud Spanner JDBC client library docs to learn how touse this Google Cloud Spanner JDBC Client Library.

The following example shows how to create a JDBC connection to Cloud Spanner and execute a simple query.

StringprojectId ="my-project";StringinstanceId ="my-instance";StringdatabaseId ="my-database";try (Connectionconnection =DriverManager.getConnection(String.format("jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",projectId,instanceId,databaseId))) {try (Statementstatement =connection.createStatement()) {try (ResultSetrs =statement.executeQuery("SELECT CURRENT_TIMESTAMP()")) {while (rs.next()) {System.out.printf("Connected to Cloud Spanner at [%s]%n",rs.getTimestamp(1).toString());      }    }  }}

The Cloud Spanner JDBC driver supports the following connection URL properties. Note that all ofthese can also be supplied in a Properties instance that is passed to theDriverManager#getConnection(String url, Properties properties) method.

SeeSupported Connection Properties for a full list of allsupported connection properties.

• default_isolation_level (String): Spanner supports isolation levels REPEATABLE_READ or SERIALIZABLE. SERIALIZABLE is the default. Using isolation level REPEATABLE_READ improves performance by reducing the amount of locks that are taken by transactions that execute a large number of queries in read/write transactions. Seehttps://cloud.google.com/spanner/docs/isolation-levels for more information on the supported isolation levels in Spanner.
• credentials (String): URL for the credentials file to use for the connection. If you do not specify any credentials at all, the default credentials of the environment as returned byGoogleCredentials#getApplicationDefault() is used. Example:jdbc:cloudspanner:/projects/my-project/instances/my-instance/databases/my-db;credentials=/path/to/credentials.json
• autocommit (boolean): Sets the initial autocommit mode for the connection. Default is true.
• readonly (boolean): Sets the initial readonly mode for the connection. Default is false.
• autoConfigEmulator (boolean): Automatically configure the connection to try to connect to the Cloud Spanner emulator. You do not need to specify any host or port in the connection string as long as the emulator is running on the default host/port (localhost:9010). The instance and database in the connection string will automatically be created if these do not yet exist on the emulator. This means that you do not need to execute anygcloud commands on the emulator to create the instance and database before you can connect to it. Example:jdbc:cloudspanner:/projects/test-project/instances/test-instance/databases/test-db;autoConfigEmulator=true
• usePlainText (boolean): Sets whether the JDBC connection should establish an unencrypted connection to a (local) server. This option can only be used when connecting to a local emulator that does not require an encrypted connection, and that does not require authentication. Example:jdbc:cloudspanner://localhost:9010/projects/test-project/instances/test-instance/databases/test-db;usePlainText=true
• optimizerVersion (String): Sets the default query optimizer version to use for this connection. See alsohttps://cloud.google.com/spanner/docs/query-optimizer/query-optimizer-versions.

• DEPRECATED minSessions (int): Sets the minimum number of sessions in the backing session pool. Defaults to 100. This configuration option is no longer needed, as the JDBC driver by default uses asingle multiplexed session for all operations.
• DEPRECATED maxSessions (int): Sets the maximum number of sessions in the backing session pool. Defaults to 400. This configuration option is no longer needed, as the JDBC driver by default uses asingle multiplexed session for all operations.
• numChannels (int): Sets the number of gRPC channels to use. Defaults to 4.
• retryAbortsInternally (boolean): The JDBC driver will by default automatically retry aborted transactions internally. This is done by keeping track of all statements and the results of these during a transaction, and if the transaction is aborted by Cloud Spanner, it will replay the statements on a new transaction and compare the results with the initial attempt. Disable this option if you want to handle aborted transactions in your own application.
• autocommit_dml_mode (string): Determines the transaction type that is used to executeDML statements when the connection isin auto-commit mode. The following values are supported:
  • TRANSACTIONAL (default): Uses atomic read/write transactions.
  • PARTITIONED_NON_ATOMIC: Use Partitioned DML for DML statements in auto-commit mode. Use this modeto execute DML statements that exceed the transaction mutation limit in Spanner.
  • TRANSACTIONAL_WITH_FALLBACK_TO_PARTITIONED_NON_ATOMIC: Execute DML statements using atomic read/writetransactions. If this fails because the mutation limit on Spanner has been exceeded, the DML statementis retried using a Partitioned DML transaction.
• auto_batch_dml (boolean): Automatically buffer DML statements and execute them as one batch,instead of executing them on Spanner directly. The buffered DML statements are executed on Spannerin one batch when a query is executed, or when the transaction is committed. This option can forexample be used in combination with Hibernate to automatically group more (small) DML statementsinto one batch.
• oauthToken (string): A valid pre-existing OAuth token to use for authentication for this connection. Setting this property will take precedence over any value set for a credentials file.
• lenient (boolean): Enable this to force the JDBC driver to ignore unknown properties in the connection URL. Some applications automatically add additional properties to the URL that are not recognized by the JDBC driver. Normally, the JDBC driver will reject this, unlesslenient mode is enabled.
• enableDirectAccess (boolean): Sets whether the JDBC connection should establish connection using Directpath. Setting this property will enable client to establish connection directly to Spanner if client is running in GCP VM, Otherwise it will fall back standard network path.

For a full list of supported connection properties, seeSupported Connection Properties.

A single jar with all dependencies can be downloaded fromhttps://repo1.maven.org/maven2/com/google/cloud/google-cloud-spanner-jdbc/latestor be built with the commandmvn package (select the jar that is namedgoogle-cloud-spanner-jdbc-<version>-single-jar-with-dependencies.jar).

A jar with all dependencies included is automatically generated when you executemvn package.The dependencies in this jar are not shaded. To create a jar with shaded dependencies you mustactivate theshade profile like this:

mvn package -Pshade

See thesamples directory for various examples for using the Spanner JDBC driver.

• snippets: Contains small code snippets for commonly used JDBC and Spannerfeatures. Refer to these snippets for examples on how to execute DDL and DML batches, use variousdata types with the JDBC driver, execute various types of transactions (read/write, read-only,Partitioned DML), use request and transaction tags, etc.
• spring-data-jdbc: Contains a sample application that uses Spring DataJDBC in combination with a Spanner PostgreSQL database.
• spring-data-mybatis: Contains a sample application that usesSpring Data MyBatis in combination with a Spanner PostgreSQL database.
• quickperf: Contains a simple benchmarking application.

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

Java 8 or above is required for using this client.

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

In general, new feature development occurs with support for the lowest JavaLTS version covered by Oracle's Premier Support (which typically lasts 5 yearsfrom initial General Availability). If the minimum required JVM for a givenlibrary is changed, it is accompanied by asemver major release.

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

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

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

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

The latest versions and the supported Java versions are identified onthe individual GitHub repositorygithub.com/GoogleAPIs/java-SERVICENAMEand ongoogle-cloud-java.

This library followsSemantic Versioning.

Contributions to this library are always welcome and highly encouraged.

SeeCONTRIBUTING for more information how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating inthis project you agree to abide by its terms. SeeCode of Conduct for moreinformation.

Apache 2.0 - SeeLICENSE for more information.

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

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