Improve docs for raw tables (#666)

Author: simolus3

.changeset/bright-snakes-clean.md

@@ -7,31 +7,6 @@
 
 Add experimental support for raw tables, giving you full control over the table structure to sync into.
 While PowerSync manages tables as JSON views by default, raw tables have to be created by the application
-developer. Also, the upsert and delete statements for raw tables needs to be specified in the app schema:
+developer.
 
-```JavaScript
-const customSchema = new Schema({});
-customSchema.withRawTables({
-  lists: {
-    put: {
-      sql: 'INSERT OR REPLACE INTO lists (id, name) VALUES (?, ?)',
-      // put statements can use `Id` and extracted columns to bind parameters.
-      params: ['Id', { Column: 'name' }]
-    },
-    delete: {
-      sql: 'DELETE FROM lists WHERE id = ?',
-      // delete statements can only use the id (but a CTE querying existing rows by id could
-      // be used as a workaround).
-      params: ['Id']
-    }
-  }
-});
-
-const powersync = // open powersync database;
-await powersync.execute('CREATE TABLE lists (id TEXT NOT NULL PRIMARY KEY, name TEXT);');
-
-// Ready to sync into your custom table at this point
-```
-
-The main benefit of raw tables is better query performance (since SQLite doesn't have to
-extract rows from JSON) and more control (allowing the use of e.g. column and table constraints).
+For more information about raw tables, see [the documentation](https://docs.powersync.com/usage/use-case-examples/raw-tables).

packages/common/src/client/sync/stream/AbstractStreamingSyncImplementation.ts

@@ -623,6 +623,10 @@ The next upload iteration will be delayed.`);
   }
 
   private async legacyStreamingSyncIteration(signal: AbortSignal, resolvedOptions: RequiredPowerSyncConnectionOptions) {
+    if (resolvedOptions.serializedSchema?.raw_tables != null) {
+      this.logger.warn('Raw tables require the Rust-based sync client. The JS client will ignore them.');
+    }
+
     this.logger.debug('Streaming sync iteration started');
     this.options.adapter.startSession();
     let [req, bucketMap] = await this.collectLocalBucketState();

packages/common/src/db/schema/RawTable.ts

@@ -38,6 +38,10 @@ export type PendingStatement = {
  * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
  * using client-side table and column constraints.
  *
+ * To collect local writes to raw tables with PowerSync, custom triggers are required. See
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * using raw tables.
+ *
  * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
  *
  * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or