api/io.github.octaviusframework.db.api/DataAccess/transaction

transaction

abstract fun <T> transaction(propagation: TransactionPropagation = TransactionPropagation.REQUIRED, isolation: IsolationLevel = IsolationLevel.DEFAULT, readOnly: Boolean = false, statementTimeout: Duration? = null, transactionTimeout: Duration? = null, block: QueryOperations.() -> DataResult<T>): DataResult<T>

Executes a block of code within a managed transaction scope.

The transaction follows a "fail-fast" commit policy:

Success: If the block returns DataResult.Success, the transaction is committed.
Failure: If the block returns DataResult.Failure, the transaction is automatically rolled back.
Exception: If the block throws any exception, the transaction is rolled back, and the exception is translated to DataResult.Failure.

Concurrency Note: In the underlying implementation, the transaction state is bound to the current thread via ThreadLocal. All operations called on this DataAccess instance (or via the receiver in the block) on the same thread will participate in the transaction.

Warning: Launching new threads or coroutines with different dispatchers inside the block will NOT automatically participate in the transaction.

Return

The result of the block as DataResult.

Parameters

propagation

Specifies how this transaction should behave if another transaction is already active.

isolation

The isolation level for the transaction.

readOnly

If true, prevents modifications to the database during this transaction.

statementTimeout

Aborts any individual statement within this transaction that takes longer than the specified time. Note: Supported only in Core Provider (SET LOCAL statement_timeout). Not supported and throws io.github.octaviusframework.db.api.exception.BadStatementException when using Spring integration.

transactionTimeout

Aborts the entire transaction if it exceeds this time. In Core Provider, this uses SET LOCAL transaction_timeout (Requires PostgreSQL 17+). In Spring integration, this maps to Spring's transaction deadline logic.

block

A lambda providing QueryOperations as a receiver for performing database operations within the transaction.

Type Parameters

The return type of the result encapsulated in DataResult.