diff --git a/README.md b/README.md index 56c60fcc..aa5bdeca 100644 --- a/README.md +++ b/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. diff --git a/integrations/room/README.md b/integrations/room/README.md index 31925dd1..9b6ce1bd 100644 --- a/integrations/room/README.md +++ b/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). \ No newline at end of file diff --git a/integrations/sqldelight/README.md b/integrations/sqldelight/README.md index de94ad7f..4e8a7399 100644 --- a/integrations/sqldelight/README.md +++ b/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). \ No newline at end of file