docs

Author: samwillis

docs/docs/sync.md

@@ -34,7 +34,11 @@ await pg.exec(`
 `)
 ```
 
-You can then use the `syncShapeToTable` method to sync a table from Electric:
+You can sync data from Electric using either the single table or multi-table API.
+
+### Single Table Sync
+
+Use the `syncShapeToTable` method to sync a single table from Electric:
 
 ```ts
 const shape = await pg.electric.syncShapeToTable({
@@ -46,13 +50,47 @@ const shape = await pg.electric.syncShapeToTable({
   },
   table: 'todo',
   primaryKey: ['id'],
+  shapeKey: 'todo', // or null if the shape state does not need to be persisted
 })
+
+// Stop syncing when done
+shape.unsubscribe()
 ```
 
-To stop syncing you can call `unsubscribe` on the shape:
+### Multi-Table Sync
+
+The multi-table API ensures transactional consistency across tables by syncing updates that happened in a single transaction in Postgres within a single transaction in PGLite.
+
+Use the `syncShapesToTables` method to sync multiple tables simultaneously:
 
 ```ts
-shape.unsubscribe()
+const sync = await pg.electric.syncShapesToTables({
+  shapes: {
+    todos: {
+      shape: { 
+        url: 'http://localhost:3000/v1/shape',
+        params: { table: 'todo' }
+      },
+      table: 'todo',
+      primaryKey: ['id'],
+    },
+    users: {
+      shape: { 
+        url: 'http://localhost:3000/v1/shape',
+        params: { table: 'users' }
+      },
+      table: 'users',
+      primaryKey: ['id'],
+    }
+  },
+  key: 'my-sync', // or null if the sync state does not need to be persisted
+  onInitialSync: () => {
+    console.log('Initial sync complete')
+  }
+})
+
+// Stop syncing when done
+sync.unsubscribe()
 ```
 
 There is a full example you can run locally in the [GitHub repository](https://github.com/electric-sql/pglite/tree/main/packages/pglite-sync/example).
@@ -94,18 +132,6 @@ It takes the following options as an object:
 - `useCopy: boolean`<br>
   Whether to use the `COPY FROM` command to insert the initial data, defaults to `false`. This process may be faster than inserting row by row as it combines the inserts into a CSV to be passed to Postgres.
 
-- `commitGranularity: CommitGranularity`<br>
-  The granularity of the commit operation, defaults to `"up-to-date"`. Note that a commit will always be performed immediately on the `up-to-date` message.
-  Options:
-
-  - `"up-to-date"`: Commit all messages when the `up-to-date` message is received.
-  <!-- - `"transaction"`: Commit all messages within transactions as they were applied to the source Postgres. -->
-  - `"operation"`: Commit each message in its own transaction.
-  - `number`: Commit every N messages.
-
-- `commitThrottle: number`<br>
-  The number of milliseconds to wait between commits, defaults to `0`.
-
 - `onInitialSync: () => void`<br>
   A callback that is called when the initial sync is complete.
 
@@ -126,6 +152,38 @@ The returned `shape` object from the `syncShapeToTable` call has the following m
 - `stream: ShapeStream`<br>
   The underlying `ShapeStream` instance, see the [ShapeStream API](https://electric-sql.com/docs/api/clients/typescript#shapestream) for more details.
 
+## syncShapesToTables API
+
+The `syncShapesToTables` API allows syncing multiple shapes into multiple tables simultaneously while maintaining transactional consistency. It takes the following options:
+
+- `shapes: Record<string, ShapeOptions>`<br>
+  An object mapping shape names to their configuration options. Each shape configuration includes:
+  - `shape: ShapeStreamOptions` - The shape stream specification
+  - `table: string` - The target table name
+  - `schema?: string` - Optional schema name (defaults to "public")
+  - `mapColumns?: MapColumns` - Optional column mapping
+  - `primaryKey: string[]` - Array of primary key columns
+
+- `key: string | null`<br>
+  Identifier for the multi-shape subscription. If provided, sync state will be persisted to allow resuming between sessions.
+
+- `useCopy?: boolean`<br>
+  Whether to use `COPY FROM` for faster initial data loading (defaults to false).
+
+- `onInitialSync?: () => void`<br>
+  Optional callback that fires when initial sync is complete for all shapes.
+
+The returned sync object provides:
+
+- `isUpToDate: boolean`<br>
+  Whether all shapes have caught up to the main Postgres.
+
+- `streams: Record<string, ShapeStream>`<br>
+  Access to individual shape streams by their names.
+
+- `unsubscribe()`<br>
+  Stop syncing all shapes.
+
 ## Limitations
 
 - It is currently not possible to sync multiple shapes into the same table, as shape subscriptions require being able to drop all data and start over. We are working on a fix for this case, but the current version will throw if a shape is synced into the same table more than once.

packages/pglite-sync/README.md

@@ -28,12 +28,47 @@ await pg.exec(`
 `)
 ```
 
-You can then use the syncShapeToTable method to sync a table from Electric:
+You can sync data from Electric using either the single table or multi-table API:
+
+### Single Table Sync
+
+Use `syncShapeToTable` to sync a single table:
 
 ```ts
 const shape = await pg.electric.syncShapeToTable({
   shape: { url: 'http://localhost:3000/v1/shape', table: 'todo' },
+  shapeKey: 'todo', // or null if the shape state does not need to be persisted
   table: 'todo',
   primaryKey: ['id'],
 })
 ```
+
+### Multi-Table Sync
+
+The multi-table API is useful when you need to sync related tables together, ensuring consistency across multiple tables by syncing updates that happened in as single transaction in Postgres within a single transaction in PGLite.
+
+Use `syncShapesToTables` to sync multiple tables simultaneously:
+
+```ts
+const sync = await pg.electric.syncShapesToTables({
+  shapes: {
+    todos: {
+      shape: { url: 'http://localhost:3000/v1/shape', table: 'todo' },
+      table: 'todo',
+      primaryKey: ['id'],
+    },
+    users: {
+      shape: { url: 'http://localhost:3000/v1/shape', table: 'users' },
+      table: 'users',
+      primaryKey: ['id'],
+    }
+  },
+  key: 'my-sync', // or null if the sync state does not need to be persisted
+  onInitialSync: () => {
+    console.log('Initial sync complete')
+  }
+})
+
+// Unsubscribe when done
+sync.unsubscribe()
+```