meldestelle/docs/02_Guides/SQLDelight_Web_Asynchron.md

type	status	owner
Guide	ACTIVE	Frontend Expert

Architekturstrategien für Asynchrone Persistenz in Kotlin Multiplatform: Eine umfassende Analyse zur Integration von SQLDelight in Web-Umgebungen

1. Einleitung und Problemstellung

Die Entwicklung plattformübergreifender Anwendungen mittels Kotlin Multiplatform (KMP) hat in den letzten Jahren einen paradigmatischen Wandel vollzogen. Ein zentraler Bestandteil dieser Architektur ist die Datenpersistenz, für die sich SQLDelight als Industriestandard etabliert hat.

Die Integration der Web-Plattform stellt jedoch eine signifikante architektonische Herausforderung dar. Wie in der Problemstellung korrekt identifiziert, existiert eine fundamentale Diskrepanz zwischen den synchronen I/O-Operationen nativer Plattformen (Android, iOS) und der zwingend asynchronen Natur des Webs. Während native SQLite-Treiber (AndroidSqliteDriver, NativeSqliteDriver) Datenbankoperationen blockierend ausführen können, erfordert der Browser die Nutzung eines WebWorkerDriver und asynchrone Initialisierungsmuster.

Dieser Bericht liefert eine Lösungsarchitektur basierend auf dem "Lazy Async Wrapper"-Muster und Koin.

---

2. Theoretisches Fundament: Die Asynchronitäts-Lücke

2.1 Native vs. Web-Laufzeitumgebungen

Auf nativen Systemen kann der SqlDriver synchron instanziiert werden. Im Browser hingegen nutzt SQLDelight sql.js oder sqlite-wasm in einem Web Worker. Die Kommunikation erfolgt über Message Passing, was suspend-Funktionen für die Initialisierung erzwingt.

2.2 Der Paradigmenwechsel mit SQLDelight 2.0

Mit Version 2.0 wurde die Konfiguration generateAsync eingeführt:kotlin sqldelight { databases { create("AppDatabase") { packageName.set("com.example.db") generateAsync.set(true) } } }

Setzt man dieses Flag auf true, werden alle Datenbankoperationen als suspend-Funktionen generiert.[1, 4] Dies ist der erste Schritt zur Vereinheitlichung: Auch native Plattformen nutzen nun (formal) asynchrone Schnittstellen, was den gemeinsamen Code homogenisiert.

---

3. Die Lösungsarchitektur: Das "Lazy Async Wrapper"-Muster

Anstatt die Datenbank direkt beim App-Start zu initialisieren (was im Web blockieren oder fehlschlagen würde, wenn der Worker noch nicht bereit ist), kapseln wir den Treiber in einer Wrapper-Klasse.[5, 2]

3.1 Definition der Factory

Datei: shared/src/commonMain/kotlin/.../DatabaseDriverFactory.kt

import app.cash.sqldelight.db.SqlDriver

interface DatabaseDriverFactory {
    suspend fun createDriver(): SqlDriver
}

3.2 Der Database Wrapper

Diese Komponente löst das Problem des Nutzers, indem sie die Initialisierung bis zum ersten Zugriff verzögert und mittels Mutex absichert.

Datei: shared/src/commonMain/kotlin/.../DatabaseWrapper.kt

import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock

class DatabaseWrapper(private val driverFactory: DatabaseDriverFactory) {
    private var _database: AppDatabase? = null
    private val mutex = Mutex()

    suspend fun get(): AppDatabase {
        _database?.let { return it }
        return mutex.withLock {
            _database?: AppDatabase(driverFactory.createDriver()).also { _database = it }
        }
    }

    // Helper für Repositories
    suspend operator fun <R> invoke(block: suspend (AppDatabase) -> R): R {
        return block(get())
    }
}

---

4. Implementierung der Plattform-Treiber

4.1 Web (Kotlin/Wasm & JS)

Hier liegt der Kern der Lösung: Wir warten explizit auf die Schema-Erstellung (awaitCreate), bevor wir den Treiber zurückgeben.

Datei: shared/src/jsMain/kotlin/.../WebDatabaseDriverFactory.kt

import app.cash.sqldelight.driver.worker.WebWorkerDriver
import org.w3c.dom.Worker

class WebDatabaseDriverFactory : DatabaseDriverFactory {
    override suspend fun createDriver(): SqlDriver {
        val worker = Worker(
            js("""new URL("@cashapp/sqldelight-sqljs-worker/sqljs.worker.js", import.meta.url)""")
        )
        val driver = WebWorkerDriver(worker)
        
        // WICHTIG: Hier wird asynchron gewartet!
        AppDatabase.Schema.create(driver).await()
        return driver
    }
}

Webpack Konfiguration: Damit dies funktioniert, muss die sql-wasm.wasm Datei korrekt kopiert werden.

// webpack.config.d/sqljs.js
const CopyWebpackPlugin = require('copy-webpack-plugin');
config.plugins.push(
    new CopyWebpackPlugin({
        patterns: [
            '../../node_modules/sql.js/dist/sql-wasm.wasm'
        ]
    })
);

4.2 Android (Synchron)

Für Android geben wir den synchronen Treiber einfach in der suspend-Funktion zurück.

class AndroidDatabaseDriverFactory(private val context: Context) : DatabaseDriverFactory {
    override suspend fun createDriver(): SqlDriver {
        return AndroidSqliteDriver(AppDatabase.Schema, context, "app.db")
    }
}

---

5. Integration mit Koin

Da der DatabaseWrapper selbst leichtgewichtig ist (er erstellt die DB noch nicht im Konstruktor), kann er problemlos als single in Koin registriert werden.

val appModule = module {
    single { DatabaseWrapper(get()) }
    single { MyRepository(get()) }
}

Das Repository nutzt dann den Wrapper:

class MyRepository(private val dbWrapper: DatabaseWrapper) {
    suspend fun getItems() = dbWrapper { db ->
        db.itemQueries.selectAll().executeAsList()
    }
}

6. Zusammenfassung

Diese Architektur löst den Konflikt zwischen synchronen und asynchronen Welten durch:

1. generateAsync = true: Erzwingt suspend überall.

2. Wrapper Pattern: Kapselt die asynchrone Initialisierung (await()) im Web.

3. Koin Singleton: Der Wrapper kann sofort injiziert werden, die DB wird erst beim ersten invoke geladen.