driver/io.github.octaviusframework.driver.query/NamedParameterQuery

NamedParameterQuery

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

Represents a query that accepts named parameters (e.g., @name, @id).

NamedParameterQuery parses the SQL to extract named parameters and maps them to positional parameters before delegating execution to the underlying QueryExecutor. It provides various execution methods to fetch rows, map results to Kotlin objects, extract single fields, or perform data modifications (updates).

A name repeated in the statement collapses to a single placeholder, so its value is supplied once. The parser leaves the rest of the statement alone: an @ inside a string literal, a quoted identifier, a comment or a $$ … $$ block is not a parameter, and neither are PostgreSQL's @-operators.

Every method here takes values either as a Map or as Pairs; the vararg forms simply build the map. A name the statement uses but the values omit raises InvalidOperationException MISSING_NAMED_PARAMETER; an extra value the statement does not use is ignored.

Constructors

NamedParameterQuery

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(params: Map<String, Any?>): T

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

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

Same as fetchField, with the values given as Pairs.

fetchFields

inline fun <T> fetchFields(params: Map<String, Any?>): List<T>

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

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

Same as fetchFields, with the values given as Pairs.

fetchFieldStrict

inline fun <T> fetchFieldStrict(params: Map<String, Any?>): T

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

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

Same as fetchFieldStrict, with the values given as Pairs.

fetchObject

inline fun <T : Any> fetchObject(params: Map<String, Any?>): T?

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

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

Same as fetchObject, with the values given as Pairs.

fetchObjects

inline fun <T : Any> fetchObjects(params: Map<String, Any?>): List<T>

Executes the query and maps every row onto T.

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

Same as fetchObjects, with the values given as Pairs.

fetchObjectStrict

inline fun <T : Any> fetchObjectStrict(params: Map<String, Any?>): T

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

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

Same as fetchObjectStrict, with the values given as Pairs.

fetchRow

fun fetchRow(params: Map<String, Any?>): Row?

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

fun fetchRow(vararg params: Pair<String, Any?>): Row?

Same as fetchRow, with the values given as Pairs.

fetchRows

fun fetchRows(params: Map<String, Any?>): List<Row>

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

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

Same as fetchRows, with the values given as Pairs.

fetchRowStrict

fun fetchRowStrict(params: Map<String, Any?>): Row

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

fun fetchRowStrict(vararg params: Pair<String, Any?>): Row

Same as fetchRowStrict, with the values given as Pairs.

forEachField

inline fun <T> forEachField(params: Map<String, Any?>, fetchSize: Int, crossinline block: (T) -> Unit)

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

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

Same as forEachField, with the values given as Pairs.

forEachObject

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

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

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

Same as forEachObject, with the values given as Pairs.

forEachRow

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

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

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

Same as forEachRow, with the values given as Pairs.

prepareNamedQuery

@PublishedApi

internal fun prepareNamedQuery(params: Map<String, Any?>): Pair<String, Array<out Any?>>

registerParameterConverter

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

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

registerResultConverter

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

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

update

fun update(params: Map<String, Any?>): Long

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

fun update(vararg params: Pair<String, Any?>): Long

Same as update, with the values given as Pairs.

withPreparedQuery

@PublishedApi

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

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