What's changing: The Flutter/Dart attachment queue releases its mutex per attachment rather than holding it for the entire batch, and persists attachment state incrementally. As a result: stopSync() returns within one attachment's processing time instead of one batch's; concurrent queue operations (saveFile(), deleteFile(), clearQueue(), expireCache()) are no longer blocked behind an active sync batch; and attachments_queue rows are updated incrementally so db.watch() streams reflect real-time progress rather than an end-of-batch jump.
Why this needs docs: This is a public behavior change to the Flutter SDK attachment queue that resolves observable issues users have reported (Discord thread linked in the PR) — stopSync() appearing to hang during large downloads, queue mutations blocking for extended periods, and diagnostics queries against attachments_queue showing no progress until a batch completes.
Likely affected pages/sections:
client-sdks/advanced/attachments.mdx — add a Flutter/Dart behavior note (or a general behavior/lifecycle section) covering: (1) stopSync() interrupts attachment sync promptly, within one attachment's processing time; (2) saveFile(), deleteFile(), and other queue operations are non-blocking with respect to an active download/upload batch; (3) db.watch('SELECT state, COUNT(*) FROM attachments_queue GROUP BY state') reflects incremental progress during a batch
Note: This PR is open and not yet merged as of the date this issue was filed. Docs updates should wait for merge.
Source PR: powersync-ja/powersync.dart#415
What's changing: The Flutter/Dart attachment queue releases its mutex per attachment rather than holding it for the entire batch, and persists attachment state incrementally. As a result:
stopSync()returns within one attachment's processing time instead of one batch's; concurrent queue operations (saveFile(),deleteFile(),clearQueue(),expireCache()) are no longer blocked behind an active sync batch; andattachments_queuerows are updated incrementally sodb.watch()streams reflect real-time progress rather than an end-of-batch jump.Why this needs docs: This is a public behavior change to the Flutter SDK attachment queue that resolves observable issues users have reported (Discord thread linked in the PR) —
stopSync()appearing to hang during large downloads, queue mutations blocking for extended periods, and diagnostics queries againstattachments_queueshowing no progress until a batch completes.Likely affected pages/sections:
client-sdks/advanced/attachments.mdx— add a Flutter/Dart behavior note (or a general behavior/lifecycle section) covering: (1)stopSync()interrupts attachment sync promptly, within one attachment's processing time; (2)saveFile(),deleteFile(), and other queue operations are non-blocking with respect to an active download/upload batch; (3)db.watch('SELECT state, COUNT(*) FROM attachments_queue GROUP BY state')reflects incremental progress during a batchSource PR: powersync-ja/powersync.dart#415