|
1 | 1 | # PowerSync Room integration |
2 | 2 |
|
3 | | -This module provides the ability to use PowerSync with Room databases. This module aims for complete |
4 | | -Room support, meaning that: |
| 3 | +> [!NOTE] |
| 4 | +> Note that this package is currently in alpha. |
5 | 5 |
|
6 | | -1. Changes synced from PowerSync automatically update your Room `Flow`s. |
7 | | -2. Room and PowerSync cooperate on the write connection, avoiding "database is locked errors". |
8 | | -3. Changes from Room trigger a CRUD upload. |
| 6 | +This module integrates PowerSync with Room databases. This allows you run typed queries against the local database with compile-time validation. |
9 | 7 |
|
10 | | -## Setup |
11 | | - |
12 | | -Add a dependency on `com.powersync:integration-room` with the same version you use for the main |
13 | | -PowerSync SDK. |
14 | | - |
15 | | -PowerSync can use an existing Room database, provided that the PowerSync core SQLite extension has |
16 | | -been loaded. To do that: |
17 | | - |
18 | | -1. Add a dependency on `androidx.sqlite:sqlite-bundled`. Using the SQLite version from the Android |
19 | | - framework will not work as it doesn't support loading extensions. |
20 | | -2. On your `RoomDatabase.Builder`, call `setDriver()` with a PowerSync-enabled driver: |
21 | | - ```Kotlin |
22 | | - val driver = BundledSQLiteDriver().also { |
23 | | - it.loadPowerSyncExtension() // Extension method by this module |
24 | | - } |
25 | | - |
26 | | - Room.databaseBuilder(...).setDriver(driver).build() |
27 | | - ``` |
28 | | -3. Configure raw tables for your Room databases. |
29 | | - |
30 | | -After these steps, you can open your Room database like you normally would. Then, you can use the |
31 | | -following method to obtain a `PowerSyncDatabase` instance which is backed by Room: |
32 | | - |
33 | | -```Kotlin |
34 | | -// With Room, you need to use raw tables (https://docs.powersync.com/usage/use-case-examples/raw-tables). |
35 | | -// This is because Room verifies your schema at runtime, and PowerSync-managed views will not |
36 | | -// pass those checks. |
37 | | -val schema = Schema(...) |
38 | | -val pool = RoomConnectionPool(yourRoomDatabase, schema) |
39 | | -val powersync = PowerSyncDatabase.opened( |
40 | | - pool = pool, |
41 | | - scope = this, |
42 | | - schema = schema, |
43 | | - identifier = "databaseName", // Prefer to use the same path/name as your Room database |
44 | | - logger = Logger, |
45 | | -) |
46 | | -powersync.connect(...) |
47 | | -``` |
48 | | - |
49 | | -Changes from PowerSync (regardless of whether they've been made with `powersync.execute` or from a |
50 | | -sync operation) will automatically trigger updates in Room. |
51 | | - |
52 | | -To also transfer local writes to PowerSync, you need to |
53 | | - |
54 | | -1. Create triggers on your Room tables to insert into `ps_crud` (see the |
55 | | - [PowerSync documentation on raw tables](https://docs.powersync.com/usage/use-case-examples/raw-tables#capture-local-writes-with-triggers) |
56 | | - for details). |
57 | | -2. Pass the schema as a second parameter to the `RoomConnectionPool` constructor. This will make the |
58 | | - pool notify PowerSync on Room writes for every raw table mentioned in the schema. |
59 | | - Alternatively, call `transferPendingRoomUpdatesToPowerSync` after writes in Room. |
| 8 | +For details on using this integration, see its page on the [PowerSync documentation](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform/libraries/room). |
0 commit comments