client/io.github.octaviusframework.client.query/UpdateQuery

UpdateQuery

class UpdateQuery @PublishedApi constructor(provider: SessionProvider, table: String) : RunnableQuery<UpdateQuery>

An UPDATE under construction. setValue and setValues assign from @name parameters supplied at the terminal; setExpression assigns SQL, which may read the column: setExpression("quantity", "quantity - 1").

A WHERE is required. An UPDATE of every row is written with rawQuery.

db.update("legion_supplies")
    .setExpression("quantity", "quantity - @taken")
    .setValue("last_drawn_at")
    .where("id = @id")
    .executeUpdate("taken" to 1, "last_drawn_at" to now, "id" to supplyId)

Constructors

UpdateQuery

@PublishedApi

internal constructor(provider: SessionProvider, table: String)

Properties

queryParameterConverters

@PublishedApi

internal var queryParameterConverters: MutableList<ParameterConverter<*>>?

queryProvider

@PublishedApi

internal val queryProvider: SessionProvider

Decides which session the terminals run on.

queryResultConverters

@PublishedApi

internal var queryResultConverters: MutableList<ResultConverter<*, *>>?

Functions

asResult

fun asResult(): ResultQuery

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.

asStep

fun asStep(): StepBuilder

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.

copy

fun copy(): UpdateQuery

Returns an independent copy, so that variants can be built from a shared base.

copyConvertersFrom

internal fun copyConvertersFrom(other: RunnableQuery<*>)

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

executeUpdate

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.

fetchField

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.

fetchFields

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.

fetchFieldStrict

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.

fetchObject

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.

fetchObjects

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.

fetchObjectStrict

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.

fetchRow

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.

fetchRows

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.

fetchRowStrict

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.

forEachField

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.

forEachObject

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.

forEachRow

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.

from

fun from(tables: String): UpdateQuery

Sets the FROM clause, for an update that reads from other tables.

preparedQuery

@PublishedApi

internal fun OctaviusSessionOperations.preparedQuery(): NamedParameterQuery

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

querySql

internal open override fun querySql(): String

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

recursive

fun recursive(): UpdateQuery

Marks the WITH clause RECURSIVE.

registerParameterConverter

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

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

registerResultConverter

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

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

returning

fun returning(vararg columns: String): UpdateQuery

Adds a RETURNING clause, which turns this into a query the fetch* family can read.

setExpression

fun setExpression(column: String, expression: String): UpdateQuery

Assigns one column from a SQL expression, which may read the column it is assigning.

setExpressions

fun setExpressions(expressions: Map<String, String>): UpdateQuery

As setExpression, for several columns at once.

setValue

fun setValue(column: String): UpdateQuery

Assigns one column from the @column parameter.

setValues

fun setValues(columns: List<String>): UpdateQuery

Assigns each column from the parameter of the same name.

fun setValues(data: Map<String, Any?>): UpdateQuery

Assigns the columns named by data's keys, each from the parameter of the same name. The map's values are not read, so pass it to the terminal too.

toSql

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.

where

fun where(condition: String): UpdateQuery

Sets the WHERE condition. Required.

with

fun with(name: String, query: String): UpdateQuery

Adds a common table expression. Call it more than once for more than one.