Multiple tab support is not currently available on Android.
For Safari, use the OPFSCoopSyncVFS virtual file system to ensure stable multi-tab functionality.
Using PowerSync between multiple tabs is supported on some web browsers. Multiple tab support relies on shared web workers for database and sync streaming operations. When enabled, shared web workers named shared-DB-worker-[dbFileName] and shared-sync-[dbFileName] will be created.
The shared sync worker connects directly to the PowerSync backend instance and applies changes to the database. Note that the shared sync worker will call the fetchCredentials and uploadData method of the latest opened available tab. Closing a tab will shift the latest tab to the previously opened one.Currently, using the SDK in multiple tabs without enabling the enableMultiTabs flag will spawn a standard web worker per tab for DB operations. These workers are safe to operate on the DB concurrently, however changes from one tab may not update watches on other tabs. Only one tab can sync from the PowerSync instance at a time. The sync status will not be shared between tabs, only the oldest tab will connect and display the latest sync status.Support is enabled by default if available. This can be disabled as below:
Copy
export const db = new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: 'my_app_db.sqlite' }, flags: { /** * Multiple tab support is enabled by default if available. * This can be disabled by setting this flag to false. */ enableMultiTabs: false }});
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).PowerSyncDatabase.writeTransaction(callback) automatically commits changes after the transaction callback is completed if tx.rollback() has not explicitly been called. If an exception is thrown in the callback then changes are automatically rolled back.
Copy
// ListsWidget.jsximport React, { useState } from 'react';export const ListsWidget = () => { const [lists, setLists] = useState([]); return ( <div> <ul> {lists.map((list) => ( <li key={list.id}> {list.name} <button onClick={async () => { try { await PowerSync.writeTransaction(async (tx) => { // Delete the main list await tx.execute(`DELETE FROM lists WHERE id = ?`, [item.id]); // Delete any children of the list await tx.execute(`DELETE FROM todos WHERE list_id = ?`, [item.id]); // Transactions are automatically committed at the end of execution // Transactions are automatically rolled back if an exception occurred }) // Watched queries should automatically reload after mutation } catch (ex) { Alert.alert('Error', ex.message) } }} > Delete </button> </li> ))} </ul> <button onClick={async () => { try { await PowerSync.execute('INSERT INTO lists (id, created_at, name, owner_id) VALUES (uuid(), datetime(), ?, ?) RETURNING *', [ 'A list name', "[The user's uuid]" ]) // Watched queries should automatically reload after mutation } catch (ex) { Alert.alert('Error', ex.message) } }} > Create List </button> </div> );};
async function* pendingLists(): AsyncIterable<string[]> { for await (const result of db.watch( `SELECT * FROM lists WHERE state = ?`, ['pending'] )) { yield result.rows?._array ?? []; }}
For advanced watch query features like incremental updates and differential results, see Live Queries / Watch Queries.
Send changes in local data to your backend service
Override uploadData to send local updates to your backend service.
Copy
// Implement the uploadData method in your backend connectorasync function uploadData(database) { const batch = await database.getCrudBatch(); if (batch === null) return; for (const op of batch.crud) { switch (op.op) { case 'put': // Send the data to your backend service // replace `_myApi` with your own API client or service await _myApi.put(op.table, op.opData); break; default: // TODO: implement the other operations (patch, delete) break; } } await batch.complete();}
// Example of using connected status to show online or offline// Tap into connectedconst [connected, setConnected] = React.useState(powersync.connected);React.useEffect(() => {// Register listener for changes made to the powersync status return powersync.registerListener({ statusChanged: (status) => { setConnected(status.connected); } });}, [powersync]);// Icon to show connected or not connected to powersync// as well as the last synced time<Icon name={connected ? 'wifi' : 'wifi-off'} type="material-community" color="black" size={20} style={{ padding: 5 }} onPress={() => { Alert.alert( 'Status', `${connected ? 'Connected' : 'Disconnected'}. \nLast Synced at ${powersync.currentStatus?.lastSyncedAt.toISOString() ?? '-' }\nVersion: ${powersync.sdkVersion}` ); }}/>;
Use the hasSynced property (available since version 0.4.1 of the SDK) and register an event listener with PowerSyncDatabase.registerListener to indicate to the user whether the initial sync is in progress.
Copy
// Example of using hasSynced to show whether the first sync has completed// Tap into hasSyncedconst [hasSynced, setHasSynced] = React.useState(powerSync.currentStatus?.hasSynced || false); React.useEffect(() => { // Register listener for changes made to the powersync status return powerSync.registerListener({ statusChanged: (status) => { setHasSynced(!!status.hasSynced); } }); }, [powerSync]);return <div>{hasSynced ? 'Initial sync completed!' : 'Busy with initial sync...'}</div>;
For async use cases, see PowerSyncDatabase.waitForFirstSync(), which returns a promise that resolves once the first full sync has completed (it queries the internal SQL ps_buckets table to determine if data has been synced).
You can show users a progress bar when data downloads using the downloadProgress property from the
SyncStatus class. This is especially useful for long-running initial syncs. downloadProgress.downloadedFraction gives you a value from 0.0 to 1.0 representing the total sync progress.Example (React, using MUI components):
This guide provides an overview of the customizable flags available for the PowerSyncDatabase in the JavaScript Web SDK. These flags allow you to enable or disable specific features to suit your application’s requirements.
You can configure flags during the initialization of the PowerSyncDatabase. Flags can be set using the flags property, which allows you to enable or disable specific functionalities.
Copy
import { PowerSyncDatabase, resolveWebPowerSyncFlags, WebPowerSyncFlags } from '@powersync/web';import { AppSchema } from '@/library/powersync/AppSchema';// Define custom flagsconst customFlags: WebPowerSyncFlags = resolveWebPowerSyncFlags({ enableMultiTabs: true, broadcastLogs: true, disableSSRWarning: false, ssrMode: false, useWebWorker: true,});// Create the PowerSync database instanceexport const db = new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: 'example.db', }, flags: customFlags,});
default: trueEnables support for multiple tabs using shared web workers. When enabled, multiple tabs can interact with the same database and sync data seamlessly.
