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
```