(feat): Added manageDestinationExternally option to diff trigger creation.

.changeset/brown-steaks-drop.md

@@ -0,0 +1,5 @@
+---
+'@powersync/common': minor
+---
+
+Added `manageDestinationExternally` option to diff trigger creation, escaping all internal management of the destination table. User is responsible for table creation and cleanup.

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

@@ -223,6 +223,13 @@ export interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
    * This table will be dropped once the trigger is removed.
    */
   destination: string;
+
+  /**
+   * When true, the diff trigger will not create or drop the destination table.
+   * The caller is responsible for ensuring the table exists with the correct
+   * schema before creating the trigger and for dropping it when no longer needed.
+   */
+  manageDestinationExternally?: boolean;
 }
 
 /**

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

@@ -201,6 +201,7 @@ export class TriggerManagerImpl implements TriggerManager {
       columns,
       when,
       hooks,
+      manageDestinationExternally = false,
       // Fall back to the provided default if not given on this level
       useStorage = this.defaultConfig.useStorageByDefault
     } = options;
@@ -272,24 +273,28 @@ export class TriggerManagerImpl implements TriggerManager {
       disposeWarningListener();
       return this.db.writeLock(async (tx) => {
         await this.removeTriggers(tx, triggerIds);
-        await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+        if (!manageDestinationExternally) {
+          await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+        }
         await releaseStorageClaim?.();
       });
     };
 
     const setup = async (tx: LockContext) => {
       // Allow user code to execute in this lock context before the trigger is created.
       await hooks?.beforeCreate?.(tx);
-      await tx.execute(/* sql */ `
-        CREATE ${tableTriggerTypeClause} TABLE ${destination} (
-          operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
-          id TEXT,
-          operation TEXT,
-          timestamp TEXT,
-          value TEXT,
-          previous_value TEXT
-        )
-      `);
+      if (!manageDestinationExternally) {
+        await tx.execute(/* sql */ `
+          CREATE ${tableTriggerTypeClause} TABLE ${destination} (
+            operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+            id TEXT,
+            operation TEXT,
+            timestamp TEXT,
+            value TEXT,
+            previous_value TEXT
+          )
+        `);
+      }
 
       if (operations.includes(DiffTriggerOperation.INSERT)) {
         const insertTriggerId = this.generateTriggerName(DiffTriggerOperation.INSERT, destination, id);

packages/node/tests/trigger.test.ts

@@ -613,6 +613,78 @@ describe('Triggers', () => {
     expect(changes[4].__previous_value).toBeNull();
   });
 
+  databaseTest('persistDestination: should not drop destination table on dispose', async ({ database }) => {
+    const table = 'persist_dest_dispose_test';
+
+    // Manually create the destination table (simulates a table that persisted from a prior session)
+    await database.execute(`
+        CREATE TABLE ${table} (
+          operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+          id TEXT,
+          operation TEXT,
+          timestamp TEXT,
+          value TEXT,
+          previous_value TEXT
+        )
+      `);
+
+    const dispose = await database.triggers.createDiffTrigger({
+      source: 'todos',
+      destination: table,
+      when: { [DiffTriggerOperation.INSERT]: 'TRUE' },
+      useStorage: true, // persistent table so we can verify via sqlite_master
+      manageDestinationExternally: true
+    });
+
+    // Table must exist before dispose
+    let rows = await database.getAll<{ name: string }>(
+      `SELECT name FROM sqlite_master WHERE type='table' AND name = ?`,
+      [table]
+    );
+    expect(rows.length).toEqual(1);
+
+    await dispose();
+
+    // Table must STILL exist
+    rows = await database.getAll<{ name: string }>(`SELECT name FROM sqlite_master WHERE type='table' AND name = ?`, [
+      table
+    ]);
+    expect(rows.length).toEqual(1);
+
+    // Manual cleanup so the test doesn't leak
+    await database.execute(`DROP TABLE IF EXISTS ${table}`);
+  });
+
+  databaseTest('persistDestination: should allow reusing an existing destination table', async ({ database }) => {
+    const table = 'persist_dest_reuse_test';
+
+    // Manually create the destination table (simulates a table that persisted from a prior session)
+    await database.execute(`
+        CREATE TABLE ${table} (
+          operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+          id TEXT,
+          operation TEXT,
+          timestamp TEXT,
+          value TEXT,
+          previous_value TEXT
+        )
+      `);
+
+    // Must NOT throw even though the table already exists.
+    const dispose = await database.triggers.createDiffTrigger({
+      source: 'todos',
+      destination: table,
+      when: { [DiffTriggerOperation.INSERT]: 'TRUE' },
+      useStorage: true,
+      manageDestinationExternally: true
+    });
+
+    await dispose();
+
+    // Manual cleanup
+    await database.execute(`DROP TABLE IF EXISTS ${table}`);
+  });
+
   databaseTest('Should cast operation_id as string with withDiff option', async ({ database }) => {
     const results: TriggerDiffRecord<string>[] = [];