How to integrate PowerSync's new built-in attachments (AttachmentQueue) with @tanstack/powersync-db-collection?

[vitorcamachoo]

Context

I'm building an offline-first mobile app on @tanstack/powersync-db-collection and want to handle file attachments (photos, PDFs, etc.) the local-first way — file metadata syncs via PowerSync, blobs go to S3 Storage.

PowerSync recently shipped a new built-in attachments API (AttachmentQueue lives inside the core SDK now — @powersync/attachments is deprecated). It expects to be wired directly to a PowerSyncDatabase instance: you give it a watch query over an attachment-id column on one of your synced tables, and it manages a local-only attachments table plus an upload/download queue against a RemoteStorage you implement.

Docs: https://docs.powersync.com/client-sdks/advanced/attachments

The question

What's the recommended pattern for using the new AttachmentQueue together with @tanstack/powersync-db-collection, so that I get the TanStack DB benefits (live queries, optimistic mutations, cross-collection joins, reactivity) for the rows that reference attachments — not just for the raw SQLite tables?

Specifically:

1. Where should the AttachmentQueue watch happen? The AttachmentQueue constructor wants a watch query over the underlying PowerSyncDatabase to learn which attachment IDs are "live". If my source of truth for "which rows exist" is now a TanStack DB collection (with optimistic state layered on top of SQLite), watching the raw SQLite table means optimistic inserts of new rows-with-attachments don't trigger an upload until the row is persisted. Is that the intended behavior, or is there a way to drive the queue from a TanStack DB live query instead?

2. Optimistic insert of an attachment-bearing row. When the user adds a row that has a local file (e.g. a capture note with a photo), I want one transaction that (a) inserts the row optimistically into the TanStack collection and (b) enqueues the file for upload. Today I'd do (a) through the collection's insert and (b) by calling attachmentQueue.saveFile(...) directly on the PowerSync db. Is there a clean way to compose these — e.g. via PowerSyncTransactor / createTransaction — so they share commit timing and rollback semantics?

3. Reading attachment state from a live query. Attachment records live in the local-only attachments table managed by AttachmentQueue. Is the recommended pattern to define a second powerSyncCollectionOptions collection on top of that local-only table and JOIN it in a TanStack DB live query, so a component can do something like note.photo.localUri reactively? If so, are there any caveats (e.g. the queue mutating the table outside of TanStack DB's mutation pipeline, deserialization of file-state enums)?

4. Is there an idiomatic example anywhere? The shopping list / capture demos I've seen use the collection but not the new attachment helpers. The PowerSync blog post on offline-first file attachments uses the queue against raw PowerSync. A small worked example combining the two would be incredibly useful.

Why ask here vs PowerSync

Either side could own the integration sugar, but the value of combining them — incremental live queries, optimistic UI, joins across the rows table and the attachments table — is squarely TanStack DB's surface area. Hence asking here first.

Versions

• @tanstack/db: 0.6.x
• @tanstack/powersync-db-collection: 0.1.39
• @powersync/react-native: latest with built-in AttachmentQueue
• Platform: React Native (Expo) + @powersync/op-sqlite

[stevensJourney]

I made a small POC for how I believe TanStackDB could be used in conjunction with PowerSync's new attachment queues.

powersync-ja/powersync-js#983

Where should the AttachmentQueue watch happen? The AttachmentQueue constructor wants a watch query over the underlying PowerSyncDatabase to learn which attachment IDs are "live". If my source of truth for "which rows exist" is now a TanStack DB collection (with optimistic state layered on top of SQLite), watching the raw SQLite table means optimistic inserts of new rows-with-attachments don't trigger an upload until the row is persisted. Is that the intended behavior, or is there a way to drive the queue from a TanStack DB live query instead?

It should be possible to use a TanStackDB live query to return the WatchedAttachmentItems. The main requirement is to get the timing of mutations - like saveFile correct, using the correct attachmentService.withContext calls. The linked example shows one way to implement a saveFile function which operates in a TanStackDB optimistic transaction.

Optimistic insert of an attachment-bearing row. When the user adds a row that has a local file (e.g. a capture note with a photo), I want one transaction that (a) inserts the row optimistically into the TanStack collection and (b) enqueues the file for upload. Today I'd do (a) through the collection's insert and (b) by calling attachmentQueue.saveFile(...) directly on the PowerSync db. Is there a clean way to compose these — e.g. via PowerSyncTransactor / createTransaction — so they share commit timing and rollback semantics?

The saveFileTanStack method is the cleanest way I can think of to achieve this currently. It will create the attachment record, and allow for associating the attachment ID with relational data in the same TanStackDB transaction which will be persisted in the same SQLite transaction.

Reading attachment state from a live query. Attachment records live in the local-only attachments table managed by AttachmentQueue. Is the recommended pattern to define a second powerSyncCollectionOptions collection on top of that local-only table and JOIN it in a TanStack DB live query, so a component can do something like note.photo.localUri reactively? If so, are there any caveats (e.g. the queue mutating the table outside of TanStack DB's mutation pipeline, deserialization of file-state enums)?

I think it should be fine to create a TanStackDB collection for the local only attachments table. It makes it much more convenient to be able to perform JOIN queries like that.
I think incoming sync operations should work just fine. There are different levels of deserialisation you could use for the attachments collection - depending on your needs, I can't think of any potential issues offhand. I used the simplest schema method in this demo.

Is there an idiomatic example anywhere? The shopping list / capture demos I've seen use the collection but not the new attachment helpers. The PowerSync blog post on offline-first file attachments uses the queue against raw PowerSync. A small worked example combining the two would be incredibly useful.

There hasn't been an example of this before. Perhaps this new POC will fulfil that role soon :)

[vitorcamachoo]

Awesome, let me take a look 👍