client/io.github.octaviusframework.client/OctaviusClient

OctaviusClient

interface OctaviusClient : AutoCloseable

Hands out queries and sessions, and runs transactions over them.

A query from rawQuery, select, insertInto, update or deleteFrom finds its own session when a terminal runs, so nothing has to be opened around it. execute hands over the driver's OctaviusSessionOperations for work that is not a query - copy, largeObjects, notifications, several statements on one session.

val db = OctaviusClient.fromDataSource(hikariDataSource)

val senators = db.rawQuery("SELECT id, cognomen FROM senators WHERE province_id = @p")
    .fetchObjects<Senator>("p" to 7)

Either way the session joins the transaction running on this thread, if there is one, so the same repository function works standalone and inside a larger transaction.

Failures are thrown. Where one should be a value, asResult covers one query, transactionResult a transaction, and dbResult anything else.

Inheritors

OctaviusClientImpl

Types

Companion

object Companion

Properties

dynamicTypes

abstract val dynamicTypes: DynamicTypes

The dynamic_dto types this client knows. Nothing reaches the database until a type is registered.

Functions

abstract override fun close()

Releases what this client holds. A data source it was given rather than built is not closed.

deleteFrom

abstract fun deleteFrom(table: String): DeleteQuery

Starts a DELETE from table, which renders only with a WHERE.

execute

abstract fun <T> execute(block: OctaviusSessionOperations.() -> T): T

Runs block on a session: inside a transaction on this thread the transaction's, otherwise one borrowed for this call, whose statements commit as they go.

executeTransactionPlan

open fun executeTransactionPlan(plan: TransactionPlan, propagation: TransactionPropagation = TransactionPropagation.REQUIRED, isolation: TransactionIsolationLevel? = null, readOnly: Boolean = false, statementTimeout: Duration? = null, transactionTimeout: Duration? = null): TransactionPlanResult

Runs every step of plan in one transaction, in order, and returns what each produced. A step's TransactionValues are resolved just before it runs.

insertInto

abstract fun insertInto(table: String): InsertQuery

Starts an INSERT into table.

rawQuery

abstract fun rawQuery(sql: String): RawQuery

SQL written by hand, with @name parameters. Every terminal call runs it, so calling two runs it twice.

select

abstract fun select(vararg columns: String): SelectQuery

Starts a SELECT of columns, each passed through as SQL: "id", "count(*) AS total".

transaction

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

Runs block in a transaction, committing when it returns and rolling back when it throws. The receiver offers no commit or rollback of its own.

transactionResult

open fun <T> transactionResult(propagation: TransactionPropagation = TransactionPropagation.REQUIRED, isolation: TransactionIsolationLevel? = null, readOnly: Boolean = false, statementTimeout: Duration? = null, transactionTimeout: Duration? = null, block: OctaviusClient.() -> DataResult<T>): DataResult<T>

transaction for the result style. A plain transaction rolls back only on a throw, so a failure turned into a value inside it is committed over; here a returned DataResult.Failure rolls back.

update

abstract fun update(table: String): UpdateQuery

Starts an UPDATE of table, which renders only with a WHERE.