Room support

Author: simolus3

build.gradle.kts

@@ -19,6 +19,8 @@ plugins {
     alias(libs.plugins.keeper) apply false
     alias(libs.plugins.kotlin.atomicfu) apply false
     alias(libs.plugins.cocoapods) apply false
+    alias(libs.plugins.ksp) apply false
+    alias(libs.plugins.androidx.room) apply false
     id("org.jetbrains.dokka") version libs.versions.dokkaBase
     id("dokka-convention")
 }

core/src/androidMain/kotlin/com/powersync/DatabaseDriverFactory.android.kt

@@ -21,3 +21,7 @@ public actual class DatabaseDriverFactory(
 public fun BundledSQLiteDriver.addPowerSyncExtension() {
     addExtension("libpowersync.so", "sqlite3_powersync_init")
 }
+
+public actual fun resolvePowerSyncLoadableExtensionPath(): String? {
+    return "libpowersync.so"
+}

core/src/appleNonWatchOsMain/kotlin/com/powersync/DatabaseDriverFactory.appleNonWatchOs.kt

@@ -21,3 +21,8 @@ public actual class DatabaseDriverFactory {
         return db
     }
 }
+
+@ExperimentalPowerSyncAPI
+public actual fun resolvePowerSyncLoadableExtensionPath(): String? {
+    return powerSyncExtensionPath
+}

core/src/commonMain/kotlin/com/powersync/DatabaseDriverFactory.kt

@@ -17,6 +17,19 @@ public expect class DatabaseDriverFactory {
     ): SQLiteConnection
 }
 
+/**
+ * Resolves a path to the loadable PowerSync core extension library.
+ *
+ * This library must be loaded on all databases using the PowerSync SDK. On platforms where the
+ * extension is linked statically (only watchOS at the moment), this returns `null`.
+ *
+ * When using the PowerSync SDK directly, there is no need to invoke this method. It is intended for
+ * configuring external database connections not managed by PowerSync to work with the PowerSync
+ * SDK.
+ */
+@ExperimentalPowerSyncAPI
+public expect fun resolvePowerSyncLoadableExtensionPath(): String?
+
 @OptIn(ExperimentalPowerSyncAPI::class)
 internal fun openDatabase(
     factory: DatabaseDriverFactory,

core/src/jvmMain/kotlin/com/powersync/DatabaseDriverFactory.jvm.kt

@@ -20,3 +20,8 @@ public fun BundledSQLiteDriver.addPowerSyncExtension() {
 }
 
 private val powersyncExtension: String by lazy { extractLib("powersync") }
+
+@ExperimentalPowerSyncAPI
+public actual fun resolvePowerSyncLoadableExtensionPath(): String? {
+    return powersyncExtension
+}

core/src/watchosMain/kotlin/com/powersync/DatabaseDriverFactory.watchos.kt

@@ -31,3 +31,9 @@ private val didLoadExtension by lazy {
 
     true
 }
+
+@ExperimentalPowerSyncAPI
+public actual fun resolvePowerSyncLoadableExtensionPath(): String? {
+    didLoadExtension
+    return null
+}

gradle/libs.versions.toml

@@ -10,9 +10,11 @@ java = "17"
 
 # Dependencies
 kermit = "2.0.8"
-kotlin = "2.2.10"
+kotlin = "2.2.10" # Note: When updating, always update the first part of the ksp version too
+ksp = "2.2.10-2.0.2"
 coroutines = "1.10.2"
 kotlinx-datetime = "0.7.1"
+serialization = "1.9.0"
 kotlinx-io = "0.8.0"
 ktor = "3.2.3"
 uuid = "0.8.4"
@@ -30,6 +32,7 @@ compose-preview = "1.9.0"
 compose-lifecycle = "2.9.2"
 androidxSqlite = "2.6.0-rc02"
 androidxSplashscreen = "1.0.1"
+room = "2.8.0-rc02"
 
 # plugins
 android-gradle-plugin = "8.12.1"
@@ -88,6 +91,7 @@ ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "kto
 ktor-client-contentnegotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
 ktor-client-mock = { module = "io.ktor:ktor-client-mock", version.ref = "ktor" }
 ktor-serialization-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "serialization" }
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
 kotlinx-coroutines-swing = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-swing", version.ref = "coroutines" }
 
@@ -97,6 +101,8 @@ supabase-auth = { module = "io.github.jan-tennert.supabase:auth-kt", version.ref
 supabase-storage = { module = "io.github.jan-tennert.supabase:storage-kt", version.ref = "supabase" }
 androidx-sqlite-sqlite = { module = "androidx.sqlite:sqlite", version.ref = "androidxSqlite" }
 androidx-sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "androidxSqlite" }
+androidx-room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" }
+androidx-room-compiler = { module = "androidx.room:room-compiler", version.ref = "room" }
 
 # Sample - Android
 androidx-core = { group = "androidx.core", name = "core-ktx", version.ref = "androidx-core" }
@@ -143,3 +149,5 @@ keeper = { id = "com.slack.keeper", version.ref = "keeper" }
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
 kotlin-atomicfu = { id = "org.jetbrains.kotlinx.atomicfu", version.ref = "atomicfu" }
 buildKonfig = { id = "com.codingfeline.buildkonfig", version.ref = "buildKonfig" }
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
+androidx-room = { id = "androidx.room", version.ref = "room" }

integrations/room/README.md

@@ -0,0 +1,58 @@
+# PowerSync Room integration
+
+This module provides the ability to use PowerSync with Room databases. This module aims for complete
+Room support, meaning that:
+
+1. Changes synced from PowerSync automatically update your Room `Flow`s.
+2. Room and PowerSync cooperate on the write connection, avoiding "database is locked errors".
+3. Changes from Room trigger a CRUD upload.
+
+## Setup
+
+PowerSync can use an existing Room database, provided that the PowerSync core SQLite extension has
+been loaded. To do that:
+
+1. Add a dependency on `androidx.sqlite:sqlite-bundled`. Using the SQLite version from the Android
+   framework will not work as it doesn't support loading extensions.
+2. On your `RoomDatabase.Builder`, call `setDriver()` with a PowerSync-enabled driver: 
+    ```Kotlin
+    val driver = BundledSQLiteDriver().also {
+        it.loadPowerSyncExtension() // Extension method by this module
+    }
+    
+    Room.databaseBuilder(...).setDriver(driver).build()
+    ```
+3. Configure raw tables for your Room databases.
+
+After these steps, you can open your Room database like you normally would. Then, you can use the
+following method to obtain  a `PowerSyncDatabase` instance that is backed by Room:
+
+```Kotlin
+val pool = RoomConnectionPool(yourRoomDatabase)
+val powersync = PowerSyncDatabase.opened(
+    pool = pool,
+    scope = this,
+    schema = Schema(...), // With Room, you need to use raw tables
+    identifier = "databaseName", // Prefer to use the same path/name as your Room database
+    logger = Logger,
+)
+
+powersync.connect(...)
+```
+
+Changes from PowerSync (regardless of whether they've been made with `powersync.execute` or from a
+sync operation) will automatically trigger updates in Room.
+
+To also transfer local writes to PowerSync, you need to
+
+1. Create triggers on your Room tables to insert into `ps_crud` (see the PowerSync documentation on
+   raw tables for details).
+2. Listen for Room changes and invoke a helper method to transfer them to PowerSync:
+    ```Kotlin
+    yourRoomDatabase.getCoroutineScope().launch {
+        // list all your tables here
+        yourRoomDatabase.invalidationTracker.createFlow("users", "groups", /*...*/).collect {
+            pool.transferRoomUpdatesToPowerSync()
+        }
+    }
+    ```

integrations/room/build.gradle.kts

@@ -0,0 +1,89 @@
+import com.powersync.plugins.sonatype.setupGithubRepository
+import com.powersync.plugins.utils.powersyncTargets
+
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlinter)
+    alias(libs.plugins.ksp)
+    alias(libs.plugins.kotlinSerialization)
+    id("com.powersync.plugins.sonatype")
+    id("dokka-convention")
+    id("com.powersync.plugins.sharedbuild")
+}
+
+kotlin {
+    powersyncTargets()
+
+    explicitApi()
+
+    sourceSets {
+        all {
+            languageSettings {
+                optIn("com.powersync.ExperimentalPowerSyncAPI")
+            }
+        }
+
+        commonMain.dependencies {
+            api(project(":core"))
+            api(libs.androidx.room.runtime)
+            api(libs.androidx.sqlite.bundled)
+
+            implementation(libs.kotlinx.serialization.json)
+        }
+
+        commonTest.dependencies {
+            implementation(libs.kotlin.test)
+            implementation(libs.kotlinx.io)
+            implementation(libs.test.kotest.assertions)
+            implementation(libs.test.coroutines)
+            implementation(libs.test.turbine)
+
+            implementation(libs.androidx.sqlite.bundled)
+        }
+    }
+}
+
+dependencies {
+    // We use a room database for testing, so we apply the symbol processor on the test target.
+    val targets = listOf(
+        "jvm",
+        "macosArm64",
+        "macosX64",
+        "iosSimulatorArm64",
+        "iosX64",
+        "tvosSimulatorArm64",
+        "tvosX64",
+        "watchosSimulatorArm64",
+        "watchosX64"
+    )
+
+    targets.forEach { target ->
+        val capitalized = target.replaceFirstChar { if (it.isLowerCase()) it.titlecase() else it.toString() }
+
+        add("ksp${capitalized}Test", libs.androidx.room.compiler)
+    }
+}
+
+android {
+    namespace = "com.powersync.compose"
+    compileSdk =
+        libs.versions.android.compileSdk
+            .get()
+            .toInt()
+    defaultConfig {
+        minSdk =
+            libs.versions.android.minSdk
+                .get()
+                .toInt()
+    }
+    kotlin {
+        jvmToolchain(17)
+    }
+}
+
+setupGithubRepository()
+
+dokka {
+    moduleName.set("PowerSync Room Integration")
+}

integrations/room/src/androidUnitTest/kotlin/com/powersync/integrations/room/utils.android.kt

@@ -0,0 +1,7 @@
+package com.powersync.integrations.room
+
+import androidx.room.RoomDatabase
+
+actual fun createDatabaseBuilder(): RoomDatabase.Builder<TestDatabase> {
+    TODO("Android unit tests are unsupported, we test on JVM instead")
+}