RunnableQuery

abstract class RunnableQuery<T : RunnableQuery<T>> @PublishedApi constructor(val queryProvider: SessionProvider)

A query that can be run: the base of every builder and of RawQuery, carrying the terminal methods.

The terminals are the driver's, with the same names and meanings, and find their session when they run - inside a transaction, the transaction's. They throw as the driver throws; asResult switches to terminals that return a value.

Parameters are @name only and are supplied at the terminal. Positional $1 placeholders are reached through db.execute { createNativeQuery(…) }.

Inheritors

Constructors

Link copied to clipboard
internal constructor(queryProvider: SessionProvider)

Properties

Link copied to clipboard

Decides which session the terminals run on.

Functions

Link copied to clipboard

This query with terminals that return a DataResult instead of throwing, on the boundary dbResult applies - a fetch*Strict that found no row still throws.

Link copied to clipboard

Turns this query into a step of a TransactionPlan instead of running it. The parameters given at the step's terminal may hold TransactionValues pointing at earlier steps.

Link copied to clipboard
internal fun copyConvertersFrom(other: RunnableQuery<*>)

Carries registered converters into a builder's copy(), alongside whatever clauses it copies.

Link copied to clipboard
fun executeUpdate(params: Map<String, Any?> = emptyMap()): Long
fun executeUpdate(vararg params: Pair<String, Any?>): Long

Runs the statement and returns how many rows it affected.

Link copied to clipboard
inline fun <T> fetchField(params: Map<String, Any?> = emptyMap()): T

Runs the query and returns the first column of its single row as T. A nullable T gives null for a missing row or a NULL; a non-nullable one throws for either.

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

Runs the query and returns the first column of its single row as T.

Link copied to clipboard
inline fun <T> fetchFields(params: Map<String, Any?> = emptyMap()): List<T>
inline fun <T> fetchFields(vararg params: Pair<String, Any?>): List<T>

Runs the query and returns the first column of every row as T.

Link copied to clipboard
inline fun <T> fetchFieldStrict(params: Map<String, Any?> = emptyMap()): T
inline fun <T> fetchFieldStrict(vararg params: Pair<String, Any?>): T

As fetchField, but the query must return exactly one row rather than at most one.

Link copied to clipboard
inline fun <T : Any> fetchObject(params: Map<String, Any?> = emptyMap()): T?
inline fun <T : Any> fetchObject(vararg params: Pair<String, Any?>): T?

Runs the query and maps its single row onto T, or null where none matched.

Link copied to clipboard
inline fun <T : Any> fetchObjects(params: Map<String, Any?> = emptyMap()): List<T>
inline fun <T : Any> fetchObjects(vararg params: Pair<String, Any?>): List<T>

Runs the query and maps every row onto T.

Link copied to clipboard
inline fun <T : Any> fetchObjectStrict(params: Map<String, Any?> = emptyMap()): T
inline fun <T : Any> fetchObjectStrict(vararg params: Pair<String, Any?>): T

Runs the query and maps its single row onto T, throwing where the count was anything but one.

Link copied to clipboard
fun fetchRow(params: Map<String, Any?> = emptyMap()): Row?
fun fetchRow(vararg params: Pair<String, Any?>): Row?

Runs the query and returns its single row, or null where none matched.

Link copied to clipboard
fun fetchRows(params: Map<String, Any?> = emptyMap()): List<Row>
fun fetchRows(vararg params: Pair<String, Any?>): List<Row>

Runs the query and returns every row.

Link copied to clipboard
fun fetchRowStrict(params: Map<String, Any?> = emptyMap()): Row
fun fetchRowStrict(vararg params: Pair<String, Any?>): Row

Runs the query and returns its single row, throwing where the count was anything but one.

Link copied to clipboard
inline fun <T> forEachField(params: Map<String, Any?> = emptyMap(), fetchSize: Int, noinline block: (T) -> Unit)

Runs the query and hands the first column of each row, as T, to block as forEachRow does.

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

Runs the query and hands the first column of each row, as T, to block as it arrives.

Link copied to clipboard
inline fun <T : Any> forEachObject(params: Map<String, Any?> = emptyMap(), fetchSize: Int, noinline block: (T) -> Unit)

Runs the query and hands each row, mapped onto T, to block as it arrives, as forEachRow does.

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

Runs the query and hands each row, mapped onto T, to block as it arrives.

Link copied to clipboard
fun forEachRow(params: Map<String, Any?> = emptyMap(), fetchSize: Int, block: (Row) -> Unit)

Runs the query and hands each row to block as it arrives, so a result too large to hold is streamed. block runs while the result is still being read, and a query from inside it is refused with CONNECTION_BUSY.

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

Runs the query and hands each row to block as it arrives, in batches of fetchSize.

Link copied to clipboard

The driver query every terminal runs, carrying this query's own converters.

Link copied to clipboard
internal abstract fun querySql(): String

Renders the SQL. Called once per terminal call, so a builder may put off assembling it until here.

Link copied to clipboard

Registers a ParameterConverter for this query alone, on the terms of registerResultConverter.

Link copied to clipboard

Registers a ResultConverter for this query alone, consulted ahead of the session's. A later registration here wins over an earlier one.

Link copied to clipboard
fun toSql(): String

Renders the SQL this query would send. A query never carries parameters, so its @name placeholders survive embedding it in a WITH, a subquery or a UNION, and are bound by whoever runs the outer statement. Not cached: a builder walks its clauses again on every call.