Internal API for Google Cloud Spanner. This API may introduce breaking changes without prior notice.
Classes
AbstractStatementParser
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 AbstractStatementParser and sent to Spanner, and Spanner will then reject it with some error message.
AbstractStatementParser.ParametersInfo
Parameter information with positional parameters translated to named parameters.
AbstractStatementParser.ParsedStatement
A statement that has been parsed
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.
PostgreSQLStatementParser
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.
SpannerStatementParser
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 ofAUTOCOMMIT
of this connection as a ResultSetSET AUTOCOMMIT=TRUE|FALSE
: Sets the value ofAUTOCOMMIT
for this connectionSHOW READONLY
: Returns the current value ofREADONLY
of this connection as a ResultSetSET READONLY=TRUE|FALSE
: Sets the value ofREADONLY
for this connectionSHOW RETRY_ABORTS_INTERNALLY
: Returns the current value ofRETRY_ABORTS_INTERNALLY
of this connection as a ResultSetSET RETRY_ABORTS_INTERNALLY=TRUE|FALSE
: Sets the value ofRETRY_ABORTS_INTERNALLY
for this connectionSHOW AUTOCOMMIT_DML_MODE
: Returns the current value ofAUTOCOMMIT_DML_MODE
of this connection as a ResultSetSET AUTOCOMMIT_DML_MODE='TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC'
: Sets the value ofAUTOCOMMIT_DML_MODE
for this connectionSHOW STATEMENT_TIMEOUT
: Returns the current value ofSTATEMENT_TIMEOUT
of this connection as a ResultSetSET STATEMENT_TIMEOUT='<int64>s|ms|us|ns' | NULL
: Sets the value ofSTATEMENT_TIMEOUT
for this connection. The supported TimeUnits are:- s - Seconds
- ms - Milliseconds
- us - Microseconds
- ns - Nanoseconds
SHOW READ_TIMESTAMP
: Returns the lastREAD_TIMESTAMP
of this connection as a ResultSetSHOW COMMIT_TIMESTAMP
: Returns the lastCOMMIT_TIMESTAMP
of this connection as a ResultSetSHOW READ_ONLY_STALENESS
: Returns the current value ofREAD_ONLY_STALENESS
of this connection as a ResultSetSET 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 ofREAD_ONLY_STALENESS
for this connection.SHOW OPTIMIZER_VERSION
: Returns the current value ofOPTIMIZER_VERSION
of this connection as a ResultSetSET OPTIMIZER_VERSION='<version>' | 'LATEST'
: Sets the value ofOPTIMIZER_VERSION
for this connection.SHOW OPTIMIZER_STATISTICS_PACKAGE
: Returns the current value ofOPTIMIZER_STATISTICS_PACKAGE
of this connection as a ResultSetSET OPTIMIZER_STATISTICS_PACKAGE='<package>' | ''
: Sets the value ofOPTIMIZER_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 whenCOMMIT [TRANSACTION]
orROLLBACK [TRANSACTION]
is executedCOMMIT [TRANSACTION]
: Commits the current transactionROLLBACK [TRANSACTION]
: Rollbacks the current transactionSET 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.
ConnectionOptions.ExternalChannelProvider
ExternalChannelProvider can be used for to specify an external channel provider. This is needed if you require different certificates than those provided by the standard grpc channel provider.
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).
Enums
AbstractStatementParser.StatementType
The type of statement that has been recognized by the parser.
AutocommitDmlMode
Enum used to define the behavior of DML statements in autocommit mode
StatementResult.ClientSideStatementType
The type of client side statement that was executed.
StatementResult.ResultType
Enum indicating the type of result that was returned by Connection#execute(com.google.cloud.spanner.Statement)
TransactionMode
Enum used to define the transaction type of a Connection
TransactionRetryListener.RetryResult
The result of a retry.