Update Privileges required - Self-hosted / Custom roles Section

architecture/architecture-overview.mdx

@@ -4,7 +4,7 @@ description: "The core components of PowerSync are the service and client SDKs"
 ---
 
 <Frame>
-  <img src="/images/powersync-diagram-architecture-overview.png" />
+  <img src="/images/architecture/powersync-docs-diagram-architecture-overview.png" />
 </Frame>
 
 The [PowerSync Service](/architecture/powersync-service) and client SDK operate in unison to keep client-side SQLite databases in sync with a backend database. Learn about their architecture:

architecture/client-architecture.mdx

@@ -19,13 +19,13 @@ A developer configures [Sync Rules](/usage/sync-rules) for their PowerSync insta
 The PowerSync Service connects directly to the backend database and uses a change stream to hydrate dynamic data partitions, called [sync buckets](/usage/sync-rules/organize-data-into-buckets). Sync buckets are used to partition data according to the configured Sync Rules. (In most use cases, only a subset of data is required in a client's database and not a copy of the entire backend database.)
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-006 (2).png" />
+  <img src="/images/architecture/powersync-docs-diagram-client-architecture-001.png" />
 </Frame>
 
 The local SQLite database embedded in the PowerSync SDK is automatically kept in sync with the backend database, based on the [Sync Rules](/usage/sync-rules) configured by the developer:
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-007 (2).png" />
+  <img src="/images/architecture/powersync-docs-diagram-client-architecture-002.png" />
 </Frame>
 
 #### Writing Data
@@ -35,7 +35,7 @@ Client-side data modifications, namely updates, deletes and inserts, are persist
 Each entry in the queue is processed by writing the entry to your existing backend application API, using a function [defined by you](/installation/client-side-setup/integrating-with-your-backend) (the developer). This is to ensure that existing backend business logic is honored when uploading data changes. For more information, see the section on [integrating with your backend](/installation/client-side-setup/integrating-with-your-backend).
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-008 (3).png" />
+  <img src="/images/architecture/powersync-docs-diagram-client-architecture-003.png" />
 </Frame>
 
 ### Schema
@@ -67,5 +67,5 @@ Most rows will be present in at least two tables — the `ps_data__<table>` tabl
 The copy in `ps_oplog` may be newer than the one in `ps_data__<table>`. Only when a full checkpoint has been downloaded, will the data be copied over to the individual tables. If multiple rows with the same table and id has been synced, only one will be preserved (the one with the highest `op_id`).
 
 <Note>
-  If you run into limitations with the above JSON-based SQLite view system, check out [this experimental feature](/usage/use-case-examples/raw-tables) which allows you to define and manage raw SQLite tables to work around some limitations. We are actively seeking feedback about this functionality.
+  If you run into limitations with the above JSON-based SQLite view system, check out [the Raw Tables experimental feature](/usage/use-case-examples/raw-tables) which allows you to define and manage raw SQLite tables to work around some limitations. We are actively seeking feedback about this functionality.
 </Note>

architecture/powersync-protocol.mdx

@@ -67,4 +67,4 @@ Write checkpoints are used to ensure clients have synced their own changes back
 
 Creating a write checkpoint is a separate operation, which is performed by the client after all data has been uploaded. It is important that this happens after the data has been written to the backend source database.
 
-The server then keeps track of the current CDC stream position on the database (LSN in Postgres, resume token in MongoDB, or binlog position in MySQL), and notifies the client when the data has been replicated, as part of checkpoint data in the normal data stream.
+The server then keeps track of the current CDC stream position on the database (LSN in Postgres, resume token in MongoDB, or GTID + Binlog Position in MySQL), and notifies the client when the data has been replicated, as part of checkpoint data in the normal data stream.

client-sdk-references/dotnet.mdx

@@ -5,6 +5,7 @@
 ---
 
 import DotNetInstallation from '/snippets/dotnet/installation.mdx';
+import DotNetWatch from '/snippets/dotnet/basic-watch-query.mdx';
 
 <CardGroup>
   <Card title="PowerSync SDK on NuGet" icon="nuget" href="https://www.nuget.org/packages/PowerSync.Common/">
@@ -38,7 +39,7 @@
 * **WPF**: Windows desktop applications
 
 **Current Limitations**:
 * Blazor (web) platforms are not yet supported.
 
 For more details, please refer to the package [README](https://github.com/powersync-ja/powersync-dotnet/tree/main?tab=readme-ov-file).
 
@@ -154,7 +155,7 @@
 
 public class MyConnector : IPowerSyncBackendConnector
 {
     private readonly HttpClient _httpClient;
 
     // User credentials for the current session
     public string UserId { get; private set; }
@@ -276,21 +277,7 @@
 Console.WriteLine(await db.GetAll<ListResult>("SELECT * FROM lists;"));
 
 // Use db.Watch() to watch queries for changes (await is used to wait for initialization):
-await db.Watch("select * from lists", null, new WatchHandler<ListResult>
-{
-  OnResult = (results) =>
-  {
-      Console.WriteLine("Results: ");
-      foreach (var result in results)
-      {
-          Console.WriteLine(result.id + ":" + result.name);
-      }
-  },
-  OnError = (error) =>
-  {
-      Console.WriteLine("Error: " + error.Message);
-  }
-});
+<DotNetWatch />
 
 // And db.Execute for inserts, updates and deletes:
 await db.Execute(
@@ -323,3 +310,7 @@
     Logger = logger
 });
 ```
+
+## Supported Platforms
+
+See [Supported Platforms -> .NET SDK](/resources/supported-platforms#net-sdk).

client-sdk-references/flutter.mdx

@@ -6,6 +6,7 @@
 
 import SdkFeatures from '/snippets/sdk-features.mdx';
 import FlutterInstallation from '/snippets/flutter/installation.mdx';
+import FlutterWatch from '/snippets/flutter/basic-watch-query.mdx';
 
 <CardGroup>
   <Card title="PowerSync SDK on pub.dev" icon="cube" href="https://pub.dev/packages/powersync">
@@ -74,7 +75,7 @@
 Similar functionality exists in the [CLI](/usage/tools/cli).
 
 </Info>
 The types available are `text`, `integer` and `real`. These should map directly to the values produced by the [Sync Rules](/usage/sync-rules). If a value doesn't match, it is cast automatically. For details on how Postgres types are mapped to the types below, see the section on [Types](/usage/sync-rules/types) in the _Sync Rules_ documentation.
 
 **Example**:
 
@@ -327,36 +328,7 @@
 
 The [watch](https://pub.dev/documentation/powersync/latest/sqlite_async/SqliteQueries/watch.html) method executes a read query whenever a change to a dependent table is made.
 
-```dart lib/widgets/todos_widget.dart {13-17}
-import 'package:flutter/material.dart';
-import '../main.dart';
-import '../models/todolist.dart';
-
-// Example Todos widget
-class TodosWidget extends StatelessWidget {
-  const TodosWidget({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return StreamBuilder(
-      // You can watch any SQL query
-      stream: db
-          .watch('SELECT * FROM lists ORDER BY created_at, id')
-          .map((results) {
-        return results.map(TodoList.fromRow).toList(growable: false);
-      }),
-      builder: (context, snapshot) {
-        if (snapshot.hasData) {
-          // TODO: implement your own UI here based on the result set
-          return ...;
-        } else {
-        return const Center(child: CircularProgressIndicator());
-        }
-      },
-    );
-  }
-}
-```
+<FlutterWatch />
 
 ### Mutations (PowerSync.execute)
 
@@ -401,3 +373,7 @@
 ## Troubleshooting
 
 See [Troubleshooting](/resources/troubleshooting) for pointers to debug common issues.
+
+## Supported Platforms
+
+See [Supported Platforms -> Dart SDK](/resources/supported-platforms#dart-sdk).

client-sdk-references/flutter/usage-examples.mdx

@@ -3,6 +3,8 @@ title: "Usage Examples"
 description: "Code snippets and guidelines for common scenarios"
 ---
 
+import FlutterWatch from '/snippets/flutter/basic-watch-query.mdx';
+
 ## Using transactions to group changes
 
 Read and write transactions present a context where multiple changes can be made then finally committed to the DB or rolled back. This ensures that either all the changes get persisted, or no change is made to the DB (in the case of a rollback or exception).
@@ -26,20 +28,7 @@ Also see [readTransaction(callback)](https://pub.dev/documentation/powersync/lat
 
 Use [watch](https://pub.dev/documentation/powersync/latest/sqlite_async/SqliteQueries/watch.html) to watch for changes to the dependent tables of any SQL query.
 
-```dart
-StreamBuilder(
-  // You can watch any SQL query
-  stream: db.watch('SELECT * FROM customers order by id asc'),
-  builder: (context, snapshot) {
-    if (snapshot.hasData) {
-      // TODO: implement your own UI here based on the result set
-      return ...;
-    } else {
-      return const Center(child: CircularProgressIndicator());
-    }
-  },
-)
-```
+<FlutterWatch />
 
 ## Insert, update, and delete data in the local database
 

client-sdk-references/javascript-web.mdx

@@ -6,6 +6,8 @@ sidebarTitle: "Overview"
 
 import SdkFeatures from '/snippets/sdk-features.mdx';
 import JavaScriptWebInstallation from '/snippets/javascript-web/installation.mdx';
+import JavaScriptAsyncWatch from '/snippets/basic-watch-query-javascript-async.mdx';
+import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-callback.mdx';
 
 <CardGroup cols={2}>
   <Card title="PowerSync SDK on NPM" icon="npm" href="https://www.npmjs.com/package/@powersync/web">
@@ -219,21 +221,16 @@ export const getLists = async () => {
 
 The [watch](https://powersync-ja.github.io/powersync-js/web-sdk/classes/PowerSyncDatabase#watch) method executes a read query whenever a change to a dependent table is made.
 
-```js
-// Watch changes to lists
-const abortController = new AbortController();
-
-export const function watchLists = (onUpdate) => {
-  for await (const update of PowerSync.watch(
-    'SELECT * from lists',
-    [],
-    { signal: abortController.signal }
-  )
-  ) {
-    onUpdate(update);
-  }
-}
-```
+<Tabs>
+  <Tab title="AsyncIterator approach">
+  <JavaScriptAsyncWatch />
+  </Tab>
+  <Tab title="Callback approach">
+  <JavaScriptCallbackWatch />
+  </Tab>
+</Tabs>
+
+For advanced watch query features like incremental updates and differential results, see [Live Queries / Watch Queries](/usage/use-case-examples/watch-queries).
 
 ### Mutations (PowerSync.execute, PowerSync.writeTransaction)
 
@@ -406,4 +403,8 @@ See [JavaScript ORM Support](/client-sdk-references/javascript-web/javascript-or
 
 ## Troubleshooting
 
-See [Troubleshooting](/resources/troubleshooting) for pointers to debug common issues.
+See [Troubleshooting](/resources/troubleshooting) for pointers to debug common issues.
+
+## Supported Platforms
+
+See [Supported Platforms -> JS/Web SDK](/resources/supported-platforms#js%2Fweb-sdk).

client-sdk-references/javascript-web/javascript-spa-frameworks.mdx

@@ -37,6 +37,10 @@ The main hooks available are:
 
 * `useSuspenseQuery`: This hook also allows you to access the results of a watched query, but its loading and fetching states are handled through [Suspense](https://react.dev/reference/react/Suspense). It automatically converts certain loading/fetching states into Suspense signals, triggering Suspense boundaries in parent components.
 
+<Info>
+For advanced watch query features like incremental updates and differential results for React Hooks, see [Live Queries / Watch Queries](/usage/use-case-examples/watch-queries).
+</Info>
+
 The full API Reference and example code can be found here:
 
 <Card title="React hooks for PowerSync | PowerSync JavaScript SDK Docs" icon="book" href="https://powersync-ja.github.io/powersync-js/react-sdk" horizontal />
@@ -93,6 +97,10 @@ The main hooks available are:
 
 * `useStatus`: Access the PowerSync connectivity status. This can be used to update the UI based on whether the client is connected or not.
 
+<Info>
+For advanced watch query features like incremental updates and differential results for Vue Hooks, see [Live Queries / Watch Queries](/usage/use-case-examples/watch-queries).
+</Info>
+
 The full API Reference and example code can be found here:
 
 <Card title="Vue composables for PowerSync | PowerSync JavaScript SDK Docs" icon="book" href="https://powersync-ja.github.io/powersync-js/vue-sdk" horizontal />

client-sdk-references/javascript-web/usage-examples.mdx

@@ -3,6 +3,9 @@ title: "Usage Examples"
 description: "Code snippets and guidelines for common scenarios"
 ---
 
+import JavaScriptAsyncWatch from '/snippets/basic-watch-query-javascript-async.mdx';
+import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-callback.mdx';
+
 ## Multiple Tab Support
 
 <Warning>
@@ -108,34 +111,16 @@ Also see [PowerSyncDatabase.readTransaction(callback)](https://powersync-ja.gith
 
 Use [PowerSyncDatabase.watch](https://powersync-ja.github.io/powersync-js/web-sdk/classes/PowerSyncDatabase#watch) to watch for changes in source tables.
 
-The `watch` method can be used with a `AsyncIterable` signature as follows:
-
-```js
-async *attachmentIds(): AsyncIterable<string[]> {
-  for await (const result of this.powersync.watch(
-    `SELECT photo_id as id FROM ${TODO_TABLE} WHERE photo_id IS NOT NULL`,
-    []
-  )) {
-    yield result.rows?._array.map((r) => r.id) ?? [];
-  }
-}
-```
-
-As of version **1.3.3** of the SDK, the `watch` method can also be used with a callback:
+<Tabs>
+  <Tab title="AsyncIterator approach">
+  <JavaScriptAsyncWatch />
+  </Tab>
+  <Tab title="Callback approach">
+  <JavaScriptCallbackWatch />
+  </Tab>
+</Tabs>
 
-```js
-attachmentIds(onResult: (ids: string[]) => void): void {
-  this.powersync.watch(
-    `SELECT photo_id as id FROM ${TODO_TABLE} WHERE photo_id IS NOT NULL`,
-    [],
-    {
-      onResult: (result) => {
-        onResult(result.rows?._array.map((r) => r.id) ?? []);
-      }
-    }
-  );
-}
-```
+For advanced watch query features like incremental updates and differential results, see [Live Queries / Watch Queries](/usage/use-case-examples/watch-queries).
 
 ## Insert, update, and delete data in the local database
 

client-sdk-references/kotlin-multiplatform.mdx

@@ -5,6 +5,7 @@
 
 import SdkFeatures from '/snippets/sdk-features.mdx';
 import KotlinMultiplatformInstallation from '/snippets/kotlin-multiplatform/installation.mdx';
+import KotlinWatch from '/snippets/kotlin-multiplatform/basic-watch-query.mdx';
 
 <CardGroup>
   <Card title="PowerSync SDK on Maven Central" icon="npm" href="https://central.sonatype.com/artifact/com.powersync/core">
@@ -242,21 +243,7 @@
 
 The `watch` method executes a read query whenever a change to a dependent table is made.
 
-```kotlin
-// You can watch any SQL query
-fun watchCustomers(): Flow<List<User>> {
-    // TODO: implement your UI based on the result set
-    return database.watch(
-                "SELECT * FROM customers"
-            ) { cursor ->
-                User(
-                    id = cursor.getString("id"),
-                    name = cursor.getString("name"),
-                    email = cursor.getString("email")
-                )
-            }
-}
-```
+<KotlinWatch />
 
 ### Mutations (PowerSync.execute)
 
@@ -351,45 +338,22 @@
    - Most upcoming features will not be ported to this implementation, and we intend to remove it eventually.
 2. **Rust (currently experimental)**
    - This is a newer implementation, mostly implemented in Rust but still using Kotlin for networking.
    - Apart from newer features, this implementation is also more performant.
    - We [encourage interested users to try it out](https://releases.powersync.com/announcements/improved-sync-performance-in-our-client-sdks)
      and report feedback, as we intend to make it the default after a stabilization period.
 
 To enable the Rust client, pass `SyncOptions(newClientImplementation = true)` as a second parameter when
 [connecting](https://powersync-ja.github.io/powersync-kotlin/core/com.powersync/-power-sync-database/connect.html).
 
-### Connection Methods
-
-This SDK supports two methods for streaming sync commands:
-
-1. **WebSocket (currently experimental)**
-   - The implementation leverages RSocket for handling reactive socket streams.
-   - Back-pressure is effectively managed through client-controlled command requests.
-   - Sync commands are transmitted efficiently as BSON (binary) documents.
-   - Enabling websocket support requires the new client implementation.
-2. **HTTP Streaming (default)**
-   - This is the original implementation method.
-   - This method sends data as text (JSON) instead of BSON.
-
-By default, the `PowerSyncDatabase.connect()` method uses HTTP streams.
-You can optionally specify the `connectionMethod` to override this:
-
-```Kotlin
-// HTTP streaming (default)
-powerSync.connect(connector)
-
-// WebSockets (experimental)
-powerSync.connect(connector, SyncOptions(
-    newClientImplementation = true,
-    method = ConnectionMethod.WebSocket(),
-))
-```
-
 ## ORM Support
 
 ORM support is not yet available, we are still investigating options to integrate the SDK with Room and SQLDelight.
 Please [let us know](/resources/contact-us) what your needs around ORMs are.
 
 ## Troubleshooting
 
 See [Troubleshooting](/resources/troubleshooting) for pointers to debug common issues.
+
+## Supported Platforms
+
+See [Supported Platforms -> Kotlin SDK](/resources/supported-platforms#kotlin-sdk).