Package com.google.cloud.spanner.connection

Internal API for Google Cloud Spanner. This API may introduce breaking changes without prior notice.

Classes

Connection.InternalMetadataQuery

This query option is used internally to indicate that a query is executed by the library itself to fetch metadata. These queries are specifically allowed to be executed even when a DDL batch is active.

NOT INTENDED FOR EXTERNAL USE!

ConnectionOptions

Internal connection API for Google Cloud Spanner. This class may introduce breaking changes without prior notice.

Options for creating a Connection to a Google Cloud Spanner database.

Usage:

 
 
 ConnectionOptions options = ConnectionOptions.newBuilder()
       .setUri("cloudspanner:/projects/my_project_id/instances/my_instance_id/databases/my_database_name?autocommit=false")
       .setCredentialsUrl("/home/cloudspanner-keys/my-key.json")
       .build();
 try(Connection connection = options.getConnection()) {
   try(ResultSet rs = connection.executeQuery(Statement.of("SELECT SingerId, AlbumId, MarketingBudget FROM Albums"))) {
     while(rs.next()) {
       // do something
     }
   }
 }

ConnectionOptions.Builder

Builder for ConnectionOptions instances.

ConnectionOptions.ConnectionProperty

Supported connection properties that can be included in the connection URI.

ReadOnlyStalenessUtil

Util class for parsing and converting ReadOnlyStaleness values to/from strings. This util is used to parse client side statements and values for read only staleness for read-only transactions on Cloud Spanner.

SpannerPool

Pool for keeping track of Spanner instances needed for connections.

When a connection is opened for a Google Cloud Spanner database, a Spanner object can be opened in the background. The SpannerPool keeps track of which Spanner objects have been opened by connections during the lifetime of the JVM, which connections are still opened and closed, and which Spanner objects could be closed.

Call the method SpannerPool#closeSpannerPool() at the end of your application to gracefully shutdown all instances in the pool.

StatementParser

Internal class for the Spanner Connection API.

Parses ClientSideStatements and normal SQL statements. The parser is able to recognize the type of statement, allowing the connection API to know which method on Spanner should be called. The parser does not validate the validity of statements, except for ClientSideStatements. This means that an invalid DML statement could be accepted by the StatementParser and sent to Spanner, and Spanner will then reject it with some error message.

Interfaces

AsyncStatementResult

Connection

Internal connection API for Google Cloud Spanner. This interface may introduce breaking changes without prior notice.

A connection to a Cloud Spanner database. Connections are not designed to be thread-safe. The only exception is the Connection#cancel() method that may be called by any other thread to stop the execution of the current statement on the connection.

All -Async methods on Connection are guaranteed to be executed in the order that they are issued on the Connection. Mixing synchronous and asynchronous method calls is also supported, and these are also guaranteed to be executed in the order that they are issued.

Connections accept a number of additional SQL statements for setting or changing the state of a Connection. These statements can only be executed using the Connection#execute(Statement) method:

SHOW AUTOCOMMIT: Returns the current value of AUTOCOMMIT of this connection as a ResultSet
SET AUTOCOMMIT=TRUE|FALSE: Sets the value of AUTOCOMMIT for this connection
SHOW READONLY: Returns the current value of READONLY of this connection as a ResultSet
SET READONLY=TRUE|FALSE: Sets the value of READONLY for this connection
SHOW RETRY_ABORTS_INTERNALLY: Returns the current value of RETRY_ABORTS_INTERNALLY of this connection as a ResultSet
SET RETRY_ABORTS_INTERNALLY=TRUE|FALSE: Sets the value of RETRY_ABORTS_INTERNALLY for this connection
SHOW AUTOCOMMIT_DML_MODE: Returns the current value of AUTOCOMMIT_DML_MODE of this connection as a ResultSet
SET AUTOCOMMIT_DML_MODE='TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC': Sets the value of AUTOCOMMIT_DML_MODE for this connection
SHOW STATEMENT_TIMEOUT: Returns the current value of STATEMENT_TIMEOUT of this connection as a ResultSet
SET STATEMENT_TIMEOUT='<int64>s|ms|us|ns' | NULL: Sets the value of STATEMENT_TIMEOUT for this connection. The supported TimeUnits are:
- s - Seconds
- ms - Milliseconds
- us - Microseconds
- ns - Nanoseconds

Setting the STATEMENT_TIMEOUT to NULL will clear the value for the STATEMENT_TIMEOUT on the connection.

SHOW READ_TIMESTAMP: Returns the last READ_TIMESTAMP of this connection as a ResultSet

SHOW COMMIT_TIMESTAMP: Returns the last COMMIT_TIMESTAMP of this connection as a ResultSet

SHOW READ_ONLY_STALENESS: Returns the current value of


       READ_ONLY_STALENESS

of this connection as a ResultSet


       SET READ_ONLY_STALENESS='STRONG' | 'MIN_READ_TIMESTAMP <timestamp>' | 'READ_TIMESTAMP <timestamp>' | 'MAX_STALENESS <int64>s|ms|mus|ns' | 'EXACT_STALENESS (<int64>s|ms|mus|ns)'

: Sets the value of READ_ONLY_STALENESS for this connection.

SHOW OPTIMIZER_VERSION: Returns the current value of


       OPTIMIZER_VERSION

of this connection as a ResultSet


       SET OPTIMIZER_VERSION='<version>' | 'LATEST'

: Sets the value of OPTIMIZER_VERSION for this connection.

SHOW OPTIMIZER_STATISTICS_PACKAGE: Returns the current value of


       OPTIMIZER_STATISTICS_PACKAGE

of this connection as a ResultSet


       SET OPTIMIZER_STATISTICS_PACKAGE='<package>' | ''

: Sets the value of OPTIMIZER_STATISTICS_PACKAGE for this connection.

BEGIN [TRANSACTION]: Begins a new transaction. This statement is optional when the connection is not in autocommit mode, as a new transaction will automatically be started when a query or update statement is issued. In autocommit mode, this statement will temporarily put the connection in transactional mode, and return the connection to autocommit mode when COMMIT [TRANSACTION] or

ROLLBACK [TRANSACTION]

is executed

COMMIT [TRANSACTION]: Commits the current transaction

ROLLBACK [TRANSACTION]: Rollbacks the current transaction

SET TRANSACTION READ ONLY|READ WRITE: Sets the type for the current transaction. May only be executed before a transaction is actually running (i.e. before any statements have been executed in the transaction)

START BATCH DDL: Starts a batch of DDL statements. May only be executed when no transaction has been started and the connection is in read/write mode. The connection will only accept DDL statements while a DDL batch is active.

START BATCH DML: Starts a batch of DML statements. May only be executed when the connection is in read/write mode. The connection will only accept DML statements while a DML batch is active.

RUN BATCH: Ends the current batch, sends the batched DML or DDL statements to Spanner and blocks until all statements have been executed or an error occurs. May only be executed when a (possibly empty) batch is active. The statement will return the update counts of the batched statements as ResultSet with an ARRAY<INT64> column. In case of a DDL batch, this array will always be empty.

ABORT BATCH: Ends the current batch and removes any DML or DDL statements from the buffer without sending any statements to Spanner. May only be executed when a (possibly empty) batch is active.

Note that Cloud Spanner could abort read/write transactions in the background, and that any database call during a read/write transaction could fail with an AbortedException. This also includes calls to ResultSet#next().

If Connection#isRetryAbortsInternally() is true, then the connection will silently handle any AbortedExceptions by internally re-acquiring all transactional locks and verifying (via the use of cryptographic checksums) that no underlying data has changed. If a change to the underlying data is detected, then an AbortedDueToConcurrentModificationException error will be thrown. If your application already uses retry loops to handle these Aborted errors, then it will be most efficient to set Connection#isRetryAbortsInternally() to false.

Use ConnectionOptions to create a Connection.

StatementResult

A result of the execution of a statement. Statements that are executed by the Connection#execute(com.google.cloud.spanner.Statement) method could have different types of return values. These are wrapped in a StatementResult.

TransactionRetryListener

Cloud Spanner can abort any read/write transaction because of potential deadlocks or other internal reasons. When a transaction is aborted, the entire transaction should be retried. A Connection can automatically retry a transaction internally and check whether the results that are returned during a retry attempt are equal to the results during the original transaction. This is done by keeping track of a SHA-256 checksum of all the results that are returned by Spanner during both transactions.

This listener class for internal transaction retries allow client applications to do additional testing or logging of transaction retries. Transaction retry listeners of a Connection can be added using Connection#addTransactionRetryListener(TransactionRetryListener).

Package com.google.cloud.spanner.connection

Classes

Connection.InternalMetadataQuery

ConnectionOptions

ConnectionOptions.Builder

ConnectionOptions.ConnectionProperty

ReadOnlyStalenessUtil

SpannerPool

StatementParser

Interfaces

AsyncStatementResult

Connection

StatementResult

TransactionRetryListener

Enums

AutocommitDmlMode

StatementResult.ClientSideStatementType

StatementResult.ResultType

TransactionMode

TransactionRetryListener.RetryResult