Use the Java client library to connect to Spanner Omni

The Java client library for Spanner works with Spanner Omni in the same way it works with Spanner. This document shows you how to establish secure connections to Spanner Omni by configuring the Java client library. You establish these connections by setting client options when you create a database administrative client or a database client.

The Java client library supports plain text, TLS, and mTLS connections.

For more information, see Get started with Spanner in Java in the Spanner documentation.

Before you begin

To get started with Spanner Omni in Java, use the Java client library version 6.115.0 or later.

If you use Maven without the Bill of Materials (BOM), add the following to the pom.xml file dependencies:

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

Configure the `SpannerOptions` object

While you configure the SpannerOptions object to create a DatabaseClient or DatabaseAdminClient, specify the Spanner Omni endpoint using setExperimentalHost().

Use plain-text communication

To establish a plain-text connection, specify the Spanner Omni endpoint and use the usePlainText() method:

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setExperimentalHost("http://ENDPOINT") // Replace with your Spanner Omni endpoint
        .usePlainText()
        .build();
Spanner spanner = options.getService();

Use a TLS setup

When you configure the SpannerOptions object for a TLS connection, you don't need to set any additional credentials properties. You must add the CA certificate to the Java truststore.

To add the CA certificate to the Java truststore, use the following command:

sudo keytool -import -trustcacerts -file /.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

Alternatively, you can pass a custom CA certificate store directly when you run the application:

java -Djavax.net.ssl.trustStore=PATH_TO_CUSTOM_CACERTS -Djavax.net.ssl.trustStorePassword=changeit app

To maintain compatibility, build your custom truststore on top of the Java truststore by making a copy:

cp $JAVA_HOME/lib/security/cacerts /PATH_TO_CUSTOM_CACERTS

Use an mTLS setup

To use an mTLS connection, convert the key generated by Spanner Omni to a format compliant with Java using the following command:

openssl pkcs8 -topk8 -in ~/.spanner/certs/client.key -out ~/.spanner/certs/java-client.key -nocrypt

The following example shows how to configure the SpannerOptions object to use a client certificate:

   SpannerOptions options =
        SpannerOptions.newBuilder()
           .setExperimentalHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
.useClientCert("PATH_TO_CLIENT_CERT","PATH_TO_CLIENT_CERT_KEY")
.build();
   Spanner spanner = options.getService();

Create the database

Next, create the database. Specify the project as default where necessary in the library code. For example, specify default when you create a DatabaseId:

DatabaseId dbId = DatabaseId.of("default", "default", DATABASE_ID);
DatabaseClient client = spanner.getDatabaseClient(dbId);