Add Room integration (#249)

Author: simolus3

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
           - os: windows-latest
             targets: jvmTest
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 20
+    timeout-minutes: 30
 
     steps:
     - uses: actions/checkout@v4

CHANGELOG.md

@@ -6,6 +6,7 @@
 * Add `rawConnection` getter to `ConnectionContext`, which is a `SQLiteConnection` instance from
   `androidx.sqlite` that can be used to step through statements in a custom way.
 * Fix an issue where `watch()` would run queries more often than intended.
+* Add an integration for the Room database library ([readme](integrations/room/README.md)).
 
 ## 1.5.1
 

README.md

@@ -13,6 +13,7 @@ This is the PowerSync client SDK for Kotlin. This SDK currently supports the fol
 - iOS
 - macOS
 - watchOS
+- tvOS
 
 If you need support for additional targets, please reach out!
 
@@ -32,6 +33,11 @@ and API documentation [here](https://powersync-ja.github.io/powersync-kotlin/).
         1. Retrieve a token to connect to the PowerSync service.
         2. Apply local changes on your backend application server (and from there, to your backend database).
 
+- [integrations](./integrations/)
+   - [room](./integrations/room/README.md): Allows using the [Room database library](https://developer.android.com/jetpack/androidx/releases/room)
+     with PowerSync, making it easier to run typed queries on the database.
+
+
 ## Demo Apps / Example Projects
 
 The easiest way to test the PowerSync KMP SDK is to run one of our demo applications.
@@ -41,12 +47,6 @@ Demo applications are located in the [`demos/`](./demos) directory. See their re
 - [demos/supabase-todolist](./demos/supabase-todolist/README.md): A simple to-do list application demonstrating the use of the PowerSync Kotlin Multiplatform SDK and the Supabase connector.
 - [demos/android-supabase-todolist](./demos/android-supabase-todolist/README.md): A simple to-do list application demonstrating the use of the PowerSync Kotlin Multiplatform SDK and the Supabase connector in an Android application.
 
-## Current Limitations / Future work
-
-Current limitations:
-
-- Integration with SQLDelight schema and API generation (ORM) is not yet supported.
-
 ## Installation
 
 Add the PowerSync Kotlin Multiplatform SDK to your project by adding the following to your `build.gradle.kts` file:

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

@@ -3,6 +3,7 @@ package com.powersync
 import android.content.Context
 import androidx.sqlite.SQLiteConnection
 import androidx.sqlite.driver.bundled.BundledSQLiteDriver
+import kotlin.Throws
 
 @Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
 public actual class DatabaseDriverFactory(
@@ -21,3 +22,7 @@ public actual class DatabaseDriverFactory(
 public fun BundledSQLiteDriver.addPowerSyncExtension() {
     addExtension("libpowersync.so", "sqlite3_powersync_init")
 }
+
+@ExperimentalPowerSyncAPI
+@Throws(PowerSyncException::class)
+public actual fun resolvePowerSyncLoadableExtensionPath(): String? = "libpowersync.so"

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

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

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

@@ -17,6 +17,20 @@ 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
+@Throws(PowerSyncException::class)
+public expect fun resolvePowerSyncLoadableExtensionPath(): String?
+
 @OptIn(ExperimentalPowerSyncAPI::class)
 internal fun openDatabase(
     factory: DatabaseDriverFactory,

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

@@ -2,6 +2,7 @@ package com.powersync
 
 import androidx.sqlite.SQLiteConnection
 import androidx.sqlite.driver.bundled.BundledSQLiteDriver
+import com.powersync.db.runWrapped
 
 @Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING", "SqlNoDataSourceInspection")
 public actual class DatabaseDriverFactory {
@@ -20,3 +21,7 @@ public fun BundledSQLiteDriver.addPowerSyncExtension() {
 }
 
 private val powersyncExtension: String by lazy { extractLib("powersync") }
+
+@ExperimentalPowerSyncAPI
+@Throws(PowerSyncException::class)
+public actual fun resolvePowerSyncLoadableExtensionPath(): String? = runWrapped { powersyncExtension }

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

@@ -31,3 +31,10 @@ private val didLoadExtension by lazy {
 
     true
 }
+
+@ExperimentalPowerSyncAPI
+@Throws(PowerSyncException::class)
+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" }