A JDBC driver for Cloud Spanner - A no-compromise relational database service.
Example for creating a JDBC connection to Cloud Spanner.
String projectId = "my-project";
String instanceId = "my-instance";
String databaseId = "my-database";
try (Connection connection =
DriverManager.getConnection(
String.format(
"jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
projectId, instanceId, databaseId))) {
try (Statement statement = connection.createStatement()) {
try (ResultSet rs = statement.executeQuery("SELECT CURRENT_TIMESTAMP()")) {
while (rs.next()) {
System.out.printf(
"Connected to Cloud Spanner at [%s]%n", rs.getTimestamp(1).toString());
}
}
}
}
See Also: Cloud Spanner JDBC Driver, JdbcDriver java doc for all supported connection URL properties.
Classes
JdbcConstants
Constants for special values used by the Cloud Spanner JDBC driver.
JdbcDataSource
DataSource implementation for Google Cloud Spanner.
JdbcDriver
JDBC Driver for Google Cloud Spanner.
Usage:
String url = "jdbc:cloudspanner:/projects/my_project_id/"
+ "instances/my_instance_id/databases/my_database_name?"
+ "credentials=/home/cloudspanner-keys/my-key.json;autocommit=false";
try (Connection connection = DriverManager.getConnection(url)) {
try(ResultSet rs = connection.createStatement().executeQuery("SELECT SingerId, AlbumId, MarketingBudget FROM Albums")) {
while(rs.next()) {
// do something
}
}
}
The connection that is returned will implement the interface CloudSpannerJdbcConnection. The JDBC connection URL must be specified in the following format:
jdbc:cloudspanner:[//host[:port]]/projects/project-id[/instances/instance-id[/databases/database-name]][?property-name=property-value[;property-name=property-value]*]?
The property-value strings should be url-encoded.
The project-id part of the URI may be filled with the placeholder DEFAULT_PROJECT_ID. This placeholder is replaced by the default project id of the environment that is requesting a connection.
The supported properties are:
- 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 by GoogleCredentials#getApplicationDefault() is used.
- 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 any
gcloudcommands on the emulator to create the instance and database before you can connect to it. - usePlainText (boolean): Sets whether the JDBC connection should establish an unencrypted connection to the 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.
- optimizerVersion (string): The query optimizer version to use for the connection. The value
must be either a valid version number or
LATEST. If no value is specified, the query optimizer version specified in the environment variableSPANNER_OPTIMIZER_VERSIONis used. If no query optimizer version is specified in the connection URL or in the environment variable, the default query optimizer version of Cloud Spanner is used. - oauthtoken (String): A valid OAuth2 token to use for the JDBC connection. The token must have been obtained with one or both of the scopes 'https://www.googleapis.com/auth/spanner.admin' and/or 'https://www.googleapis.com/auth/spanner.data'. If you specify both a credentials file and an OAuth token, the JDBC driver will throw an exception when you try to obtain a connection.
- retryAbortsInternally (boolean): Sets the initial retryAbortsInternally mode for the connection. Default is true. @see com.google.cloud.spanner.jdbc.CloudSpannerJdbcConnection#setRetryAbortsInternally(boolean) for more information.
- minSessions (int): Sets the minimum number of sessions in the backing session pool. Defaults to 100.
- maxSessions (int): Sets the maximum number of sessions in the backing session pool. Defaults to 400.
- numChannels (int): Sets the number of gRPC channels to use. Defaults to 4.
- rpcPriority (String): Sets the priority for all RPC invocations from this connection. Defaults to HIGH.
JdbcSqlExceptionFactory
Factory class for creating SQLExceptions for Cloud Spanner
JsonType
Custom SQL type for Spanner JSON data type. This type (or the vendor type number) must be used when setting a JSON parameter using PreparedStatement#setObject(int, Object, SQLType).
SpannerPool
See Also: com.google.cloud.spanner.connection.SpannerPool
Interfaces
CloudSpannerJdbcConnection
JDBC connection with a number of additional Cloud Spanner specific methods. JDBC connections that are returned by the Cloud Spanner JdbcDriver will implement this interface.
Calling Connection#unwrap(Class) with CloudSpannerJdbcConnection#getClass() as input on a Connection returned by the Cloud Spanner JDBC Driver will return a CloudSpannerJdbcConnection instance.
JdbcSqlException
Base interface for all Cloud Spanner SQLExceptions. All SQLExceptions that are thrown by the Cloud Spanner JDBC driver implement this interface.
TransactionRetryListener
Use com.google.cloud.spanner.connection.TransactionRetryListener
Enums
TransactionRetryListener.RetryResult
Use com.google.cloud.spanner.connection.TransactionRetryListener.RetryResult
Exceptions
JdbcSqlExceptionFactory.JdbcAbortedDueToConcurrentModificationException
Specific SQLException that is thrown when a transaction was aborted and could not be retried due to a concurrent modification.
JdbcSqlExceptionFactory.JdbcAbortedException
Specific SQLException that is thrown when a transaction was aborted and could not be successfully retried.
JdbcSqlExceptionFactory.JdbcSqlBatchUpdateException
Specific SQLException that is thrown when a SpannerBatchUpdateException occurs.
JdbcSqlExceptionFactory.JdbcSqlClientInfoException
Specific SQLException that is thrown when setting client info on a connection
JdbcSqlExceptionFactory.JdbcSqlExceptionImpl
Base SQLException for Cloud Spanner
JdbcSqlExceptionFactory.JdbcSqlFeatureNotSupportedException
Specific SQLException that is thrown for unsupported methods and values
JdbcSqlExceptionFactory.JdbcSqlTimeoutException
Specific SQLException that is thrown when a statement times out