Interface Spanner (6.74.0)

public interface Spanner extends Service<SpannerOptions>, AutoCloseable

An interface for Cloud Spanner. Typically, there would only be one instance of this for the lifetime of the application which must be closed by invoking #close() when it is no longer needed. Failure to do so may result in leaking session resources and exhausting session quota.

Implements

com.google.cloud.Service<com.google.cloud.spanner.SpannerOptions>, AutoCloseable

Methods

close()

public abstract void close()

Closes all the clients associated with this instance and frees up all the resources. This method will block until it can clean up all the resources. Specifically, it deletes all the underlying sessions (which involves rpcs) and closes all the gRPC channels. Once this method called, this object is no longer usable. It is strongly advised to call this method when you are done with the Spanner object, typically when your application shuts down. There is a hard limit on number of sessions in Cloud Spanner and not calling this method can lead to unused sessions piling up on the backend.

createDatabaseAdminClient()

public default DatabaseAdminClient createDatabaseAdminClient()

Returns a com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient to execute admin operations on Cloud Spanner databases. This method always creates a new instance of com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient which is an AutoCloseable resource. For optimising the number of clients, caller may choose to cache the clients instead of repeatedly invoking this method and creating new instances.

Returns
Type Description
DatabaseAdminClient com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient

createInstanceAdminClient()

public default InstanceAdminClient createInstanceAdminClient()

Returns a com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient to execute admin operations on Cloud Spanner databases. This method always creates a new instance of com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient which is an AutoCloseable resource. For optimising the number of clients, caller may choose to cache the clients instead of repeatedly invoking this method and creating new instances.

Returns
Type Description
InstanceAdminClient com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient

getAsyncExecutorProvider()

public abstract ExecutorProvider getAsyncExecutorProvider()
Returns
Type Description
ExecutorProvider

the ExecutorProvider that is used for asynchronous queries and operations.

getBatchClient(DatabaseId db)

public abstract BatchClient getBatchClient(DatabaseId db)

Returns a BatchClient to do batch operations on Cloud Spanner databases. Batch client is useful when one wants to read/query a large amount of data from Cloud Spanner across multiple processes, even across different machines. It allows to create partitions of Cloud Spanner database and then read/query over each partition independently yet at the same snapshot.

For all other use cases, DatabaseClient is more appropriate and performant.


 SpannerOptions options = SpannerOptions.newBuilder().build();
 Spanner spanner = options.getService();
 final String project = "test-project";
 final String instance = "test-instance";
 final String database = "example-db";
 DatabaseId db =
     DatabaseId.of(project, instance, database);
 BatchClient batchClient = spanner.getBatchClient(db);
 
Parameter
Name Description
db DatabaseId
Returns
Type Description
BatchClient

getDatabaseAdminClient()

public abstract DatabaseAdminClient getDatabaseAdminClient()

Returns a DatabaseAdminClient to execute admin operations on Cloud Spanner databases.

Returns
Type Description
DatabaseAdminClient

DatabaseAdminClient

getDatabaseClient(DatabaseId db)

public abstract DatabaseClient getDatabaseClient(DatabaseId db)

Returns a DatabaseClient for the given database. It uses a pool of sessions to talk to the database.


 SpannerOptions options = SpannerOptions.newBuilder().build();
 Spanner spanner = options.getService();
 final String project = "test-project";
 final String instance = "test-instance";
 final String database = "example-db";
 DatabaseId db =
     DatabaseId.of(project, instance, database);
 DatabaseClient dbClient = spanner.getDatabaseClient(db);
 
Parameter
Name Description
db DatabaseId
Returns
Type Description
DatabaseClient

getInstanceAdminClient()

public abstract InstanceAdminClient getInstanceAdminClient()

Returns an InstanceAdminClient to execute admin operations on Cloud Spanner instances.

Returns
Type Description
InstanceAdminClient

InstanceAdminClient

isClosed()

public abstract boolean isClosed()
Returns
Type Description
boolean

true if this Spanner object is closed.