This document shows you how to use the Spanner JDBC driver to connect your Java applications to Spanner Omni and execute SQL statements.
Java Database Connectivity (JDBC) is a standard Java API that provides a consistent way for applications to interact with relational databases. The Spanner JDBC driver works with Spanner Omni in the same way it works with Spanner.
By using the JDBC driver, you can leverage standard JDBC-compatible tools and libraries with Spanner Omni.
Spanner Omni JDBC connections support three security modes: plain-text, TLS, and mTLS.
For more information, see Get started with Spanner in JDBC in the Spanner documentation.
Connection URL considerations
Because Spanner Omni is not directly connected to a
Google Cloud project, the projects/name
component is not required in the JDBC connection URL. Similarly, because each
Spanner Omni deployment has a single, already-created instance
(instances/default), the instances/name component is
optional.
Establish a Spanner Omni connection
The following examples show how to establish a connection with Spanner Omni using the Spanner JDBC driver for each supported security mode:
Plain-text communication
To establish plain-text communication, use a connection URL similar to the following:
String url = "jdbc:spanner://HOST_ADDRESS:PORT/databases/DATABASE_ID;usePlainText=true;isExperimentalHost=true";
try {
java.sql.Connection connection = DriverManager.getConnection(url);
try {
ResultSet rs = connection.createStatement().executeQuery("SELECT * FROM Singers");
while (rs.next()) {
System.out.print(rs.getLong(1) + "\t");
System.out.println(rs.getString(2));
}
} catch (Exception e) {
System.out.println(e.getMessage());
}
} catch (Exception e) {
System.out.println(e.getMessage());
}
When using an authentication token with TLS or mTLS for a
Spanner Omni endpoint, set the
SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN environment variable to the
path of the authentication token generated by the Spanner Omni CLI. For
connections that don't require credentials, leave this variable unset.
Authentication tokens aren't recommended for client use because
tokens generated by Spanner Omni expire and require manual
renewal with the Spanner Omni CLI.
TLS connection
To establish a TLS connection, add the CA certificate to the Java truststore or pass it directly when you run the application as instructed in the Java SDK TLS instructions. The JDBC URL doesn't require any additional parameters while establishing a TLS connection:
String url = "jdbc:spanner://HOST_ADDRESS:PORT/databases/DATABASE_ID?isExperimentalHost=true";
mTLS connection
To establish an mTLS connection, the JDBC URL requires two additional parameters: clientCertificate and clientKey. These parameters must specify the file paths to the client certificate and client private key, respectively. The client private key must be in a Java-compatible format as mentioned in the Java SDK mTLS instructions:
String url = "jdbc:spanner://HOST_ADDRESS:PORT/databases/DATABASE_ID;clientCertificate=PATH_TO_CLIENT_CERT;clientKey=PATH_TO_CLIENT_KEY;isExperimentalHost=true";