Merge pull request #268 from powersync-ja/sql-libs-readme-polish

Leaner Readmes for Room and SQLDelight, linking to docs

Author: benitav

README.md

@@ -34,8 +34,7 @@ and API documentation [here](https://powersync-ja.github.io/powersync-kotlin/).
         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.
+  - [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.
   - [sqldelight](./integrations/sqldelight/README.md): Allows using [SQLDelight](https://sqldelight.github.io/sqldelight)
     with PowerSync, also enabling typed statements on the database.
 

integrations/room/README.md

@@ -3,62 +3,6 @@
 > [!NOTE]
 > Note that this package is currently in alpha.
 
-This module provides the ability to use PowerSync with Room databases. This module aims for complete
-Room support, meaning that:
+This module integrates PowerSync with Room databases. This allows you run typed queries against the local database with compile-time validation. 
 
-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.
-
-For more details on using this module, see its page on the [PowerSync documentation](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform/libraries/room).
-
-## Setup
-
-Add a dependency on `com.powersync:integration-room` with the same version you use for the main
-PowerSync SDK.
-
-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 which is backed by Room:
-
-```Kotlin
-// With Room, you need to use raw tables (https://docs.powersync.com/usage/use-case-examples/raw-tables).
-// This is because Room verifies your schema at runtime, and PowerSync-managed views will not
-// pass those checks.
-val schema = Schema(...)
-val pool = RoomConnectionPool(yourRoomDatabase, schema)
-val powersync = PowerSyncDatabase.opened(
-    pool = pool,
-    scope = this,
-    schema = schema,
-    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](https://docs.powersync.com/usage/use-case-examples/raw-tables#capture-local-writes-with-triggers)
-   for details).
-2. Pass the schema as a second parameter to the `RoomConnectionPool` constructor. This will make the
-   pool notify PowerSync on Room writes for every raw table mentioned in the schema.
-   Alternatively, call `transferPendingRoomUpdatesToPowerSync` after writes in Room.
+For details on using this integration, see its page on the [PowerSync documentation](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform/libraries/room).

integrations/sqldelight/README.md

@@ -3,65 +3,6 @@
 > [!NOTE]
 > Note that this package is currently in beta.
 
-This library provides the `PowerSyncDriver` class, which implements an `SqlDriver` for `SQLDelight`
-backed by PowerSync.
+This library integrates PowerSync with SQLDelight. This allows you run typed queries against the local database with compile-time validation. It provides the `PowerSyncDriver` class, which implements a `SqlDriver` for `SQLDelight` backed by PowerSync.
 
-For more details on using this module, see its page on the [PowerSync documentation](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform/libraries/sqldelight).
-
-## Setup
-
-Add a dependency on `com.powersync:integration-sqldelight`, using the same version you use for the
-PowerSync SDK.
-
-## Usage
-
-To get started, ensure that SQLDelight is not linking sqlite3 (the PowerSync SDK takes care of that,
-and you don't want to link it twice). Also, ensure the async generator is active because the
-PowerSync driver does not support synchronous reads:
-
-```kotlin
-sqldelight {
-    databases {
-        linkSqlite.set(false)
-
-        create("MyAppDatabase") {
-            generateAsync.set(true)
-            deriveSchemaFromMigrations.set(false)
-
-            dialect("app.cash.sqldelight:sqlite-3-38-dialect")
-        }
-    }
-}
-```
-
-Next, define your tables in `.sq` files (but note that the `CREATE TABLE` statement won't be used,
-PowerSync creates JSON-backed views for tables instead).
-Open a PowerSync database [in the usual way](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform#getting-started)
-and finally pass it to the constructor of your generated SQLDelight database:
-
-```kotlin
-val db: PowerSyncDatabase = openPowerSyncDatabase()
-val yourSqlDelightDatabase = YourDatabase(PowerSyncDriver(db))
-```
-
-Afterwards, writes on both databases (the original `PowerSyncDatabase` instance and the SQLDelight
-database) will be visible to each other, update each other's query flows and will get synced
-properly.
-
-## Limitations
-
-Please note that this library is currently in alpha. It is tested, but API changes are still
-possible.
-
-There are also some limitations to be aware of:
-
-1. Due to historical reasons, the PowerSync SDK migrates all databases to `user_version` 1 when
-   created (but it will never downgrade a database).
-   So if you want to use SQLDelight's schema tools, the first version would have to be `2`.
-2. The `CREATE TABLE` statements in your `.sq` files are only used at build time to verify your
-   queries. At runtime, PowerSync will create tables from your schema as views, the defined
-   statements are ignored.
-   If you want to use the schema managed by SQLDelight, configure PowerSync to use
-   [raw tables](https://docs.powersync.com/usage/use-case-examples/raw-tables).
-3. Functions and tables contributed by the PowerSync core extension are not visible to `.sq` files
-   at the moment. We might revisit this with a custom dialect in the future.
+For details on using this integration, see its page on the [PowerSync documentation](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform/libraries/sqldelight).