Skip to content

Improve docs for raw tables #666

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 16, 2025
Merged

Improve docs for raw tables #666

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0441cc2
Improve docs for raw tables
simolus3 Jul 15, 2025
92f8c5b
Simplify condition
simolus3 Jul 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 2 additions & 27 deletions .changeset/bright-snakes-clean.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
4 changes: 4 additions & 0 deletions packages/common/src/client/sync/stream/AbstractStreamingSyncImplementation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
4 changes: 4 additions & 0 deletions packages/common/src/db/schema/RawTable.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down