Handling Attachments

You can synchronize attachments, such as images and PDFs, between user devices and a remote storage provider using the powersync_attachments_helper package for Flutter. This guide uses Supabase Storage as the remote storage provider to store and serve photos. Other media types, like PDFs, are also supported.

At a high level, the [powersync_attachments_helper] package syncs attachments by:

• Storing files locally on the device in a structured way, linking them to specific database records.
• Maintaining attachment metadata in the local SQLite database to track the sync state of each attachment.
• Managing uploads, downloads, and retries through a local attachment queue to ensure local files stay in sync with remote storage.
• Providing a file operations API with methods to add, remove, and retrieve attachments.

​

Prerequisites

To follow this guide, ensure you have completed the FlutterFlow + PowerSync integration guide. At minimum, you should have implemented everything up to step 4, which involves reading data where your app’s lists are displayed and clickable.

​

Update schema to track attachments

Here we add a photo_id column to the lists table to link a photo to a list.

​

Update Supabase schema

1. In your Supabase dashboard, run the below SQL statement in your Supabase SQL Editor to add the photo_id column to the lists table:
   Copy

   ALTER TABLE public.lists
   ADD COLUMN photo_id text;
   

2. In FlutterFlow, under “App Settings” -> “Integrations”, click “Get Schema”.

​

Update PowerSync schema

The schema of the local SQLite database should now be updated to include the new photo_id column. Additionally, we need to set up a local-only table to store the metadata of photos which is being managed by the helper package.

1. In the PowerSync Dashboard, generate your updated client-side schema: Right-click on your instance and select “Generate Client-Side Schema” and select “FlutterFlow” as the language.
2. In FlutterFlow, under “App Settings” -> “Project Dependencies” -> “FlutterFlow Libraries”, click “View Details” of the PowerSync library.
3. Copy and paste the generated schema into the “PowerSyncSchema” field.

​

Configure Supabase Storage

1. To configure Supabase Storage for your app, navigate to the Storage section of your Supabase project and create a new bucket:

2. Give the storage bucket a name, such as media, and hit “Save”.

3. Next, configure a policy for this bucket. For the purpose of this demo, we will allow all user operations on the media bucket.
4. Create a new policy for the media bucket:

2. Give the new policy a name, and allow SELECT, INSERT, UPDATE, and DELETE.

3. Proceed to review and save the policy.

4. Finally, back in FlutterFlow, create an App Constant to store the bucket name:
   1. Under “App Values” -> “Constants”, click “Add App Constant”.
   2. Set “Constant Name” to supabaseStorageBucket.
   3. Click “Create”.
   4. Set the “Value” to the name of your Supabase Storage bucket, e.g. media.

​

Add the PowerSync Attachments Helper to your project

1. Under “App Settings” -> “Project Dependencies” -> “Custom Pub Dependencies” click “Add Pub Dependency”.
2. Enter powersync_attachments_helper: ^0.6.18.
3. Click “Add”.

​

Create setUpAttachments Custom Action

This creates an attachment queue which is responsible for tracking, storing and synching attachment metadata and CRUD operations.

1. Navigate to “Custom Code” and add a Custom Action.

2. Name the action setUpAttachments.

3. Add the following code:

   In the below code, power_sync_b0w5r9 is the project ID of the PowerSync library. Update it if it changes.

   Copy

   // DO NOT REMOVE OR MODIFY THE CODE ABOVE!
   import 'dart:async';
   import 'dart:io';
   import 'package:powersync/powersync.dart' as powersync;
   import 'package:powersync_attachments_helper/powersync_attachments_helper.dart';
   import 'package:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart'
       show db;
   Future setUpAttachments() async {
     // Add your function code here!
     await _initializeAttachmentQueue(db);
   }
   
   PhotoAttachmentQueue? attachmentQueue;
   final _remoteStorage = SupabaseStorageAdapter();
   
   class SupabaseStorageAdapter implements AbstractRemoteStorageAdapter {
     @override
     Future<void> uploadFile(String filename, File file,
         {String mediaType = 'text/plain'}) async {
       _checkSupabaseBucketIsConfigured();
       try {
         await Supabase.instance.client.storage
             .from(FFAppConstants.supabaseStorageBucket)
             .upload(filename, file,
                 fileOptions: FileOptions(contentType: mediaType));
       } catch (error) {
         throw Exception(error);
       }
     }
   
     @override
     Future<Uint8List> downloadFile(String filePath) async {
       _checkSupabaseBucketIsConfigured();
       try {
         return await Supabase.instance.client.storage
             .from(FFAppConstants.supabaseStorageBucket)
             .download(filePath);
       } catch (error) {
         throw Exception(error);
       }
     }
   
     @override
     Future<void> deleteFile(String filename) async {
       _checkSupabaseBucketIsConfigured();
       try {
         await Supabase.instance.client.storage
             .from(FFAppConstants.supabaseStorageBucket)
             .remove([filename]);
       } catch (error) {
         throw Exception(error);
       }
     }
   
     void _checkSupabaseBucketIsConfigured() {
       if (FFAppConstants.supabaseStorageBucket.isEmpty) {
         throw Exception(
             'Supabase storage bucket is not configured in App Constants');
       }
     }
   }
   
   /// Function to handle errors when downloading attachments
   /// Return false if you want to archive the attachment
   Future<bool> onDownloadError(Attachment attachment, Object exception) async {
     if (exception.toString().contains('Object not found')) {
       return false;
     }
     return true;
   }
   
   class PhotoAttachmentQueue extends AbstractAttachmentQueue {
     PhotoAttachmentQueue(db, remoteStorage)
         : super(
               db: db,
               remoteStorage: remoteStorage,
               onDownloadError: onDownloadError);
   
     @override
     init() async {
       if (FFAppConstants.supabaseStorageBucket.isEmpty) {
         log.info(
             'No Supabase bucket configured, skip setting up PhotoAttachmentQueue watches');
         return;
       }
       await super.init();
     }
   
     @override
     Future<Attachment> saveFile(String fileId, int size,
         {mediaType = 'image/jpeg'}) async {
       String filename = '$fileId.jpg';
       Attachment photoAttachment = Attachment(
         id: fileId,
         filename: filename,
         state: AttachmentState.queuedUpload.index,
         mediaType: mediaType,
         localUri: getLocalFilePathSuffix(filename),
         size: size,
       );
       return attachmentsService.saveAttachment(photoAttachment);
     }
   
     @override
     Future<Attachment> deleteFile(String fileId) async {
       String filename = '$fileId.jpg';
       Attachment photoAttachment = Attachment(
           id: fileId,
           filename: filename,
           state: AttachmentState.queuedDelete.index);
       return attachmentsService.saveAttachment(photoAttachment);
     }
   
     @override
     StreamSubscription<void> watchIds({String fileExtension = 'jpg'}) {
       log.info('Watching photos in lists table...');
       return db.watch('''
         SELECT photo_id FROM lists
         WHERE photo_id IS NOT NULL
       ''').map((results) {
         return results.map((row) => row['photo_id'] as String).toList();
       }).listen((ids) async {
         List<String> idsInQueue = await attachmentsService.getAttachmentIds();
         List<String> relevantIds =
             ids.where((element) => !idsInQueue.contains(element)).toList();
         syncingService.processIds(relevantIds, fileExtension);
       });
     }
   }
   
   Future<void> _initializeAttachmentQueue(powersync.PowerSyncDatabase db) async {
     final queue = attachmentQueue = PhotoAttachmentQueue(db, _remoteStorage);
     await queue.init();
   }
   

4. Click “Save Action”.

​

Add Final Actions to your main.dart

We need to call initializePowerSync from the Library to create the PowerSync database, and then call setUpAttachments to create the attachments queue. These actions need to happen in this specific order since setUpAttachments depends on having the database ready.

1. Still under Custom Code, select main.dart. Under File Settings -> Final Actions, click the plus icon.
2. Select initializePowerSync.
3. Click the plus icon again, and select setUpAttachments.
4. Save your changes.

​

Create resolveItemPicture Custom Action (downloads)

This action handles downloads by taking an attachment ID and returning an UploadedFile, which is FLutterFlow’s representation of an in-memory file asset. This action calls attachmentQueue.getLocalUri() and reads contents from the underlying file.

1. Create another Custom Action and name it resolveItemPicture.
2. Add the following code:
   Copy

   // DO NOT REMOVE OR MODIFY THE CODE ABOVE!
   import 'dart:io';
   import 'set_up_attachments.dart';
   
   Future<FFUploadedFile?> resolveItemPicture(String? id) async {
     if (id == null) {
       return null;
     }
     final name = '$id.jpg';
     final path = await attachmentQueue?.getLocalUri(name);
     if (path == null) {
       return null;
     }
     final file = File(path);
     if (!await file.exists()) {
       return null;
     }
     return FFUploadedFile(
       name: name,
       bytes: await file.readAsBytes(),
     );
   }
   

3. Under Action Settings -> Define Arguments on the right, click “Add Arguments”.
   1. Set the “Name” to id.
4. Click “Save Action”.
5. Click “Yes” when prompted about parameters in the settings not matching parameters in the code editor.

​

Create setItemPicture Custom Action (uploads)

This action handles uploads by passing the UploadedFile to local storage and then to the upload queue.

1. Create another Custom Action and name it setItemPicture.

2. Add the following code:

   In the below code, power_sync_b0w5r9 is the project ID of the PowerSync library. Update it if it changes.

   Copy

   // DO NOT REMOVE OR MODIFY THE CODE ABOVE!
   import 'package:power_sync_b0w5r9/custom_code/actions/initialize_power_sync.dart'
       show db;
   import 'package:powersync/powersync.dart' as powersync;
   import 'set_up_attachments.dart' show attachmentQueue;
   
   Future setItemPicture(
     FFUploadedFile? picture,
     Future Function(String? photoId) applyToDatabase,
   ) async {
     if (picture == null) {
       await applyToDatabase(null);
       return;
     }
   
     final queue = attachmentQueue;
     if (queue == null) {
       return;
     }
   
     String photoId = powersync.uuid.v4();
     final storageDirectory = await queue.getStorageDirectory();
     await queue.localStorage
         .saveFile('$storageDirectory/$photoId.jpg', picture.bytes!);
     queue.saveFile(photoId, picture.bytes!.length);
     await applyToDatabase(photoId);
   }
   

3. Under Action Settings -> Define Arguments on the right, click “Add Arguments”.

   1. Set the “Name” to picture.
   2. Under “Type” select “UploadedFile”.

4. Click “Add Arguments” again.

   1. Set the “Name” to applyToDatabase.
   2. Under “Type” select “Action”.
   3. Add an Action Parameter.
   4. Set the “Name” to photoId.
   5. Set its “Type” to “String”.

5. Click “Save Action”.

6. Click “Yes” when prompted about parameters in the settings not matching parameters in the code editor.

7. Check the Custom Actions for any errors.

​

Create a Custom Component to display and upload photos

Next, we’ll create a custom component that displays an image and includes a button to upload or replace the image file. You can use this component throughout your app wherever you need to display and update images.

​

Create the UI widgets of the component

1. Under the “Page Selector”, click “Add Page, Component, or Flow”.
2. Select the “New Component” tab.
3. Select “Create Blank” and call the component ListImage.
4. Under the “Widget Tree”, click on “Add a child to this widget”.
   1. Add the “Image” widget.
   2. Expand the width of the image to fill the available space.
5. Click on “Add a child to this widget” for the ListImage again.
   1. Add the “Button” widget.
   2. Select “Wrap in Column” when prompted.

​

Set component parameters and state variables

1. Still under the “Widget Tree”, select the ListImage component.
   1. At the top right under “Component Parameters” click “Add Parameters”.
   2. Click “Add Parameter”.
   3. Set its “Name” to listId.
   4. Set its “Type” to String.
   5. Click “Confirm”.
2. In the same panel, add Local Component State Variables:
   1. Define a variable to store the image file:
      1. Click “Add Field”.
      2. Set its “Field Name” to image.
      3. Set its “Type” to Uploaded File.
   2. Define a variable that stores the ID of the image:
      1. Click “Add Field” again.
      2. Set its “Field Name” to photoId.
      3. Set its “Type” to String.
      4. Check “Nullable.
   3. Define a variable that indicates whether an image is loaded or not. We’ll use this to set conditional visibility of the component:
      1. Click “Add Field” again.
      2. Set its “Field Name” to imageLoaded.
      3. Set its “Type” to Boolean.
      4. Toggle “Initial Field Value” on and off (click it twice) to set it to false.
   4. Click “Confirm”.

​

Set conditional visibility and state

1. Back under the “Widget Tree”, select the Image widget.
   1. In the “Properties” panel on the right, enable “Conditional” under “Visibility”.
      1. Click on “Unset”.
      2. Select the “Component State” -> imageLoaded state variable.
      3. Click “Confirm”.
   2. Further down in the “Properties” panel, set the “Image Type” to “Uploaded File”.
      1. Select the “Component State” -> image state variable.
      2. Click “Confirm”.

​

Define the Image widget logic

1. Under the “Widget Tree”, select the “Column” component within your ListImage component.
   1. Click “Add a child to this widget”.
   2. Add the “Container” widget.
   3. In the “Properties” panel on the right, set its “Width” and “Height” to 0 respectively. This container can be hidden.
   4. Back under the “Widget Tree”, click “Add a child to this widget” for the “Container”.
   5. Select the “Select the “Components and custom widgets imported from library projects” panel, and select the PowerSyncStateUpdater component.
   6. In the “Properties” panel on the right, under the “Component Properties” section:
      1. Under the “sql” section, add the SQL query to set the photo: select * from lists where id = :id;
      2. Under the “parameters” section, set the id parameter we’re using the above query:
      3. Click on “UNSET”.
      4. Select “Create Map (JSON)” as the variable.
      5. Under “Add Map Entries”, click “Add Key Value Pair”.
      6. Set the “Key” to id.
      7. Set the Value to “Component Parameters” -> listId.
      8. Click “Confirm”.
      9. Check “watch [Boolean]”. This ensures that the query auto-updates.
      10. Configure the “onData” action:
          1. Open the “Action Flow Editor”.
          2. Select the “Callback” trigger type.
          3. Click “Add Action”.
             1. Search for “update com” and select “Update Component State”.
             2. Click “Add Field”.
             3. Select your photoId state variable.
             4. Set “Select Update Type” to “Set Value”.
             5. Set “Value to set” to “Callback Parameters” -> rows.
             6. Under “Available Options”, select “Item at Index”.
             7. Under “List Index Options” select “First”.
             8. Under “Available Options” select “JSON Path”.
             9. Set “JSON Path” to $.photo_id.
             10. Click “Confirm”.
             11. Set “Update Type” to “No Rebuild”.
          4. Chain another action and select the resolveItemPicture custom action.
             1. Under “Set Action Arguments”, click on the settings icon next to “Value”.
             2. Select “Callback Parameters” -> rows.
             3. Under “Available Options”, select “Item at Index”.
             4. Under “List Index Options” select “First”.
             5. Under “Available Options” select “JSON Path”.
             6. Set “JSON Path” to $.photo_id.
             7. Click “Confirm”.
             8. Set “Action Output Variable Name” to picture.
          5. Chain another action, search for “update com” and select “Update Component State”.
             1. Click on “Add Field”.
             2. Select the “image - Uploaded File” state variable.
             3. Under “Select Update Type”, select “Set Value”.
             4. Set the “Value to set” to the “Action Outputs” -> picture variable.
             5. Click “Confirm”.
             6. Click on “Add Field” again.
             7. Select the “imageLoaded” state variable.
             8. Under “Select Update Type”, select “Set Value”.
             9. Click on the settings icon next to “Value to set” and select “Code Expression”.
             10. Select “Code Expression”.
             11. Click on “Add argument”.
             12. Select the “var1” placeholder argument.
             13. Set its “Name” to photoId.
             14. Check “Nullable”.
             15. Set the “Value” to the “Component State” -> photoId state variable.
             16. Set the “Expression” to photoId != null && photoId != 'null'.
             17. Ensure there are no errors.
             18. Click “Confirm”.
          6. Close the Action Flow Editor.

​

Define the Button widget logic

1. Under the “Widget Tree”, select the “Button” widget.
2. In the “Properties” panel on the right, under “Button Text”, update the text to Add/replace image.
3. Switch to the “Actions” panel and open the “Action Flow Editor”.
4. Select the “On Tap” trigger type.
5. Add an action, search for “media” and select “Upload/Save Media”.
6. Under “Upload Type” select “Local Upload (Widget State).
7. Chain another action and select the setItemPicture custom action.
8. Under “Set Action Arguments”, under the “picture” argument, set the “Value”, to the “Widget State” -> “Uploaded Local File” variable.
9. Click “Confirm”.
10. Under the “applyToDatabase” argument, add an action and under “Custom Action” -> “PowerSync”, select “powersyncWrite”.
11. Under the “Set Action Arguments” -> “sql” section, add the SQL query to update the photo.
    1. Paste the following into the “Value” field: update lists set photo_id = :photo where id = :id;
    2. Under the “parameters” section, set the photo parameter and id parameters we’re using the above query:
    3. Click on “UNSET”.
    4. Select “Create Map (JSON)” as the variable.
    5. Under “Add Map Entries”, click “Add Key Value Pair”.
    6. Set the “Key” to photo.
    7. Set the “Value” to “Action Parameter” -> photoId.
    8. Click “Confirm”.
    9. Add another Key Value Pair.
    10. Set the “Key” to id.
    11. Set the Value to “Component Parameters” -> listId.
    12. Click “Confirm”.

​

Add the ListImage Custom Component to your page

1. Under the “Page Selector”, select the Todos page.
2. Under the “Widget Tree”, right-click on the PowerSyncStateUpdater library component.
   1. Select “Wrap Widget”.
   2. Select the “Container” widget.
   3. In the “Properties” panel on the right, set the Container’s “Width” and “Height” to 0 respectively. This container can be hidden.
3. Back under the “Widget Tree”, add a child to the “Column” widget.
   1. Select the “Components and custom widgets defined in this project” panel, and select the ListImage component.
   2. In the ListImage “Properties” panel on the right, under “Component Parameters”, click on the settings icons next to “listId [String]”.
   3. Select the “Page Parameter” -> id variable.
   4. Click “Confirm”.