[PowerSync] Write mutation metadata to _metadata column when trackMetadata is enabled

[Nick-Motion]

Problem

When using @tanstack/powersync-db-collection with PowerSync tables that have trackMetadata: true, the metadata passed to collection operations (insert, update, delete) is not written to the _metadata column in SQLite.

This means PowerSync's CRUD operations don't receive the metadata, even though it's available on the PendingMutation type.

Use Case

When optimistically deleting a record, the record is removed from the database before the sync handler runs. We need to pass routing information (e.g., workspaceId) via metadata so the sync handler can make the correct API call.

// This metadata is available on PendingMutation but not written to SQLite
labelsCollection.delete(label.id, {
  metadata: { workspaceId: label.workspaceId },
})

PowerSync supports this via the _metadata column when trackMetadata: true is set on the table schema, but the transactor doesn't write to it.

Expected Behavior

When a PowerSync table has trackMetadata: true and a mutation includes metadata, the PowerSyncTransactor should write JSON.stringify(metadata) to the _metadata column.

Current Behavior

The handleInsert, handleUpdate, and handleDelete methods in PowerSyncTransactor.ts only write the record's data fields, ignoring mutation.metadata.

Relevant Code

PowerSyncTransactor.ts line ~160-175 (handleInsert):

const values = serializeValue(mutation.modified)
// mutation.metadata is available but not used
await context.execute(`INSERT into ${tableName} ...`, Object.values(values))

Workaround

Currently maintaining a separate in-memory Map to preserve metadata across the optimistic update → sync handler boundary.

[kobiebotha]

Thanks for opening this! We have some ideas and will take a look at this in the next few days.