Usage Examples - PowerSync

Multiple Tab Support

Multiple tab support is not currently available on Android or Safari.

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.

`shared-DB-worker-[dbFileName]`

The shared database worker will ensure writes to the database will instantly be available between tabs.

`shared-sync-[dbFileName]`

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:

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
  }
});

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).

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.

// ListsWidget.jsx
import 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>
  );
};

Also see PowerSyncDatabase.readTransaction(callback).

Use PowerSyncDatabase.watch to watch for changes in source tables.

The watch method can be used with a AsyncIterable signature as follows:

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:

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) ?? []);
      }
    }
  );
}

Insert, update, and delete data in the local database

Use PowerSyncDatabase.execute to run INSERT, UPDATE or DELETE queries.

const handleButtonClick = async () => {
  await db.execute(
    'INSERT INTO customers(id, name, email) VALUES(uuid(), ?, ?)',
    ['Fred', 'fred@example.org']
  );
};

return (
  <button onClick={handleButtonClick} title="+">
    <span>+</span>
    <i className="material-icons">add</i>
  </button>
);

Send changes in local data to your backend service

Override uploadData to send local updates to your backend service.

// Implement the uploadData method in your backend connector
async 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();
}

Accessing PowerSync connection status information

Use PowerSyncDatabase.connected and register an event listener with PowerSyncDatabase.registerListener to listen for status changes to your PowerSync instance.

// Example of using connected status to show online or offline

// Tap into connected
const [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}`
    );
  }}
/>;

Wait for the initial sync to complete

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.

// Example of using hasSynced to show whether the first sync has completed

// Tap into hasSynced
const [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).

Using logging to troubleshoot issues

You can enable logging to see what’s happening under the hood or to debug connection/authentication/sync issues. This SDK uses js-logger.

Enable JS Logger with your logging interface of choice or use the default console.

import Logger from 'js-logger';

// Log messages will be written to the window's console.
Logger.useDefaults();

Logger.setLevel(Logger.DEBUG);

Enable verbose output in the developer tools for detailed logs.

The WASQLiteDBAdapter opens SQLite connections inside a shared web worker. This worker can be inspected in Chrome by accessing:

chrome://inspect/#workers

Using PowerSyncDatabase Flags

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.

Configuring Flags

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.

import { PowerSyncDatabase, resolveWebPowerSyncFlags, WebPowerSyncFlags } from '@powersync/web';
import { AppSchema } from '@/library/powersync/AppSchema';

// Define custom flags
const customFlags: WebPowerSyncFlags = resolveWebPowerSyncFlags({
  enableMultiTabs: true,
  broadcastLogs: true,
  disableSSRWarning: false,
  ssrMode: false,
  useWebWorker: true,
});

// Create the PowerSync database instance
export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'example.db',
  },
  flags: customFlags,
});

Available Flags

enableMultiTabs

default: true

Enables support for multiple tabs using shared web workers. When enabled, multiple tabs can interact with the same database and sync data seamlessly.

broadcastLogs

default: false

Enables the broadcasting of logs for debugging purposes. This flag helps monitor shared worker logs in a multi-tab environment.

disableSSRWarning

default: false

Disables warnings when running in SSR (Server-Side Rendering) mode.

ssrMode

default: false

Enables SSR mode. In this mode, only empty query results will be returned, and syncing with the backend is disabled.

useWebWorker

default: true

Enables the use of web workers for database operations. Disabling this flag also disables multi-tab support.

Flag Behavior

Example 1: Multi-Tab Support

By default, multi-tab support is enabled if supported by the browser. To explicitly disable this feature:

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'my_app_db.sqlite',
  },
  flags: {
    enableMultiTabs: false,
  },
});

When disabled, each tab will use independent workers, and changes in one tab will not automatically propagate to others.

Example 2: SSR Mode

To enable SSR mode and suppress warnings:

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'my_app_db.sqlite',
  },
  flags: {
    ssrMode: true,
    disableSSRWarning: true,
  },
});

Example 3: Verbose Debugging with Broadcast Logs

To enable detailed logging for debugging:

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'my_app_db.sqlite',
  },
  flags: {
    broadcastLogs: true,
  },
});

Logs will include detailed insights into database operations and synchronization.

Recommendations

Set enableMultiTabs to true if your application requires seamless data sharing across multiple tabs.
Set useWebWorker to true for efficient database operations using web workers.
Set broadcastLogs to true during development to troubleshoot and monitor database and sync operations.
Set disableSSRWarning to true when running in SSR mode to avoid unnecessary console warnings.
Test combinations of flags to validate their behavior in your application’s specific use case.

Client SDKs

​Multiple Tab Support

​shared-DB-worker-[dbFileName]

​shared-sync-[dbFileName]

​Using transactions to group changes

​Subscribe to changes in data

​Insert, update, and delete data in the local database

​Send changes in local data to your backend service

​Accessing PowerSync connection status information

​Wait for the initial sync to complete

​Using logging to troubleshoot issues

​Using PowerSyncDatabase Flags

​Configuring Flags

​Available Flags

​Flag Behavior

​Example 1: Multi-Tab Support

​Example 2: SSR Mode

​Example 3: Verbose Debugging with Broadcast Logs

​Recommendations

Multiple Tab Support

`shared-DB-worker-[dbFileName]`

`shared-sync-[dbFileName]`

Using transactions to group changes

Subscribe to changes in data

Insert, update, and delete data in the local database

Send changes in local data to your backend service

Accessing PowerSync connection status information

Wait for the initial sync to complete

Using logging to troubleshoot issues

Using PowerSyncDatabase Flags

Configuring Flags

Available Flags

Flag Behavior

Example 1: Multi-Tab Support

Example 2: SSR Mode

Example 3: Verbose Debugging with Broadcast Logs

Recommendations