Interface Connection (6.82.0) 

public interface Connection extends AutoCloseable

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.

Implements

AutoCloseable

Methods

abortBatch()

public abstract void abortBatch()

Clears all buffered statements in the current batch and ends the batch.

This method may only be called when a (possibly empty) batch is active.

addTransactionRetryListener(TransactionRetryListener listener)

public abstract void addTransactionRetryListener(TransactionRetryListener listener)

Add a TransactionRetryListener to this Connection for testing and logging purposes. The method TransactionRetryListener#retryStarting(Timestamp, long, int) will be called before an automatic retry is started for a read/write transaction on this connection. The method TransactionRetryListener#retryFinished(Timestamp, long, int, TransactionRetryListener.RetryResult) will be called after the retry has finished.

Parameter
Name Description
listener TransactionRetryListener

The listener to add to this connection.

analyzeQuery(Statement query, ReadContext.QueryAnalyzeMode queryMode)

public abstract ResultSet analyzeQuery(Statement query, ReadContext.QueryAnalyzeMode queryMode)

Analyzes a query or a DML statement and returns query plan and/or query execution statistics information.

The query plan and query statistics information is contained in com.google.spanner.v1.ResultSetStats that can be accessed by calling ResultSet#getStats() on the returned ResultSet.

 
 
 ResultSet resultSet =
     connection.analyzeQuery(
         Statement.of("SELECT SingerId, AlbumId, MarketingBudget FROM Albums"),
         ReadContext.QueryAnalyzeMode.PROFILE);
 while (resultSet.next()) {
   // Discard the results. We're only processing because getStats() below requires it.
 }
 ResultSetStats stats = resultSet.getStats();
Parameters
Name Description
query Statement

the query statement to execute
queryMode ReadContext.QueryAnalyzeMode

the mode in which to execute the query
Returns
Type Description
ResultSet

analyzeUpdate(Statement update, ReadContext.QueryAnalyzeMode analyzeMode) (deprecated)

public default ResultSetStats analyzeUpdate(Statement update, ReadContext.QueryAnalyzeMode analyzeMode)

Deprecated. Use #analyzeUpdateStatement(Statement, QueryAnalyzeMode, UpdateOption...) instead

Analyzes a DML statement and returns query plan and/or execution statistics information.

com.google.cloud.spanner.ReadContext.QueryAnalyzeMode#PLAN only returns the plan for the statement. com.google.cloud.spanner.ReadContext.QueryAnalyzeMode#PROFILE executes the DML statement, returns the modified row count and execution statistics, and the effects of the DML statement will be visible to subsequent operations in the transaction.

Parameters
Name Description
update Statement
analyzeMode ReadContext.QueryAnalyzeMode
Returns
Type Description
ResultSetStats

analyzeUpdateStatement(Statement statement, ReadContext.QueryAnalyzeMode analyzeMode, Options.UpdateOption[] options)

public default ResultSet analyzeUpdateStatement(Statement statement, ReadContext.QueryAnalyzeMode analyzeMode, Options.UpdateOption[] options)

Analyzes a DML statement and returns execution plan, undeclared parameters and optionally execution statistics information.

com.google.cloud.spanner.ReadContext.QueryAnalyzeMode#PLAN only returns the plan and undeclared parameters for the statement. com.google.cloud.spanner.ReadContext.QueryAnalyzeMode#PROFILE also executes the DML statement, returns the modified row count and execution statistics, and the effects of the DML statement will be visible to subsequent operations in the transaction.

Parameters
Name Description
statement Statement
analyzeMode ReadContext.QueryAnalyzeMode
options UpdateOption[]
Returns
Type Description
ResultSet

beginTransaction()

public abstract void beginTransaction()

Begins a new transaction for this connection.

  • Calling this method on a connection that has no transaction and that is not in autocommit mode, will register a new transaction that has not yet started on this connection
  • Calling this method on a connection that has no transaction and that is in autocommit mode, will register a new transaction that has not yet started on this connection, and temporarily turn off autocommit mode until the next commit/rollback
  • Calling this method on a connection that already has a transaction that has not yet started, will cause a SpannerException
  • Calling this method on a connection that already has a transaction that has started, will cause a SpannerException (no nested transactions)

beginTransactionAsync()

public abstract ApiFuture<Void> beginTransactionAsync()

Begins a new transaction for this connection. This method is guaranteed to be non-blocking. The returned ApiFuture will be done when the transaction has been initialized.

  • Calling this method on a connection that has no transaction and that is not in autocommit mode, will register a new transaction that has not yet started on this connection
  • Calling this method on a connection that has no transaction and that is in autocommit mode, will register a new transaction that has not yet started on this connection, and temporarily turn off autocommit mode until the next commit/rollback
  • Calling this method on a connection that already has a transaction that has not yet started, will cause a SpannerException
  • Calling this method on a connection that already has a transaction that has started, will cause a SpannerException (no nested transactions)
Returns
Type Description
ApiFuture<Void>

bufferedWrite(Mutation mutation)

public abstract void bufferedWrite(Mutation mutation)

Buffers the given mutation locally on the current transaction of this Connection. The mutation will be written to the database at the next call to Connection#commit(). The value will not be readable on this Connection before the transaction is committed.

Calling this method is only allowed when not in autocommit mode. See Connection#write(Mutation) for writing mutations in autocommit mode.

Parameter
Name Description
mutation Mutation

the Mutation to buffer for writing to the database on the next commit

bufferedWrite(Iterable<Mutation> mutations)

public abstract void bufferedWrite(Iterable<Mutation> mutations)

Buffers the given mutations locally on the current transaction of this Connection. The mutations will be written to the database at the next call to Connection#commit(). The values will not be readable on this Connection before the transaction is committed.

Calling this method is only allowed when not in autocommit mode. See Connection#write(Iterable) for writing mutations in autocommit mode.

Parameter
Name Description
mutations Iterable<Mutation>

the Mutations to buffer for writing to the database on the next commit

cancel()

public abstract void cancel()

Cancels the currently running statement on this Connection (if any). If canceling the statement execution succeeds, the statement will be terminated and a SpannerException with code ErrorCode#CANCELLED will be thrown. The result of the statement will be the same as when a statement times out (see Connection#setStatementTimeout(long, TimeUnit) for more information).

Canceling a DDL statement in autocommit mode or a RUN BATCH statement of a DDL batch will cause the connection to try to cancel the execution of the DDL statement(s). This is not guaranteed to cancel the execution of the statement(s) on Cloud Spanner. See https://cloud.google.com/spanner/docs/reference/rpc/google.longrunning#google.longrunning.Operations.CancelOperation for more information.

Canceling a DML statement that is running in AutocommitDmlMode#PARTITIONED_NON_ATOMIC mode will not cancel a statement on Cloud Spanner that is already being executed, and its effects will still be applied to the database.

clearStatementTimeout()

public abstract void clearStatementTimeout()

Clears the statement timeout value for this connection. This is a no-op if there is currently no statement timeout set on this connection.

close()

public abstract void close()

Closes this connection. This is a no-op if the Connection has already been closed.

closeAsync()

public abstract ApiFuture<Void> closeAsync()

Closes this connection without blocking. This is a no-op if the Connection has already been closed. The Connection is no longer usable directly after calling this method. The returned ApiFuture is done when the running statement(s) (if any) on the connection have finished.

Returns
Type Description
ApiFuture<Void>

commit()

public abstract void commit()

Commits the current transaction of this connection. All mutations that have been buffered during the current transaction will be written to the database.

If the connection is in autocommit mode, and there is a temporary transaction active on this connection, calling this method will cause the connection to go back to autocommit mode after calling this method.

This method will throw a SpannerException with code ErrorCode#DEADLINE_EXCEEDED if a statement timeout has been set on this connection, and the commit operation takes longer than this timeout.

  • Calling this method on a connection in autocommit mode and with no temporary transaction, will cause an exception
  • Calling this method while a DDL batch is active will cause an exception
  • Calling this method on a connection with a transaction that has not yet started, will end that transaction and any properties that might have been set on that transaction, and return the connection to its previous state. This means that if a transaction is created and set to read-only, and then committed before any statements have been executed, the read-only transaction is ended and any subsequent statements will be executed in a new transaction. If the connection is in read-write mode, the default for new transactions will be TransactionMode#READ_WRITE_TRANSACTION. Committing an empty transaction also does not generate a read timestamp or a commit timestamp, and calling one of the methods Connection#getReadTimestamp() or Connection#getCommitTimestamp() will cause an exception.
  • Calling this method on a connection with a TransactionMode#READ_ONLY_TRANSACTION transaction will end that transaction. If the connection is in read-write mode, any subsequent transaction will by default be a TransactionMode#READ_WRITE_TRANSACTION transaction, unless any following transaction is explicitly set to TransactionMode#READ_ONLY_TRANSACTION
  • Calling this method on a connection with a TransactionMode#READ_WRITE_TRANSACTION transaction will send all buffered mutations to the database, commit any DML statements that have been executed during this transaction and end the transaction.

commitAsync()

public abstract ApiFuture<Void> commitAsync()

Commits the current transaction of this connection. All mutations that have been buffered during the current transaction will be written to the database.

This method is guaranteed to be non-blocking. The returned ApiFuture will be done when the transaction has committed or the commit has failed.

Calling this method will always end the current transaction and start a new transaction when the next statement is executed, regardless whether this commit call succeeded or failed. If the next statement(s) rely on the results of the transaction that is being committed, it is recommended to check the status of this commit by inspecting the value of the returned ApiFuture before executing the next statement, to ensure that the commit actually succeeded.

If the connection is in autocommit mode, and there is a temporary transaction active on this connection, calling this method will cause the connection to go back to autocommit mode after calling this method.

This method will throw a SpannerException with code ErrorCode#DEADLINE_EXCEEDED if a statement timeout has been set on this connection, and the commit operation takes longer than this timeout.

  • Calling this method on a connection in autocommit mode and with no temporary transaction, will cause an exception
  • Calling this method while a DDL batch is active will cause an exception
  • Calling this method on a connection with a transaction that has not yet started, will end that transaction and any properties that might have been set on that transaction, and return the connection to its previous state. This means that if a transaction is created and set to read-only, and then committed before any statements have been executed, the read-only transaction is ended and any subsequent statements will be executed in a new transaction. If the connection is in read-write mode, the default for new transactions will be TransactionMode#READ_WRITE_TRANSACTION. Committing an empty transaction also does not generate a read timestamp or a commit timestamp, and calling one of the methods Connection#getReadTimestamp() or Connection#getCommitTimestamp() will cause an exception.
  • Calling this method on a connection with a TransactionMode#READ_ONLY_TRANSACTION transaction will end that transaction. If the connection is in read-write mode, any subsequent transaction will by default be a TransactionMode#READ_WRITE_TRANSACTION transaction, unless any following transaction is explicitly set to TransactionMode#READ_ONLY_TRANSACTION
  • Calling this method on a connection with a TransactionMode#READ_WRITE_TRANSACTION transaction will send all buffered mutations to the database, commit any DML statements that have been executed during this transaction and end the transaction.
Returns
Type Description
ApiFuture<Void>

execute(Statement statement)

public abstract StatementResult execute(Statement statement)

Executes the given statement if allowed in the current TransactionMode and connection state. The returned value depends on the type of statement:

  • Queries and DML statements with returning clause will return a ResultSet.
  • Simple DML statements will return an update count
  • DDL statements will return a ResultType#NO_RESULT
  • Connection and transaction statements (SET AUTOCOMMIT=TRUE|FALSE, SHOW AUTOCOMMIT, SET TRANSACTION READ ONLY, etc) will return either a ResultSet or ResultType#NO_RESULT, depending on the type of statement (SHOW or SET)
Parameter
Name Description
statement Statement

The statement to execute
Returns
Type Description
StatementResult

the result of the statement

execute(Statement statement, Set<StatementResult.ResultType> allowedResultTypes)

public default StatementResult execute(Statement statement, Set<StatementResult.ResultType> allowedResultTypes)

Executes the given statement if allowed in the current TransactionMode and connection state, and if the result that would be returned is in the set of allowed result types. The statement will not be sent to Cloud Spanner if the result type would not be allowed. This method can be used by drivers that must limit the type of statements that are allowed for a given method, e.g. for the java.sql.Statement#executeQuery(String) and java.sql.Statement#executeUpdate(String) methods.

The returned value depends on the type of statement:

  • Queries and DML statements with returning clause will return a ResultSet.
  • Simple DML statements will return an update count
  • DDL statements will return a ResultType#NO_RESULT
  • Connection and transaction statements (SET AUTOCOMMIT=TRUE|FALSE, SHOW AUTOCOMMIT, SET TRANSACTION READ ONLY, etc) will return either a ResultSet or ResultType#NO_RESULT, depending on the type of statement (SHOW or SET)
Parameters
Name Description
statement Statement

The statement to execute
allowedResultTypes Set<ResultType>

The result types that this method may return. The statement will not be sent to Cloud Spanner if the statement would return a result that is not one of the types in this set.
Returns
Type Description
StatementResult

the result of the statement

executeAsync(Statement statement)

public abstract AsyncStatementResult executeAsync(Statement statement)

Executes the given statement if allowed in the current TransactionMode and connection state asynchronously. The returned value depends on the type of statement:

  • Queries and DML statements with returning clause will return an AsyncResultSet.
  • Simple DML statements will return an ApiFuture with an update count that is done when the DML statement has been applied successfully, or that throws an ExecutionException if the DML statement failed.
  • DDL statements will return an ApiFuture containing a Void that is done when the DDL statement has been applied successfully, or that throws an ExecutionException if the DDL statement failed.
  • Connection and transaction statements (SET AUTOCOMMIT=TRUE|FALSE, SHOW AUTOCOMMIT, SET TRANSACTION READ ONLY, etc) will return either a ResultSet or ResultType#NO_RESULT, depending on the type of statement (SHOW or SET)

This method is guaranteed to be non-blocking.

Parameter
Name Description
statement Statement

The statement to execute
Returns
Type Description
AsyncStatementResult

the result of the statement

executeBatchUpdate(Iterable<Statement> updates)

public abstract long[] executeBatchUpdate(Iterable<Statement> updates)

Executes a list of DML statements (can be simple DML statements or DML statements with returning clause) in a single request. The statements will be executed in order and the semantics is the same as if each statement is executed by Connection#executeUpdate(Statement) in a loop. This method returns an array of long integers, each representing the number of rows modified by each statement.

If an individual statement fails, execution stops and a SpannerBatchUpdateException is returned, which includes the error and the number of rows affected by the statements that are run prior to the error.

For example, if statements contains 3 statements, and the 2nd one is not a valid DML. This method throws a SpannerBatchUpdateException that contains the error message from the 2nd statement, and an array of length 1 that contains the number of rows modified by the 1st statement. The 3rd statement will not run. Executes the given statements as DML statements in one batch. If one of the statements does not contain a valid DML statement, the method will throw a SpannerException.

Parameter
Name Description
updates Iterable<Statement>

The update statements that will be executed as one batch.
Returns
Type Description
long[]

an array containing the update counts per statement.

executeBatchUpdateAsync(Iterable<Statement> updates)

public abstract ApiFuture<long[]> executeBatchUpdateAsync(Iterable<Statement> updates)

Executes a list of DML statements (can be simple DML statements or DML statements with returning clause) in a single request. The statements will be executed in order and the semantics is the same as if each statement is executed by Connection#executeUpdate(Statement) in a loop. This method returns an ApiFuture that contains an array of long integers, each representing the number of rows modified by each statement.

This method is guaranteed to be non-blocking.

If an individual statement fails, execution stops and a SpannerBatchUpdateException is returned, which includes the error and the number of rows affected by the statements that are run prior to the error.

For example, if statements contains 3 statements, and the 2nd one is not a valid DML. This method throws a SpannerBatchUpdateException that contains the error message from the 2nd statement, and an array of length 1 that contains the number of rows modified by the 1st statement. The 3rd statement will not run. Executes the given statements as DML statements in one batch. If one of the statements does not contain a valid DML statement, the method will throw a SpannerException.

Parameter
Name Description
updates Iterable<Statement>

The update statements that will be executed as one batch.
Returns
Type Description
ApiFuture<long[]>

an ApiFuture containing an array with the update counts per statement.

executeQuery(Statement query, Options.QueryOption[] options)

public abstract ResultSet executeQuery(Statement query, Options.QueryOption[] options)

Executes the given statement (a query or a DML statement with returning clause) and returns the result as a ResultSet. This method blocks and waits for a response from Spanner. If the statement does not contain a valid query or a DML statement with returning clause, the method will throw a SpannerException.

Parameters
Name Description
query Statement

The query statement or DML statement with returning clause to execute
options QueryOption[]

the options to configure the query
Returns
Type Description
ResultSet

a ResultSet with the results of the statement

executeQueryAsync(Statement query, Options.QueryOption[] options)

public abstract AsyncResultSet executeQueryAsync(Statement query, Options.QueryOption[] options)

Executes the given statement (a query or a DML statement with returning clause) asynchronously and returns the result as an AsyncResultSet. This method is guaranteed to be non-blocking. If the statement does not contain a valid query or a DML statement with returning clause, the method will throw a SpannerException.

See AsyncResultSet#setCallback(java.util.concurrent.Executor, com.google.cloud.spanner.AsyncResultSet.ReadyCallback) for more information on how to consume the results of the statement asynchronously.

It is also possible to consume the returned AsyncResultSet in the same way as a normal ResultSet, i.e. in a while-loop calling AsyncResultSet#next().

Parameters
Name Description
query Statement

The query statement or DML statement with returning clause to execute
options QueryOption[]

the options to configure the query
Returns
Type Description
AsyncResultSet

an AsyncResultSet with the results of the statement

executeUpdate(Statement update)

public abstract long executeUpdate(Statement update)

Executes the given statement as a simple DML statement. If the statement does not contain a valid DML statement, the method will throw a SpannerException.

Parameter
Name Description
update Statement

The update statement to execute
Returns
Type Description
long

the number of records that were inserted/updated/deleted by this statement

executeUpdateAsync(Statement update)

public abstract ApiFuture<Long> executeUpdateAsync(Statement update)

Executes the given statement asynchronously as a simple DML statement. If the statement does not contain a simple DML statement, the method will throw a SpannerException. A DML statement with returning clause will throw a SpannerException.

This method is guaranteed to be non-blocking.

Parameter
Name Description
update Statement

The update statement to execute
Returns
Type Description
ApiFuture<Long>

an ApiFuture containing the number of records that were inserted/updated/deleted by this statement

getAutoBatchDmlUpdateCount()

public abstract long getAutoBatchDmlUpdateCount()

Returns the update count that is returned for DML statements that are buffered during an automatic DML batch.

Returns
Type Description
long

getAutocommitDmlMode()

public abstract AutocommitDmlMode getAutocommitDmlMode()
Returns
Type Description
AutocommitDmlMode

the current AutocommitDmlMode setting for this connection. This method may only be called on a connection that is in autocommit mode and not while in a temporary transaction.

getCommitResponse()

public abstract CommitResponse getCommitResponse()
Returns
Type Description
CommitResponse

the CommitResponse of the last TransactionMode#READ_WRITE_TRANSACTION transaction. This method throws a SpannerException if there is no last TransactionMode#READ_WRITE_TRANSACTION transaction. That is, if the last transaction was a TransactionMode#READ_ONLY_TRANSACTION), or if the last TransactionMode#READ_WRITE_TRANSACTION transaction rolled back. It also throws a SpannerException if the last TransactionMode#READ_WRITE_TRANSACTION transaction was empty when committed.

getCommitTimestamp()

public abstract Timestamp getCommitTimestamp()
Returns
Type Description
com.google.cloud.Timestamp

the commit timestamp of the last TransactionMode#READ_WRITE_TRANSACTION transaction. This method throws a SpannerException if there is no last TransactionMode#READ_WRITE_TRANSACTION transaction. That is, if the last transaction was a TransactionMode#READ_ONLY_TRANSACTION), or if the last TransactionMode#READ_WRITE_TRANSACTION transaction rolled back. It also throws a SpannerException if the last TransactionMode#READ_WRITE_TRANSACTION transaction was empty when committed.

getDatabaseClient()

public default DatabaseClient getDatabaseClient()

The DatabaseClient that is used by this Connection.

Returns
Type Description
DatabaseClient

getDdlInTransactionMode()

public abstract DdlInTransactionMode getDdlInTransactionMode()

Returns the current DdlInTransactionMode for this connection.

Returns
Type Description
DdlInTransactionMode

getDialect()

public default Dialect getDialect()

The Dialect that is used by this Connection.

Returns
Type Description
Dialect

getDirectedRead()

public default DirectedReadOptions getDirectedRead()

Returns the DirectedReadOptions that are used for both single-use and multi-use read-only transactions on this connection.

Returns
Type Description
DirectedReadOptions

getMaxCommitDelay()

public default Duration getMaxCommitDelay()

Returns the max_commit_delay that will be applied to commit requests from this connection.

Returns
Type Description
Duration

getMaxPartitionedParallelism()

public abstract int getMaxPartitionedParallelism()

Returns the maximum degree of parallelism that is used for #runPartitionedQuery(Statement, PartitionOptions, QueryOption...)

Returns
Type Description
int

getMaxPartitions()

public abstract int getMaxPartitions()

Gets the maximum number of partitions that should be included as a hint to Cloud Spanner when partitioning a query on this connection. Note that this is only a hint and Cloud Spanner might choose to ignore the hint.

Returns
Type Description
int

getOptimizerStatisticsPackage()

public default String getOptimizerStatisticsPackage()

Gets the current query optimizer statistics package of this connection.

Returns
Type Description
String

The query optimizer statistics package that is currently used by this connection.

getOptimizerVersion()

public abstract String getOptimizerVersion()

Gets the current query optimizer version of this connection.

Returns
Type Description
String

The query optimizer version that is currently used by this connection.

getProtoDescriptors()

public default byte[] getProtoDescriptors()
Returns
Type Description
byte[]

The proto descriptor that will be used with the next DDL statement (single or batch) that is executed on this connection.

getRPCPriority()

public default Options.RpcPriority getRPCPriority()

Gets the current RPC priority of this connection.

Returns
Type Description
Options.RpcPriority

The RPC priority that is currently used by this connection.

getReadOnlyStaleness()

public abstract TimestampBound getReadOnlyStaleness()
Returns
Type Description
TimestampBound

the read-only staleness setting for the current read-only transaction. This method may only be called when the current transaction is a read-only transaction, or when the connection is in read-only and autocommit mode.

getReadTimestamp()

public abstract Timestamp getReadTimestamp()

Returns the read timestamp of the current/last TransactionMode#READ_ONLY_TRANSACTION transaction, or the read timestamp of the last query in autocommit mode.

  • When in autocommit mode: The method will return the read timestamp of the last statement if the last statement was a query.
  • When in a TransactionMode#READ_ONLY_TRANSACTION transaction that has started (a query has been executed), or that has just committed: The read timestamp of the transaction. If the read-only transaction was committed without ever executing a query, calling this method after the commit will also throw a SpannerException
  • In all other cases the method will throw a SpannerException.
Returns
Type Description
com.google.cloud.Timestamp

the read timestamp of the current/last read-only transaction.

getSavepointSupport()

public abstract SavepointSupport getSavepointSupport()

Returns the current savepoint support for this connection.

Returns
Type Description
SavepointSupport

getSpanner()

public default Spanner getSpanner()

The Spanner instance that is used by this Connection.

Returns
Type Description
Spanner

getStatementTag()

public default String getStatementTag()
Returns
Type Description
String

The statement tag that will be used with the next statement that is executed on this connection.

getStatementTimeout(TimeUnit unit)

public abstract long getStatementTimeout(TimeUnit unit)
Parameter
Name Description
unit TimeUnit

The TimeUnit to get the timeout value in. Must be one of TimeUnit#NANOSECONDS, TimeUnit#MICROSECONDS, TimeUnit#MILLISECONDS, TimeUnit#SECONDS
Returns
Type Description
long

the current statement timeout value or 0 if no timeout value has been set.

getTransactionMode()

public abstract TransactionMode getTransactionMode()
Returns
Type Description
TransactionMode

the transaction mode of the current transaction. This method may only be called when the connection is in a transaction.

getTransactionRetryListeners()

public abstract Iterator<TransactionRetryListener> getTransactionRetryListeners()
Returns
Type Description
Iterator<TransactionRetryListener>

an unmodifiable iterator of the TransactionRetryListeners registered for this connection.

getTransactionTag()

public default String getTransactionTag()
Returns
Type Description
String

The transaction tag of the current transaction.

hasStatementTimeout()

public abstract boolean hasStatementTimeout()
Returns
Type Description
boolean

true if this Connection has a statement timeout value.

isAutoBatchDml()

public abstract boolean isAutoBatchDml()

Returns whether automatic DML batching is enabled on this connection.

Returns
Type Description
boolean

isAutoBatchDmlUpdateCountVerification()

public abstract boolean isAutoBatchDmlUpdateCountVerification()

Indicates whether the update counts of automatic DML batches should be verified.

Returns
Type Description
boolean

isAutoPartitionMode()

public abstract boolean isAutoPartitionMode()

Returns whether this connection will execute all queries as partitioned queries.

Returns
Type Description
boolean

isAutocommit()

public abstract boolean isAutocommit()
Returns
Type Description
boolean

true if this connection is in autocommit mode

isClosed()

public abstract boolean isClosed()
Returns
Type Description
boolean

true if this connection has been closed.

isDataBoostEnabled()

public abstract boolean isDataBoostEnabled()

Returns whether data boost is enabled for partitioned queries. See also #partitionQuery(Statement, PartitionOptions, QueryOption...)

Returns
Type Description
boolean

isDdlBatchActive()

public abstract boolean isDdlBatchActive()
Returns
Type Description
boolean

true if a DDL batch is active on this connection.

isDelayTransactionStartUntilFirstWrite()

public default boolean isDelayTransactionStartUntilFirstWrite()
Returns
Type Description
boolean

true if this connection delays the actual start of a read/write transaction until the first write operation on that transaction.

isDmlBatchActive()

public abstract boolean isDmlBatchActive()
Returns
Type Description
boolean

true if a DML batch is active on this connection.

isExcludeTxnFromChangeStreams()

public default boolean isExcludeTxnFromChangeStreams()

Returns true if the next transaction should be excluded from all change streams with the DDL option allow_txn_exclusion=true

Returns
Type Description
boolean

isInTransaction()

public abstract boolean isInTransaction()
Returns
Type Description
boolean

true if this connection has a transaction (that has not necessarily started). This method will only return false when the Connection is in autocommit mode and no explicit transaction has been started by calling Connection#beginTransaction(). If the Connection is not in autocommit mode, there will always be a transaction.

isKeepTransactionAlive()

public default boolean isKeepTransactionAlive()
Returns
Type Description
boolean

true if this connection keeps read/write transactions alive by executing a SELECT 1 once every 10 seconds during inactive read/write transactions.

isReadOnly()

public abstract boolean isReadOnly()
Returns
Type Description
boolean

true if this connection is in read-only mode

isRetryAbortsInternally()

public abstract boolean isRetryAbortsInternally()
Returns
Type Description
boolean

true if this connection will automatically retry read/write transactions that abort. This method may only be called when the connection is in read/write transactional mode and no transaction has been started yet.

isReturnCommitStats()

public abstract boolean isReturnCommitStats()
Returns
Type Description
boolean

true if this connection requests commit statistics from Cloud Spanner

isTransactionStarted()

public abstract boolean isTransactionStarted()
Returns
Type Description
boolean

true if this connection has a transaction that has started. A transaction is automatically started by the first statement that is executed in the transaction.

partitionQuery(Statement query, PartitionOptions partitionOptions, Options.QueryOption[] options)

public abstract ResultSet partitionQuery(Statement query, PartitionOptions partitionOptions, Options.QueryOption[] options)

Partitions the given query, so it can be executed in parallel. This method returns a ResultSet with a string-representation of the partitions that were created. These strings can be used to execute a partition either on this connection or an any other connection (on this host or an any other host) by calling the method #runPartition(String). This method will automatically enable data boost for the query if #isDataBoostEnabled() returns true.

Parameters
Name Description
query Statement
partitionOptions PartitionOptions
options QueryOption[]
Returns
Type Description
ResultSet

releaseSavepoint(String name)

public abstract void releaseSavepoint(String name)

Releases the savepoint with the given name. The savepoint and all later savepoints will be removed from the current transaction and can no longer be used.

Parameter
Name Description
name String

the name of the savepoint to release

removeTransactionRetryListener(TransactionRetryListener listener)

public abstract boolean removeTransactionRetryListener(TransactionRetryListener listener)

Removes one existing TransactionRetryListener from this Connection, if it is present (optional operation).

Parameter
Name Description
listener TransactionRetryListener

The listener to remove from the connection.
Returns
Type Description
boolean

true if a listener was removed from the connection.

reset()

public abstract void reset()

Resets the state of this connection to the default state that it had when it was first created. Calling this method after a transaction has started (that is; after a statement has been executed in the transaction), does not change the active transaction. If for example a transaction has been started with a transaction tag, the transaction tag for the active transaction is not reset.

You can use this method to reset the state of the connection before returning a connection to a connection pool, and/or before using a connection that was retrieved from a connection pool.

rollback()

public abstract void rollback()

Rollbacks the current transaction of this connection. All mutations or DDL statements that have been buffered during the current transaction will be removed from the buffer.

If the connection is in autocommit mode, and there is a temporary transaction active on this connection, calling this method will cause the connection to go back to autocommit mode after calling this method.

  • Calling this method on a connection in autocommit mode and with no temporary transaction will cause an exception
  • Calling this method while a DDL batch is active will cause an exception
  • Calling this method on a connection with a transaction that has not yet started, will end that transaction and any properties that might have been set on that transaction, and return the connection to its previous state. This means that if a transaction is created and set to read-only, and then rolled back before any statements have been executed, the read-only transaction is ended and any subsequent statements will be executed in a new transaction. If the connection is in read-write mode, the default for new transactions will be TransactionMode#READ_WRITE_TRANSACTION.
  • Calling this method on a connection with a TransactionMode#READ_ONLY_TRANSACTION transaction will end that transaction. If the connection is in read-write mode, any subsequent transaction will by default be a TransactionMode#READ_WRITE_TRANSACTION transaction, unless any following transaction is explicitly set to TransactionMode#READ_ONLY_TRANSACTION
  • Calling this method on a connection with a TransactionMode#READ_WRITE_TRANSACTION transaction will clear all buffered mutations, rollback any DML statements that have been executed during this transaction and end the transaction.

rollbackAsync()

public abstract ApiFuture<Void> rollbackAsync()

Rollbacks the current transaction of this connection. All mutations or DDL statements that have been buffered during the current transaction will be removed from the buffer.

This method is guaranteed to be non-blocking. The returned ApiFuture will be done when the transaction has been rolled back.

If the connection is in autocommit mode, and there is a temporary transaction active on this connection, calling this method will cause the connection to go back to autocommit mode after calling this method.

  • Calling this method on a connection in autocommit mode and with no temporary transaction will cause an exception
  • Calling this method while a DDL batch is active will cause an exception
  • Calling this method on a connection with a transaction that has not yet started, will end that transaction and any properties that might have been set on that transaction, and return the connection to its previous state. This means that if a transaction is created and set to read-only, and then rolled back before any statements have been executed, the read-only transaction is ended and any subsequent statements will be executed in a new transaction. If the connection is in read-write mode, the default for new transactions will be TransactionMode#READ_WRITE_TRANSACTION.
  • Calling this method on a connection with a TransactionMode#READ_ONLY_TRANSACTION transaction will end that transaction. If the connection is in read-write mode, any subsequent transaction will by default be a TransactionMode#READ_WRITE_TRANSACTION transaction, unless any following transaction is explicitly set to TransactionMode#READ_ONLY_TRANSACTION
  • Calling this method on a connection with a TransactionMode#READ_WRITE_TRANSACTION transaction will clear all buffered mutations, rollback any DML statements that have been executed during this transaction and end the transaction.
Returns
Type Description
ApiFuture<Void>

rollbackToSavepoint(String name)

public abstract void rollbackToSavepoint(String name)

Rolls back to the given savepoint. Rolling back to a savepoint undoes all changes and releases all internal locks that have been taken by the transaction after the savepoint. Rolling back to a savepoint does not remove the savepoint from the transaction, and it is possible to roll back to the same savepoint multiple times. All savepoints that have been defined after the given savepoint are removed from the transaction.

Parameter
Name Description
name String

the name of the savepoint to roll back to.

runBatch()

public abstract long[] runBatch()

Sends all buffered DML or DDL statements of the current batch to the database, waits for these to be executed and ends the current batch. The method will throw an exception for the first statement that cannot be executed, or return successfully if all statements could be executed. If an exception is thrown for a statement in the batch, the preceding statements in the same batch may still have been applied to the database.

This method may only be called when a (possibly empty) batch is active.

Returns
Type Description
long[]

the update counts in case of a DML batch. Returns an array containing 1 for each successful statement and 0 for each failed statement or statement that was not executed in case of a DDL batch.

runBatchAsync()

public abstract ApiFuture<long[]> runBatchAsync()

Sends all buffered DML or DDL statements of the current batch to the database, waits for these to be executed and ends the current batch. The method will throw an exception for the first statement that cannot be executed, or return successfully if all statements could be executed. If an exception is thrown for a statement in the batch, the preceding statements in the same batch may still have been applied to the database.

This method is guaranteed to be non-blocking. The returned ApiFuture will be done when the batch has been successfully applied, or when one or more of the statements in the batch has failed and the further execution of the batch has been halted.

This method may only be called when a (possibly empty) batch is active.

Returns
Type Description
ApiFuture<long[]>

an ApiFuture containing the update counts in case of a DML batch. The ApiFuture contains an array containing 1 for each successful statement and 0 for each failed statement or statement that was not executed in case of a DDL batch.

runPartition(String encodedPartitionId)

public abstract ResultSet runPartition(String encodedPartitionId)

Executes the given partition of a query. The encodedPartitionId should be a string that was returned by #partitionQuery(Statement, PartitionOptions, QueryOption...).

Parameter
Name Description
encodedPartitionId String
Returns
Type Description
ResultSet

runPartitionedQuery(Statement query, PartitionOptions partitionOptions, Options.QueryOption[] options)

public abstract PartitionedQueryResultSet runPartitionedQuery(Statement query, PartitionOptions partitionOptions, Options.QueryOption[] options)

Executes the given query as a partitioned query. The query will first be partitioned using the #partitionQuery(Statement, PartitionOptions, QueryOption...) method. Each of the partitions will then be executed in the background, and the results will be merged into a single result set.

This method will use maxPartitionedParallelism threads to execute the partitioned query. Set this variable to a higher/lower value to increase/decrease the degree of parallelism used for execution.

Parameters
Name Description
query Statement
partitionOptions PartitionOptions
options QueryOption[]
Returns
Type Description
PartitionedQueryResultSet

savepoint(String name)

public abstract void savepoint(String name)

Creates a savepoint with the given name.

The uniqueness constraints on a savepoint name depends on the database dialect that is used:

  • Dialect#GOOGLE_STANDARD_SQL requires that savepoint names are unique within a transaction. The name of a savepoint that has been released or destroyed because the transaction has rolled back to a savepoint that was defined before that savepoint can be re-used within the transaction.
  • Dialect#POSTGRESQL follows the rules for savepoint names in PostgreSQL. This means that multiple savepoints in one transaction can have the same name, but only the last savepoint with a given name is visible. See PostgreSQL savepoint documentation for more information.
Parameter
Name Description
name String

the name of the savepoint to create

setAutoBatchDml(boolean autoBatchDml)

public abstract void setAutoBatchDml(boolean autoBatchDml)

Enables or disables automatic batching of DML statements. When enabled, DML statements that are executed on this connection will be buffered in memory instead of actually being executed. The buffered DML statements are flushed to Spanner when a statement that cannot be part of a DML batch is executed on the connection. This can be a query, a DDL statement with a THEN RETURN clause, or a Commit call. The update count that is returned for DML statements that are buffered is determined by the value that has been set with #setAutoBatchDmlUpdateCount(long). The default is 1. The connection verifies that the update counts that were returned while buffering DML statements match the actual update counts that are returned by Spanner when the batch is executed. This verification can be disabled by calling #setAutoBatchDmlUpdateCountVerification(boolean).

Parameter
Name Description
autoBatchDml boolean

setAutoBatchDmlUpdateCount(long updateCount)

public abstract void setAutoBatchDmlUpdateCount(long updateCount)

Sets the update count that is returned for DML statements that are buffered during an automatic DML batch. This value is only used if #isAutoBatchDml() is enabled.

Parameter
Name Description
updateCount long

setAutoBatchDmlUpdateCountVerification(boolean verification)

public abstract void setAutoBatchDmlUpdateCountVerification(boolean verification)

Sets whether the update count that is returned by Spanner after executing an automatic DML batch should be verified against the update counts that were returned during the buffering of those statements.

Parameter
Name Description
verification boolean

setAutoPartitionMode(boolean autoPartitionMode)

public abstract void setAutoPartitionMode(boolean autoPartitionMode)

Sets whether this connection should always use partitioned queries when a query is executed on this connection. Setting this flag to true and then executing a query that cannot be partitioned, or executing a query in a read/write transaction, will cause an error. Use this flag in combination with #setDataBoostEnabled(boolean) to force all queries on this connection to use data boost.

Parameter
Name Description
autoPartitionMode boolean

setAutocommit(boolean autocommit)

public abstract void setAutocommit(boolean autocommit)

Sets autocommit on/off for this Connection. Connections in autocommit mode will apply any changes to the database directly without waiting for an explicit commit. DDL- and DML statements as well as Mutations are sent directly to Spanner, and committed automatically unless the statement caused an error. The statement is retried in case of an AbortedException. All other errors will cause the underlying transaction to be rolled back.

A Connection that is in autocommit and read/write mode will allow all types of statements: Queries, DML, DDL, and Mutations (writes). If the connection is in read-only mode, only queries will be allowed.

Connections in autocommit mode may also accept partitioned DML statements. See Connection#setAutocommitDmlMode(AutocommitDmlMode) for more information.

Parameter
Name Description
autocommit boolean

true/false to turn autocommit on/off

setAutocommitDmlMode(AutocommitDmlMode mode)

public abstract void setAutocommitDmlMode(AutocommitDmlMode mode)

Sets the mode for executing DML statements in autocommit mode for this connection. This setting is only used when the connection is in autocommit mode, and may only be set while the transaction is in autocommit mode and not in a temporary transaction. The autocommit transaction mode is reset to its default value of AutocommitDmlMode#TRANSACTIONAL when autocommit mode is changed on the connection.

Parameter
Name Description
mode AutocommitDmlMode

The DML autocommit mode to use

  • AutocommitDmlMode#TRANSACTIONAL DML statements are executed as single read-write transaction. After successful execution, the DML statement is guaranteed to have been applied exactly once to the database
  • AutocommitDmlMode#PARTITIONED_NON_ATOMIC DML statements are executed as partitioned DML transactions. If an error occurs during the execution of the DML statement, it is possible that the statement has been applied to some but not all of the rows specified in the statement.

setDataBoostEnabled(boolean dataBoostEnabled)

public abstract void setDataBoostEnabled(boolean dataBoostEnabled)

Enable data boost for partitioned queries. See also #partitionQuery(Statement, PartitionOptions, QueryOption...)

Parameter
Name Description
dataBoostEnabled boolean

setDdlInTransactionMode(DdlInTransactionMode ddlInTransactionMode)

public abstract void setDdlInTransactionMode(DdlInTransactionMode ddlInTransactionMode)

Sets how the connection should behave if a DDL statement is executed during a transaction.

Parameter
Name Description
ddlInTransactionMode DdlInTransactionMode

setDelayTransactionStartUntilFirstWrite(boolean delayTransactionStartUntilFirstWrite)

public default void setDelayTransactionStartUntilFirstWrite(boolean delayTransactionStartUntilFirstWrite)

Sets whether this connection should delay the actual start of a read/write transaction until the first write operation is observed on that transaction. All read operations that are executed before the first write operation in the transaction will be executed as if the connection was in auto-commit mode. This can reduce locking, especially for transactions that execute a large number of reads before any writes, at the expense of a lower transaction isolation.

NOTE: This will make read/write transactions non-serializable.

Parameter
Name Description
delayTransactionStartUntilFirstWrite boolean

setDirectedRead(DirectedReadOptions directedReadOptions)

public default void setDirectedRead(DirectedReadOptions directedReadOptions)

Sets the DirectedReadOptions to use for both single-use and multi-use read-only transactions on this connection.

Parameter
Name Description
directedReadOptions DirectedReadOptions

setExcludeTxnFromChangeStreams(boolean excludeTxnFromChangeStreams)

public default void setExcludeTxnFromChangeStreams(boolean excludeTxnFromChangeStreams)

Sets whether the next transaction should be excluded from all change streams with the DDL option allow_txn_exclusion=true

Parameter
Name Description
excludeTxnFromChangeStreams boolean

setKeepTransactionAlive(boolean keepTransactionAlive)

public default void setKeepTransactionAlive(boolean keepTransactionAlive)

Sets whether this connection should keep read/write transactions alive by executing a SELECT 1 once every 10 seconds during inactive read/write transactions.

NOTE: This will keep read/write transactions alive and hold on to locks until it is explicitly committed or rolled back.

Parameter
Name Description
keepTransactionAlive boolean

setMaxCommitDelay(Duration maxCommitDelay)

public default void setMaxCommitDelay(Duration maxCommitDelay)

Sets the max_commit_delay that will be applied to commit requests from this connection.

Parameter
Name Description
maxCommitDelay Duration

setMaxPartitionedParallelism(int maxThreads)

public abstract void setMaxPartitionedParallelism(int maxThreads)

Sets the maximum degree of parallelism that is used when executing a partitioned query using #runPartitionedQuery(Statement, PartitionOptions, QueryOption...). The method will use up to maxThreads to execute and retrieve the results from Cloud Spanner. Set this value to 0> to use the number of available processors as returned by Runtime#availableProcessors().

Parameter
Name Description
maxThreads int

setMaxPartitions(int maxPartitions)

public abstract void setMaxPartitions(int maxPartitions)

Sets the maximum number of partitions that should be included as a hint to Cloud Spanner when partitioning a query on this connection. Note that this is only a hint and Cloud Spanner might choose to ignore the hint.

Parameter
Name Description
maxPartitions int

setOptimizerStatisticsPackage(String optimizerStatisticsPackage)

public default void setOptimizerStatisticsPackage(String optimizerStatisticsPackage)

Sets the query optimizer statistics package

Parameter
Name Description
optimizerStatisticsPackage String

The query optimizer statistics package to use. Must be a string composed of letters, numbers, dashes and underscores or an empty string. The empty string will instruct the connection to use the optimizer statistics package that is defined the environment variable SPANNER_OPTIMIZER_STATISTICS_PACKAGE. If no value is specified in the environment variable, the client level query optimizer is used. If none is set, the default query optimizer of Cloud Spanner is used.

setOptimizerVersion(String optimizerVersion)

public abstract void setOptimizerVersion(String optimizerVersion)

Sets the query optimizer version to use for this connection.

Parameter
Name Description
optimizerVersion String

The query optimizer version to use. Must be a valid optimizer version number, the string LATEST or an empty string. The empty string will instruct the connection to use the optimizer version that is defined in the environment variable SPANNER_OPTIMIZER_VERSION. If no value is specified in the environment variable, the default query optimizer of Cloud Spanner is used.

setProtoDescriptors(byte[] protoDescriptors)

public default void setProtoDescriptors(byte[] protoDescriptors)

Sets the proto descriptors to use for the next DDL statement (single or batch) that will be executed. The proto descriptor is automatically cleared after the statement is executed.

Parameter
Name Description
protoDescriptors byte[]

The proto descriptors to use with the next DDL statement (single or batch) that will be executed on this connection.

setRPCPriority(Options.RpcPriority rpcPriority)

public default void setRPCPriority(Options.RpcPriority rpcPriority)

Sets the priority to use for RPCs executed by this connection..

Parameter
Name Description
rpcPriority Options.RpcPriority

The RPC priority to use.

  • RpcPriority#HIGH This specifies that the RPC's invocation will be of high priority.
  • RpcPriority#MEDIUM This specifies that the RPC's invocation will be of medium priority.
  • RpcPriority#LOW This specifies that the RPC's invocation will be of low priority.

setReadOnly(boolean readOnly)

public abstract void setReadOnly(boolean readOnly)

Sets this connection to read-only or read-write. This method may only be called when no transaction is active. A connection that is in read-only mode, will never allow any kind of changes to the database to be submitted.

Parameter
Name Description
readOnly boolean

true/false to turn read-only mode on/off

setReadOnlyStaleness(TimestampBound staleness)

public abstract void setReadOnlyStaleness(TimestampBound staleness)

Sets the staleness to use for the current read-only transaction. This method may only be called when the transaction mode of the current transaction is TransactionMode#READ_ONLY_TRANSACTION and there is no transaction that has started, or when the connection is in read-only and autocommit mode.

Parameter
Name Description
staleness TimestampBound

The staleness to use for the current but not yet started read-only transaction

setRetryAbortsInternally(boolean retryAbortsInternally)

public abstract void setRetryAbortsInternally(boolean retryAbortsInternally)

Sets whether this connection will internally retry read/write transactions that abort. The default is true. When internal retry is enabled, the Connection will keep track of a running SHA256 checksum of all ResultSets that have been returned from Cloud Spanner. If the checksum that is calculated during an internal retry differs from the original checksum, the transaction will abort with an AbortedDueToConcurrentModificationException.

Note that retries of a read/write transaction that calls a non-deterministic function on Cloud Spanner, such as CURRENT_TIMESTAMP(), will never be successful, as the data returned during the retry will always be different from the original transaction.

It is also highly recommended that all queries in a read/write transaction have an ORDER BY clause that guarantees that the data is returned in the same order as in the original transaction if the transaction is internally retried. The most efficient way to achieve this is to always include the primary key columns at the end of the ORDER BY clause.

This method may only be called when the connection is in read/write transactional mode and no transaction has been started yet.

Parameter
Name Description
retryAbortsInternally boolean

Set to true to internally retry transactions that are aborted by Spanner. When set to false, any database call on a transaction that has been aborted by Cloud Spanner will throw an AbortedException instead of being retried. Set this to false if your application already uses retry loops to handle AbortedExceptions.

setReturnCommitStats(boolean returnCommitStats)

public abstract void setReturnCommitStats(boolean returnCommitStats)

Sets whether this connection should request commit statistics from Cloud Spanner for read/write transactions and DML statements in autocommit mode.

Parameter
Name Description
returnCommitStats boolean

setSavepointSupport(SavepointSupport savepointSupport)

public abstract void setSavepointSupport(SavepointSupport savepointSupport)

Sets how savepoints should be supported on this connection.

Parameter
Name Description
savepointSupport SavepointSupport

setStatementTag(String tag)

public default void setStatementTag(String tag)

Sets the statement tag to use for the next statement that is executed. The tag is automatically cleared after the statement is executed. Statement tags can be used both with autocommit=true and autocommit=false, and can be used for partitioned DML.

Statement tags are not allowed before COMMIT and ROLLBACK statements.

Statement tags are allowed before START BATCH DML statements and will be included in the ExecuteBatchDmlRequest that is sent to Spanner. Statement tags are not allowed inside a batch.

Parameter
Name Description
tag String

The statement tag to use with the next statement that will be executed on this connection.

setStatementTimeout(long timeout, TimeUnit unit)

public abstract void setStatementTimeout(long timeout, TimeUnit unit)

Sets the duration the connection should wait before automatically aborting the execution of a statement. The default is no timeout. Statement timeouts are applied all types of statements, both in autocommit and transactional mode. They also apply to Connection#commit() and Connection#rollback() statements.

A DML statement in autocommit mode may or may not have actually been applied to the database, depending on when the timeout occurred.

A DML statement in a transaction that times out may still have been applied to the transaction. If you still decide to commit the transaction after such a timeout, the DML statement may or may not have been part of the transaction, depending on whether the timeout occurred before or after the statement was (successfully) sent to Spanner. You should therefore either always rollback a transaction that had a DML statement that timed out, or you should accept that the timed out statement still might have been applied to the database.

DDL statements and DML statements in AutocommitDmlMode#PARTITIONED_NON_ATOMIC mode cannot be rolled back. If such a statement times out, it may or may not have been applied to the database. The same applies to commit and rollback statements.

Statements that time out will throw a SpannerException with error code ErrorCode#DEADLINE_EXCEEDED.

Parameters
Name Description
timeout long

The number of TimeUnits before a statement is automatically aborted by the connection. Zero or negative values are not allowed. The maximum allowed value is 315,576,000,000 seconds. Use Connection#clearStatementTimeout() to remove a timeout value that has been set.
unit TimeUnit

The TimeUnit to specify the timeout value in. Must be one of TimeUnit#NANOSECONDS, TimeUnit#MICROSECONDS, TimeUnit#MILLISECONDS, TimeUnit#SECONDS.

setTransactionMode(TransactionMode transactionMode)

public abstract void setTransactionMode(TransactionMode transactionMode)

Sets the transaction mode to use for current transaction. This method may only be called when in a transaction, and before the transaction is actually started, i.e. before any statements have been executed in the transaction.

Parameter
Name Description
transactionMode TransactionMode

The transaction mode to use for the current transaction.

setTransactionTag(String tag)

public default void setTransactionTag(String tag)

Sets the transaction tag to use for the current transaction. This method may only be called when in a transaction and before any statements have been executed in the transaction.

The tag will be set as the transaction tag of all statements during the transaction, and as the transaction tag of the commit.

The transaction tag will automatically be cleared after the transaction has ended.

Parameter
Name Description
tag String

The tag to use.

startBatchDdl()

public abstract void startBatchDdl()

Starts a new DDL batch on this connection. A DDL batch allows several DDL statements to be grouped into a batch that can be executed as a group. DDL statements that are issued during the batch are buffered locally and will return immediately with an OK. It is not guaranteed that a DDL statement that has been issued during a batch will eventually succeed when running the batch. Aborting a DDL batch will clear the DDL buffer and will have made no changes to the database. Running a DDL batch will send all buffered DDL statements to Spanner, and Spanner will try to execute these. The result will be OK if all the statements executed successfully. If a statement cannot be executed, Spanner will stop execution at that point and return an error message for the statement that could not be executed. Preceding statements of the batch may have been executed.

This method may only be called when the connection is in read/write mode, autocommit mode is enabled or no read/write transaction has been started, and there is not already another batch active. The connection will only accept DDL statements while a DDL batch is active.

startBatchDml()

public abstract void startBatchDml()

Starts a new DML batch on this connection. A DML batch allows several DML statements to be grouped into a batch that can be executed as a group. DML statements that are issued during the batch are buffered locally and will return immediately with an OK. It is not guaranteed that a DML statement that has been issued during a batch will eventually succeed when running the batch. Aborting a DML batch will clear the DML buffer and will have made no changes to the database. Running a DML batch will send all buffered DML statements to Spanner, and Spanner will try to execute these. The result will be OK if all the statements executed successfully. If a statement cannot be executed, Spanner will stop execution at that point and return SpannerBatchUpdateException for the statement that could not be executed. Preceding statements of the batch will have been executed, and the update counts of those statements can be retrieved through SpannerBatchUpdateException#getUpdateCounts().

This method may only be called when the connection is in read/write mode, autocommit mode is enabled or no read/write transaction has been started, and there is not already another batch active. The connection will only accept DML statements while a DML batch is active.

write(Mutation mutation)

public abstract void write(Mutation mutation)

Writes the specified mutation directly to the database and commits the change. The value is readable after the successful completion of this method. Writing multiple mutations to a database by calling this method multiple times mode is inefficient, as each call will need a round trip to the database. Instead, you should consider writing the mutations together by calling Connection#write(Iterable).

Calling this method is only allowed in autocommit mode. See Connection#bufferedWrite(Iterable) for writing mutations in transactions.

Parameter
Name Description
mutation Mutation

The Mutation to write to the database

write(Iterable<Mutation> mutations)

public abstract void write(Iterable<Mutation> mutations)

Writes the specified mutations directly to the database and commits the changes. The values are readable after the successful completion of this method.

Calling this method is only allowed in autocommit mode. See Connection#bufferedWrite(Iterable) for writing mutations in transactions.

Parameter
Name Description
mutations Iterable<Mutation>

The Mutations to write to the database

writeAsync(Mutation mutation)

public abstract ApiFuture<Void> writeAsync(Mutation mutation)

Writes the specified mutation directly to the database and commits the change. The value is readable after the successful completion of the returned ApiFuture. Writing multiple mutations to a database by calling this method multiple times mode is inefficient, as each call will need a round trip to the database. Instead, you should consider writing the mutations together by calling Connection#writeAsync(Iterable).

This method is guaranteed to be non-blocking.

Calling this method is only allowed in autocommit mode. See Connection#bufferedWrite(Iterable) for writing mutations in transactions.

Parameter
Name Description
mutation Mutation

The Mutation to write to the database
Returns
Type Description
ApiFuture<Void>

writeAsync(Iterable<Mutation> mutations)

public abstract ApiFuture<Void> writeAsync(Iterable<Mutation> mutations)

Writes the specified mutations directly to the database and commits the changes. The values are readable after the successful completion of the returned ApiFuture.

This method is guaranteed to be non-blocking.

Calling this method is only allowed in autocommit mode. See Connection#bufferedWrite(Iterable) for writing mutations in transactions.

Parameter
Name Description
mutations Iterable<Mutation>

The Mutations to write to the database
Returns
Type Description
ApiFuture<Void>