SergeychWorks/lyng
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases 21 Wiki Activity

Add Lyng DB contract and SQLite provider skeleton

Browse Source
This commit is contained in:
Sergey Chernov 2026-04-15 20:39:38 +03:00
parent b42ceec686
commit 55ba6113e7
21 changed files with 3860 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
gradle/libs.versions.toml
View File

@ -15,6 +15,7 @@ okioVersion = "3.10.2"
compiler = "3.2.0-alpha11"
ktor = "3.3.1"
slf4j = "2.0.17"
sqlite-jdbc = "3.50.3.0"
[libraries]
clikt = { module = "com.github.ajalt.clikt:clikt", version.ref = "clikt" }
@ -43,6 +44,7 @@ ktor-client-winhttp = { module = "io.ktor:ktor-client-winhttp", version.ref = "k
ktor-client-websockets = { module = "io.ktor:ktor-client-websockets", version.ref = "ktor" }
ktor-network = { module = "io.ktor:ktor-network", version.ref = "ktor" }
slf4j-nop = { module = "org.slf4j:slf4j-nop", version.ref = "slf4j" }
sqlite-jdbc = { module = "org.xerial:sqlite-jdbc", version.ref = "sqlite-jdbc" }
[plugins]
androidLibrary = { id = "com.android.library", version.ref = "agp" }

22
lyngio/build.gradle.kts
View File

@ -58,6 +58,27 @@ kotlin {
// nodejs()
// }
targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget::class.java).configureEach {
compilations.getByName("main").cinterops.create("sqlite3") {
defFile(project.file("src/nativeInterop/cinterop/sqlite/sqlite3.def"))
packageName("net.sergeych.lyng.io.db.sqlite.cinterop")
includeDirs(project.file("src/nativeInterop/cinterop/sqlite"))
}
binaries.all {
when (konanTarget.name) {
"linux_x64" -> linkerOpts(
"-L/lib/x86_64-linux-gnu",
"-l:libsqlite3.so.0",
"-ldl",
"-lpthread",
"-lm",
"-Wl,--allow-shlib-undefined"
)
else -> linkerOpts("-lsqlite3")
}
}
}
// Keep expect/actual warning suppressed consistently with other modules
targets.configureEach {
compilations.configureEach {
@ -155,6 +176,7 @@ kotlin {
implementation("org.jline:jline-terminal:3.29.0")
implementation(libs.ktor.client.cio)
implementation(libs.ktor.network)
implementation(libs.sqlite.jdbc)
}
}
// // For Wasm we use in-memory VFS for now

37
lyngio/src/androidMain/kotlin/net/sergeych/lyng/io/db/sqlite/PlatformAndroid.kt Normal file
View File

@ -0,0 +1,37 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db.sqlite
import net.sergeych.lyng.ScopeFacade
import net.sergeych.lyng.requireScope
import net.sergeych.lyng.obj.ObjException
import net.sergeych.lyng.obj.ObjString
internal actual suspend fun openSqliteBackend(
scope: ScopeFacade,
core: SqliteCoreModule,
options: SqliteOpenOptions,
): SqliteDatabaseBackend {
scope.raiseError(
ObjException(
core.databaseException,
scope.requireScope(),
ObjString("SQLite provider is not implemented on this platform yet")
)
)
}

142
lyngio/src/commonMain/kotlin/net/sergeych/lyng/io/db/LyngDbModule.kt Normal file
View File

@ -0,0 +1,142 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db
import net.sergeych.lyng.ModuleScope
import net.sergeych.lyng.Pos
import net.sergeych.lyng.Scope
import net.sergeych.lyng.ScopeFacade
import net.sergeych.lyng.Source
import net.sergeych.lyng.Arguments
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjException
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.obj.ObjVoid
import net.sergeych.lyng.obj.requiredArg
import net.sergeych.lyng.pacman.ImportManager
import net.sergeych.lyng.requireScope
import net.sergeych.lyngio.stdlib_included.dbLyng
private const val DB_MODULE_NAME = "lyng.io.db"
fun createDbModule(scope: Scope): Boolean = createDbModule(scope.importManager)
fun createDb(scope: Scope): Boolean = createDbModule(scope)
fun createDbModule(manager: ImportManager): Boolean {
if (manager.packageNames.contains(DB_MODULE_NAME)) return false
manager.addPackage(DB_MODULE_NAME) { module ->
buildDbModule(module)
}
return true
}
fun createDb(manager: ImportManager): Boolean = createDbModule(manager)
private suspend fun buildDbModule(module: ModuleScope) {
module.eval(Source(DB_MODULE_NAME, dbLyng))
val exceptions = installDbExceptionClasses(module)
val registry = DbProviderRegistry()
module.addFn("registerDatabaseProvider") {
val scheme = requiredArg<ObjString>(0).value
val opener = args.list.getOrNull(1)
?: raiseError("Expected exactly 2 arguments, got ${args.list.size}")
registry.register(this, scheme, opener)
ObjVoid
}
module.addFn("openDatabase") {
val connectionUrl = requiredArg<ObjString>(0).value
val extraParams = args.list.getOrNull(1)
?: raiseError("Expected exactly 2 arguments, got ${args.list.size}")
if (!extraParams.isInstanceOf("Map")) {
raiseIllegalArgument("extraParams must be Map")
}
val scheme = parseConnectionScheme(connectionUrl)
?: raiseIllegalArgument("Malformed database connection URL: $connectionUrl")
val opener = registry.providers[scheme]
?: raiseDatabaseException(exceptions.database, "No database provider registered for scheme '$scheme'")
call(opener, Arguments(listOf(ObjString(connectionUrl), extraParams)), newThisObj = ObjNull)
}
}
private data class DbExceptionClasses(
val database: ObjException.Companion.ExceptionClass,
val sqlExecution: ObjException.Companion.ExceptionClass,
val sqlConstraint: ObjException.Companion.ExceptionClass,
val sqlUsage: ObjException.Companion.ExceptionClass,
val rollback: ObjException.Companion.ExceptionClass,
)
private fun installDbExceptionClasses(module: ModuleScope): DbExceptionClasses {
val database = ObjException.Companion.ExceptionClass("DatabaseException", ObjException.Root)
val sqlExecution = ObjException.Companion.ExceptionClass("SqlExecutionException", database)
val sqlConstraint = ObjException.Companion.ExceptionClass("SqlConstraintException", sqlExecution)
val sqlUsage = ObjException.Companion.ExceptionClass("SqlUsageException", database)
val rollback = ObjException.Companion.ExceptionClass("RollbackException", ObjException.Root)
module.addConst("DatabaseException", database)
module.addConst("SqlExecutionException", sqlExecution)
module.addConst("SqlConstraintException", sqlConstraint)
module.addConst("SqlUsageException", sqlUsage)
module.addConst("RollbackException", rollback)
return DbExceptionClasses(
database = database,
sqlExecution = sqlExecution,
sqlConstraint = sqlConstraint,
sqlUsage = sqlUsage,
rollback = rollback,
)
}
private class DbProviderRegistry {
val providers: MutableMap<String, Obj> = linkedMapOf()
fun register(scope: ScopeFacade, rawScheme: String, opener: Obj) {
val scheme = normalizeScheme(rawScheme)
?: scope.raiseIllegalArgument("Database provider scheme must not be empty")
if (!opener.isInstanceOf("Callable")) {
scope.raiseIllegalArgument("Database provider opener must be callable")
}
if (providers.containsKey(scheme)) {
scope.raiseIllegalState("Database provider already registered for scheme '$scheme'")
}
providers[scheme] = opener
}
}
private fun normalizeScheme(rawScheme: String): String? {
val trimmed = rawScheme.trim()
if (trimmed.isEmpty()) return null
if (':' in trimmed) return null
return trimmed.lowercase()
}
private fun parseConnectionScheme(connectionUrl: String): String? {
val colonIndex = connectionUrl.indexOf(':')
if (colonIndex <= 0) return null
return normalizeScheme(connectionUrl.substring(0, colonIndex))
}
private fun ScopeFacade.raiseDatabaseException(
exceptionClass: ObjException.Companion.ExceptionClass,
message: String,
): Nothing = raiseError(ObjException(exceptionClass, requireScope(), ObjString(message)))

542
lyngio/src/commonMain/kotlin/net/sergeych/lyng/io/db/sqlite/LyngSqliteModule.kt Normal file
View File

@ -0,0 +1,542 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db.sqlite
import net.sergeych.lyng.Arguments
import net.sergeych.lyng.ModuleScope
import net.sergeych.lyng.Pos
import net.sergeych.lyng.Scope
import net.sergeych.lyng.ScopeFacade
import net.sergeych.lyng.Source
import net.sergeych.lyng.asFacade
import net.sergeych.lyng.io.db.createDbModule
import net.sergeych.lyng.requireScope
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjBool
import net.sergeych.lyng.obj.ObjClass
import net.sergeych.lyng.obj.ObjEnumClass
import net.sergeych.lyng.obj.ObjEnumEntry
import net.sergeych.lyng.obj.ObjException
import net.sergeych.lyng.obj.ObjImmutableList
import net.sergeych.lyng.obj.ObjInt
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjReal
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.obj.ObjVoid
import net.sergeych.lyng.obj.requiredArg
import net.sergeych.lyng.obj.thisAs
import net.sergeych.lyng.pacman.ImportManager
import net.sergeych.lyngio.stdlib_included.db_sqliteLyng
private const val SQLITE_MODULE_NAME = "lyng.io.db.sqlite"
private const val DB_MODULE_NAME = "lyng.io.db"
fun createSqliteModule(scope: Scope): Boolean = createSqliteModule(scope.importManager)
fun createSqlite(scope: Scope): Boolean = createSqliteModule(scope)
fun createSqliteModule(manager: ImportManager): Boolean {
createDbModule(manager)
if (manager.packageNames.contains(SQLITE_MODULE_NAME)) return false
manager.addPackage(SQLITE_MODULE_NAME) { module ->
buildSqliteModule(module)
}
return true
}
fun createSqlite(manager: ImportManager): Boolean = createSqliteModule(manager)
private suspend fun buildSqliteModule(module: ModuleScope) {
module.eval(Source(SQLITE_MODULE_NAME, db_sqliteLyng))
val dbModule = module.importProvider.createModuleScope(Pos.builtIn, DB_MODULE_NAME)
val core = SqliteCoreModule.resolve(dbModule)
val runtimeTypes = SqliteRuntimeTypes.create(core)
module.addFn("openSqlite") {
val options = parseOpenSqliteArgs(this)
SqliteDatabaseObj(runtimeTypes, openSqliteBackend(this, core, options))
}
dbModule.callFn(
"registerDatabaseProvider",
ObjString("sqlite"),
net.sergeych.lyng.obj.ObjExternCallable.fromBridge {
val connectionUrl = requiredArg<ObjString>(0).value
val extraParams = args.list.getOrNull(1)
?: raiseError("Expected exactly 2 arguments, got ${args.list.size}")
val options = parseSqliteConnectionUrl(this, connectionUrl, extraParams)
SqliteDatabaseObj(runtimeTypes, openSqliteBackend(this, core, options))
}
)
}
private suspend fun parseOpenSqliteArgs(scope: ScopeFacade): SqliteOpenOptions {
val pathValue = readArg(scope, "path", 0) ?: scope.raiseError("argument 'path' is required")
val path = (pathValue as? ObjString)?.value ?: scope.raiseClassCastError("path must be String")
val readOnly = readBoolArg(scope, "readOnly", 1, false)
val createIfMissing = readBoolArg(scope, "createIfMissing", 2, true)
val foreignKeys = readBoolArg(scope, "foreignKeys", 3, true)
val busyTimeoutMillis = readIntArg(scope, "busyTimeoutMillis", 4, 5000)
return SqliteOpenOptions(
path = normalizeSqlitePath(path, scope),
readOnly = readOnly,
createIfMissing = createIfMissing,
foreignKeys = foreignKeys,
busyTimeoutMillis = busyTimeoutMillis,
)
}
private suspend fun parseSqliteConnectionUrl(
scope: ScopeFacade,
connectionUrl: String,
extraParams: Obj,
): SqliteOpenOptions {
val prefix = "sqlite:"
if (!connectionUrl.startsWith(prefix, ignoreCase = true)) {
scope.raiseIllegalArgument("Malformed SQLite connection URL: $connectionUrl")
}
val rawPath = connectionUrl.substring(prefix.length)
val path = normalizeSqlitePath(rawPath, scope)
val readOnly = mapBool(extraParams, scope, "readOnly") ?: false
val createIfMissing = mapBool(extraParams, scope, "createIfMissing") ?: true
val foreignKeys = mapBool(extraParams, scope, "foreignKeys") ?: true
val busyTimeoutMillis = mapInt(extraParams, scope, "busyTimeoutMillis") ?: 5000
return SqliteOpenOptions(
path = path,
readOnly = readOnly,
createIfMissing = createIfMissing,
foreignKeys = foreignKeys,
busyTimeoutMillis = busyTimeoutMillis,
)
}
private fun normalizeSqlitePath(rawPath: String, scope: ScopeFacade): String {
val path = rawPath.trim()
if (path.isEmpty()) {
scope.raiseIllegalArgument("SQLite path must not be empty")
}
if (path.startsWith("//")) {
scope.raiseIllegalArgument("Unsupported SQLite URL form: sqlite:$path")
}
return path
}
private suspend fun readArg(scope: ScopeFacade, name: String, position: Int): Obj? {
val named = scope.args.named[name]
val positional = scope.args.list.getOrNull(position)
if (named != null && positional != null) {
scope.raiseIllegalArgument("argument '$name' is already set")
}
return named ?: positional
}
private suspend fun readBoolArg(scope: ScopeFacade, name: String, position: Int, default: Boolean): Boolean {
val value = readArg(scope, name, position) ?: return default
return (value as? ObjBool)?.value ?: scope.raiseClassCastError("$name must be Bool")
}
private suspend fun readIntArg(scope: ScopeFacade, name: String, position: Int, default: Int): Int {
val value = readArg(scope, name, position) ?: return default
return when (value) {
is ObjInt -> value.value.toInt()
else -> scope.raiseClassCastError("$name must be Int")
}
}
private suspend fun mapBool(map: Obj, scope: ScopeFacade, key: String): Boolean? {
val value = map.getAt(scope.requireScope(), ObjString(key))
return when (value) {
ObjNull -> null
is ObjBool -> value.value
else -> scope.raiseClassCastError("extraParams.$key must be Bool")
}
}
private suspend fun mapInt(map: Obj, scope: ScopeFacade, key: String): Int? {
val value = map.getAt(scope.requireScope(), ObjString(key))
return when (value) {
ObjNull -> null
is ObjInt -> value.value.toInt()
else -> scope.raiseClassCastError("extraParams.$key must be Int")
}
}
private suspend fun ModuleScope.callFn(name: String, vararg args: Obj): Obj {
val callee = get(name)?.value ?: error("Missing $name in module")
return callee.invoke(this, ObjNull, *args)
}
internal data class SqliteOpenOptions(
val path: String,
val readOnly: Boolean,
val createIfMissing: Boolean,
val foreignKeys: Boolean,
val busyTimeoutMillis: Int,
)
internal data class SqliteColumnMeta(
val name: String,
val sqlType: ObjEnumEntry,
val nullable: Boolean,
val nativeType: String,
)
internal data class SqliteResultSetData(
val columns: List<SqliteColumnMeta>,
val rows: List<List<Obj>>,
)
internal data class SqliteExecutionResultData(
val affectedRowsCount: Int,
val generatedKeys: SqliteResultSetData,
)
internal interface SqliteDatabaseBackend {
suspend fun <T> transaction(scope: ScopeFacade, block: suspend (SqliteTransactionBackend) -> T): T
}
internal interface SqliteTransactionBackend {
suspend fun select(scope: ScopeFacade, clause: String, params: List<Obj>): SqliteResultSetData
suspend fun execute(scope: ScopeFacade, clause: String, params: List<Obj>): SqliteExecutionResultData
suspend fun <T> transaction(scope: ScopeFacade, block: suspend (SqliteTransactionBackend) -> T): T
}
internal expect suspend fun openSqliteBackend(
scope: ScopeFacade,
core: SqliteCoreModule,
options: SqliteOpenOptions,
): SqliteDatabaseBackend
internal class SqliteCoreModule private constructor(
val module: ModuleScope,
val databaseClass: ObjClass,
val transactionClass: ObjClass,
val resultSetClass: ObjClass,
val rowClass: ObjClass,
val columnClass: ObjClass,
val executionResultClass: ObjClass,
val databaseException: ObjException.Companion.ExceptionClass,
val sqlExecutionException: ObjException.Companion.ExceptionClass,
val sqlConstraintException: ObjException.Companion.ExceptionClass,
val sqlUsageException: ObjException.Companion.ExceptionClass,
val rollbackException: ObjException.Companion.ExceptionClass,
val sqlTypes: SqlTypeEntries,
) {
companion object {
fun resolve(module: ModuleScope): SqliteCoreModule = SqliteCoreModule(
module = module,
databaseClass = module.requireClass("Database"),
transactionClass = module.requireClass("SqlTransaction"),
resultSetClass = module.requireClass("ResultSet"),
rowClass = module.requireClass("SqlRow"),
columnClass = module.requireClass("SqlColumn"),
executionResultClass = module.requireClass("ExecutionResult"),
databaseException = module.requireClass("DatabaseException") as ObjException.Companion.ExceptionClass,
sqlExecutionException = module.requireClass("SqlExecutionException") as ObjException.Companion.ExceptionClass,
sqlConstraintException = module.requireClass("SqlConstraintException") as ObjException.Companion.ExceptionClass,
sqlUsageException = module.requireClass("SqlUsageException") as ObjException.Companion.ExceptionClass,
rollbackException = module.requireClass("RollbackException") as ObjException.Companion.ExceptionClass,
sqlTypes = SqlTypeEntries.resolve(module),
)
}
}
internal class SqlTypeEntries private constructor(
private val entries: Map<String, ObjEnumEntry>,
) {
fun require(name: String): ObjEnumEntry = entries[name]
?: error("lyng.io.db.SqlType entry is missing: $name")
companion object {
fun resolve(module: ModuleScope): SqlTypeEntries {
val enumClass = resolveEnum(module, "SqlType")
return SqlTypeEntries(
listOf(
"Binary", "String", "Int", "Double", "Decimal",
"Bool", "Instant", "Date", "DateTime"
).associateWith { name ->
enumClass.byName[ObjString(name)] as? ObjEnumEntry
?: error("lyng.io.db.SqlType.$name is missing")
}
)
}
private fun resolveEnum(module: ModuleScope, enumName: String): ObjEnumClass {
val local = module.get(enumName)?.value as? ObjEnumClass
if (local != null) return local
val root = module.importProvider.rootScope.get(enumName)?.value as? ObjEnumClass
return root ?: error("lyng.io.db declaration enum is missing: $enumName")
}
}
}
private class SqliteRuntimeTypes private constructor(
val core: SqliteCoreModule,
val databaseClass: ObjClass,
val transactionClass: ObjClass,
val resultSetClass: ObjClass,
val rowClass: ObjClass,
val columnClass: ObjClass,
val executionResultClass: ObjClass,
) {
companion object {
fun create(core: SqliteCoreModule): SqliteRuntimeTypes {
val databaseClass = object : ObjClass("SqliteDatabase", core.databaseClass) {}
val transactionClass = object : ObjClass("SqliteTransaction", core.transactionClass) {}
val resultSetClass = object : ObjClass("SqliteResultSet", core.resultSetClass) {}
val rowClass = object : ObjClass("SqliteRow", core.rowClass) {}
val columnClass = object : ObjClass("SqliteColumn", core.columnClass) {}
val executionResultClass = object : ObjClass("SqliteExecutionResult", core.executionResultClass) {}
val runtime = SqliteRuntimeTypes(
core = core,
databaseClass = databaseClass,
transactionClass = transactionClass,
resultSetClass = resultSetClass,
rowClass = rowClass,
columnClass = columnClass,
executionResultClass = executionResultClass,
)
runtime.bind()
return runtime
}
}
private fun bind() {
databaseClass.addFn("transaction") {
val self = thisAs<SqliteDatabaseObj>()
val block = args.list.getOrNull(0) ?: raiseError("Expected exactly 1 argument, got ${args.list.size}")
if (!block.isInstanceOf("Callable")) {
raiseClassCastError("transaction block must be callable")
}
self.backend.transaction(this) { backend ->
val lifetime = TransactionLifetime(this@SqliteRuntimeTypes.core)
try {
call(block, Arguments(SqliteTransactionObj(this@SqliteRuntimeTypes, backend, lifetime)), ObjNull)
} finally {
lifetime.close()
}
}
}
transactionClass.addFn("select") {
val self = thisAs<SqliteTransactionObj>()
self.lifetime.ensureActive(this)
val clause = requiredArg<ObjString>(0).value
val params = args.list.drop(1)
SqliteResultSetObj(thisAs<SqliteTransactionObj>().types, self.lifetime, self.backend.select(this, clause, params))
}
transactionClass.addFn("execute") {
val self = thisAs<SqliteTransactionObj>()
self.lifetime.ensureActive(this)
val clause = requiredArg<ObjString>(0).value
val params = args.list.drop(1)
SqliteExecutionResultObj(self.types, self.lifetime, self.backend.execute(this, clause, params))
}
transactionClass.addFn("transaction") {
val self = thisAs<SqliteTransactionObj>()
self.lifetime.ensureActive(this)
val block = args.list.getOrNull(0) ?: raiseError("Expected exactly 1 argument, got ${args.list.size}")
if (!block.isInstanceOf("Callable")) {
raiseClassCastError("transaction block must be callable")
}
self.backend.transaction(this) { backend ->
val lifetime = TransactionLifetime(this@SqliteRuntimeTypes.core)
try {
call(block, Arguments(SqliteTransactionObj(self.types, backend, lifetime)), ObjNull)
} finally {
lifetime.close()
}
}
}
resultSetClass.addProperty("columns", getter = {
val self = thisAs<SqliteResultSetObj>()
self.lifetime.ensureActive(this)
ObjImmutableList(self.columns)
})
resultSetClass.addFn("size") {
val self = thisAs<SqliteResultSetObj>()
self.lifetime.ensureActive(this)
ObjInt.of(self.rows.size.toLong())
}
resultSetClass.addFn("isEmpty") {
val self = thisAs<SqliteResultSetObj>()
self.lifetime.ensureActive(this)
ObjBool(self.rows.isEmpty())
}
resultSetClass.addFn("iterator") {
val self = thisAs<SqliteResultSetObj>()
self.lifetime.ensureActive(this)
ObjImmutableList(self.rows).invokeInstanceMethod(requireScope(), "iterator")
}
resultSetClass.addFn("toList") {
val self = thisAs<SqliteResultSetObj>()
self.lifetime.ensureActive(this)
ObjImmutableList(self.rows)
}
rowClass.addProperty("size", getter = {
val self = thisAs<SqliteRowObj>()
self.lifetime.ensureActive(this)
ObjInt.of(self.values.size.toLong())
})
rowClass.addProperty("values", getter = {
val self = thisAs<SqliteRowObj>()
self.lifetime.ensureActive(this)
ObjImmutableList(self.values)
})
columnClass.addProperty("name", getter = { ObjString(thisAs<SqliteColumnObj>().meta.name) })
columnClass.addProperty("sqlType", getter = { thisAs<SqliteColumnObj>().meta.sqlType })
columnClass.addProperty("nullable", getter = { ObjBool(thisAs<SqliteColumnObj>().meta.nullable) })
columnClass.addProperty("nativeType", getter = { ObjString(thisAs<SqliteColumnObj>().meta.nativeType) })
executionResultClass.addProperty("affectedRowsCount", getter = {
val self = thisAs<SqliteExecutionResultObj>()
self.lifetime.ensureActive(this)
ObjInt.of(self.result.affectedRowsCount.toLong())
})
executionResultClass.addFn("getGeneratedKeys") {
val self = thisAs<SqliteExecutionResultObj>()
self.lifetime.ensureActive(this)
SqliteResultSetObj(self.types, self.lifetime, self.result.generatedKeys)
}
}
}
private class TransactionLifetime(
private val core: SqliteCoreModule,
) {
private var active = true
fun close() {
active = false
}
fun ensureActive(scope: ScopeFacade) {
if (!active) {
scope.raiseError(
ObjException(core.sqlUsageException, scope.requireScope(), ObjString("SQL result can be used only while its transaction is active"))
)
}
}
}
private class SqliteDatabaseObj(
val types: SqliteRuntimeTypes,
val backend: SqliteDatabaseBackend,
) : Obj() {
override val objClass: ObjClass
get() = types.databaseClass
}
private class SqliteTransactionObj(
val types: SqliteRuntimeTypes,
val backend: SqliteTransactionBackend,
val lifetime: TransactionLifetime,
) : Obj() {
override val objClass: ObjClass
get() = types.transactionClass
}
private class SqliteResultSetObj(
val types: SqliteRuntimeTypes,
val lifetime: TransactionLifetime,
data: SqliteResultSetData,
) : Obj() {
val columns: List<Obj> = data.columns.map { SqliteColumnObj(types, it) }
val rows: List<Obj> = buildRows(types, lifetime, data)
override val objClass: ObjClass
get() = types.resultSetClass
private fun buildRows(
types: SqliteRuntimeTypes,
lifetime: TransactionLifetime,
data: SqliteResultSetData,
): List<Obj> {
val indexByName = linkedMapOf<String, MutableList<Int>>()
data.columns.forEachIndexed { index, column ->
indexByName.getOrPut(column.name.lowercase()) { mutableListOf() }.add(index)
}
return data.rows.map { rowValues ->
SqliteRowObj(types, lifetime, rowValues, indexByName)
}
}
}
private class SqliteRowObj(
val types: SqliteRuntimeTypes,
val lifetime: TransactionLifetime,
val values: List<Obj>,
private val indexByName: Map<String, List<Int>>,
) : Obj() {
override val objClass: ObjClass
get() = types.rowClass
override suspend fun getAt(scope: Scope, index: Obj): Obj {
lifetime.ensureActive(scope.asFacade())
return when (index) {
is ObjInt -> {
val idx = index.value.toInt()
if (idx !in values.indices) {
scope.raiseIndexOutOfBounds("SQL row index $idx is out of bounds")
}
values[idx]
}
is ObjString -> {
val matches = indexByName[index.value.lowercase()]
?: scope.raiseError(
ObjException(
types.core.sqlUsageException,
scope,
ObjString("No such SQL result column: ${index.value}")
)
)
if (matches.size != 1) {
scope.raiseError(
ObjException(
types.core.sqlUsageException,
scope,
ObjString("Ambiguous SQL result column: ${index.value}")
)
)
}
values[matches.first()]
}
else -> scope.raiseClassCastError("SQL row index must be Int or String")
}
}
}
private class SqliteColumnObj(
val types: SqliteRuntimeTypes,
val meta: SqliteColumnMeta,
) : Obj() {
override val objClass: ObjClass
get() = types.columnClass
}
private class SqliteExecutionResultObj(
val types: SqliteRuntimeTypes,
val lifetime: TransactionLifetime,
val result: SqliteExecutionResultData,
) : Obj() {
override val objClass: ObjClass
get() = types.executionResultClass
}

134
lyngio/src/commonTest/kotlin/net/sergeych/lyng/io/db/LyngDbModuleTest.kt Normal file
View File

@ -0,0 +1,134 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db
import kotlinx.coroutines.test.runTest
import net.sergeych.lyng.Compiler
import net.sergeych.lyng.ExecutionError
import net.sergeych.lyng.pacman.ImportManager
import net.sergeych.lyng.Pos
import net.sergeych.lyng.Script
import net.sergeych.lyng.Source
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjExternCallable
import net.sergeych.lyng.obj.ObjInt
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.obj.requiredArg
import net.sergeych.lyng.requireScope
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertFalse
import kotlin.test.assertTrue
class LyngDbModuleTest {
@Test
fun testModuleRegistrationIsIdempotent() = runTest {
val importManager = ImportManager()
assertTrue(createDbModule(importManager))
assertFalse(createDbModule(importManager))
}
@Test
fun testOpenDatabaseDispatchesByNormalizedScheme() = runTest {
val scope = Script.newScope()
createDbModule(scope.importManager)
val module = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db")
module.callFn(
"registerDatabaseProvider",
ObjString("TeSt"),
ObjExternCallable.fromBridge {
val url = requiredArg<ObjString>(0).value
val params = requiredArg<Obj>(1)
val size = (params.invokeInstanceMethod(requireScope(), "size") as ObjInt).value
ObjString("$url|$size")
}
)
val code = """
import lyng.io.db
openDatabase("TEST:demo", Map("a" => 1, "b" => 2))
""".trimIndent()
val result = Compiler.compile(Source("<db-test>", code), scope.importManager).execute(scope) as ObjString
assertEquals("TEST:demo|2", result.value)
}
@Test
fun testDuplicateSchemeRegistrationFailsCaseInsensitively() = runTest {
val importManager = Script.defaultImportManager.copy()
createDbModule(importManager)
val module = importManager.createModuleScope(Pos.builtIn, "lyng.io.db")
module.callFn("registerDatabaseProvider", ObjString("sqlite"), trivialOpener())
val error = try {
module.callFn("registerDatabaseProvider", ObjString("SQLITE"), trivialOpener())
kotlin.test.fail("expected duplicate registration to fail")
} catch (e: ExecutionError) {
e
}
assertTrue(error.errorMessage.contains("already registered"), error.errorMessage)
}
@Test
fun testMalformedUrlFailsWithIllegalArgument() = runTest {
val scope = Script.newScope()
createDbModule(scope.importManager)
val code = """
import lyng.io.db
openDatabase("not-a-url", Map())
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<db-test>", code), scope.importManager).execute(scope)
}
assertEquals("IllegalArgumentException", error.errorObject.objClass.className)
assertTrue(error.errorMessage.contains("Malformed database connection URL"), error.errorMessage)
}
@Test
fun testUnknownSchemeFailsWithDatabaseException() = runTest {
val scope = Script.newScope()
createDbModule(scope.importManager)
val code = """
import lyng.io.db
openDatabase("unknown:demo", Map())
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<db-test>", code), scope.importManager).execute(scope)
}
assertEquals("DatabaseException", error.errorObject.objClass.className)
assertTrue(error.errorMessage.contains("No database provider registered"), error.errorMessage)
}
private suspend fun net.sergeych.lyng.ModuleScope.callFn(name: String, vararg args: Obj): Obj {
val callee = get(name)?.value ?: error("Missing $name in module")
return callee.invoke(this, ObjNull, *args)
}
private fun trivialOpener(): Obj = ObjExternCallable.fromBridge { ObjInt.One }
}

37
lyngio/src/jsMain/kotlin/net/sergeych/lyng/io/db/sqlite/PlatformJs.kt Normal file
View File

@ -0,0 +1,37 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db.sqlite
import net.sergeych.lyng.ScopeFacade
import net.sergeych.lyng.requireScope
import net.sergeych.lyng.obj.ObjException
import net.sergeych.lyng.obj.ObjString
internal actual suspend fun openSqliteBackend(
scope: ScopeFacade,
core: SqliteCoreModule,
options: SqliteOpenOptions,
): SqliteDatabaseBackend {
scope.raiseError(
ObjException(
core.databaseException,
scope.requireScope(),
ObjString("SQLite provider is not implemented on this platform yet")
)
)
}

389
lyngio/src/jvmMain/kotlin/net/sergeych/lyng/io/db/sqlite/PlatformJvm.kt Normal file
View File

@ -0,0 +1,389 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db.sqlite
import net.sergeych.lyng.ExecutionError
import net.sergeych.lyng.Arguments
import net.sergeych.lyng.ScopeFacade
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjBool
import net.sergeych.lyng.obj.ObjBuffer
import net.sergeych.lyng.obj.ObjDateTime
import net.sergeych.lyng.obj.ObjEnumEntry
import net.sergeych.lyng.obj.ObjException
import net.sergeych.lyng.obj.ObjInt
import net.sergeych.lyng.obj.ObjInstant
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjReal
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.requireScope
import kotlinx.datetime.LocalDateTime
import kotlinx.datetime.TimeZone
import kotlinx.datetime.toInstant
import org.sqlite.SQLiteConfig
import org.sqlite.SQLiteErrorCode
import org.sqlite.SQLiteOpenMode
import java.sql.Connection
import java.sql.DriverManager
import java.sql.PreparedStatement
import java.sql.ResultSet
import java.sql.SQLException
import java.sql.Statement
import kotlin.time.Instant
internal actual suspend fun openSqliteBackend(
scope: ScopeFacade,
core: SqliteCoreModule,
options: SqliteOpenOptions,
): SqliteDatabaseBackend {
if (options.busyTimeoutMillis < 0) {
scope.raiseIllegalArgument("busyTimeoutMillis must be >= 0")
}
return JdbcSqliteDatabaseBackend(core, options)
}
private class JdbcSqliteDatabaseBackend(
private val core: SqliteCoreModule,
private val options: SqliteOpenOptions,
) : SqliteDatabaseBackend {
override suspend fun <T> transaction(scope: ScopeFacade, block: suspend (SqliteTransactionBackend) -> T): T {
val connection = openConnection(scope)
try {
connection.autoCommit = false
val tx = JdbcSqliteTransactionBackend(core, connection)
return try {
val result = block(tx)
connection.commit()
result
} catch (e: Throwable) {
rollbackQuietly(connection)
throw e
}
} catch (e: SQLException) {
throw mapSqlException(scope, core, e)
} finally {
try {
connection.close()
} catch (_: SQLException) {
}
}
}
private fun openConnection(scope: ScopeFacade): Connection {
try {
val config = SQLiteConfig().apply {
setOpenMode(SQLiteOpenMode.OPEN_URI)
if (options.readOnly) {
setReadOnly(true)
setOpenMode(SQLiteOpenMode.READONLY)
} else {
setReadOnly(false)
setOpenMode(SQLiteOpenMode.READWRITE)
if (options.createIfMissing) {
setOpenMode(SQLiteOpenMode.CREATE)
}
}
enforceForeignKeys(options.foreignKeys)
busyTimeout = options.busyTimeoutMillis
}
return DriverManager.getConnection(jdbcUrl(options.path), config.toProperties())
} catch (e: SQLException) {
throw mapOpenException(scope, core, e)
} catch (e: IllegalArgumentException) {
scope.raiseIllegalArgument(e.message ?: "Invalid SQLite configuration")
}
}
private fun jdbcUrl(path: String): String {
return when (path) {
":memory:" -> "jdbc:sqlite::memory:"
else -> if (path.startsWith("/")) "jdbc:sqlite:$path" else "jdbc:sqlite:$path"
}
}
}
private class JdbcSqliteTransactionBackend(
private val core: SqliteCoreModule,
private val connection: Connection,
) : SqliteTransactionBackend {
override suspend fun select(scope: ScopeFacade, clause: String, params: List<Obj>): SqliteResultSetData {
try {
connection.prepareStatement(clause).use { statement ->
bindParams(statement, params, scope)
statement.executeQuery().use { rs ->
return readResultSet(scope, core, rs)
}
}
} catch (e: SQLException) {
throw mapSqlException(scope, core, e)
}
}
override suspend fun execute(scope: ScopeFacade, clause: String, params: List<Obj>): SqliteExecutionResultData {
if (containsRowReturningClause(clause)) {
scope.raiseError(
ObjException(
core.sqlUsageException,
scope.requireScope(),
ObjString("execute(...) cannot be used with statements that return rows; use select(...)")
)
)
}
try {
connection.prepareStatement(clause, Statement.RETURN_GENERATED_KEYS).use { statement ->
bindParams(statement, params, scope)
val hasResultSet = statement.execute()
if (hasResultSet) {
scope.raiseError(
ObjException(
core.sqlUsageException,
scope.requireScope(),
ObjString("execute(...) cannot be used with statements that return rows; use select(...)")
)
)
}
val affected = statement.updateCount
val generatedKeys = statement.generatedKeys.use { rs ->
if (rs == null) {
emptyResultSet(core)
} else {
readResultSet(scope, core, rs)
}
}
return SqliteExecutionResultData(affected, generatedKeys)
}
} catch (e: SQLException) {
throw mapSqlException(scope, core, e)
}
}
override suspend fun <T> transaction(scope: ScopeFacade, block: suspend (SqliteTransactionBackend) -> T): T {
val savepoint = try {
connection.setSavepoint()
} catch (e: SQLException) {
throw mapSqlUsage(scope, core, "Nested transactions are not supported by this SQLite backend", e)
}
return try {
val result = block(JdbcSqliteTransactionBackend(core, connection))
connection.releaseSavepoint(savepoint)
result
} catch (e: Throwable) {
rollbackQuietly(connection, savepoint)
throw e
}
}
}
private suspend fun bindParams(statement: PreparedStatement, params: List<Obj>, scope: ScopeFacade) {
params.forEachIndexed { index, value ->
val jdbcIndex = index + 1
when (value) {
ObjNull -> statement.setObject(jdbcIndex, null)
is ObjBool -> statement.setBoolean(jdbcIndex, value.value)
is ObjInt -> statement.setLong(jdbcIndex, value.value)
is ObjReal -> statement.setDouble(jdbcIndex, value.value)
is ObjString -> statement.setString(jdbcIndex, value.value)
is ObjBuffer -> statement.setBytes(jdbcIndex, value.byteArray.toByteArray())
is ObjInstant -> statement.setString(jdbcIndex, value.instant.toString())
is ObjDateTime -> statement.setString(jdbcIndex, value.localDateTime.toString())
else -> when (value.objClass.className) {
"Date", "Decimal" -> statement.setString(jdbcIndex, scope.toStringOf(value).value)
else -> scope.raiseClassCastError("Unsupported SQLite parameter type: ${value.objClass.className}")
}
}
}
}
private suspend fun readResultSet(
scope: ScopeFacade,
core: SqliteCoreModule,
resultSet: ResultSet,
): SqliteResultSetData {
val meta = resultSet.metaData
val columns = (1..meta.columnCount).map { index ->
SqliteColumnMeta(
name = meta.getColumnLabel(index),
sqlType = mapSqlType(core, meta.getColumnTypeName(index), meta.getColumnType(index)),
nullable = meta.isNullable(index) != java.sql.ResultSetMetaData.columnNoNulls,
nativeType = meta.getColumnTypeName(index) ?: "",
)
}
val rows = mutableListOf<List<Obj>>()
while (resultSet.next()) {
rows += columns.mapIndexed { index, column ->
readColumnValue(scope, core, resultSet, index + 1, column.nativeType)
}
}
return SqliteResultSetData(columns, rows)
}
private suspend fun readColumnValue(
scope: ScopeFacade,
core: SqliteCoreModule,
resultSet: ResultSet,
index: Int,
nativeType: String,
): Obj {
val value = resultSet.getObject(index) ?: return ObjNull
if (isDecimalNativeType(nativeType) && value is Number) {
return decimalFromString(scope, value.toString())
}
return when (value) {
is Boolean -> ObjBool(value)
is Byte, is Short, is Int -> ObjInt.of((value as Number).toLong())
is Long -> ObjInt.of(value)
is Float, is Double -> ObjReal.of((value as Number).toDouble())
is ByteArray -> ObjBuffer(value.toUByteArray())
is String -> convertStringValue(scope, core, nativeType, value)
is java.math.BigDecimal -> decimalFromString(scope, value.toPlainString())
else -> ObjString(value.toString())
}
}
private suspend fun convertStringValue(
scope: ScopeFacade,
core: SqliteCoreModule,
nativeType: String,
value: String,
): Obj {
val normalized = nativeType.trim().uppercase()
return when {
normalized == "DECIMAL" || normalized == "NUMERIC" -> decimalFromString(scope, value)
normalized == "DATETIME" || normalized == "TIMESTAMP" -> dateTimeFromString(value)
normalized == "TIMESTAMP WITH TIME ZONE" || normalized == "TIMESTAMPTZ" ->
ObjInstant(Instant.parse(value))
else -> ObjString(value)
}
}
private fun isDecimalNativeType(nativeType: String): Boolean {
val normalized = nativeType.trim().uppercase()
return normalized == "DECIMAL" || normalized == "NUMERIC"
}
private suspend fun decimalFromString(scope: ScopeFacade, value: String): Obj {
val decimalModule = scope.requireScope().currentImportProvider.createModuleScope(scope.pos, "lyng.decimal")
val decimalClass = decimalModule.requireClass("Decimal")
return decimalClass.invokeInstanceMethod(scope.requireScope(), "fromString", ObjString(value))
}
private fun dateTimeFromString(value: String): ObjDateTime {
val trimmed = value.trim()
return if (hasExplicitTimeZone(trimmed)) {
val instant = Instant.parse(trimmed)
ObjDateTime(instant, parseTimeZoneOrUtc(trimmed))
} else {
val local = LocalDateTime.parse(trimmed)
ObjDateTime(local.toInstant(TimeZone.UTC), TimeZone.UTC)
}
}
private fun hasExplicitTimeZone(value: String): Boolean {
if (value.endsWith("Z", ignoreCase = true)) return true
val tIndex = value.indexOf('T')
if (tIndex < 0) return false
val plus = value.lastIndexOf('+')
val minus = value.lastIndexOf('-')
val offsetStart = maxOf(plus, minus)
return offsetStart > tIndex
}
private fun containsRowReturningClause(clause: String): Boolean =
Regex("""\breturning\b""", RegexOption.IGNORE_CASE).containsMatchIn(clause)
private fun parseTimeZoneOrUtc(value: String): TimeZone {
if (value.endsWith("Z", ignoreCase = true)) return TimeZone.UTC
val tIndex = value.indexOf('T')
if (tIndex < 0) return TimeZone.UTC
val plus = value.lastIndexOf('+')
val minus = value.lastIndexOf('-')
val offsetStart = maxOf(plus, minus)
if (offsetStart <= tIndex) return TimeZone.UTC
return try {
TimeZone.of(value.substring(offsetStart))
} catch (_: IllegalArgumentException) {
TimeZone.UTC
}
}
private fun mapSqlType(core: SqliteCoreModule, nativeTypeName: String, jdbcType: Int): ObjEnumEntry {
val normalized = nativeTypeName.trim().uppercase()
return when {
normalized == "BOOLEAN" -> core.sqlTypes.require("Bool")
normalized == "DATE" -> core.sqlTypes.require("Date")
normalized == "DATETIME" || normalized == "TIMESTAMP" -> core.sqlTypes.require("DateTime")
normalized == "TIMESTAMP WITH TIME ZONE" || normalized == "TIMESTAMPTZ" -> core.sqlTypes.require("Instant")
normalized == "DECIMAL" || normalized == "NUMERIC" -> core.sqlTypes.require("Decimal")
normalized.contains("BLOB") -> core.sqlTypes.require("Binary")
normalized.contains("INT") -> core.sqlTypes.require("Int")
normalized.contains("CHAR") || normalized.contains("TEXT") || normalized.contains("CLOB") -> core.sqlTypes.require("String")
normalized.contains("REAL") || normalized.contains("FLOA") || normalized.contains("DOUB") -> core.sqlTypes.require("Double")
jdbcType == java.sql.Types.BOOLEAN -> core.sqlTypes.require("Bool")
jdbcType == java.sql.Types.BLOB || jdbcType == java.sql.Types.BINARY || jdbcType == java.sql.Types.VARBINARY -> core.sqlTypes.require("Binary")
jdbcType == java.sql.Types.INTEGER -> core.sqlTypes.require("Int")
jdbcType == java.sql.Types.BIGINT -> core.sqlTypes.require("Int")
jdbcType == java.sql.Types.DECIMAL || jdbcType == java.sql.Types.NUMERIC -> core.sqlTypes.require("Decimal")
jdbcType == java.sql.Types.FLOAT || jdbcType == java.sql.Types.REAL || jdbcType == java.sql.Types.DOUBLE -> core.sqlTypes.require("Double")
else -> core.sqlTypes.require("String")
}
}
private fun emptyResultSet(core: SqliteCoreModule): SqliteResultSetData = SqliteResultSetData(emptyList(), emptyList())
private fun rollbackQuietly(connection: Connection, savepoint: java.sql.Savepoint? = null) {
try {
if (savepoint == null) connection.rollback() else connection.rollback(savepoint)
} catch (_: SQLException) {
}
}
private fun mapOpenException(scope: ScopeFacade, core: SqliteCoreModule, e: SQLException): Nothing {
val message = e.message ?: "SQLite open failed"
val lower = message.lowercase()
if ("malformed" in lower || "no such access mode" in lower || "invalid uri" in lower) {
scope.raiseIllegalArgument(message)
}
throw mapSqlException(scope, core, e)
}
private fun mapSqlException(scope: ScopeFacade, core: SqliteCoreModule, e: SQLException): ExecutionError {
val code = SQLiteErrorCode.getErrorCode(e.errorCode)
val exceptionClass = when (code) {
SQLiteErrorCode.SQLITE_CONSTRAINT,
SQLiteErrorCode.SQLITE_CONSTRAINT_PRIMARYKEY,
SQLiteErrorCode.SQLITE_CONSTRAINT_UNIQUE,
SQLiteErrorCode.SQLITE_CONSTRAINT_FOREIGNKEY,
SQLiteErrorCode.SQLITE_CONSTRAINT_NOTNULL -> core.sqlConstraintException
else -> core.sqlExecutionException
}
return ExecutionError(
ObjException(exceptionClass, scope.requireScope(), ObjString(e.message ?: "SQLite error")),
scope.pos,
e.message ?: "SQLite error",
e,
)
}
private fun mapSqlUsage(scope: ScopeFacade, core: SqliteCoreModule, message: String, cause: Throwable? = null): ExecutionError {
return ExecutionError(
ObjException(core.sqlUsageException, scope.requireScope(), ObjString(message)),
scope.pos,
message,
cause,
)
}

452
lyngio/src/jvmTest/kotlin/net/sergeych/lyng/io/db/sqlite/LyngSqliteModuleTest.kt Normal file
View File

@ -0,0 +1,452 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db.sqlite
import kotlinx.coroutines.test.runTest
import net.sergeych.lyng.ExecutionError
import net.sergeych.lyng.ModuleScope
import net.sergeych.lyng.Pos
import net.sergeych.lyng.Scope
import net.sergeych.lyng.Script
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjBuffer
import net.sergeych.lyng.obj.ObjDateTime
import net.sergeych.lyng.obj.ObjExternCallable
import net.sergeych.lyng.obj.ObjInt
import net.sergeych.lyng.obj.ObjInstant
import net.sergeych.lyng.obj.ObjMap
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.obj.requiredArg
import net.sergeych.lyng.requireScope
import kotlinx.datetime.TimeZone
import java.nio.file.Files
import kotlin.io.path.deleteIfExists
import kotlin.time.Instant
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertTrue
class LyngSqliteModuleTest {
@Test
fun testTypedOpenSqliteExecutesQueriesAndGeneratedKeys() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val db = sqliteModule.callFn("openSqlite", ObjString(":memory:"))
val insertedId = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("create table person(id integer primary key autoincrement, name text not null)"))
val result = tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into person(name) values(?)"),
ObjString("John Doe")
)
val generatedKeys = result.invokeInstanceMethod(requireScope(), "getGeneratedKeys")
val rows = generatedKeys.invokeInstanceMethod(requireScope(), "toList")
rows.getAt(requireScope(), ObjInt.Zero).getAt(requireScope(), ObjInt.Zero)
}
) as ObjInt
assertEquals(1L, insertedId.value)
}
@Test
fun testGenericOpenDatabaseUsesRegisteredSqliteProvider() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val dbModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db")
val db = dbModule.callFn("openDatabase", ObjString("sqlite::memory:"), emptyMapObj())
val count = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("create table items(id integer primary key autoincrement, name text not null)"))
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("insert into items(name) values(?)"), ObjString("alpha"))
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("insert into items(name) values(?)"), ObjString("beta"))
val resultSet = tx.invokeInstanceMethod(requireScope(), "select", ObjString("select count(*) as count from items"))
val rows = resultSet.invokeInstanceMethod(requireScope(), "toList")
rows.getAt(requireScope(), ObjInt.Zero).getAt(requireScope(), ObjString("count"))
}
) as ObjInt
assertEquals(2L, count.value)
}
@Test
fun testNestedTransactionRollbackUsesSavepoint() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val db = sqliteModule.callFn("openSqlite", ObjString(":memory:"))
val count = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("create table items(id integer primary key autoincrement, name text not null)"))
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("insert into items(name) values(?)"), ObjString("outer"))
try {
tx.invokeInstanceMethod(
requireScope(),
"transaction",
ObjExternCallable.fromBridge {
val inner = requiredArg<Obj>(0)
inner.invokeInstanceMethod(requireScope(), "execute", ObjString("insert into items(name) values(?)"), ObjString("inner"))
throw IllegalStateException("rollback nested")
}
)
} catch (_: IllegalStateException) {
}
val resultSet = tx.invokeInstanceMethod(requireScope(), "select", ObjString("select count(*) as count from items"))
val rows = resultSet.invokeInstanceMethod(requireScope(), "toList")
rows.getAt(requireScope(), ObjInt.Zero).getAt(requireScope(), ObjString("count"))
}
) as ObjInt
assertEquals(1L, count.value)
}
@Test
fun testResultSetFailsAfterTransactionEnds() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val db = sqliteModule.callFn("openSqlite", ObjString(":memory:"))
var leakedResultSet: Obj = ObjNull
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("create table items(id integer primary key autoincrement, name text not null)"))
leakedResultSet = tx.invokeInstanceMethod(requireScope(), "select", ObjString("select 42 as answer"))
ObjNull
}
)
val error = assertFailsWith<ExecutionError> {
leakedResultSet.invokeInstanceMethod(scope, "size")
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
assertTrue(error.errorMessage.contains("transaction is active"), error.errorMessage)
}
@Test
fun testInvalidSqliteUrlFailsWithIllegalArgument() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val dbModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db")
val error = assertFailsWith<ExecutionError> {
dbModule.callFn("openDatabase", ObjString("sqlite://bad"), emptyMapObj())
}
assertEquals("IllegalArgumentException", error.errorObject.objClass.className)
}
@Test
fun testConstraintViolationIsMappedToSqlConstraintException() = runTest {
val scope = Script.newScope()
val db = openMemoryDb(scope)
val error = assertFailsWith<ExecutionError> {
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("create table person(id integer primary key autoincrement, email text unique not null)")
)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into person(email) values(?)"),
ObjString("a@example.com")
)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into person(email) values(?)"),
ObjString("a@example.com")
)
}
)
}
assertEquals("SqlConstraintException", error.errorObject.objClass.className)
}
@Test
fun testAmbiguousColumnNameAccessFailsWithSqlUsageException() = runTest {
val scope = Script.newScope()
val db = openMemoryDb(scope)
val error = assertFailsWith<ExecutionError> {
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
val resultSet = tx.invokeInstanceMethod(
requireScope(),
"select",
ObjString("select 1 as value, 2 as value")
)
val row = rowsOf(requireScope(), resultSet)[0]
row.getAt(requireScope(), ObjString("value"))
}
)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
assertTrue(error.errorMessage.contains("Ambiguous SQL result column"), error.errorMessage)
}
@Test
fun testExecuteRejectsReturningButSelectSupportsIt() = runTest {
val scope = Script.newScope()
withTempDb(scope) { db ->
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("create table item(id integer primary key autoincrement, name text not null)")
)
}
)
val error = assertFailsWith<ExecutionError> {
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into item(name) values(?) returning id"),
ObjString("bad")
)
}
)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
val insertedId = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
val resultSet = tx.invokeInstanceMethod(
requireScope(),
"select",
ObjString("insert into item(name) values(?) returning id"),
ObjString("good")
)
val row = rowsOf(requireScope(), resultSet)[0]
row.getAt(requireScope(), ObjString("id"))
}
) as ObjInt
assertEquals(1L, insertedId.value)
}
}
@Test
fun testColumnMetadataAndTypedValueConversion() = runTest {
val scope = Script.newScope()
val db = openMemoryDb(scope)
val summary = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString(
"create table events(" +
"amount NUMERIC not null, " +
"happened TIMESTAMPTZ not null, " +
"scheduled TIMESTAMP not null, " +
"note TEXT not null, " +
"payload BLOB not null)"
)
)
val decimal = decimalOf(requireScope(), "12.50")
val happened = ObjInstant(Instant.parse("2024-05-06T07:08:09Z"))
val scheduled = ObjDateTime(Instant.parse("2024-05-06T10:11:12Z"), TimeZone.UTC)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into events(amount, happened, scheduled, note, payload) values(?, ?, ?, ?, ?)"),
decimal,
happened,
scheduled,
ObjString("hello"),
ObjBuffer(byteArrayOf(1, 2, 3).toUByteArray())
)
val resultSet = tx.invokeInstanceMethod(
requireScope(),
"select",
ObjString("select amount, happened, scheduled, note, payload from events")
)
val columns = field(requireScope(), resultSet, "columns")
val firstColumn = columns.getAt(requireScope(), ObjInt.Zero)
val row = rowsOf(requireScope(), resultSet)[0]
ObjString(
listOf(
stringValue(requireScope(), field(requireScope(), firstColumn, "name")),
enumName(requireScope(), field(requireScope(), firstColumn, "sqlType")),
stringValue(requireScope(), field(requireScope(), firstColumn, "nativeType")),
row.getAt(requireScope(), ObjString("amount")).objClass.className,
row.getAt(requireScope(), ObjString("happened")).objClass.className,
row.getAt(requireScope(), ObjString("scheduled")).objClass.className,
stringValue(requireScope(), row.getAt(requireScope(), ObjString("note"))),
row.getAt(requireScope(), ObjString("payload")).objClass.className,
).joinToString("|")
)
}
) as ObjString
assertEquals(
"amount|Decimal|NUMERIC|Decimal|Instant|DateTime|hello|Buffer",
summary.value
)
}
@Test
fun testReadOnlyOpenPreventsWrites() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val tempFile = Files.createTempFile("lyng-sqlite-", ".db")
try {
val writableDb = sqliteModule.callFn("openSqlite", ObjString(tempFile.toString()))
writableDb.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("create table item(id integer primary key autoincrement, name text not null)")
)
}
)
val readOnlyDb = sqliteModule.callFn(
"openSqlite",
ObjString(tempFile.toString()),
net.sergeych.lyng.obj.ObjTrue,
net.sergeych.lyng.obj.ObjFalse
)
val error = assertFailsWith<ExecutionError> {
readOnlyDb.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into item(name) values(?)"),
ObjString("blocked")
)
}
)
}
assertEquals("SqlExecutionException", error.errorObject.objClass.className)
} finally {
tempFile.deleteIfExists()
}
}
private suspend fun ModuleScope.callFn(name: String, vararg args: Obj): Obj {
val callee = get(name)?.value ?: error("Missing $name in module")
return callee.invoke(this, ObjNull, *args)
}
private suspend fun openMemoryDb(scope: Scope): Obj {
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
return sqliteModule.callFn("openSqlite", ObjString(":memory:"))
}
private suspend fun withTempDb(scope: Scope, block: suspend (Obj) -> Unit) {
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val tempFile = Files.createTempFile("lyng-sqlite-", ".db")
try {
val db = sqliteModule.callFn("openSqlite", ObjString(tempFile.toString()))
block(db)
} finally {
tempFile.deleteIfExists()
}
}
private suspend fun field(scope: Scope, obj: Obj, name: String): Obj =
obj.readField(scope, name).value
private suspend fun rowsOf(scope: Scope, resultSet: Obj): List<Obj> {
val rows = resultSet.invokeInstanceMethod(scope, "toList")
val size = (field(scope, rows, "size") as ObjInt).value.toInt()
return (0 until size).map { index -> rows.getAt(scope, ObjInt.of(index.toLong())) }
}
private suspend fun stringValue(scope: Scope, obj: Obj): String =
(obj as? ObjString ?: obj.toString(scope)) .value
private suspend fun enumName(scope: Scope, obj: Obj): String =
stringValue(scope, field(scope, obj, "name"))
private suspend fun decimalOf(scope: Scope, value: String): Obj {
val decimalModule = scope.currentImportProvider.createModuleScope(scope.pos, "lyng.decimal")
val decimalClass = decimalModule.requireClass("Decimal")
return decimalClass.invokeInstanceMethod(scope, "fromString", ObjString(value))
}
private fun emptyMapObj(): Obj = ObjMap()
}

353
lyngio/src/linuxTest/kotlin/net/sergeych/lyng/io/db/sqlite/LyngSqliteModuleNativeTest.kt Normal file
View File

@ -0,0 +1,353 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db.sqlite
import kotlinx.coroutines.test.runTest
import kotlinx.datetime.TimeZone
import net.sergeych.lyng.ExecutionError
import net.sergeych.lyng.ModuleScope
import net.sergeych.lyng.Pos
import net.sergeych.lyng.Scope
import net.sergeych.lyng.Script
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjBuffer
import net.sergeych.lyng.obj.ObjDateTime
import net.sergeych.lyng.obj.ObjExternCallable
import net.sergeych.lyng.obj.ObjInt
import net.sergeych.lyng.obj.ObjInstant
import net.sergeych.lyng.obj.ObjMap
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.obj.requiredArg
import net.sergeych.lyng.requireScope
import okio.FileSystem
import okio.Path
import okio.Path.Companion.toPath
import kotlin.random.Random
import kotlin.time.Instant
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertTrue
class LyngSqliteModuleNativeTest {
@Test
fun testTypedOpenSqliteExecutesQueriesAndGeneratedKeys() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
val db = sqliteModule.callFn("openSqlite", ObjString(":memory:"))
val insertedId = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("create table person(id integer primary key autoincrement, name text not null)"))
val result = tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into person(name) values(?)"),
ObjString("John Doe")
)
val generatedKeys = result.invokeInstanceMethod(requireScope(), "getGeneratedKeys")
val rows = generatedKeys.invokeInstanceMethod(requireScope(), "toList")
rows.getAt(requireScope(), ObjInt.Zero).getAt(requireScope(), ObjInt.Zero)
}
) as ObjInt
assertEquals(1L, insertedId.value)
}
@Test
fun testNestedTransactionRollbackUsesSavepoint() = runTest {
val scope = Script.newScope()
val db = openMemoryDb(scope)
val count = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("create table items(id integer primary key autoincrement, name text not null)"))
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("insert into items(name) values(?)"), ObjString("outer"))
try {
tx.invokeInstanceMethod(
requireScope(),
"transaction",
ObjExternCallable.fromBridge {
val inner = requiredArg<Obj>(0)
inner.invokeInstanceMethod(requireScope(), "execute", ObjString("insert into items(name) values(?)"), ObjString("inner"))
throw IllegalStateException("rollback nested")
}
)
} catch (_: IllegalStateException) {
}
val resultSet = tx.invokeInstanceMethod(requireScope(), "select", ObjString("select count(*) as count from items"))
val rows = resultSet.invokeInstanceMethod(requireScope(), "toList")
rows.getAt(requireScope(), ObjInt.Zero).getAt(requireScope(), ObjString("count"))
}
) as ObjInt
assertEquals(1L, count.value)
}
@Test
fun testResultSetFailsAfterTransactionEnds() = runTest {
val scope = Script.newScope()
val db = openMemoryDb(scope)
var leakedResultSet: Obj = ObjNull
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(requireScope(), "execute", ObjString("create table items(id integer primary key autoincrement, name text not null)"))
leakedResultSet = tx.invokeInstanceMethod(requireScope(), "select", ObjString("select 42 as answer"))
ObjNull
}
)
val error = assertFailsWith<ExecutionError> {
leakedResultSet.invokeInstanceMethod(scope, "size")
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
assertTrue(error.errorMessage.contains("transaction is active"), error.errorMessage)
}
@Test
fun testExecuteRejectsReturningButSelectSupportsIt() = runTest {
val scope = Script.newScope()
withTempDb(scope) { db ->
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("create table item(id integer primary key autoincrement, name text not null)")
)
}
)
val error = assertFailsWith<ExecutionError> {
db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into item(name) values(?) returning id"),
ObjString("bad")
)
}
)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
val insertedId = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
val resultSet = tx.invokeInstanceMethod(
requireScope(),
"select",
ObjString("insert into item(name) values(?) returning id"),
ObjString("good")
)
val row = rowsOf(requireScope(), resultSet)[0]
row.getAt(requireScope(), ObjString("id"))
}
) as ObjInt
assertEquals(1L, insertedId.value)
}
}
@Test
fun testColumnMetadataAndTypedValueConversion() = runTest {
val scope = Script.newScope()
val db = openMemoryDb(scope)
val summary = db.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString(
"create table events(" +
"amount NUMERIC not null, " +
"happened TIMESTAMPTZ not null, " +
"scheduled TIMESTAMP not null, " +
"note TEXT not null, " +
"payload BLOB not null)"
)
)
val decimal = decimalOf(requireScope(), "12.50")
val happened = ObjInstant(Instant.parse("2024-05-06T07:08:09Z"))
val scheduled = ObjDateTime(Instant.parse("2024-05-06T10:11:12Z"), TimeZone.UTC)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into events(amount, happened, scheduled, note, payload) values(?, ?, ?, ?, ?)"),
decimal,
happened,
scheduled,
ObjString("hello"),
ObjBuffer(byteArrayOf(1, 2, 3).toUByteArray())
)
val resultSet = tx.invokeInstanceMethod(
requireScope(),
"select",
ObjString("select amount, happened, scheduled, note, payload from events")
)
val columns = field(requireScope(), resultSet, "columns")
val firstColumn = columns.getAt(requireScope(), ObjInt.Zero)
val row = rowsOf(requireScope(), resultSet)[0]
ObjString(
listOf(
stringValue(requireScope(), field(requireScope(), firstColumn, "name")),
enumName(requireScope(), field(requireScope(), firstColumn, "sqlType")),
stringValue(requireScope(), field(requireScope(), firstColumn, "nativeType")),
row.getAt(requireScope(), ObjString("amount")).objClass.className,
row.getAt(requireScope(), ObjString("happened")).objClass.className,
row.getAt(requireScope(), ObjString("scheduled")).objClass.className,
stringValue(requireScope(), row.getAt(requireScope(), ObjString("note"))),
row.getAt(requireScope(), ObjString("payload")).objClass.className,
).joinToString("|")
)
}
) as ObjString
assertEquals(
"amount|Decimal|NUMERIC|Decimal|Instant|DateTime|hello|Buffer",
summary.value
)
}
@Test
fun testReadOnlyOpenPreventsWrites() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
withTempPath { tempPath ->
val writableDb = sqliteModule.callFn("openSqlite", ObjString(tempPath.toString()))
writableDb.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("create table item(id integer primary key autoincrement, name text not null)")
)
}
)
val readOnlyDb = sqliteModule.callFn(
"openSqlite",
ObjString(tempPath.toString()),
net.sergeych.lyng.obj.ObjTrue,
net.sergeych.lyng.obj.ObjFalse
)
val error = assertFailsWith<ExecutionError> {
readOnlyDb.invokeInstanceMethod(
scope,
"transaction",
ObjExternCallable.fromBridge {
val tx = requiredArg<Obj>(0)
tx.invokeInstanceMethod(
requireScope(),
"execute",
ObjString("insert into item(name) values(?)"),
ObjString("blocked")
)
}
)
}
assertEquals("SqlExecutionException", error.errorObject.objClass.className)
}
}
private suspend fun ModuleScope.callFn(name: String, vararg args: Obj): Obj {
val callee = get(name)?.value ?: error("Missing $name in module")
return callee.invoke(this, ObjNull, *args)
}
private suspend fun openMemoryDb(scope: Scope): Obj {
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
return sqliteModule.callFn("openSqlite", ObjString(":memory:"))
}
private suspend fun withTempDb(scope: Scope, block: suspend (Obj) -> Unit) {
createSqliteModule(scope.importManager)
val sqliteModule = scope.importManager.createModuleScope(Pos.builtIn, "lyng.io.db.sqlite")
withTempPath { tempPath ->
val db = sqliteModule.callFn("openSqlite", ObjString(tempPath.toString()))
block(db)
}
}
private suspend fun withTempPath(block: suspend (Path) -> Unit) {
val path = "/tmp/lyng-sqlite-${Random.nextInt(Int.MAX_VALUE)}.db".toPath()
try {
block(path)
} finally {
FileSystem.SYSTEM.delete(path, mustExist = false)
}
}
private suspend fun field(scope: Scope, obj: Obj, name: String): Obj =
obj.readField(scope, name).value
private suspend fun rowsOf(scope: Scope, resultSet: Obj): List<Obj> {
val rows = resultSet.invokeInstanceMethod(scope, "toList")
val size = (field(scope, rows, "size") as ObjInt).value.toInt()
return (0 until size).map { index -> rows.getAt(scope, ObjInt.of(index.toLong())) }
}
private suspend fun stringValue(scope: Scope, obj: Obj): String =
(obj as? ObjString ?: obj.toString(scope)).value
private suspend fun enumName(scope: Scope, obj: Obj): String =
stringValue(scope, field(scope, obj, "name"))
private suspend fun decimalOf(scope: Scope, value: String): Obj {
val decimalModule = scope.currentImportProvider.createModuleScope(scope.pos, "lyng.decimal")
val decimalClass = decimalModule.requireClass("Decimal")
return decimalClass.invokeInstanceMethod(scope, "fromString", ObjString(value))
}
private fun emptyMapObj(): Obj = ObjMap()
}

2
lyngio/src/nativeInterop/cinterop/sqlite/sqlite3.def Normal file
View File

@ -0,0 +1,2 @@
headers = sqlite3_lyng.h
package = net.sergeych.lyng.io.db.sqlite.cinterop

102
lyngio/src/nativeInterop/cinterop/sqlite/sqlite3_lyng.h Normal file
View File

@ -0,0 +1,102 @@
#ifndef LYNG_SQLITE3_LYNG_H
#define LYNG_SQLITE3_LYNG_H
#ifdef __cplusplus
extern "C" {
#endif
typedef struct sqlite3 sqlite3;
typedef struct sqlite3_stmt sqlite3_stmt;
typedef long long sqlite3_int64;
typedef void (*sqlite3_destructor_type)(void*);
#define SQLITE_OK 0
#define SQLITE_ERROR 1
#define SQLITE_INTERNAL 2
#define SQLITE_PERM 3
#define SQLITE_ABORT 4
#define SQLITE_BUSY 5
#define SQLITE_LOCKED 6
#define SQLITE_NOMEM 7
#define SQLITE_READONLY 8
#define SQLITE_INTERRUPT 9
#define SQLITE_IOERR 10
#define SQLITE_CORRUPT 11
#define SQLITE_NOTFOUND 12
#define SQLITE_FULL 13
#define SQLITE_CANTOPEN 14
#define SQLITE_PROTOCOL 15
#define SQLITE_EMPTY 16
#define SQLITE_SCHEMA 17
#define SQLITE_TOOBIG 18
#define SQLITE_CONSTRAINT 19
#define SQLITE_MISMATCH 20
#define SQLITE_MISUSE 21
#define SQLITE_NOLFS 22
#define SQLITE_AUTH 23
#define SQLITE_FORMAT 24
#define SQLITE_RANGE 25
#define SQLITE_NOTADB 26
#define SQLITE_NOTICE 27
#define SQLITE_WARNING 28
#define SQLITE_ROW 100
#define SQLITE_DONE 101
#define SQLITE_INTEGER 1
#define SQLITE_FLOAT 2
#define SQLITE_TEXT 3
#define SQLITE_BLOB 4
#define SQLITE_NULL 5
#define SQLITE_OPEN_READONLY 0x00000001
#define SQLITE_OPEN_READWRITE 0x00000002
#define SQLITE_OPEN_CREATE 0x00000004
#define SQLITE_OPEN_URI 0x00000040
int sqlite3_open_v2(const char* filename, sqlite3** ppDb, int flags, const char* zVfs);
int sqlite3_close_v2(sqlite3*);
int sqlite3_extended_result_codes(sqlite3*, int onoff);
int sqlite3_busy_timeout(sqlite3*, int ms);
int sqlite3_prepare_v2(sqlite3* db, const char* zSql, int nByte, sqlite3_stmt** ppStmt, const char** pzTail);
int sqlite3_finalize(sqlite3_stmt* pStmt);
int sqlite3_step(sqlite3_stmt*);
int sqlite3_reset(sqlite3_stmt* pStmt);
int sqlite3_clear_bindings(sqlite3_stmt*);
int sqlite3_bind_parameter_count(sqlite3_stmt*);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
int sqlite3_bind_double(sqlite3_stmt*, int, double);
int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, sqlite3_destructor_type);
int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, sqlite3_destructor_type);
int sqlite3_column_count(sqlite3_stmt* pStmt);
const char* sqlite3_column_name(sqlite3_stmt*, int N);
const char* sqlite3_column_decltype(sqlite3_stmt*, int);
int sqlite3_column_type(sqlite3_stmt*, int iCol);
sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
const unsigned char* sqlite3_column_text(sqlite3_stmt*, int iCol);
const void* sqlite3_column_blob(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
const char* sqlite3_errmsg(sqlite3*);
int sqlite3_extended_errcode(sqlite3*);
int sqlite3_changes(sqlite3*);
sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
int sqlite3_db_readonly(sqlite3*, const char* zDbName);
static inline sqlite3* lyng_sqlite3_open(const char* filename, int flags) {
sqlite3* db = 0;
sqlite3_open_v2(filename, &db, flags, 0);
return db;
}
static inline sqlite3_stmt* lyng_sqlite3_prepare(sqlite3* db, const char* sql) {
sqlite3_stmt* stmt = 0;
sqlite3_prepare_v2(db, sql, -1, &stmt, 0);
return stmt;
}
#ifdef __cplusplus
}
#endif
#endif

573
lyngio/src/nativeMain/kotlin/net/sergeych/lyng/io/db/sqlite/PlatformNative.kt Normal file
View File

@ -0,0 +1,573 @@
@file:OptIn(ExperimentalForeignApi::class)
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.io.db.sqlite
import cnames.structs.sqlite3
import cnames.structs.sqlite3_stmt
import kotlinx.cinterop.ByteVar
import kotlinx.cinterop.CFunction
import kotlinx.cinterop.CPointer
import kotlinx.cinterop.COpaquePointer
import kotlinx.cinterop.ExperimentalForeignApi
import kotlinx.cinterop.MemScope
import kotlinx.cinterop.allocArray
import kotlinx.cinterop.addressOf
import kotlinx.cinterop.memScoped
import kotlinx.cinterop.readBytes
import kotlinx.cinterop.reinterpret
import kotlinx.cinterop.toCPointer
import kotlinx.cinterop.toKString
import kotlinx.cinterop.usePinned
import kotlinx.datetime.LocalDateTime
import kotlinx.datetime.TimeZone
import kotlinx.datetime.toInstant
import net.sergeych.lyng.ExecutionError
import net.sergeych.lyng.ScopeFacade
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_BLOB
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_CONSTRAINT
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_DONE
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_FLOAT
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_INTEGER
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_NULL
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_OK
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_OPEN_CREATE
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_OPEN_READONLY
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_OPEN_READWRITE
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_OPEN_URI
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_ROW
import net.sergeych.lyng.io.db.sqlite.cinterop.SQLITE_TEXT
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_bind_blob
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_bind_double
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_bind_int64
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_bind_null
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_bind_parameter_count
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_bind_text
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_busy_timeout
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_changes
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_close_v2
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_blob
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_bytes
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_count
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_decltype
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_double
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_int64
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_name
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_text
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_column_type
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_errmsg
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_extended_errcode
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_extended_result_codes
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_finalize
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_last_insert_rowid
import net.sergeych.lyng.io.db.sqlite.cinterop.lyng_sqlite3_open
import net.sergeych.lyng.io.db.sqlite.cinterop.lyng_sqlite3_prepare
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_open_v2
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_reset
import net.sergeych.lyng.io.db.sqlite.cinterop.sqlite3_step
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjBool
import net.sergeych.lyng.obj.ObjBuffer
import net.sergeych.lyng.obj.ObjDateTime
import net.sergeych.lyng.obj.ObjEnumEntry
import net.sergeych.lyng.obj.ObjException
import net.sergeych.lyng.obj.ObjInt
import net.sergeych.lyng.obj.ObjInstant
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjReal
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.requireScope
import platform.posix.memcpy
import kotlin.time.Instant
internal actual suspend fun openSqliteBackend(
scope: ScopeFacade,
core: SqliteCoreModule,
options: SqliteOpenOptions,
): SqliteDatabaseBackend {
if (options.busyTimeoutMillis < 0) {
scope.raiseIllegalArgument("busyTimeoutMillis must be >= 0")
}
return NativeSqliteDatabaseBackend(core, options)
}
private class NativeSqliteDatabaseBackend(
private val core: SqliteCoreModule,
private val options: SqliteOpenOptions,
) : SqliteDatabaseBackend {
override suspend fun <T> transaction(scope: ScopeFacade, block: suspend (SqliteTransactionBackend) -> T): T {
val handle = openHandle(scope, core, options)
val savepoints = SavepointCounter()
try {
handle.execUnit(scope, core, "begin")
val tx = NativeSqliteTransactionBackend(core, handle, savepoints)
return try {
val result = block(tx)
handle.execUnit(scope, core, "commit")
result
} catch (e: Throwable) {
handle.execUnitQuietly("rollback")
throw e
}
} finally {
handle.close()
}
}
}
private class NativeSqliteTransactionBackend(
private val core: SqliteCoreModule,
private val handle: NativeSqliteHandle,
private val savepoints: SavepointCounter,
) : SqliteTransactionBackend {
override suspend fun select(scope: ScopeFacade, clause: String, params: List<Obj>): SqliteResultSetData {
return handle.select(scope, core, clause, params)
}
override suspend fun execute(scope: ScopeFacade, clause: String, params: List<Obj>): SqliteExecutionResultData {
return handle.execute(scope, core, clause, params)
}
override suspend fun <T> transaction(scope: ScopeFacade, block: suspend (SqliteTransactionBackend) -> T): T {
val savepoint = "lyng_sp_${savepoints.next()}"
handle.execUnit(scope, core, "savepoint $savepoint")
return try {
val result = block(NativeSqliteTransactionBackend(core, handle, savepoints))
handle.execUnit(scope, core, "release savepoint $savepoint")
result
} catch (e: Throwable) {
handle.execUnitQuietly("rollback to savepoint $savepoint")
handle.execUnitQuietly("release savepoint $savepoint")
throw e
}
}
}
private class SavepointCounter {
private var nextValue = 0
fun next(): Int {
nextValue += 1
return nextValue
}
}
private class NativeSqliteHandle(
private val db: CPointer<sqlite3>,
) {
suspend fun select(
scope: ScopeFacade,
core: SqliteCoreModule,
clause: String,
params: List<Obj>,
): SqliteResultSetData = memScoped {
val stmt = prepare(scope, core, clause)
try {
bindParams(scope, core, stmt, params, this)
readResultSet(scope, core, stmt)
} finally {
sqlite3_finalize(stmt)
}
}
suspend fun execute(
scope: ScopeFacade,
core: SqliteCoreModule,
clause: String,
params: List<Obj>,
): SqliteExecutionResultData = memScoped {
if (containsRowReturningClause(clause)) {
raiseExecuteReturningUsage(scope, core)
}
val stmt = prepare(scope, core, clause)
try {
bindParams(scope, core, stmt, params, this)
when (val rc = sqlite3_step(stmt)) {
SQLITE_DONE -> {
val affectedRows = sqlite3_changes(db)
val generatedKeys = readGeneratedKeys(core, clause, affectedRows)
SqliteExecutionResultData(affectedRows, generatedKeys)
}
SQLITE_ROW -> raiseExecuteReturningUsage(scope, core)
else -> throw sqlError(scope, core, rc)
}
} finally {
sqlite3_reset(stmt)
sqlite3_finalize(stmt)
}
}
fun execUnit(scope: ScopeFacade, core: SqliteCoreModule, sql: String) {
memScoped {
val stmt = prepare(scope, core, sql)
try {
when (val rc = sqlite3_step(stmt)) {
SQLITE_DONE, SQLITE_ROW -> Unit
else -> throw sqlError(scope, core, rc)
}
} finally {
sqlite3_finalize(stmt)
}
}
}
fun execUnitQuietly(sql: String) {
memScoped {
val stmt = lyng_sqlite3_prepare(db, sql) ?: return@memScoped
try {
sqlite3_step(stmt)
} finally {
sqlite3_finalize(stmt)
}
}
}
fun close() {
sqlite3_close_v2(db)
}
private fun MemScope.prepare(scope: ScopeFacade, core: SqliteCoreModule, sql: String): CPointer<sqlite3_stmt> {
return lyng_sqlite3_prepare(db, sql) ?: throw sqlError(scope, core, sqlite3_extended_errcode(db))
}
private suspend fun bindParams(
scope: ScopeFacade,
core: SqliteCoreModule,
stmt: CPointer<sqlite3_stmt>,
params: List<Obj>,
memScope: MemScope,
) {
val expectedCount = sqlite3_bind_parameter_count(stmt)
if (expectedCount != params.size) {
throw usageError(
scope,
core,
"SQL parameter count mismatch: statement expects $expectedCount value(s), got ${params.size}"
)
}
params.forEachIndexed { index, value ->
val parameterIndex = index + 1
val rc = when (value) {
ObjNull -> sqlite3_bind_null(stmt, parameterIndex)
is ObjBool -> sqlite3_bind_int64(stmt, parameterIndex, if (value.value) 1L else 0L)
is ObjInt -> sqlite3_bind_int64(stmt, parameterIndex, value.value)
is ObjReal -> sqlite3_bind_double(stmt, parameterIndex, value.value)
is ObjString -> bindText(stmt, parameterIndex, value.value, memScope)
is ObjBuffer -> bindBlob(stmt, parameterIndex, value.byteArray.toByteArray(), memScope)
is ObjInstant -> bindText(stmt, parameterIndex, value.instant.toString(), memScope)
is ObjDateTime -> bindText(stmt, parameterIndex, value.localDateTime.toString(), memScope)
else -> when (value.objClass.className) {
"Date", "Decimal" -> bindText(stmt, parameterIndex, scope.toStringOf(value).value, memScope)
else -> scope.raiseClassCastError("Unsupported SQLite parameter type: ${value.objClass.className}")
}
}
if (rc != SQLITE_OK) {
throw sqlError(scope, core, rc)
}
}
}
private fun bindText(
stmt: CPointer<sqlite3_stmt>,
parameterIndex: Int,
value: String,
memScope: MemScope,
): Int {
return sqlite3_bind_text(stmt, parameterIndex, value, -1, SQLITE_TRANSIENT)
}
private fun bindBlob(
stmt: CPointer<sqlite3_stmt>,
parameterIndex: Int,
value: ByteArray,
memScope: MemScope,
): Int {
if (value.isEmpty()) {
return sqlite3_bind_blob(stmt, parameterIndex, null, 0, null)
}
val target = memScope.allocArray<ByteVar>(value.size)
value.usePinned { pinned ->
memcpy(target, pinned.addressOf(0), value.size.toULong())
}
return sqlite3_bind_blob(stmt, parameterIndex, target, value.size, SQLITE_TRANSIENT)
}
private suspend fun readResultSet(
scope: ScopeFacade,
core: SqliteCoreModule,
stmt: CPointer<sqlite3_stmt>,
): SqliteResultSetData {
val columnCount = sqlite3_column_count(stmt)
val columns = (0 until columnCount).map { index ->
val nativeType = sqlite3_column_decltype(stmt, index)?.toKString().orEmpty()
SqliteColumnMeta(
name = sqlite3_column_name(stmt, index)?.toKString().orEmpty(),
sqlType = mapSqlType(core, nativeType, SQLITE_NULL),
nullable = true,
nativeType = nativeType,
)
}.toMutableList()
if (columnCount == 0) {
return emptyResultSet()
}
val rows = mutableListOf<List<Obj>>()
while (true) {
when (val rc = sqlite3_step(stmt)) {
SQLITE_ROW -> {
val row = (0 until columnCount).map { index ->
val dynamicType = sqlite3_column_type(stmt, index)
if (columns[index].nativeType.isBlank()) {
columns[index] = columns[index].copy(sqlType = mapSqlType(core, columns[index].nativeType, dynamicType))
}
readColumnValue(scope, core, stmt, index, columns[index].nativeType)
}
rows += row
}
SQLITE_DONE -> return SqliteResultSetData(columns, rows)
else -> throw sqlError(scope, core, rc)
}
}
}
private suspend fun readColumnValue(
scope: ScopeFacade,
core: SqliteCoreModule,
stmt: CPointer<sqlite3_stmt>,
index: Int,
nativeType: String,
): Obj {
val normalizedNativeType = nativeType.trim().uppercase()
return when (val type = sqlite3_column_type(stmt, index)) {
SQLITE_NULL -> ObjNull
SQLITE_INTEGER -> {
val value = sqlite3_column_int64(stmt, index)
when {
normalizedNativeType == "BOOLEAN" -> ObjBool(value != 0L)
isDecimalNativeType(nativeType) -> decimalFromString(scope, value.toString())
else -> ObjInt.of(value)
}
}
SQLITE_FLOAT -> {
val value = sqlite3_column_double(stmt, index)
if (isDecimalNativeType(nativeType)) decimalFromString(scope, value.toString()) else ObjReal.of(value)
}
SQLITE_TEXT -> {
val textPtr = sqlite3_column_text(stmt, index)?.reinterpret<ByteVar>()
val value = textPtr?.toKString() ?: ""
convertStringValue(scope, nativeType, value)
}
SQLITE_BLOB -> {
val size = sqlite3_column_bytes(stmt, index)
val blob = sqlite3_column_blob(stmt, index)
val bytes = if (blob == null || size <= 0) byteArrayOf() else blob.reinterpret<ByteVar>().readBytes(size)
ObjBuffer(bytes.toUByteArray())
}
else -> ObjString(columnText(stmt, index))
}
}
private suspend fun convertStringValue(scope: ScopeFacade, nativeType: String, value: String): Obj {
val normalized = nativeType.trim().uppercase()
return when {
normalized == "DECIMAL" || normalized == "NUMERIC" -> decimalFromString(scope, value)
normalized == "DATETIME" || normalized == "TIMESTAMP" -> dateTimeFromString(value)
normalized == "TIMESTAMP WITH TIME ZONE" || normalized == "TIMESTAMPTZ" -> ObjInstant(Instant.parse(value))
else -> ObjString(value)
}
}
private fun readGeneratedKeys(
core: SqliteCoreModule,
clause: String,
affectedRows: Int,
): SqliteResultSetData {
if (affectedRows <= 0 || !looksLikeInsert(clause)) {
return emptyResultSet()
}
return SqliteResultSetData(
columns = listOf(
SqliteColumnMeta(
name = "generated_key",
sqlType = core.sqlTypes.require("Int"),
nullable = false,
nativeType = "INTEGER",
)
),
rows = listOf(listOf(ObjInt.of(sqlite3_last_insert_rowid(db))))
)
}
private fun columnText(stmt: CPointer<sqlite3_stmt>, index: Int): String {
return sqlite3_column_text(stmt, index)?.reinterpret<ByteVar>()?.toKString().orEmpty()
}
private fun sqlError(scope: ScopeFacade, core: SqliteCoreModule, rc: Int): ExecutionError {
val code = sqlite3_extended_errcode(db)
val message = sqlite3_errmsg(db)?.toKString() ?: "SQLite error ($rc)"
val exceptionClass = if ((code and 0xff) == SQLITE_CONSTRAINT) core.sqlConstraintException else core.sqlExecutionException
return ExecutionError(
ObjException(exceptionClass, scope.requireScope(), ObjString(message)),
scope.pos,
message,
)
}
}
private fun openHandle(
scope: ScopeFacade,
core: SqliteCoreModule,
options: SqliteOpenOptions,
): NativeSqliteHandle = memScoped {
val flags = buildOpenFlags(options)
val db = lyng_sqlite3_open(options.path, flags)
val rc = db?.let { sqlite3_extended_errcode(it) } ?: SQLITE_OK
if (db == null || rc != SQLITE_OK) {
val message = db?.let { sqlite3_errmsg(it)?.toKString() } ?: "SQLite open failed"
if (db != null) {
sqlite3_close_v2(db)
}
throw databaseError(scope, core, message)
}
sqlite3_extended_result_codes(db, 1)
if (sqlite3_busy_timeout(db, options.busyTimeoutMillis) != SQLITE_OK) {
val message = sqlite3_errmsg(db)?.toKString() ?: "Failed to configure SQLite busy timeout"
sqlite3_close_v2(db)
throw databaseError(scope, core, message)
}
val handle = NativeSqliteHandle(db)
try {
handle.execUnit(scope, core, if (options.foreignKeys) "pragma foreign_keys = on" else "pragma foreign_keys = off")
} catch (e: Throwable) {
handle.close()
throw e
}
handle
}
private fun buildOpenFlags(options: SqliteOpenOptions): Int {
var flags = SQLITE_OPEN_URI
if (options.readOnly) {
flags = flags or SQLITE_OPEN_READONLY
} else {
flags = flags or SQLITE_OPEN_READWRITE
if (options.createIfMissing) {
flags = flags or SQLITE_OPEN_CREATE
}
}
return flags
}
private fun containsRowReturningClause(clause: String): Boolean =
Regex("""\breturning\b""", RegexOption.IGNORE_CASE).containsMatchIn(clause)
private fun looksLikeInsert(clause: String): Boolean = clause.trimStart().startsWith("insert", ignoreCase = true)
private val SQLITE_TRANSIENT = (-1L).toCPointer<CFunction<(COpaquePointer?) -> Unit>>()
private fun emptyResultSet(): SqliteResultSetData = SqliteResultSetData(emptyList(), emptyList())
private fun mapSqlType(core: SqliteCoreModule, nativeType: String, sqliteType: Int): ObjEnumEntry = when {
nativeType.trim().equals("BOOLEAN", ignoreCase = true) -> core.sqlTypes.require("Bool")
nativeType.trim().equals("DATE", ignoreCase = true) -> core.sqlTypes.require("Date")
nativeType.trim().equals("DATETIME", ignoreCase = true) || nativeType.trim().equals("TIMESTAMP", ignoreCase = true) -> core.sqlTypes.require("DateTime")
nativeType.trim().equals("TIMESTAMP WITH TIME ZONE", ignoreCase = true) || nativeType.trim().equals("TIMESTAMPTZ", ignoreCase = true) -> core.sqlTypes.require("Instant")
nativeType.trim().equals("DECIMAL", ignoreCase = true) || nativeType.trim().equals("NUMERIC", ignoreCase = true) -> core.sqlTypes.require("Decimal")
nativeType.contains("BLOB", ignoreCase = true) -> core.sqlTypes.require("Binary")
nativeType.contains("INT", ignoreCase = true) -> core.sqlTypes.require("Int")
nativeType.contains("CHAR", ignoreCase = true) || nativeType.contains("TEXT", ignoreCase = true) || nativeType.contains("CLOB", ignoreCase = true) -> core.sqlTypes.require("String")
nativeType.contains("REAL", ignoreCase = true) || nativeType.contains("FLOA", ignoreCase = true) || nativeType.contains("DOUB", ignoreCase = true) -> core.sqlTypes.require("Double")
sqliteType == SQLITE_INTEGER -> core.sqlTypes.require("Int")
sqliteType == SQLITE_FLOAT -> core.sqlTypes.require("Double")
sqliteType == SQLITE_BLOB -> core.sqlTypes.require("Binary")
else -> core.sqlTypes.require("String")
}
private fun isDecimalNativeType(nativeType: String): Boolean {
val normalized = nativeType.trim().uppercase()
return normalized == "DECIMAL" || normalized == "NUMERIC"
}
private suspend fun decimalFromString(scope: ScopeFacade, value: String): Obj {
val decimalModule = scope.requireScope().currentImportProvider.createModuleScope(scope.pos, "lyng.decimal")
val decimalClass = decimalModule.requireClass("Decimal")
return decimalClass.invokeInstanceMethod(scope.requireScope(), "fromString", ObjString(value))
}
private fun dateTimeFromString(value: String): ObjDateTime {
val trimmed = value.trim()
return if (hasExplicitTimeZone(trimmed)) {
val instant = Instant.parse(trimmed)
ObjDateTime(instant, parseTimeZoneOrUtc(trimmed))
} else {
val local = LocalDateTime.parse(trimmed)
ObjDateTime(local.toInstant(TimeZone.UTC), TimeZone.UTC)
}
}
private fun hasExplicitTimeZone(value: String): Boolean {
if (value.endsWith("Z", ignoreCase = true)) return true
val tIndex = value.indexOf('T')
if (tIndex < 0) return false
val plus = value.lastIndexOf('+')
val minus = value.lastIndexOf('-')
val offsetStart = maxOf(plus, minus)
return offsetStart > tIndex
}
private fun parseTimeZoneOrUtc(value: String): TimeZone {
if (value.endsWith("Z", ignoreCase = true)) return TimeZone.UTC
val tIndex = value.indexOf('T')
if (tIndex < 0) return TimeZone.UTC
val plus = value.lastIndexOf('+')
val minus = value.lastIndexOf('-')
val offsetStart = maxOf(plus, minus)
if (offsetStart <= tIndex) return TimeZone.UTC
return try {
TimeZone.of(value.substring(offsetStart))
} catch (_: IllegalArgumentException) {
TimeZone.UTC
}
}
private fun raiseExecuteReturningUsage(scope: ScopeFacade, core: SqliteCoreModule): Nothing {
scope.raiseError(
ObjException(
core.sqlUsageException,
scope.requireScope(),
ObjString("execute(...) cannot be used with statements that return rows; use select(...)")
)
)
}
private fun usageError(scope: ScopeFacade, core: SqliteCoreModule, message: String): ExecutionError {
return ExecutionError(
ObjException(core.sqlUsageException, scope.requireScope(), ObjString(message)),
scope.pos,
message,
)
}
private fun databaseError(scope: ScopeFacade, core: SqliteCoreModule, message: String): ExecutionError {
return ExecutionError(
ObjException(core.databaseException, scope.requireScope(), ObjString(message)),
scope.pos,
message,
)
}

209
lyngio/stdlib/lyng/io/db.lyng Normal file
View File

@ -0,0 +1,209 @@
package lyng.io.db
/*
Portable value categories exposed by the Lyng SQL layer and used in
`SqlColumn`.
*/
enum SqlType {
Binary, String, Int, Double, Decimal,
Bool, Instant, Date, DateTime
}
extern class SqlColumn {
val name: String
val sqlType: SqlType
val nullable: Bool
/*
Original database type name as reported by the backend, such as
VARCHAR, TEXT, INT8, TIMESTAMPTZ, or BYTEA.
*/
val nativeType: String
}
extern class SqlRow {
/* Number of columns in the row */
val size: Int
val values: List<Object?>
/*
Return the already converted Lyng value for a column addressed by
index or output column label. SQL NULL is returned as null.
Name lookup uses result-column labels. If several columns share the same
label, name-based access is ambiguous and should fail. Missing column
names and invalid indexes should also fail.
*/
override fun getAt(indexOrName: String | Int): Object?
}
/*
A result set is valid only while its owning transaction is active.
Implementations may stream rows or buffer them internally, but:
- rows must be exposed through normal iteration
- iteration to the end or canceled iteration should close the underlying
resources automatically
- using the result set after its transaction ends is invalid
- rows obtained from the result set are also invalid after the owning
transaction ends, even if the implementation had already buffered them
If user code wants row data to survive independently, it should copy the
values it needs into ordinary Lyng objects while the transaction is active.
*/
extern class ResultSet : Iterable<SqlRow> {
/*
Column metadata for the result rows, in positional order.
*/
val columns: List<SqlColumn>
/*
Number of rows if the implementation can determine it. Implementations
may need to consume or buffer the whole result in order to answer, but
this must not change visible later iteration behavior.
*/
fun size(): Int
/*
Fast emptiness check when the implementation can provide it without
consuming the result. Implementations may still peek or buffer
internally, but this must not change visible later iteration behavior.
*/
override fun isEmpty(): Bool
}
extern class ExecutionResult {
val affectedRowsCount: Int
/*
Return implementation-supported auto-generated values produced by
`execute`. This is intentionally stricter than arbitrary SQL result
sets: statements such as INSERT/UPDATE/DELETE ... RETURNING should be
executed with `select`, not exposed here.
The returned result set has the same transaction-scoped lifetime as any
other result set.
If the statement produced no generated values, the returned result set
is empty.
*/
fun getGeneratedKeys(): ResultSet
}
extern class DatabaseException: Exception
extern class SqlExecutionException: DatabaseException
extern class SqlConstraintException: SqlExecutionException
extern class SqlUsageException: DatabaseException
/*
Special exception to be thrown from `SqlTransaction.transaction` when an
intentional rollback is requested without treating it as a backend failure.
It causes rollback and is propagated to the caller, but should not be
treated as a backend/driver failure.
If rollback itself fails, that rollback failure becomes the primary backend
error instead.
*/
extern class RollbackException: Exception
/*
Transaction represents a database transaction.
Important: a transaction has no explicit commit; instead it commits when
leaving the transaction block normally.
If the transaction block throws any exception not caught inside the calling
code, it will be rolled back.
*/
extern class SqlTransaction {
/*
Execute a SQL statement that returns rows. This includes plain SELECT
queries and database-specific DML statements with row-returning clauses
such as RETURNING or OUTPUT.
Portable SQL uses positional `?` placeholders only.
Portable bindable values are:
- null
- Bool
- Int, Double, Decimal
- String
- Buffer
- Date, DateTime, Instant
Unsupported parameter values should fail with `SqlUsageException`.
*/
fun select(clause: String, params...): ResultSet
/*
Execute a SQL statement for side effects. Use `select` for any statement
whose primary result is a row set.
Parameters follow the same binding rules as `select`.
*/
fun execute(clause: String, params...): ExecutionResult
/*
Create a nested transaction with real nested semantics, typically using
database savepoints.
If the backend cannot provide real nested transaction semantics, this
call should fail with `SqlUsageException` rather than flattening into
the outer transaction.
Failure inside the nested transaction rolls back only the nested scope;
the outer transaction remains active unless the exception is allowed to
propagate further.
*/
fun transaction<T>(block: (SqlTransaction) -> T): T
}
extern class Database {
/*
Open a transaction. Any pooling, physical connection lifecycle, and
implementation-specific configuration are owned by the database
implementation and hidden from the user.
The transaction commits when the block finishes normally,
and rolls back if the block exits with an uncaught exception.
Failure precedence is:
- user exception + successful rollback -> original exception escapes
- user exception + rollback failure -> original exception stays primary
- RollbackException + rollback failure -> rollback failure is primary
- commit failure after normal completion -> commit failure is primary
*/
fun transaction<T>(block: (SqlTransaction) -> T): T
}
/*
Register a database provider for a URL scheme.
Provider modules should call this during module initialization when first
imported. Scheme matching is case-insensitive and normalized to lowercase.
Registering the same scheme more than once should fail.
*/
extern fun registerDatabaseProvider(
scheme: String,
opener: (String, Map<String, Object?>) -> Database
)
/*
The mandatory generic entry point for all providers. It opens a database
handle from a provider-specific connection URL plus extra parameters.
Providers may expose additional typed constructors such as `openSqlite(...)`
or `openPostgres(...)`, but `openDatabase(...)` should remain available for
configuration-driven usage.
It should throw IllegalArgumentException for malformed connection URLs or
invalid extra parameter shapes detected before opening the backend.
Runtime opening failures such as authentication, connectivity, or provider
initialization errors should be reported as DatabaseException.
The matching provider must already be registered, normally because its
module was imported and executed. Unknown schemes or missing providers
should fail with DatabaseException.
*/
extern fun openDatabase(connectionUrl: String, extraParams: Map<String, Object?>): Database

24
lyngio/stdlib/lyng/io/db_sqlite.lyng Normal file
View File

@ -0,0 +1,24 @@
package lyng.io.db.sqlite
import lyng.io.db
/*
SQLite provider for `lyng.io.db`.
Importing this module registers the `sqlite:` URL scheme for
`openDatabase(...)`.
SQLite provider defaults:
- `Bool` is written as `0` / `1`
- `Decimal` is written as canonical text
- `Date` is written as `YYYY-MM-DD`
- `DateTime` is written as an ISO local timestamp without timezone
- `Instant` is written as an ISO UTC timestamp with explicit timezone marker
*/
extern fun openSqlite(
path: String,
readOnly: Bool = false,
createIfMissing: Bool = true,
foreignKeys: Bool = true,
busyTimeoutMillis: Int = 5000
): Database

94
notes/db/db_interface.md Normal file
View File

@ -0,0 +1,94 @@
# Lyng.io.db
Core level interface to SQL implementations. Pooling, physical connections, and implementation-specific configuration are hidden behind the opened database handle.
All providers should support the generic `openDatabase(connectionUrl, extraParams)`
entry point for configuration-driven usage. Providers may also expose typed
helpers such as `openSqlite(...)` or `openPostgres(...)`.
Provider modules should register their URL schemes when first imported. The
generic `openDatabase(...)` then dispatches by normalized URL scheme to the
registered provider.
See [db definitions](lyngdb.lyng).
## Platforms support:
| DB | JVM | Native |
|----------|-----|--------|
| Postgres | + | ? |
| H2 | + | + |
| SQLITE | + | + |
Question for the future: what to do on JS platforms? Browsers have their crazy own storages, bit it is not SQL. Probably for this case we need some simpler standard compatible with browsers and with special implementation on JVM.
## Proposed type mapping:
| SQL | Lyng | comments |
|--------------------------------------------|----------|----------|
| SMALLINT | Int | Lyng `Int` is already 64-bit |
| INTEGER / INT | Int | |
| BIGINT | Int | Lyng `Int` is already 64-bit |
| REAL / FLOAT / DOUBLE PRECISION | Double | |
| DECIMAL / NUMERIC | Decimal | exact numeric |
| BOOLEAN / BOOL | Bool | |
| CHAR / VARCHAR / TEXT | String | |
| BINARY / VARBINARY / BLOB / BYTEA | Buffer | |
| DATE | Date | calendar date |
| TIME / TIME WITHOUT TIME ZONE | String | v1: no standalone Lyng `Time` type yet |
| TIMESTAMP / TIMESTAMP WITHOUT TIME ZONE | DateTime | local calendar-dependent timestamp |
| TIME WITH TIME ZONE | String | v1: preserve exact value textually |
| TIMESTAMP WITH TIME ZONE | Instant | absolute point in time |
Notes:
- `TIME` mappings in v1 should stay textual. A SQL time-of-day value has no
date component, so mapping it to `DateTime` would require inventing one, and
mapping it to `Instant` would incorrectly assign absolute-time semantics.
- Because of that, `TIME` and `TIME WITH TIME ZONE` should be exposed as
`String` in portable code. The original backend type is still available
through `SqlColumn.nativeType`.
- Name-based `SqlRow` access uses result-column labels and should fail on
missing or ambiguous names.
- `SqlColumn` should expose both the normalized portable `SqlType` and the
original backend-reported type name.
- For any non-null cell, the converted row value should match the column's
portable `SqlType`. Providers should not advertise `SqlType.Date`,
`SqlType.Decimal`, etc. and then return mismatched raw values for those
columns.
- If a backend-reported value cannot be converted to the advertised Lyng value
type for that column, row production should fail with `SqlExecutionException`
rather than silently degrading to some other visible type.
- `ResultSet` should stay iterable, but also expose `isEmpty()` for cheap
emptiness checks where possible and `size()` as a separate operation.
- `ResultSet` and all `SqlRow` instances obtained from it are valid only while
the owning transaction is active. After transaction end, any further row or
result-set access should fail with `SqlUsageException`, even if the provider
had buffered data internally.
- Portable SQL parameter values should match the row conversion set: `null`,
`Bool`, `Int`, `Double`, `Decimal`, `String`, `Buffer`,
`Date`, `DateTime`, and `Instant`.
- Lyng has a single integer type, `Int`, with 64-bit range. Portable SQL
integer values should therefore normalize to `Int` rather than exposing
separate `Short` / `Int` / `Long` categories.
- Portable SQL placeholder syntax is positional `?` only.
- The core exception model should stay small: `DatabaseException`,
`SqlExecutionException`, `SqlConstraintException`, and `SqlUsageException`,
plus propagated `RollbackException`.
- `openDatabase(...)` should use `IllegalArgumentException` for malformed
arguments detected before opening, and `DatabaseException` for runtime open
failures such as authentication, connectivity, or provider initialization.
- Nested `SqlTransaction.transaction {}` must provide real nested transaction
semantics, usually via savepoints. If the backend cannot support this, it
should throw `SqlUsageException`.
- Transaction failure precedence should be:
- if user code throws and rollback succeeds, rethrow the original exception
- if user code throws and rollback fails, the original exception stays
primary and the rollback failure is secondary/suppressed where possible
- if `RollbackException` was used intentionally and rollback itself fails,
the rollback failure becomes primary
- if commit fails after normal block completion, the commit failure is
primary
- Provider URL schemes should be matched case-insensitively. Duplicate scheme
registration should fail. Unknown schemes or missing providers should fail
with `DatabaseException`.

213
notes/db/lyngdb.lyng Normal file
View File

@ -0,0 +1,213 @@
/*
Portable value categories exposed by the Lyng SQL layer and used in
[SqlColumn].
*/
enum SqlType {
Binary, String, Int, Double, Decimal,
Bool, Instant, Date, DateTime
}
class SqlColumn(
val name: String,
val sqlType: SqlType,
val nullable: Bool,
/*
Original database type name as reported by the backend, such as
VARCHAR, TEXT, INT8, TIMESTAMPTZ, or BYTEA.
*/
val nativeType: String
)
class SqlRow(
/* Number of columns in the row */
val size: Int,
val values: ImmutableList<Object?>
) {
/*
Return the already converted Lyng value for a column addressed by
index or output column label. SQL NULL is returned as null.
Name lookup uses result-column labels. If several columns share the same
label, name-based access is ambiguous and should fail. Missing column
names and invalid indexes should also fail.
*/
abstract override fun getAt(indexOrName: String|Int): Object?
}
/*
A result set is valid only while its owning transaction is active.
Implementations may stream rows or buffer them internally, but:
- rows must be exposed through normal iteration
- iteration to the end or canceled iteration should close the underlying
resources automatically
- using the result set after its transaction ends is invalid
- rows obtained from the result set are also invalid after the owning
transaction ends, even if the implementation had already buffered them
If user code wants row data to survive independently, it should copy the
values it needs into ordinary Lyng objects while the transaction is active.
*/
interface ResultSet : Iterable<SqlRow> {
/*
Column metadata for the result rows, in positional order.
*/
abstract val columns: ImmutableList<SqlColumn>
/*
Number of rows if the implementation can determine it. Implementations
may need to consume or buffer the whole result in order to answer.
*/
abstract override fun size(): Int
/*
Fast emptiness check when the implementation can provide it without
consuming the result.
*/
abstract override fun isEmpty(): Bool
}
abstract class ExecutionResult(
val affectedRowsCount: Int
) {
/*
Return implementation-supported auto-generated values produced by
[execute]. This is intentionally stricter than arbitrary SQL result
sets: statements such as INSERT/UPDATE/DELETE ... RETURNING should be
executed with [select], not exposed here.
If the statement produced no generated values, the returned result set
is empty.
*/
abstract fun getGeneratedKeys(): ResultSet
}
/*
Base exception for the SQL database module.
*/
open class DatabaseException: Exception
/*
The SQL statement could not be executed successfully by the backend.
*/
open class SqlExecutionException: DatabaseException
/*
Execution failed because of a constraint violation, such as UNIQUE,
FOREIGN KEY, CHECK, or NOT NULL.
*/
class SqlConstraintException: SqlExecutionException
/*
The DB API was used incorrectly, such as invalid transaction state,
ambiguous column-name access, or invalid row indexes.
*/
class SqlUsageException: DatabaseException
/*
Transaction represents a database transaction (non-transactional operations
we intentionally do not support).
Important: a transaction has __no commit__; instead it commits when
leaving the transaction block normally.
If the transaction block throws any exception not caught inside the calling
code, it will be rolled back.
*/
interface SqlTransaction {
/*
Execute a SQL statement that returns rows. This includes plain SELECT
queries and database-specific DML statements with row-returning clauses
such as RETURNING or OUTPUT.
Portable SQL uses positional ? placeholders only.
Parameters are already-converted Lyng values bound positionally to the
statement. Portable bindable values are:
- null
- Bool
- Int, Double, Decimal
- String
- Buffer
- Date, DateTime, Instant
Backends may support additional parameter types, but portable code
should limit itself to the values above.
*/
abstract fun select(clause: String,params: Object...): ResultSet
/*
Execute a SQL statement for side effects. Use [select] for any statement
whose primary result is a row set.
Parameters follow the same binding rules as [select].
*/
abstract fun execute(clause: String,params: Object...): ExecutionResult
/*
Create a nested transaction with real nested semantics, typically using
database savepoints.
If the backend cannot provide real nested transaction semantics, this
call should fail with SqlUsageException rather than flattening into the
outer transaction.
Failure inside the nested transaction rolls back only the nested scope;
the outer transaction remains active unless the exception is allowed to
propagate further.
*/
abstract fun transaction<T>( block: (SqlTransaction)->T): T
}
/*
Special exception to be thrown from SqlTransaction.transaction
when nothing else matters/needed (DRY).
It causes rollback and is propagated to the caller, but should not be
treated as a backend/driver failure.
If rollback itself fails, that rollback failure becomes the primary backend
error instead.
*/
class RollbackException: Exception
interface Database {
/*
Open a transaction. Any pooling, physical connection lifecycle, and implementation-specific configuration are owned by the database implementation and hidden from the user.
The transaction commits when the block finishes normally,
and rolls back if the block exits with an uncaught exception.
*/
abstract fun transaction<T>(block: (SqlTransaction) -> T): T
}
/*
Register a database provider for a URL scheme.
Provider modules should call this during module initialization when first
imported. Scheme matching is case-insensitive and normalized to lowercase.
Registering the same scheme more than once should fail.
*/
fun registerDatabaseProvider(
scheme: String,
opener: (connectionUrl: String, extraParams: Map<String,Object?>) -> Database
)
/*
The mandatory generic entry point for all providers. It opens a database
handle from a provider-specific connection URL plus extra parameters.
Providers may expose additional typed constructors such as openSqlite(...)
or openPostgres(...), but openDatabase(...) should remain available for
configuration-driven usage.
It should throw IllegalArgumentException for malformed connection URLs or
invalid extra parameter shapes detected before opening the backend.
Runtime opening failures such as authentication, connectivity, or provider
initialization errors should be reported as DatabaseException.
The matching provider must already be registered, normally because its
module was imported and executed. Unknown schemes or missing providers
should fail with DatabaseException.
*/
extern fun openDatabase(connectionUrl: String,extraParams: Map<String,Object?>): Database

261
notes/db/sqlite_implementation_plan.md Normal file
View File

@ -0,0 +1,261 @@
# SQLite provider implementation plan
Implementation checklist for the first concrete DB provider:
- module: `lyng.io.db.sqlite`
- targets: JVM and Native
- role: reference implementation for the core `lyng.io.db` contract
## Scope
In scope for the first implementation:
- provider registration on module import
- `sqlite:` URL dispatch through `openDatabase(...)`
- typed `openSqlite(...)` helper
- `Database` and `SqlTransaction` implementation
- result-set implementation
- row and column metadata conversion
- SQLite savepoint-based nested transactions
- generated keys for `execute(...)`
- JVM and Native test coverage for the core portable contract
Out of scope for the first implementation:
- schema inspection APIs beyond result-set column metadata
- public prepared statement API
- batch API
- JS support
- heuristic temporal parsing
- heuristic decimal parsing
## Proposed module layout
Core/public declarations:
- `.lyng` declaration source for `lyng.io.db`
- `.lyng` declaration source for `lyng.io.db.sqlite`
Backend/runtime implementation:
- common transaction/result-set abstractions in `commonMain` where possible
- JVM SQLite implementation in `jvmMain`
- Native SQLite implementation in `nativeMain`
## Milestone 1: core DB module skeleton
1. Move or copy the current DB declarations from `notes/db/lyngdb.lyng` into the
real module declaration source location.
2. Add the provider registry runtime for:
- normalized lowercase scheme lookup
- duplicate registration failure
- unknown-scheme failure
3. Implement generic `openDatabase(connectionUrl, extraParams)` dispatch.
4. Add basic tests for:
- successful provider registration
- duplicate scheme registration failure
- unknown scheme failure
- malformed URL failure
## Milestone 2: SQLite provider skeleton
1. Create `lyng.io.db.sqlite` declaration source with:
- typed `openSqlite(...)`
- provider-specific documentation
2. Register `sqlite` scheme at module initialization time.
3. Parse supported URL forms:
- `sqlite::memory:`
- `sqlite:relative/path.db`
- `sqlite:/absolute/path.db`
4. Convert typed helper arguments into the same normalized open options used by
the generic `openDatabase(...)` path.
5. Add tests for:
- import-time registration
- typed helper open
- generic URL-based open
- invalid URL handling
## Milestone 3: JVM backend
Implementation strategy:
- use SQLite JDBC under the hood
- keep JDBC fully internal to the provider
- preserve the Lyng-facing transaction/result contracts rather than exposing
JDBC semantics directly
Steps:
1. Create JVM `Database` implementation that stores normalized SQLite config.
2. For each outer `Database.transaction {}`:
- open/acquire one JDBC connection
- configure connection-level options
- begin transaction
- commit on normal exit
- rollback on uncaught exception
- close/release connection
- preserve error precedence:
- original user exception stays primary on rollback failure
- rollback failure becomes primary for intentional `RollbackException`
- commit failure is primary on normal-exit commit failure
3. For nested `SqlTransaction.transaction {}`:
- create savepoint
- release savepoint on success
- rollback to savepoint on failure
- preserve the same primary/secondary exception rules for savepoint rollback
failures
4. Implement `select(...)`:
- bind positional `?` parameters
- expose result rows through `ResultSet`
- preserve transaction-scoped lifetime
- invalidate both the result set and any rows obtained from it when the
owning transaction ends
5. Implement `execute(...)`:
- bind positional parameters
- collect affected row count
- expose generated keys when supported
6. Implement column metadata normalization:
- output column label
- nullable flag where available
- portable `SqlType`
- backend native type name
7. Add JVM tests for:
- transaction commit
- transaction rollback
- nested transaction savepoint behavior
- rollback failure precedence
- commit failure precedence
- row lookup by index and name
- ambiguous name failure
- result-set use-after-transaction failure
- row use-after-transaction failure
- generated keys
- `RETURNING` via `select(...)` if the backend supports it
## Milestone 4: Native backend
Implementation strategy:
- use direct SQLite C bindings
- keep semantics aligned with the JVM backend
Steps:
1. Create Native `Database` implementation that stores normalized SQLite config.
2. For each outer transaction:
- open one SQLite handle if needed
- configure pragmas/options
- begin transaction
- commit or rollback
3. Implement nested transactions with SQLite savepoints.
4. Implement prepared statement lifecycle internally for `select(...)` and
`execute(...)`.
5. Implement result-set iteration and statement finalization.
6. Implement the same value-conversion policy as JVM:
- exact integer mapping
- `Double`
- `String`
- `Buffer`
- schema-driven `Bool`
- schema-driven `Decimal`
- schema-driven temporal parsing
7. Add Native tests matching the JVM behavioral suite as closely as possible.
## Milestone 5: conversion policy
1. Normalize integer reads:
- return `Int`
2. Normalize floating-point reads to `Double`.
3. Normalize text reads to `String`.
4. Normalize blob reads to `Buffer`.
5. Parse `Decimal` only for declared/native `DECIMAL` / `NUMERIC` columns.
- bind Lyng `Decimal` as canonical text using existing Decimal formatting
- read back with the existing Decimal parser
6. Parse `Bool` only for declared/native `BOOLEAN` / `BOOL` columns:
- prefer integer `0` / `1`
- also accept legacy text `true`, `false`, `t`, `f` case-insensitively
- always write `Bool` as integer `0` / `1`
7. Parse temporal values only from an explicit normalized type-name whitelist:
- `DATE`
- `DATETIME`
- `TIMESTAMP`
- `TIMESTAMP WITH TIME ZONE`
- `TIMESTAMPTZ`
- `DATETIME WITH TIME ZONE`
- `TIME`
- `TIME WITHOUT TIME ZONE`
- `TIME WITH TIME ZONE`
8. Never heuristically parse arbitrary string or numeric values into temporal or
decimal values.
9. If a declared strong type (`Bool`, `Decimal`, `Date`, `DateTime`, `Instant`)
cannot be converted from the stored value, fail with `SqlExecutionException`.
10. Add tests for each conversion rule.
## Milestone 6: result-set contract
1. Ensure `ResultSet.columns` is available before iteration.
2. Implement name lookup using result-column labels.
3. Throw `SqlUsageException` for:
- invalid row index
- missing column name
- ambiguous column name
- use after transaction end
4. Implement cheap `isEmpty()` where practical.
5. Implement `size()` separately, allowing buffering/consumption when required.
6. Verify resource cleanup on:
- full iteration
- canceled iteration
- transaction rollback
## Milestone 7: provider options
Support these typed helper options first:
- `readOnly`
- `createIfMissing`
- `foreignKeys`
- `busyTimeoutMillis`
Expected behavior:
- `foreignKeys` defaults to `true`
- `busyTimeoutMillis` has a non-zero sensible default
- `readOnly` is explicit
- `createIfMissing` is explicit
Add tests for option handling where backend behavior is observable.
## Milestone 8: documentation and examples
1. Add user docs for:
- importing `lyng.io.db.sqlite`
- generic `openDatabase(...)`
- typed `openSqlite(...)`
- transaction usage
- nested transactions
2. Add small sample snippets for:
- in-memory DB
- file-backed DB
- schema creation
- insert/select/update
- rollback on exception
## Testing priorities
Highest priority behavioral tests:
1. provider registration and scheme dispatch
2. outer transaction commit/rollback
3. nested savepoint semantics
4. row metadata and name lookup behavior
5. generated keys for inserts
6. result-set lifetime rules
7. value conversion rules
8. helper vs generic-open parity
## Risks
Main implementation risks:
- keeping JVM and Native value-conversion behavior identical
- correctly enforcing result-set lifetime across both backends
- SQLite temporal conversion ambiguity
- JDBC metadata differences on JVM
- native statement/finalizer lifecycle bugs
## Suggested implementation order
1. core registry runtime
2. SQLite `.lyng` provider declarations
3. JVM SQLite backend
4. JVM test suite
5. Native SQLite backend
6. shared behavioral test suite refinement
7. documentation/examples

272
notes/db/sqlite_provider.md Normal file
View File

@ -0,0 +1,272 @@
# SQLite provider for `lyng.io.db`
First concrete provider candidate for the DB module.
Module name:
- `lyng.io.db.sqlite`
Responsibilities:
- register SQLite URL schemes on first import
- provide the generic `openDatabase(...)` entry point for SQLite URLs
- provide typed SQLite-specific helpers for ergonomic opening
- implement the core `Database` / `SqlTransaction` API on both JVM and Native
## Registration and URL schemes
On first import, the module should register at least:
- `sqlite`
Possible accepted URL forms:
- `sqlite::memory:`
- `sqlite:./local.db`
- `sqlite:/absolute/path/data.db`
The exact accepted path grammar can be tightened during implementation, but it
should stay simple and configuration-friendly.
## Typed helper
The provider should also expose a typed helper, e.g.:
```lyng
fun openSqlite(
path: String,
readOnly: Bool = false,
createIfMissing: Bool = true,
foreignKeys: Bool = true,
busyTimeoutMillis: Int = 5000
): Database
```
Possible special values:
- `":memory:"` for in-memory DB
The helper is provider-specific sugar with explicit typed arguments. The generic
`openDatabase(...)` path must stay fully supported for configuration-driven
usage.
## Implementation strategy
SQLite should be the first real provider because it is available on both JVM and
Native and exercises almost the whole core API surface.
### JVM
Preferred implementation:
- JDBC-backed SQLite provider for the JVM-specific backend implementation
This is acceptable because SQLite itself is local and the JDBC bridge is much
simpler here than for network databases.
### Native
Preferred implementation:
- direct SQLite C library binding
The provider should present the same Lyng-facing semantics on both backends.
## Transactions
Required behavior:
- `Database.transaction {}` starts a real SQLite transaction
- `SqlTransaction.transaction {}` uses SQLite savepoints
- nested transactions must be supported
- failures in nested transactions roll back only to the nested savepoint unless
the exception escapes further
- error precedence follows the core DB contract:
- user exception + successful rollback -> user exception escapes unchanged
- user exception + rollback failure -> user exception stays primary
- intentional `RollbackException` + rollback failure -> rollback failure is
primary
- commit failure after normal completion -> commit failure is primary
SQLite is a good fit here because savepoints are well-supported.
Connection/handle semantics:
- one outer `Database.transaction {}` must use exactly one physical SQLite
connection/handle for its whole lifetime
- nested transactions must stay on that same connection/handle
- a transaction must never hop across connections
This is required because SQLite transaction state, savepoints, and generated
row-id behavior are all connection-local.
## Result sets
The provider may stream rows or buffer them, but it must preserve the core
contract:
- result sets are valid only while the owning transaction is active
- rows obtained from a result set are also invalid after the owning
transaction ends, even if they were already buffered
- iteration closes underlying resources when finished or canceled
- `isEmpty()` should be cheap where possible
- `size()` may consume or buffer the full result
## SQLite-specific type mapping notes
SQLite uses dynamic typing and affinity rules, so the provider must normalize
returned values into the portable Lyng types.
Recommended mapping strategy:
- integer values -> `Int`
- floating-point values -> `Double`
- text values -> `String`
- blob values -> `Buffer`
- declared/native `BOOLEAN` / `BOOL` -> `Bool`
- numeric values that are explicitly read/declared as decimal -> `Decimal` when
the provider can determine this reliably
- date/time values should be parsed only when the declared/native column type
indicates temporal intent
The provider should not heuristically parse arbitrary `TEXT`, `INTEGER`, or
`REAL` values into temporal or decimal types just because the stored value looks
like one.
If a column is exposed with a stronger portable `SqlType` such as `Bool`,
`Decimal`, `Date`, `DateTime`, or `Instant`, then the produced row value should
either be that Lyng value or `null`. Invalid stored representations should fail
with `SqlExecutionException`.
Boolean policy exception:
- unlike temporal values, legacy boolean encodings are cheap to recognize and
have low ambiguity
- therefore SQLite `BOOL` / `BOOLEAN` columns may accept a small tolerant set of
legacy boolean encodings on read
- writes should still always use integer `0` / `1`
- temporal and decimal conversions remain strict/schema-driven
Declared type-name normalization for SQLite v1:
- trim surrounding whitespace
- uppercase
- collapse internal whitespace runs to a single space
- strip a trailing `( ... )` size/precision suffix before matching
Examples:
- ` numeric(10,2) ` -> `NUMERIC`
- `timestamp with time zone` -> `TIMESTAMP WITH TIME ZONE`
SQLite v1 declared type-name whitelist:
| normalized declared/native type | portable `SqlType` |
|---------------------------------|--------------------|
| `BOOLEAN` | `Bool` |
| `BOOL` | `Bool` |
| `DECIMAL` | `Decimal` |
| `NUMERIC` | `Decimal` |
| `DATE` | `Date` |
| `DATETIME` | `DateTime` |
| `TIMESTAMP` | `DateTime` |
| `TIMESTAMP WITH TIME ZONE` | `Instant` |
| `TIMESTAMPTZ` | `Instant` |
| `DATETIME WITH TIME ZONE` | `Instant` |
| `TIME` | `String` |
| `TIME WITHOUT TIME ZONE` | `String` |
| `TIME WITH TIME ZONE` | `String` |
Anything not in this table should not be promoted to a stronger portable type
just from its declared name.
## SQLite temporal policy
SQLite has no strong built-in temporal storage types, so the provider should use
a strict schema-driven conversion policy.
Binding:
- `null` -> SQL `NULL`
- `Bool` -> integer `0` / `1`
- `Int` -> SQLite integer
- `Double` -> SQLite real
- `Decimal` -> canonical decimal text representation using the existing Lyng
Decimal formatter
- `String` -> text
- `Buffer` -> blob
- `Date` -> ISO text `YYYY-MM-DD`
- `DateTime` -> ISO text without timezone
- `Instant` -> ISO text in UTC with explicit timezone marker
Reading:
- storage class `NULL` -> `null`
- normalized declared/native type `BOOLEAN` or `BOOL` -> parse as `Bool` with
this ordered rule:
- integer `0` / `1` first
- then legacy text forms, case-insensitively: `true`, `false`, `t`, `f`
- other stored values are conversion errors
- normalized declared/native type `DATE` -> parse as `Date`
- normalized declared/native type `DATETIME` or `TIMESTAMP` -> parse as `DateTime`
- normalized declared/native type `TIMESTAMP WITH TIME ZONE`,
`TIMESTAMPTZ`, or `DATETIME WITH TIME ZONE` -> parse as `Instant`
- normalized declared/native type `TIME`, `TIME WITHOUT TIME ZONE`, or
`TIME WITH TIME ZONE` -> keep as `String` in v1
- normalized declared/native type `DECIMAL` or `NUMERIC` -> parse as `Decimal`
- otherwise integer storage -> `Int`
- otherwise real storage -> `Double`
- otherwise text storage -> `String`
- otherwise blob storage -> `Buffer`
- otherwise do not guess, and return the raw normalized SQLite value type
For v1, the provider should not automatically interpret numeric epoch values or
Julian date encodings unless this is later added as an explicit provider option.
## SQLite decimal policy
Decimal conversion should also be schema-driven:
- normalized declared/native type `DECIMAL` or `NUMERIC` -> parse as `Decimal`
- otherwise do not guess from text or floating-point storage alone
Decimal exactness note:
- SQLite has no native decimal storage class; values are stored as `INTEGER`,
`REAL`, `TEXT`, `BLOB`, or `NULL`
- binding Lyng `Decimal` as text is only the provider's chosen encoding, not a
native SQLite decimal representation
- SQLite v1 should therefore store Lyng `Decimal` values as canonical text and
parse them back with the existing Lyng Decimal parser/formatter stack
- schemas that care about decimal semantics should still declare
`DECIMAL` / `NUMERIC` affinity so the provider knows to expose `Decimal`
- exact round-tripping therefore cannot be guaranteed for generic
`DECIMAL` / `NUMERIC` columns, because SQLite affinity rules may coerce stored
values before they are read back
- SQLite values already stored as `REAL` in `DECIMAL` / `NUMERIC` columns may
already reflect floating-point precision loss before Lyng sees them
- if exact decimal preservation is required, the schema and provider policy must
intentionally store decimal values in an exact representation, most simply as
canonical text
This area will need careful implementation rules because SQLite itself does not
have a strong native temporal type system.
## Generated keys
`ExecutionResult.getGeneratedKeys()` for SQLite should return implementation-
supported generated values for `execute(...)`.
Typical example:
- row id generated by an insert into a table with integer primary key
Statements that explicitly return rows should still go through `select(...)`,
for example if the provider eventually supports SQLite `RETURNING`.
## Options
Likely provider-specific options:
- read-only mode
- create-if-missing
- busy timeout
- foreign keys on/off
These options can be accepted both through SQLite helper functions and through
`openDatabase(..., extraParams)` when the URL scheme is `sqlite`.
Recommended defaults:
- foreign keys enabled by default
- busy timeout may be configurable, but should have a sensible default
- read-only and create-if-missing should be explicit options rather than hidden
URL magic
## Non-goals for v1
Not required for the first SQLite provider:
- schema metadata beyond result-column metadata
- prepared statement API in public surface
- batch execution API
- provider capability flags
- JS/browser support

0
proposals/db_interface.md Normal file
View File

0
proposals/lyngdb.lyng Normal file
View File