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

DataAccess

interface DataAccess : QueryOperations, AutoCloseable

Main entry point to the data access layer, providing a unified API for interacting with PostgreSQL.

This facade orchestrates different interaction patterns:

Direct Queries: Execution of single SELECT, INSERT, UPDATE, or DELETE operations in auto-commit mode.
Managed Transactions: Atomic execution of complex logic blocks where multiple operations must succeed or fail together.
Declarative Transaction Plans: Execution of pre-built sequences of operations (TransactionPlan) that can handle step dependencies.
Pub/Sub Messaging: Native integration with PostgreSQL LISTEN/NOTIFY mechanism for real-time updates.

Implementation is typically thread-safe and manages an underlying connection pool (e.g., HikariCP). Call close or use the interface within a use block to ensure proper resource cleanup.

Properties

enumSerializers

abstract val enumSerializers: SerializersModule

A dynamically generated SerializersModule containing contextual serializers for all PostgreSQL enums discovered and registered by the database.

json

abstract val json: Json

The custom JSON configuration used internally by the database operations, especially crucial for dynamic_dto serialization.

Functions

abstract override fun close()

Closes the data access object and releases any underlying resources (e.g., connection pool).

createChannelListener

abstract fun createChannelListener(): PgChannelListener

Creates a new PgChannelListener backed by a dedicated database connection.

deleteFrom

abstract fun deleteFrom(table: String): DeleteQueryBuilder

Starts building a DELETE query.

executeTransactionPlan

abstract fun executeTransactionPlan(plan: TransactionPlan, propagation: TransactionPropagation = TransactionPropagation.REQUIRED, isolation: IsolationLevel = IsolationLevel.DEFAULT, readOnly: Boolean = false, statementTimeout: Duration? = null, transactionTimeout: Duration? = null): DataResult<TransactionPlanResult>

Executes a pre-configured TransactionPlan as a single, atomic transaction.

insertInto

abstract fun insertInto(table: String): InsertQueryBuilder

Starts building an INSERT query.

notify

abstract fun notify(channel: String, payload: String? = null): DataResult<Unit>

Sends a notification to the given PostgreSQL channel via pg_notify.

notifyStep

abstract fun notifyStep(channel: String, payload: String? = null): TransactionStep<Unit>

Generates a deferred notification step for use within a TransactionPlan.

rawQuery

abstract fun rawQuery(sql: String): RawQueryBuilder

Enables execution of a raw SQL query.

select

abstract fun select(vararg columns: String): SelectQueryBuilder

Starts building a SELECT query.

toDynamicDto

abstract fun toDynamicDto(value: Any, json: Json? = null): DynamicDto

Helper method to manually serialize a domain object into a DynamicDto.

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.

update

abstract fun update(table: String): UpdateQueryBuilder

Starts building an UPDATE query.