0
# SQLDelight Runtime
1
2
SQLDelight Runtime is a Kotlin Multiplatform library that provides the foundational runtime components for SQLDelight-generated database code. It offers type-safe database operations, transaction management, and cross-platform database abstraction with first-class support for both synchronous and asynchronous execution patterns.
3
4
## Package Information
5
6
- **Package Name**: app.cash.sqldelight:runtime-iossimulatorarm64
7
- **Package Type**: Maven/Gradle
8
- **Language**: Kotlin
9
- **Installation**: `implementation("app.cash.sqldelight:runtime:2.1.0")`
10
11
## Core Imports
12
13
```kotlin
14
import app.cash.sqldelight.Query
15
import app.cash.sqldelight.Transacter
16
import app.cash.sqldelight.ColumnAdapter
17
import app.cash.sqldelight.db.SqlDriver
18
import app.cash.sqldelight.db.SqlCursor
19
import app.cash.sqldelight.db.QueryResult
20
```
21
22
## Basic Usage
23
24
```kotlin
25
import app.cash.sqldelight.Query
26
import app.cash.sqldelight.Transacter
27
import app.cash.sqldelight.db.SqlDriver
28
29
// Executing a query (typically generated by SQLDelight)
30
val query: Query<User> = // ... generated query
31
val users: List<User> = query.executeAsList()
32
val singleUser: User? = query.executeAsOneOrNull()
33
34
// Transaction management
35
class MyDatabase(driver: SqlDriver) : TransacterImpl(driver) {
36
fun transferMoney(fromId: Long, toId: Long, amount: Double) {
37
transaction {
38
// Update account balances atomically
39
updateBalance(fromId, -amount)
40
updateBalance(toId, amount)
41
}
42
}
43
}
44
45
// Column adapters for custom types
46
val dateAdapter = object : ColumnAdapter<LocalDate, String> {
47
override fun decode(databaseValue: String): LocalDate = LocalDate.parse(databaseValue)
48
override fun encode(value: LocalDate): String = value.toString()
49
}
50
```
51
52
## Architecture
53
54
SQLDelight Runtime is built around several key components:
55
56
- **Query System**: Type-safe query execution with result mapping and change listening
57
- **Transaction Management**: ACID-compliant transactions with nested support and lifecycle callbacks
58
- **Driver Abstraction**: Platform-agnostic database driver interface supporting both sync and async operations
59
- **Type System**: Column adapters for marshaling custom types to/from database primitives
60
- **Result System**: Unified result handling supporting both immediate values and suspending operations
61
- **Schema Management**: Database creation and migration support with version management
62
63
## Capabilities
64
65
### Query Execution
66
67
Core query execution functionality providing type-safe database operations with result mapping and change notification.
68
69
```kotlin { .api }
70
abstract class Query<out RowType : Any>(
71
mapper: (SqlCursor) -> RowType
72
) : ExecutableQuery<RowType>(mapper) {
73
abstract fun addListener(listener: Listener)
74
abstract fun removeListener(listener: Listener)
75
76
fun interface Listener {
77
fun queryResultsChanged()
78
}
79
}
80
81
abstract class ExecutableQuery<out RowType : Any>(
82
val mapper: (SqlCursor) -> RowType
83
) {
84
abstract fun <R> execute(mapper: (SqlCursor) -> QueryResult<R>): QueryResult<R>
85
fun executeAsList(): List<RowType>
86
fun executeAsOne(): RowType
87
fun executeAsOneOrNull(): RowType?
88
}
89
```
90
91
[Query Execution](./query-execution.md)
92
93
### Transaction Management
94
95
Comprehensive transaction management with support for nested transactions, rollback semantics, and lifecycle callbacks.
96
97
```kotlin { .api }
98
interface Transacter : TransacterBase {
99
fun <R> transactionWithResult(
100
noEnclosing: Boolean = false,
101
bodyWithReturn: TransactionWithReturn<R>.() -> R
102
): R
103
104
fun transaction(
105
noEnclosing: Boolean = false,
106
body: TransactionWithoutReturn.() -> Unit
107
)
108
}
109
110
interface SuspendingTransacter : TransacterBase {
111
suspend fun <R> transactionWithResult(
112
noEnclosing: Boolean = false,
113
bodyWithReturn: suspend SuspendingTransactionWithReturn<R>.() -> R
114
): R
115
116
suspend fun transaction(
117
noEnclosing: Boolean = false,
118
body: suspend SuspendingTransactionWithoutReturn.() -> Unit
119
)
120
}
121
```
122
123
[Transaction Management](./transaction-management.md)
124
125
### Database Driver Interface
126
127
Low-level database driver abstraction providing platform-agnostic SQL execution and connection management.
128
129
```kotlin { .api }
130
interface SqlDriver : Closeable {
131
fun <R> executeQuery(
132
identifier: Int?,
133
sql: String,
134
mapper: (SqlCursor) -> QueryResult<R>,
135
parameters: Int,
136
binders: (SqlPreparedStatement.() -> Unit)? = null
137
): QueryResult<R>
138
139
fun execute(
140
identifier: Int?,
141
sql: String,
142
parameters: Int,
143
binders: (SqlPreparedStatement.() -> Unit)? = null
144
): QueryResult<Long>
145
146
fun newTransaction(): QueryResult<Transacter.Transaction>
147
fun currentTransaction(): Transacter.Transaction?
148
}
149
```
150
151
[Database Driver Interface](./database-driver.md)
152
153
### Column Adapters
154
155
Type marshaling system for converting between Kotlin types and database-supported primitives with built-in enum support.
156
157
```kotlin { .api }
158
interface ColumnAdapter<T : Any, S> {
159
fun decode(databaseValue: S): T
160
fun encode(value: T): S
161
}
162
163
class EnumColumnAdapter<T : Enum<T>> internal constructor(
164
private val enumValues: Array<out T>
165
) : ColumnAdapter<T, String>
166
167
inline fun <reified T : Enum<T>> EnumColumnAdapter(): EnumColumnAdapter<T>
168
```
169
170
[Column Adapters](./column-adapters.md)
171
172
### Schema Management
173
174
Database schema creation, versioning, and migration support with callback-based upgrade logic.
175
176
```kotlin { .api }
177
interface SqlSchema<T : QueryResult<Unit>> {
178
val version: Long
179
fun create(driver: SqlDriver): T
180
fun migrate(driver: SqlDriver, oldVersion: Long, newVersion: Long, vararg callbacks: AfterVersion): T
181
}
182
183
class AfterVersion(
184
val afterVersion: Long,
185
val block: (SqlDriver) -> Unit
186
)
187
```
188
189
[Schema Management](./schema-management.md)
190
191
### Logging and Debugging
192
193
Comprehensive logging support for debugging database operations with query and transaction visibility.
194
195
```kotlin { .api }
196
class LogSqliteDriver(
197
private val sqlDriver: SqlDriver,
198
private val logger: (String) -> Unit
199
) : SqlDriver
200
```
201
202
[Logging and Debugging](./logging-debugging.md)
203
204
## Types
205
206
```kotlin { .api }
207
sealed interface QueryResult<T> {
208
val value: T
209
suspend fun await(): T
210
211
@JvmInline
212
value class Value<T>(override val value: T) : QueryResult<T>
213
214
@JvmInline
215
value class AsyncValue<T>(private val getter: suspend () -> T) : QueryResult<T>
216
}
217
218
interface SqlCursor {
219
fun next(): QueryResult<Boolean>
220
fun getString(index: Int): String?
221
fun getLong(index: Int): Long?
222
fun getBytes(index: Int): ByteArray?
223
fun getDouble(index: Int): Double?
224
fun getBoolean(index: Int): Boolean?
225
}
226
227
interface SqlPreparedStatement {
228
fun bindBytes(index: Int, bytes: ByteArray?)
229
fun bindLong(index: Int, long: Long?)
230
fun bindDouble(index: Int, double: Double?)
231
fun bindString(index: Int, string: String?)
232
fun bindBoolean(index: Int, boolean: Boolean?)
233
}
234
235
expect interface Closeable {
236
fun close()
237
}
238
239
expect inline fun <T : Closeable?, R> T.use(body: (T) -> R): R
240
241
class OptimisticLockException(message: String?, cause: Throwable? = null) : IllegalStateException(message, cause)
242
```