Interface CloudSpannerJdbcConnection (2.23.0)

public interface CloudSpannerJdbcConnection extends Connection

JDBC connection with a number of additional Cloud Spanner specific methods. JDBC connections that are returned by the Cloud Spanner JdbcDriver will implement this interface.

Calling Connection#unwrap(Class) with CloudSpannerJdbcConnection class as input on a Connection returned by the Cloud Spanner JDBC Driver will return a CloudSpannerJdbcConnection instance.

Implements

Connection

Methods

addTransactionRetryListener(TransactionRetryListener listener)

public abstract void addTransactionRetryListener(TransactionRetryListener listener)

See Also: com.google.cloud.spanner.connection.Connection#addTransactionRetryListener(com.google.cloud.spanner.connection.TransactionRetryListener)

Parameter
Name Description
listener com.google.cloud.spanner.connection.TransactionRetryListener
Exceptions
Type Description
SQLException

if the Connection is closed.

addTransactionRetryListener(TransactionRetryListener listener) (deprecated)

public abstract void addTransactionRetryListener(TransactionRetryListener listener)
Parameter
Name Description
listener TransactionRetryListener
Exceptions
Type Description
SQLException

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

Exceptions
Type Description
SQLException

if the Connection is in autocommit mode or the Connection is closed.

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

Exceptions
Type Description
SQLException

if the Connection is in autocommit mode or the Connection is closed.

getAutocommitDmlMode()

public abstract AutocommitDmlMode getAutocommitDmlMode()
Returns
Type Description
com.google.cloud.spanner.connection.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.

Exceptions
Type Description
SQLException

getCommitResponse()

public abstract CommitResponse getCommitResponse()
Returns
Type Description
CommitResponse

the CommitResponse of the last read/write transaction. If the last transaction was not a read/write transaction, or a read/write transaction that did not return a CommitResponse because the transaction was not committed, the method will throw a SQLException. The CommitResponse will include CommitStats if #isReturnCommitStats() returns true.

Exceptions
Type Description
SQLException

getCommitTimestamp()

public abstract Timestamp getCommitTimestamp()
Returns
Type Description
Timestamp

the commit Timestamp of the last read/write transaction. If the last transaction was not a read/write transaction, or a read/write transaction that did not return a commit timestamp because the transaction was not committed, the method will throw a SQLException.

Exceptions
Type Description
SQLException

getConnectionUrl()

public abstract String getConnectionUrl()
Returns
Type Description
String

a connection URL that can be used to create a new Connection that is equal to the initial state of this connection. If this connection was initially opened in read-only mode, and later changed to read-write, this will not be reflected in the connection URL that is returned.

getDialect()

public default Dialect getDialect()
Returns
Type Description
Dialect

The Dialect that is used by this connection.

getMaxPartitionedParallelism()

public default int getMaxPartitionedParallelism()

Returns the maximum degree of parallelism that is used for partitioned queries.

Returns
Type Description
int
Exceptions
Type Description
SQLException

getMaxPartitions()

public default 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
Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

getReadTimestamp()

public abstract Timestamp getReadTimestamp()
Returns
Type Description
Timestamp

the read Timestamp of the last read-only transaction. If the last transaction was not a read-only transaction, or a read-only transaction that did not return a read timestamp because no data was read, the method will throw a SQLException.

Exceptions
Type Description
SQLException

getSavepointSupport()

public abstract SavepointSupport getSavepointSupport()

Returns the current savepoint support for this connection.

Returns
Type Description
com.google.cloud.spanner.connection.SavepointSupport
Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

getTransactionMode()

public abstract TransactionMode getTransactionMode()
Returns
Type Description
com.google.cloud.spanner.connection.TransactionMode

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

Exceptions
Type Description
SQLException

getTransactionRetryListeners() (deprecated)

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

getTransactionRetryListenersFromConnection()

public abstract Iterator<TransactionRetryListener> getTransactionRetryListenersFromConnection()

See Also: com.google.cloud.spanner.connection.Connection#getTransactionRetryListeners()

Returns
Type Description
Iterator<com.google.cloud.spanner.connection.TransactionRetryListener>
Exceptions
Type Description
SQLException

if the Connection is closed.

getTransactionTag()

public default String getTransactionTag()
Returns
Type Description
String

The transaction tag of the current transaction.

Exceptions
Type Description
SQLException

isAutoPartitionMode()

public default boolean isAutoPartitionMode()

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

Returns
Type Description
boolean
Exceptions
Type Description
SQLException

isDataBoostEnabled()

public default boolean isDataBoostEnabled()
Returns
Type Description
boolean
Exceptions
Type Description
SQLException

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 executing BEGIN TRANSACTION. If the Connection is not in autocommit mode, there will always be a transaction.

Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

isReturnCommitStats()

public abstract boolean isReturnCommitStats()
Returns
Type Description
boolean

true if this connection requests commit statistics from Cloud Spanner.

Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

removeTransactionRetryListener(TransactionRetryListener listener)

public abstract boolean removeTransactionRetryListener(TransactionRetryListener listener)

See Also: com.google.cloud.spanner.connection.Connection#removeTransactionRetryListener(com.google.cloud.spanner.connection.TransactionRetryListener)

Parameter
Name Description
listener com.google.cloud.spanner.connection.TransactionRetryListener
Returns
Type Description
boolean
Exceptions
Type Description
SQLException

if the Connection is closed.

removeTransactionRetryListener(TransactionRetryListener listener) (deprecated)

public abstract boolean removeTransactionRetryListener(TransactionRetryListener listener)
Parameter
Name Description
listener TransactionRetryListener
Returns
Type Description
boolean
Exceptions
Type Description
SQLException

setAutoPartitionMode(boolean alwaysUsePartitionedQueries)

public default void setAutoPartitionMode(boolean alwaysUsePartitionedQueries)

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
alwaysUsePartitionedQueries boolean
Exceptions
Type Description
SQLException

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 com.google.cloud.spanner.connection.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.

Exceptions
Type Description
SQLException

setDataBoostEnabled(boolean dataBoostEnabled)

public default void setDataBoostEnabled(boolean dataBoostEnabled)
Parameter
Name Description
dataBoostEnabled boolean
Exceptions
Type Description
SQLException

setMaxPartitionedParallelism(int maxThreads)

public default void setMaxPartitionedParallelism(int maxThreads)

Sets the maximum degree of parallelism that is used when executing a partitioned query. A partitioned query 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
Exceptions
Type Description
SQLException

setMaxPartitions(int maxPartitions)

public default 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
Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

setProtoDescriptors(InputStream protoDescriptors)

public default void setProtoDescriptors(InputStream 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 InputStream

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

Exceptions
Type Description
SQLException
IOException

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

Exceptions
Type Description
SQLException

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.

Exceptions
Type Description
SQLException

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 for DML statements in autocommit mode.

Parameter
Name Description
returnCommitStats boolean
Exceptions
Type Description
SQLException

setSavepointSupport(SavepointSupport savepointSupport)

public abstract void setSavepointSupport(SavepointSupport savepointSupport)

Sets how savepoints should be supported on this connection.

Parameter
Name Description
savepointSupport com.google.cloud.spanner.connection.SavepointSupport
Exceptions
Type Description
SQLException

setStatementTag(String tag)

public default void setStatementTag(String tag)

Sets the statement tag to use for the next statement that will be 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.

Parameter
Name Description
tag String

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

Exceptions
Type Description
SQLException

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 com.google.cloud.spanner.connection.TransactionMode

The transaction mode to use for the current transaction.

  • TransactionMode#READ_ONLY_TRANSACTION will create a read-only transaction and prevent any changes to written to the database through this transaction. The read timestamp to be used will be determined based on the current readOnlyStaleness setting of this connection. It is recommended to use TransactionMode#READ_ONLY_TRANSACTION instead of TransactionMode#READ_WRITE_TRANSACTION when possible, as read-only transactions do not acquire locks on Cloud Spanner, and read-only transactions never abort.
  • TransactionMode#READ_WRITE_TRANSACTION this value is only allowed when the connection is not in read-only mode and will create a read-write transaction. If CloudSpannerJdbcConnection#isRetryAbortsInternally() is true, each read/write transaction will keep track of a running SHA256 checksum for each ResultSet that is returned in order to be able to retry the transaction in case the transaction is aborted by Spanner.

Exceptions
Type Description
SQLException

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 the transaction is actually started, i.e. 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.

Exceptions
Type Description
SQLException

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 CloudSpannerJdbcConnection#write(Iterable).

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

Parameter
Name Description
mutation Mutation

The Mutation to write to the database.

Exceptions
Type Description
SQLException

if the Connection is not in autocommit mode or if the Connection is closed.

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 CloudSpannerJdbcConnection#bufferedWrite(Iterable) for writing mutations in transactions.

Parameter
Name Description
mutations Iterable<Mutation>

The Mutations to write to the database.

Exceptions
Type Description
SQLException

if the Connection is not in autocommit mode or if the Connection is closed.