feat: OPFS Multiple Tab Trigger Invocation (#804)

Co-authored-by: Simon Binder <simon@journeyapps.com>

Author: stevensJourney

.changeset/mighty-keys-compete.md

@@ -0,0 +1,6 @@
+---
+'@powersync/common': minor
+'@powersync/web': minor
+---
+
+Add support for storage-backed (non-TEMP) SQLite triggers and tables for managed triggers. These resources persist on disk while in use and are automatically cleaned up when no longer claimed or needed. They should not be considered permanent triggers; PowerSync manages their lifecycle.

.changeset/shaggy-donuts-boil.md

@@ -0,0 +1,5 @@
+---
+'@powersync/web': minor
+---
+
+Managed triggers now use storage-backed (non-TEMP) SQLite triggers and tables when OPFS is the VFS. Resources persist across tabs and connection cycles to detect cross‑tab changes, and are automatically cleaned up when no longer in use. These should not be treated as permanent triggers; their lifecycle is managed by PowerSync.

demos/react-supabase-todolist-tanstackdb/src/components/providers/SystemProvider.tsx

@@ -4,7 +4,7 @@ import { SupabaseConnector } from '@/library/powersync/SupabaseConnector';
 import { TodosDeserializationSchema, TodosSchema } from '@/library/powersync/TodosSchema';
 import { CircularProgress } from '@mui/material';
 import { PowerSyncContext } from '@powersync/react';
-import { LogLevel, PowerSyncDatabase, createBaseLogger } from '@powersync/web';
+import { createBaseLogger, LogLevel, PowerSyncDatabase, WASQLiteOpenFactory, WASQLiteVFS } from '@powersync/web';
 import { createCollection } from '@tanstack/db';
 import { powerSyncCollectionOptions } from '@tanstack/powersync-db-collection';
 import React, { Suspense } from 'react';
@@ -15,9 +15,10 @@ export const useSupabase = () => React.useContext(SupabaseContext);
 
 export const db = new PowerSyncDatabase({
   schema: AppSchema,
-  database: {
-    dbFilename: 'example.db'
-  }
+  database: new WASQLiteOpenFactory({
+    dbFilename: 'example.db',
+    vfs: WASQLiteVFS.OPFSCoopSyncVFS
+  })
 });
 
 export const listsCollection = createCollection(

packages/capacitor/src/PowerSyncDatabase.ts

@@ -1,9 +1,11 @@
 import { Capacitor } from '@capacitor/core';
 import {
   DBAdapter,
+  MEMORY_TRIGGER_CLAIM_MANAGER,
   PowerSyncBackendConnector,
   RequiredAdditionalConnectionOptions,
   StreamingSyncImplementation,
+  TriggerManagerConfig,
   PowerSyncDatabase as WebPowerSyncDatabase,
   WebPowerSyncDatabaseOptionsWithSettings,
   WebRemote
@@ -44,6 +46,18 @@ export class PowerSyncDatabase extends WebPowerSyncDatabase {
     }
   }
 
+  protected generateTriggerManagerConfig(): TriggerManagerConfig {
+    const config = super.generateTriggerManagerConfig();
+    if (this.isNativeCapacitorPlatform) {
+      /**
+       * We usually only ever have a single tab for capacitor.
+       * Avoiding navigator locks allows insecure contexts (during development).
+       */
+      config.claimManager = MEMORY_TRIGGER_CLAIM_MANAGER;
+    }
+    return config;
+  }
+
   protected runExclusive<T>(cb: () => Promise<T>): Promise<T> {
     if (this.isNativeCapacitorPlatform) {
       // Use mutex for mobile platforms.

packages/common/src/client/AbstractPowerSyncDatabase.ts

@@ -40,7 +40,8 @@ import {
 } from './sync/stream/AbstractStreamingSyncImplementation.js';
 import { CoreSyncStatus, coreStatusToJs } from './sync/stream/core-instruction.js';
 import { SyncStream } from './sync/sync-streams.js';
-import { TriggerManager } from './triggers/TriggerManager.js';
+import { MEMORY_TRIGGER_CLAIM_MANAGER } from './triggers/MemoryTriggerClaimManager.js';
+import { TriggerManager, TriggerManagerConfig } from './triggers/TriggerManager.js';
 import { TriggerManagerImpl } from './triggers/TriggerManagerImpl.js';
 import { DEFAULT_WATCH_THROTTLE_MS, WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
@@ -222,6 +223,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
    */
   readonly triggers: TriggerManager;
+  protected triggersImpl: TriggerManagerImpl;
 
   logger: ILogger;
 
@@ -296,9 +298,10 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
     this._isReadyPromise = this.initialize();
 
-    this.triggers = new TriggerManagerImpl({
+    this.triggers = this.triggersImpl = new TriggerManagerImpl({
       db: this,
-      schema: this.schema
+      schema: this.schema,
+      ...this.generateTriggerManagerConfig()
     });
   }
 
@@ -334,6 +337,16 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    */
   protected abstract openDBAdapter(options: PowerSyncDatabaseOptionsWithSettings): DBAdapter;
 
+  /**
+   * Generates a base configuration for {@link TriggerManagerImpl}.
+   * Implementations should override this if necessary.
+   */
+  protected generateTriggerManagerConfig(): TriggerManagerConfig {
+    return {
+      claimManager: MEMORY_TRIGGER_CLAIM_MANAGER
+    };
+  }
+
   protected abstract generateSyncStreamImplementation(
     connector: PowerSyncBackendConnector,
     options: CreateSyncImplementationOptions & RequiredAdditionalConnectionOptions
@@ -420,6 +433,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     await this.updateSchema(this.options.schema);
     await this.resolveOfflineSyncStatus();
     await this.database.execute('PRAGMA RECURSIVE_TRIGGERS=TRUE');
+    await this.triggersImpl.cleanupResources();
     this.ready = true;
     this.iterateListeners((cb) => cb.initialized?.());
   }
@@ -560,7 +574,6 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
     const { clearLocal } = options;
 
-    // TODO DB name, verify this is necessary with extension
     await this.database.writeTransaction(async (tx) => {
       await tx.execute('SELECT powersync_clear(?)', [clearLocal ? 1 : 0]);
     });
@@ -597,6 +610,8 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
       return;
     }
 
+    this.triggersImpl.dispose();
+
     await this.iterateAsyncListeners(async (cb) => cb.closing?.());
 
     const { disconnect } = options;

packages/common/src/client/triggers/MemoryTriggerClaimManager.ts

@@ -0,0 +1,25 @@
+import { TriggerClaimManager } from './TriggerManager.js';
+
+const CLAIM_STORE = new Map<string, () => Promise<void>>();
+
+/**
+ * @internal
+ * @experimental
+ */
+export const MEMORY_TRIGGER_CLAIM_MANAGER: TriggerClaimManager = {
+  async obtainClaim(identifier: string): Promise<() => Promise<void>> {
+    if (CLAIM_STORE.has(identifier)) {
+      throw new Error(`A claim is already present for ${identifier}`);
+    }
+    const release = async () => {
+      CLAIM_STORE.delete(identifier);
+    };
+    CLAIM_STORE.set(identifier, release);
+
+    return release;
+  },
+
+  async checkClaim(identifier: string): Promise<boolean> {
+    return CLAIM_STORE.has(identifier);
+  }
+};

packages/common/src/client/triggers/TriggerManager.ts

@@ -47,8 +47,9 @@ export interface BaseTriggerDiffRecord<TOperationId extends string | number = nu
  * This record contains the new value and optionally the previous value.
  * Values are stored as JSON strings.
  */
-export interface TriggerDiffUpdateRecord<TOperationId extends string | number = number>
-  extends BaseTriggerDiffRecord<TOperationId> {
+export interface TriggerDiffUpdateRecord<
+  TOperationId extends string | number = number
+> extends BaseTriggerDiffRecord<TOperationId> {
   operation: DiffTriggerOperation.UPDATE;
   /**
    * The updated state of the row in JSON string format.
@@ -65,8 +66,9 @@ export interface TriggerDiffUpdateRecord<TOperationId extends string | number =
  * Represents a diff record for a SQLite INSERT operation.
  * This record contains the new value represented as a JSON string.
  */
-export interface TriggerDiffInsertRecord<TOperationId extends string | number = number>
-  extends BaseTriggerDiffRecord<TOperationId> {
+export interface TriggerDiffInsertRecord<
+  TOperationId extends string | number = number
+> extends BaseTriggerDiffRecord<TOperationId> {
   operation: DiffTriggerOperation.INSERT;
   /**
    * The value of the row, at the time of INSERT, in JSON string format.
@@ -79,8 +81,9 @@ export interface TriggerDiffInsertRecord<TOperationId extends string | number =
  * Represents a diff record for a SQLite DELETE operation.
  * This record contains the new value represented as a JSON string.
  */
-export interface TriggerDiffDeleteRecord<TOperationId extends string | number = number>
-  extends BaseTriggerDiffRecord<TOperationId> {
+export interface TriggerDiffDeleteRecord<
+  TOperationId extends string | number = number
+> extends BaseTriggerDiffRecord<TOperationId> {
   operation: DiffTriggerOperation.DELETE;
   /**
    * The value of the row, before the DELETE operation, in JSON string format.
@@ -201,6 +204,12 @@ interface BaseCreateDiffTriggerOptions {
    * Hooks which allow execution during the trigger creation process.
    */
   hooks?: TriggerCreationHooks;
+
+  /**
+   * Use storage-backed (non-TEMP) tables and triggers that persist across sessions.
+   * These resources are still automatically disposed when no longer claimed.
+   */
+  useStorage?: boolean;
 }
 
 /**
@@ -449,3 +458,38 @@ export interface TriggerManager {
    */
   trackTableDiff(options: TrackDiffOptions): Promise<TriggerRemoveCallback>;
 }
+
+/**
+ * @experimental
+ * @internal
+ * Manages claims on persisted SQLite triggers and destination tables to enable proper cleanup
+ * when they are no longer actively in use.
+ *
+ * When using persisted triggers (especially for OPFS multi-tab scenarios), we need a reliable way to determine which resources are still actively in use across different connections/tabs so stale resources can be safely cleaned up without interfering with active triggers.
+ *
+ * A cleanup process runs
+ * on database creation (and every 2 minutes) that:
+ * 1. Queries for existing managed persisted resources
+ * 2. Checks with the claim manager if any consumer is actively using those resources
+ * 3. Deletes unused resources
+ */
+
+export interface TriggerClaimManager {
+  /**
+   * Obtains or marks a claim on a certain identifier.
+   * @returns a callback to release the claim.
+   */
+  obtainClaim: (identifier: string) => Promise<() => Promise<void>>;
+  /**
+   * Checks if a claim is present for an identifier.
+   */
+  checkClaim: (identifier: string) => Promise<boolean>;
+}
+
+/**
+ * @experimental
+ * @internal
+ */
+export interface TriggerManagerConfig {
+  claimManager: TriggerClaimManager;
+}