driver/io.github.octaviusframework.driver.query/NativeQuery

NativeQuery

class NativeQuery(sql: String, queryExecutor: QueryExecutor, typeManager: TypeManager) : Query<NativeQuery>

Represents a query that uses standard PostgreSQL positional parameters (e.g., $1, $2).

NativeQuery passes the provided SQL string and parameters directly to the underlying QueryExecutor without any intermediate parsing or modification of the SQL statement. It provides various execution methods to fetch rows, map results to Kotlin objects, extract single fields, or perform data modifications (updates).

Constructors

NativeQuery

internal constructor(sql: String, queryExecutor: QueryExecutor, typeManager: TypeManager)

Properties

queryExecutor

internal val queryExecutor: QueryExecutor

sql

internal val sql: String

typeManager

internal val typeManager: TypeManager

The session's type manager, resolving OIDs and publishing the catalog an execution pins.

Functions

beginExecution

internal fun beginExecution(): Execution

Pins the catalog this execution will read, and builds the mappers over it.

execute

fun execute(ignoreRows: Boolean = false)

Executes a statement with no result and no row count — DDL, SET, administrative commands.

executeUpdate

fun executeUpdate(vararg params: Any?): Long

Executes a statement that changes rows without returning any — INSERT, UPDATE, DELETE.

fetchField

inline fun <T> fetchField(vararg params: Any?): T

Executes the query and returns the first column of its single row.

fetchFieldOf

@PublishedApi

internal fun <T> fetchFieldOf(params: Array<out Any?>, targetType: KType): T

fetchFields

inline fun <T> fetchFields(vararg params: Any?): List<T>

Executes the query and returns the first column of every row, mapped to T.

fetchFieldsOf

@PublishedApi

internal fun <T> fetchFieldsOf(params: Array<out Any?>, targetType: KType): List<T>

fetchFieldStrict

inline fun <T> fetchFieldStrict(vararg params: Any?): T

Executes the query and returns the first column of its single row, requiring exactly one row.

fetchFieldStrictOf

@PublishedApi

internal fun <T> fetchFieldStrictOf(params: Array<out Any?>, targetType: KType): T

fetchObject

inline fun <T : Any> fetchObject(vararg params: Any?): T?

Executes the query and maps its single row onto T, or returns null when nothing matched.

fetchObjectOf

@PublishedApi

internal fun <T : Any> fetchObjectOf(params: Array<out Any?>, targetType: KType): T?

fetchObjects

inline fun <T : Any> fetchObjects(vararg params: Any?): List<T>

Executes the query and maps every row onto T.

fetchObjectsOf

@PublishedApi

internal fun <T : Any> fetchObjectsOf(params: Array<out Any?>, targetType: KType): List<T>

fetchObjectStrict

inline fun <T : Any> fetchObjectStrict(vararg params: Any?): T

Executes the query and maps its single row onto T, requiring exactly one row.

fetchObjectStrictOf

@PublishedApi

internal fun <T : Any> fetchObjectStrictOf(params: Array<out Any?>, targetType: KType): T

fetchRow

fun fetchRow(vararg params: Any?): Row?

Executes the query and returns its single row, or null when nothing matched.

fetchRows

fun fetchRows(vararg params: Any?): List<Row>

Executes the query and returns every row, undecoded into any particular shape.

fetchRowStrict

fun fetchRowStrict(vararg params: Any?): Row

Executes the query and returns its single row, requiring exactly one.

forEachField

inline fun <T> forEachField(vararg params: Any?, fetchSize: Int, noinline block: (T) -> Unit)

Streams the result, handing the first column of each row to block as T.

forEachFieldOf

@PublishedApi

internal fun <T> forEachFieldOf(params: Array<out Any?>, fetchSize: Int, targetType: KType, block: (T) -> Unit)

forEachObject

inline fun <T : Any> forEachObject(vararg params: Any?, fetchSize: Int, noinline block: (T) -> Unit)

Streams the result, mapping each row onto T and handing it to block.

forEachObjectOf

@PublishedApi

internal fun <T : Any> forEachObjectOf(params: Array<out Any?>, fetchSize: Int, targetType: KType, block: (T) -> Unit)

forEachRow

fun forEachRow(vararg params: Any?, fetchSize: Int, block: (Row) -> Unit)

Streams the result, handing each row to block as it arrives.

registerParameterConverter

fun registerParameterConverter(converter: ParameterConverter<*>): NativeQuery

Registers a ParameterConverter for this query only, ahead of any the session already holds.

registerResultConverter

fun registerResultConverter(converter: ResultConverter<*, *>): NativeQuery

Registers a ResultConverter for this query only, ahead of any the session already holds.

withPositionalContext

internal inline fun <R> withPositionalContext(params: Array<out Any?>, block: () -> R): R

Names this query's parameters for a QueryContext and runs block under it.

withQueryContext

internal inline fun <R> withQueryContext(sql: String, crossinline paramsProvider: () -> Map<String, Any?>, crossinline dbSqlProvider: () -> String? = { null }, crossinline dbParamsProvider: () -> List<Any?>? = { null }, block: () -> R): R