From 15096131f81c742a3c5eb825ca855765ebd33ab0 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 17 Sep 2026 13:55:32 +0200 Subject: [PATCH 1/4] Correct usage of soft: true with disconnectAndClear --- client-sdks/advanced/raw-tables.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/client-sdks/advanced/raw-tables.mdx b/client-sdks/advanced/raw-tables.mdx index de17713b..c4f8edcd 100644 --- a/client-sdks/advanced/raw-tables.mdx +++ b/client-sdks/advanced/raw-tables.mdx @@ -800,13 +800,15 @@ tables. #### Deleting Data on Migrations -One option that makes migrations safe (with obvious downsides) is to simply reset the database before -migrating: `await db.disconnectAndClear(soft: true)` deletes materialized sync rows while keeping -downloaded data active. Afterwards, migrations can migrate the schema in any way before you reconnect. - -In a soft clear, data doesn't have to be downloaded again in most cases. This might reduce the downtime -in which no data is available, but a network connection is necessary for data to become -available again. +One option that makes migrations safe (with obvious downsides) is to reset the database before migrating: +`await db.disconnectAndClear()` deletes all synced rows. Afterwards, migrations can change the schema in +any way before you reconnect. The downside is that no synced data is available until the next sync +completes, which requires a network connection. + +In the Kotlin and Swift SDKs, you can pass `soft = true` (Kotlin) or `soft: true` +(Swift) to `disconnectAndClear()`. A soft clear deletes the visible rows but keeps PowerSync's internal copy +of the synced data. When you reconnect as the same user, the next sync reuses that copy, so data doesn't +have to be downloaded again in most cases. This reduces the downtime in which no data is available. #### Triggering Resync on Migrations From 187f902d3c96db127a665ec225cdfeb099321b91 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 17 Sep 2026 14:19:58 +0200 Subject: [PATCH 2/4] With Codex review --- client-sdks/advanced/raw-tables.mdx | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/client-sdks/advanced/raw-tables.mdx b/client-sdks/advanced/raw-tables.mdx index c4f8edcd..0e4c716a 100644 --- a/client-sdks/advanced/raw-tables.mdx +++ b/client-sdks/advanced/raw-tables.mdx @@ -800,15 +800,17 @@ tables. #### Deleting Data on Migrations -One option that makes migrations safe (with obvious downsides) is to reset the database before migrating: -`await db.disconnectAndClear()` deletes all synced rows. Afterwards, migrations can change the schema in -any way before you reconnect. The downside is that no synced data is available until the next sync -completes, which requires a network connection. - -In the Kotlin and Swift SDKs, you can pass `soft = true` (Kotlin) or `soft: true` -(Swift) to `disconnectAndClear()`. A soft clear deletes the visible rows but keeps PowerSync's internal copy -of the synced data. When you reconnect as the same user, the next sync reuses that copy, so data doesn't -have to be downloaded again in most cases. This reduces the downtime in which no data is available. +One migration approach is to clear synced data before changing the schema. First, configure a `clear` +statement for each raw table to delete its rows, since `disconnectAndClear()` does not clear raw tables +automatically. Then call `await db.disconnectAndClear()`, migrate the schema, and reconnect. + +By default, clearing the database also removes PowerSync's internal copy of the synced data. The next +sync must download that data again, leaving synced data unavailable until the sync completes. + +To reduce this downtime, the Kotlin and Swift SDKs support a soft clear: pass `soft = true` (Kotlin) or +`soft: true` (Swift) to `disconnectAndClear()`. A soft clear runs the same raw-table `clear` statements +but keeps PowerSync's internal copy of the synced data. When you reconnect as the same user, the next +sync reuses that copy, so data doesn't have to be downloaded again in most cases. #### Triggering Resync on Migrations From d0be47374d5c797d1269c1403fcdc96bbd5b2dd9 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Fri, 18 Sep 2026 09:59:24 +0200 Subject: [PATCH 3/4] Document soft parameter more generally --- client-sdks/advanced/raw-tables.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/client-sdks/advanced/raw-tables.mdx b/client-sdks/advanced/raw-tables.mdx index 0e4c716a..fbdb275e 100644 --- a/client-sdks/advanced/raw-tables.mdx +++ b/client-sdks/advanced/raw-tables.mdx @@ -807,8 +807,7 @@ automatically. Then call `await db.disconnectAndClear()`, migrate the schema, an By default, clearing the database also removes PowerSync's internal copy of the synced data. The next sync must download that data again, leaving synced data unavailable until the sync completes. -To reduce this downtime, the Kotlin and Swift SDKs support a soft clear: pass `soft = true` (Kotlin) or -`soft: true` (Swift) to `disconnectAndClear()`. A soft clear runs the same raw-table `clear` statements +To reduce this downtime, `disconnectAndClear()` supports a `soft` parameter which runs the same raw-table `clear` statements but keeps PowerSync's internal copy of the synced data. When you reconnect as the same user, the next sync reuses that copy, so data doesn't have to be downloaded again in most cases. From c8fbed2c7430c4a6726d5e06965ea1662137686a Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Fri, 18 Sep 2026 10:12:30 +0200 Subject: [PATCH 4/4] Mention soft clears on the reducing usage page --- resources/usage-and-billing/reducing-usage.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/resources/usage-and-billing/reducing-usage.mdx b/resources/usage-and-billing/reducing-usage.mdx index a8a8cc7f..ab3291db 100644 --- a/resources/usage-and-billing/reducing-usage.mdx +++ b/resources/usage-and-billing/reducing-usage.mdx @@ -37,11 +37,15 @@ Large data synced totals often come from devices downloading the same data repea A client that loses its local database must download all its subscribed data from scratch. This is expected after a fresh installation. If the same device repeatedly starts from scratch, check for these causes: -- The app calls `disconnectAndClear()` when a user signs out. This clears the local database, so the next session starts from nothing. Clearing is appropriate when another user can access the device or your security requirements prohibit keeping the data. If the same user will return and keeping their data is safe, `disconnect()` closes the sync connection without clearing the database. +- The app calls `disconnectAndClear()` when a user signs out. By default, this removes both the visible synced rows and PowerSync's internal copy of the synced data, so the next session starts with a full download. - The browser clears or cannot retain the web client's storage. Private browsing modes and browser storage policies can cause the app to lose its database between sessions. - App code deletes or recreates the database file as part of its own lifecycle. -Do not retain one user's local data for another user to avoid an initial sync. Investigate why the database is being cleared, but preserve the security boundary your app requires. +If the same user will sign back in, choose how to handle sign-out based on which data is allowed to remain on the device: + +- If the data can stay available to the app, call `disconnect()` instead. This closes the sync connection without clearing the database. +- If the app must not show the data but a copy may remain in PowerSync's internal tables, call `disconnectAndClear()` with `soft` set to `true`. A soft clear deletes the visible synced rows but keeps the internal copy, so the next sync can reuse it instead of downloading the data again in most cases. +- If no synced data may remain on the device, keep the default `disconnectAndClear()` behavior. ### Avoiding Reconnect Loops