Top Description Methods
io.r2dbc.spi

public Interface Connection

extends Closeable
Imports
org.reactivestreams.Publisher, .Subscriber, java.time.Duration
A single connection to a database. SQL statements are executed and results are returned within the context of a connection. A Connection object can consist of any number of transport connections to the underlying database or represent a session over a multiplexed transport connection. For maximum portability, connections should be used synchronously.

Connection objects initiate database conversations for transaction management and statement execution. Objects created by a connection are only valid as long as the connection remains open.

When configuring a connection, R2DBC applications should use the appropriate methods such as beginTransaction(), setAutoCommit(boolean) and setTransactionIsolationLevel(IsolationLevel) to change transaction properties instead. Applications should not execute SQL commands directly to change the connection configuration when a R2DBC method is available.

New connections are by default created in auto-commit mode.

See Also
Statement, Result, Row

Method Summary

Modifier and TypeMethod and Description
public Publisher<Void>

Returns:

a Publisher that indicates that the transaction is open
beginTransaction()

Begins a new transaction.

public Publisher<Void>

Returns:

a Publisher that indicates that the transaction is open
beginTransaction(TransactionDefinition
attributes for the transaction.
definition)

Begins a new transaction.

public Publisher<Void>

Returns:

a Publisher that termination is complete
close()

Redeclares io.r2dbc.spi.Closeable.close.

Release any resources held by the Connection.
public Publisher<Void>

Returns:

a Publisher that indicates that a transaction has been committed
commitTransaction()

Commits the current transaction.

public Batch

Returns:

a new Batch instance
createBatch()

Creates a new Batch instance for building a batched request.

public Publisher<Void>

Returns:

a Publisher that indicates that a savepoint has been created
createSavepoint(String
the name of the savepoint to create
name)

Creates a savepoint in the current transaction.

public Statement

Returns:

a new Statement instance
createStatement(String
the SQL of the statement
sql)

Creates a new statement for building a statement-based request.

public ConnectionMetadata

Returns:

the ConnectionMetadata about the product this Connection is connected to
getMetadata()

Returns the ConnectionMetadata about the product this Connection is connected to.

public IsolationLevel

Returns:

the IsolationLevel for this connection.
getTransactionIsolationLevel()

Returns the IsolationLevel for this connection.

public boolean

Returns:

true if the connection is in auto-commit mode; false otherwise.
isAutoCommit()

Returns the auto-commit mode for this connection.

public Publisher<Void>

Returns:

a Publisher that indicates that a savepoint has been released
releaseSavepoint(String
the name of the savepoint to release
name)

Releases a savepoint in the current transaction.

public Publisher<Void>

Returns:

a Publisher that indicates that a transaction has been rolled back
rollbackTransaction()

Rolls back the current transaction.

public Publisher<Void>

Returns:

a Publisher that indicates that a savepoint has been rolled back to
rollbackTransactionToSavepoint(String
the name of the savepoint to rollback to
name)

Rolls back to a savepoint in the current transaction.

public Publisher<Void>

Returns:

a Publisher that indicates that auto-commit mode has been configured
setAutoCommit(boolean
the isolation level for this transaction
autoCommit)

Configures the auto-commit mode for the current transaction.

public Publisher<Void>

Returns:

a Publisher that indicates that a lock timeout has been configured
setLockWaitTimeout(Duration
the lock timeout for this connection. Support for no timeout is vendor-specific.
timeout)

Configures the lock acquisition timeout for statements to be executed using the current connection.

public Publisher<Void>

Returns:

a Publisher that indicates that a statement timeout has been configured
setStatementTimeout(Duration
the statement timeout for this connection. Duration#ZERO indicates no timeout.
timeout)

Configures the statement timeout for statements to be executed using the current connection.

public Publisher<Void>

Returns:

a Publisher that indicates that a transaction level has been configured
setTransactionIsolationLevel(IsolationLevel
the isolation level for this transaction
isolationLevel)

Configures the isolation level for the connection.

public Publisher<Boolean>

Returns:

a Publisher that indicates whether the validation was successful
validate(ValidationDepth
the validation depth
depth)

Validates the connection according to the given ValidationDepth.

Method Detail

beginTransactionback to summary
public Publisher<Void> beginTransaction()

Begins a new transaction. Calling this method disables auto-commit mode.

Returns:Publisher<Void>

a Publisher that indicates that the transaction is open

beginTransactionback to summary
public Publisher<Void> beginTransaction(TransactionDefinition definition)

Begins a new transaction. Calling this method disables auto-commit mode. Beginning the transaction may fail if the TransactionDefinition conflicts with the connection configuration.

Parameters
definition:TransactionDefinition

attributes for the transaction.

Returns:Publisher<Void>

a Publisher that indicates that the transaction is open

Since
0.9
closeback to summary
public Publisher<Void> close()

Redeclares io.r2dbc.spi.Closeable.close.

Release any resources held by the Connection.

Returns:Publisher<Void>

a Publisher that termination is complete

Annotations
@Override
commitTransactionback to summary
public Publisher<Void> commitTransaction()

Commits the current transaction.

Returns:Publisher<Void>

a Publisher that indicates that a transaction has been committed

createBatchback to summary
public Batch createBatch()

Creates a new Batch instance for building a batched request.

Returns:Batch

a new Batch instance

createSavepointback to summary
public Publisher<Void> createSavepoint(String name)

Creates a savepoint in the current transaction.

Parameters
name:String

the name of the savepoint to create

Returns:Publisher<Void>

a Publisher that indicates that a savepoint has been created

Exceptions
IllegalArgumentException:
if name is null
UnsupportedOperationException:
if savepoints are not supported
createStatementback to summary
public Statement createStatement(String sql)

Creates a new statement for building a statement-based request.

Parameters
sql:String

the SQL of the statement

Returns:Statement

a new Statement instance

Exceptions
IllegalArgumentException:
if sql is null
getMetadataback to summary
public ConnectionMetadata getMetadata()

Returns the ConnectionMetadata about the product this Connection is connected to.

Returns:ConnectionMetadata

the ConnectionMetadata about the product this Connection is connected to

getTransactionIsolationLevelback to summary
public IsolationLevel getTransactionIsolationLevel()

Returns the IsolationLevel for this connection.

Isolation level is typically one of the following constants:

IsolationLevel is extensible so drivers can return a vendor-specific IsolationLevel.

Returns:IsolationLevel

the IsolationLevel for this connection.

isAutoCommitback to summary
public boolean isAutoCommit()

Returns the auto-commit mode for this connection.

Returns:boolean

true if the connection is in auto-commit mode; false otherwise.

releaseSavepointback to summary
public Publisher<Void> releaseSavepoint(String name)

Releases a savepoint in the current transaction. Calling this for drivers not supporting savepoint release results in a no-op.

Parameters
name:String

the name of the savepoint to release

Returns:Publisher<Void>

a Publisher that indicates that a savepoint has been released

Exceptions
IllegalArgumentException:
if name is null
rollbackTransactionback to summary
public Publisher<Void> rollbackTransaction()

Rolls back the current transaction.

Returns:Publisher<Void>

a Publisher that indicates that a transaction has been rolled back

rollbackTransactionToSavepointback to summary
public Publisher<Void> rollbackTransactionToSavepoint(String name)

Rolls back to a savepoint in the current transaction.

Parameters
name:String

the name of the savepoint to rollback to

Returns:Publisher<Void>

a Publisher that indicates that a savepoint has been rolled back to

Exceptions
IllegalArgumentException:
if name is null
UnsupportedOperationException:
if savepoints are not supported
setAutoCommitback to summary
public Publisher<Void> setAutoCommit(boolean autoCommit)

Configures the auto-commit mode for the current transaction. If a connection is in auto-commit mode, then all Statements will be executed and committed as individual transactions. Otherwise, in explicit transaction mode, transactions have to be started explicitly. A transaction needs to be either committed or rolled back to clean up the transaction state.

Calling this method during an active transaction and the auto-commit mode is changed, the transaction is committed. Calling this method without changing auto-commit mode this invocation results in a no-op.

Parameters
autoCommit:boolean

the isolation level for this transaction

Returns:Publisher<Void>

a Publisher that indicates that auto-commit mode has been configured

setLockWaitTimeoutback to summary
public Publisher<Void> setLockWaitTimeout(Duration timeout)

Configures the lock acquisition timeout for statements to be executed using the current connection. The default lock acquisition timeout is vendor-specific and can be specified for new connections through ConnectionFactoryOptions. If the timeout is exceeded, a R2dbcTimeoutException is raised.

In the case of Batch/Statement batching, it is vendor-specific as to whether the timeout is applied to individual SQL commands or the entire batch.

Parameters
timeout:Duration

the lock timeout for this connection. Support for no timeout is vendor-specific.

Returns:Publisher<Void>

a Publisher that indicates that a lock timeout has been configured

Exceptions
IllegalArgumentException:
if timeout is null
Since
0.9
setStatementTimeoutback to summary
public Publisher<Void> setStatementTimeout(Duration timeout)

Configures the statement timeout for statements to be executed using the current connection. By default, there is no limit on the amount of time allowed for a running statement to complete unless specified through ConnectionFactoryOptions. If the limit is exceeded, a R2dbcTimeoutException is raised.

The minimum amount of time can be used to either let the data source cancel the statement or attempt a client-side cancellation. The timeout applies to statements through a combination of Statement#execute() and Result consumption. In the case of Batch/Statement batching, it is vendor-specific whether the timeout is applied to individual SQL commands or the entire batch.

Note that the timeout applies until receiving the first response from the data source and does not span until publisher completion.

Parameters
timeout:Duration

the statement timeout for this connection. Duration#ZERO indicates no timeout.

Returns:Publisher<Void>

a Publisher that indicates that a statement timeout has been configured

Exceptions
IllegalArgumentException:
if timeout is null
Since
0.9
setTransactionIsolationLevelback to summary
public Publisher<Void> setTransactionIsolationLevel(IsolationLevel isolationLevel)

Configures the isolation level for the connection. When called outside a transaction, then the isolation level applies for all subsequent transactions. Setting the isolation level within a transaction results in vendor-specific behavior.

Isolation level is typically one of the following constants:

IsolationLevel is extensible so drivers can accept a vendor-specific IsolationLevel.

Parameters
isolationLevel:IsolationLevel

the isolation level for this transaction

Returns:Publisher<Void>

a Publisher that indicates that a transaction level has been configured

Exceptions
IllegalArgumentException:
if isolationLevel is null
validateback to summary
public Publisher<Boolean> validate(ValidationDepth depth)

Validates the connection according to the given ValidationDepth. Emits true if the validation was successful or false if the validation failed. Does not emit errors and does not complete empty.

Parameters
depth:ValidationDepth

the validation depth

Returns:Publisher<Boolean>

a Publisher that indicates whether the validation was successful

Exceptions
IllegalArgumentException:
if depth is null