Package com.google.cloud.spanner.connection (6.52.0)

Version 6.52.0

• 6.82.0 (latest)
• 6.80.1
• 6.79.0
• 6.77.0
• 6.74.1
• 6.72.0
• 6.71.0
• 6.69.0
• 6.68.0
• 6.66.0
• 6.65.1
• 6.62.0
• 6.60.0
• 6.58.0
• 6.57.0
• 6.56.0
• 6.55.0
• 6.54.0
• 6.53.0
• 6.52.1
• 6.51.0
• 6.50.1
• 6.49.0
• 6.25.1
• 6.24.0
• 6.23.4
• 6.22.0
• 6.21.2
• 6.20.0
• 6.19.1
• 6.18.0
• 6.17.4
• 6.14.1

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.

PartitionId

Contains a reference to a BatchTransactionId and a Partition. The combination of these two are needed to execute a partition of a partitioned query on a Connection. A PartitionId can safely be given to a different connection and/or host to be executed there.

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 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.

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.

PartitionedQueryResultSet

Result set that is returned for partitioned queries.

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

SavepointSupport

Option value used for determining the behavior of savepoints.

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.