PowerSync Dart SDK

Instead of embedding large binary data (like images) directly in your source database, PowerSync uses an attachments model. You store references (IDs) to binary data in your regular database schema, while the actual files are stored in a secondary data store (e.g., Supabase Storage, S3) and cached locally on the device.

Key Concepts

• Attachment Identification: Each attachment is identified by a unique id.
• Immutability: Attachments are immutable once created.
• Referential Integrity: Relational data should reference attachments using a foreign key.
• Automatic Cleanup: The sync process manages the lifecycle. If no relational data in your database references an attachment, the SDK will eventually delete that orphaned attachment from local storage.
• Alpha Status: The attachments API is currently marked as @experimental. It is intended for testing and may undergo breaking changes. Do not use in production.

To allow users to use an app without signing in and then sync their data later, use a combination of localOnly tables and the viewName property. This prevents app queries from needing to change logic when the user's authentication state changes.

The Strategy

1. Local-only State: Define tables with the localOnly flag. Use the viewName property to override their names to match your standard synced table names (e.g., lists). This allows your queries (like PowerSync.getAll("SELECT * FROM lists")) to work immediately.
2. Transition to Synced State: When the user signs in:
   • Call updateSchema to change the viewName of the synced tables from their inactive names (e.g., inactive_synced_lists) to their active names (e.g., lists).
   • Copy data from the localOnly tables to the newly active synced tables.
   • Delete the data from the localOnly tables to save space.
3. Consistency: By using viewName overrides, the SQL queries used throughout the app remain identical regardless of whether the data is currently being served from a local-only table or a synced table.

Important Implementation Notes

• updateSchema Constraints: updateSchema cannot be called inside a transaction. It is recommended to perform schema updates when the database is not connected.
• watch Method Behavior: The watch method may not correctly track tables altered by updateSchema. To resolve this, execute refreshSchema after updating the schema.

To use the attachments helper, you must extend AbstractAttachmentQueue and implement three core methods to define how files are handled and how the sync process is triggered:

1. saveFile(String fileId, int size, {mediaType}): Defines how a new file is queued for upload. You create an Attachment object with the appropriate AttachmentState.queuedUpload and call attachmentsService.saveAttachment().
2. deleteFile(String fileId): Defines how a file is queued for deletion. You create an Attachment object with AttachmentState.queuedDelete and call attachmentsService.saveAttachment().
3. watchIds({String fileExtension}): A watcher that monitors the PowerSync database for new IDs that need processing. When new IDs are detected (e.g., a new photo_id in a users table), you should call syncingService.processIds(relevantIds, fileExtension) to trigger the sync.

Note: The Attachment object requires an id, filename, state, and (for uploads) localUri, size, and mediaType.

class PhotoAttachmentQueue extends AbstractAttachmentQueue {
  PhotoAttachmentQueue(db, remoteStorage)
      : super(db: db, remoteStorage: remoteStorage);

  @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'}) {
    return db.watch('''
      SELECT photo_id FROM users
      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);
    });
  }
}