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

parameterConverterRegistry

val parameterConverterRegistry: ParameterConverterRegistry

Parameter converters local to this query, chained to the session's. Converters here are tried first.

parameterMapper

internal val parameterMapper: ParameterMapper

parameterSerializer

@PublishedApi

internal val parameterSerializer: ParameterSerializer

queryExecutor

@PublishedApi

internal val queryExecutor: QueryExecutor

resultConverterRegistry

val resultConverterRegistry: ResultConverterRegistry

Result converters local to this query, chained to the session's. Converters here are tried first.

resultMapper

@PublishedApi

internal val resultMapper: ResultMapper

sql

@PublishedApi

internal val sql: String

typeManager

internal val typeManager: TypeManager

The session's type manager, resolving OIDs and holding the parent registries.

Functions

execute

fun execute(ignoreRows: Boolean = false)

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

fetchField

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

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

fetchFields

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

Executes the query and returns the first column of every row, mapped to 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.

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.

fetchObjects

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

Executes the query and maps every row onto 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.

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, crossinline block: (T) -> Unit)

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

forEachObject

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

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

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.

update

fun update(vararg params: Any?): Long

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

withPositionalContext

@PublishedApi

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

@PublishedApi

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