Correct usage of soft: true with disconnectAndClear

client-sdks/advanced/raw-tables.mdx

@@ -800,13 +800,16 @@ 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.
+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.
 
-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.
+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, `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.
 
 #### Triggering Resync on Migrations
 

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