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.
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)
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.
|
getAutoBatchDmlUpdateCount()
public default 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 |
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.
|
getCommitResponse()
public abstract CommitResponse getCommitResponse()
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.
|
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 |
|
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 |
|
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.
|
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 |
| 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.
|
getSavepointSupport()
public abstract SavepointSupport getSavepointSupport()
Returns the current savepoint support for this connection.
| Returns |
| Type |
Description |
com.google.cloud.spanner.connection.SavepointSupport |
|
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.
|
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.
|
getTransactionRetryListeners() (deprecated)
public abstract Iterator<TransactionRetryListener> getTransactionRetryListeners()
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.
|
isAutoBatchDml()
public default boolean isAutoBatchDml()
Returns whether automatic DML batching is enabled on this connection.
isAutoBatchDmlUpdateCountVerification()
public default boolean isAutoBatchDmlUpdateCountVerification()
Indicates whether the update counts of automatic DML batches should be verified.
isAutoPartitionMode()
public default boolean isAutoPartitionMode()
Returns whether this connection will execute all queries as partitioned queries.
isDataBoostEnabled()
public default boolean isDataBoostEnabled()
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.
|
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.
|
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
|
| Exceptions |
| Type |
Description |
SQLException |
if the Connection is closed.
|
removeTransactionRetryListener(TransactionRetryListener listener) (deprecated)
public abstract boolean removeTransactionRetryListener(TransactionRetryListener listener)
setAutoBatchDml(boolean autoBatchDml)
public default 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 default 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 default 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 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
|
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.
|
setDataBoostEnabled(boolean dataBoostEnabled)
public default void setDataBoostEnabled(boolean dataBoostEnabled)
| Parameter |
| Name |
Description |
dataBoostEnabled |
boolean
|
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
|
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
|
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.
|
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.
|
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 for 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 |
com.google.cloud.spanner.connection.SavepointSupport
|
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.
|
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.
|
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.
|
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.
| Exceptions |
| Type |
Description |
SQLException |
if the Connection is not in autocommit mode or if the Connection is closed.
|
