Attachments / Files

Sync file attachments like images and PDFs without storing them in the database, using an offline-first queue for uploads and downloads.

Introduction

The @powersync/attachments package (JavaScript/TypeScript) and powersync_attachments_helper package (Flutter/Dart) are deprecated. Attachment functionality is now built-in to the PowerSync SDKs. Please use the built-in attachment helpers instead, and see the migration notes.

While PowerSync excels at syncing structured data, storing large files (images, videos, PDFs) directly in SQLite is not recommended. Embedding files as base64-encoded data or binary blobs in database rows can lead to many issues.

Instead, PowerSync uses a metadata + storage provider pattern: sync small metadata records through PowerSync while storing actual files in purpose-built storage systems (S3, Supabase Storage, Cloudflare R2, etc.). This approach provides:

• Optimal performance - Database stays small and fast
• Automatic queue management - Background uploads/downloads with retry logic
• Offline-first support - Local files available immediately, sync happens in background
• Cache management - Automatic cleanup of unused files
• Platform flexibility - Works across web, mobile, and desktop

SDK & Demo Reference

We provide attachment helpers for multiple platforms:

SDK	Package	Min. SDK version	Demo App
JavaScript/TypeScript	Built-in attachments (alpha)	Web v1.33.0, React Native v1.30.0, Node.js v0.17.0	React Native Todo
Flutter	Built-in attachments (alpha)	v1.16.0	Flutter Todo
Swift	Built-in attachments (alpha)	v1.0.0	iOS Demo
Kotlin	Built-in attachments (alpha)	v1.0.0	Android Todo
.NET	Built-in attachments (alpha)	v0.1.2	MAUI Todo

Most demo applications use Supabase Storage as the storage provider, but the patterns are adaptable to any storage system.

How It Works

PowerSync attachments flow & architecture

Workflow

1. Save file - Your app calls saveFile() with file data and an updateHook to handle linking the attachment to your data model
2. Queue for upload - File is saved locally and a record is created in the attachments table with state QUEUED_UPLOAD
3. Background upload - The attachment queue automatically uploads file to remote storage (S3/Supabase/etc.)
4. Remote storage - File is stored in remote storage with the attachment ID
5. State update - The updateHook runs, updating your data model with the attachment ID and marking the file locally as SYNCED
6. Cross-device sync - PowerSync syncs the data model changes to other clients
7. Data model updated - Other clients receive the updated data model with the new attachment reference (e.g., user.photo_id = "id-123")
8. Watch detects attachment - Other clients’ watchAttachments() callback detects the new attachment reference and creates a record in the attachments table with state QUEUED_DOWNLOAD
9. File download - The attachment queue automatically downloads the file from remote storage
10. Local storage - File is saved to local storage on the other client
11. State update - File is marked locally as SYNCED and ready for use

Attachment States

State	Description
QUEUED_UPLOAD	File saved locally, waiting to upload to remote storage
QUEUED_DOWNLOAD	Data model synced from another device, file needs to be downloaded
SYNCED	File exists both locally and in remote storage, fully synced
QUEUED_DELETE	Marked for deletion from both local and remote storage
ARCHIVED	No longer referenced in your data model, candidate for cleanup

Core Components

Attachment Table

The Attachment Table is a local-only table that stores metadata about each file. It’s not synced through PowerSync’s Sync Streams/Rules - instead, it’s managed entirely by the attachment queue on each device.

Metadata stored:

• id - Unique attachment identifier (UUID)
• filename - File name with extension (e.g., photo-123.jpg)
• localUri - Reference to the file in local storage. The format is platform-specific: a file path on native platforms and Node.js, or an internal indexeddb:// reference on web
• size - File size in bytes
• mediaType - MIME type (e.g., image/jpeg)
• state - Current sync state (see states above)
• hasSynced - Boolean indicating if file has ever been uploaded
• timestamp - Last update time
• metaData - Optional JSON string for custom data

Key characteristics:

• Local-only - Each device maintains its own attachment table
• Automatic management - Queue handles all inserts/updates
• Cross-client coordination - Your data model (e.g., users.photo_id) tells each client which files it needs

Remote Storage Adapter

The Remote Storage Adapter is an interface you implement to connect PowerSync with your cloud storage provider. It’s completely platform-agnostic - Implementations can use S3, Supabase Storage, Cloudflare R2, Azure Blob, or even IPFS.

Interface methods:

• uploadFile(fileData, attachment) - Upload file to cloud storage
• downloadFile(attachment) - Download file from cloud storage
• deleteFile(attachment) - Delete file from cloud storage

In the JavaScript/TypeScript SDK, this adapter backs the default attachment transport, which delegates upload, download, and delete to it. A queue configured with a transportAdapter instead does not use a remote storage adapter at all.

Common pattern: For security reasons, client-side implementations should use signed URLs

1. Request a signed upload/download URL from your backend
2. Your backend validates permissions and generates a temporary URL
3. Client uploads/downloads directly to storage using the signed URL
4. Never expose storage credentials to clients

Local Storage Adapter

The Local Storage Adapter handles file persistence on the device. PowerSync provides implementations for common platforms and allows you to create custom adapters.

Interface methods:

• initialize() - Set up storage (create directories, etc.)
• saveFile(path, data) - Write file to storage
• readFile(path) - Read file from storage
• deleteFile(path) - Remove file from storage
• fileExists(path) - Check if file exists
• getLocalUri(filename) - Get full path for a filename

In the JavaScript/TypeScript SDK, adapters that can relocate a file without loading it into memory implement the StreamingLocalStorageAdapter subinterface, which adds moveFile(sourceUri, targetUri). Configuring the queue with a streaming-capable adapter enables saveFileFromUri. The Node.js, Expo, and React Native FS adapters are streaming-capable; the web IndexedDB adapter is not.

Built-in adapters:

• IndexedDB - For web browsers (IndexDBFileSystemStorageAdapter)
• Node.js Filesystem - For Node/Electron (NodeFileSystemAdapter)
• React Native - For React Native with Expo or bare React Native we have a dedicated package (@powersync/attachments-storage-react-native)
• Native mobile storage - For Flutter, Kotlin, Swift

The React Native local storage adapter requires Expo 54 or later. The Expo streaming transport requires Expo 56 or later.

Attachment Transport

The Attachment Transport owns all remote operations for an attachment: upload, download, and delete. It is available in the JavaScript/TypeScript SDK only.

By default, the queue wraps your remote storage adapter in an internal buffered transport. It reads the entire file into JS memory as an ArrayBuffer before handing it to the remote storage adapter, and the reverse for downloads. This works well for small files, but large files can cause memory pressure, particularly in React Native on lower-end devices.

To avoid this, pass an AttachmentTransportAdapter in the queue’s transportAdapter option. A transport implements three methods:

• upload(attachment) - Transfer the file at attachment.localUri to remote storage
• download(attachment) - Fetch the remote file into attachment.localUri (the queue assigns the destination path before the call)
• delete(attachment) - Remove the file from remote storage

Because a transport owns the entire transfer, it can stream bytes natively between the file on disk and the network without materializing them in the JS heap. PowerSync provides streaming transports for Node.js and React Native, created from their local storage adapters with createTransportAdapter; see Transferring Large Files Without Buffering.

You can configure the queue with either a remoteStorage or a transportAdapter, but not both. Supplying both, or neither, is a TypeScript compile-time error. A queue configured with a transportAdapter handles all remote operations through it and does not use a remote storage adapter.

The transport API requires @powersync/web v3.0.0, @powersync/react-native v2.0.3, or @powersync/node v0.21.0 or later. React Native also requires @powersync/attachments-storage-react-native v0.1.0 or later.

Attachment Queue

The Attachment Queue is the orchestrator that manages the entire attachment lifecycle. It:

• Watches your data model - You pass a watchAttachments function as a parameter that monitors which files your app references
• Manages state transitions - Automatically moves files through states (upload/download → synced → archive → delete)
• Handles retries - Failed operations are retried on the next sync interval
• Performs cleanup - Removes archived files that are no longer needed
• Verifies integrity - Checks local files exist and repairs inconsistencies

Watched Attachments pattern: The queue needs to know which attachments exist in your data model. The watchAttachments function you provide monitors your data model and returns a list of attachment IDs that your app references. The queue compares this list with its internal attachment table to determine:

• New attachments - Download them
• Missing attachments - Upload them
• Removed attachments - Archive them

The watchAttachments queries are reactive and execute whenever the watched tables change, keeping the attachment queue in sync with your data model.

There are a few scenarios you might encounter:

Single Attachment Type

For a single attachment type, you watch one table. For example, if users have profile photos:

SELECT photo_id FROM users WHERE photo_id IS NOT NULL

Multiple Attachment Types - Single Queue

You can watch multiple attachment types using a single queue by combining queries with SQL UNION or UNION ALL. This allows you to monitor attachments across different tables (e.g., users.photo_id, documents.document_id, videos.video_id) in one queue. Each attachment type may have different file extensions, which can be handled in the query by selecting the extension from your data model or using type-specific defaults.

For example:

SELECT photo_id as id, photo_file_extension as file_extension
FROM users 
WHERE photo_id IS NOT NULL

UNION ALL

SELECT document_id as id, document_file_extension as file_extension
FROM documents 
WHERE document_id IS NOT NULL

UNION ALL

SELECT video_id as id, video_file_extension as file_extension
FROM videos 
WHERE video_id IS NOT NULL

Use UNION ALL when you want to include all rows (including duplicates), or UNION when you want to automatically deduplicate results. For attachment watching, UNION ALL is typically preferred since attachment IDs should already be unique.

The UNION query executes whenever any of the watched tables change, which may have higher database overhead compared to watching a single table. Implementation examples are shown in the Initialize Attachment Queue section below.

Multiple Attachment Types - Multiple Queues

Alternatively, you can create separate queues for different attachment types. Each queue watches its own specific table(s) with simpler queries, allowing for independent configuration and management.

Multiple queues may use more memory, but each queue watches simpler queries. Implementation examples are shown in the Initialize Attachment Queue section below.

Implementation Guide

Installation

JavaScript/TypeScript

# Built into @powersync/web, @powersync/node, and @powersync/react-native.
# React Native requires an additional storage adapter:
# npm install @powersync/attachments-storage-react-native

# Expo projects (v54+) also require:
# npm install expo-file-system

# Bare React Native projects also require:
# npm install @dr.pogodin/react-native-fs

Setup: Add Attachment Table to Schema

JavaScript/TypeScript

import { Schema, Table, column, AttachmentTable } from '@powersync/web';

const appSchema = new Schema({
  users: new Table({
    name: column.text,
    email: column.text,
    photo_id: column.text  // References attachment ID
  }),
  // Add the attachment table
  attachments: new AttachmentTable()
});

Configure Storage Adapters

JavaScript/TypeScript

// For web browsers (IndexedDB)
import { IndexDBFileSystemStorageAdapter } from '@powersync/web';
const localStorage = new IndexDBFileSystemStorageAdapter('my-app-files');

// For Node.js/Electron (filesystem)
// import { NodeFileSystemAdapter } from '@powersync/node';
// const localStorage = new NodeFileSystemAdapter('./user-attachments');

// For React Native (Expo or bare React Native)
// Need to install @powersync/attachments-storage-react-native
//
// For Expo projects, also install expo-file-system
// import { ExpoFileSystemStorageAdapter } from '@powersync/attachments-storage-react-native';
// const localStorage = new ExpoFileSystemStorageAdapter();
//
// For bare React Native, also install @dr.pogodin/react-native-fs
// import { ReactNativeFileSystemStorageAdapter } from '@powersync/attachments-storage-react-native';
// const localStorage = new ReactNativeFileSystemStorageAdapter();

// Remote storage adapter (example with signed URLs)
const remoteStorage = {
  async uploadFile(fileData: ArrayBuffer, attachment: AttachmentRecord) {
    // Request signed upload URL from your backend
    const { uploadUrl } = await fetch('/api/attachments/upload-url', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ 
        filename: attachment.filename,
        contentType: attachment.mediaType 
      })
    }).then(r => r.json());
    
    // Upload to cloud storage using signed URL
    await fetch(uploadUrl, {
      method: 'PUT',
      body: fileData,
      headers: { 
        'Content-Type': attachment.mediaType || 'application/octet-stream' 
      }
    });
  },
  
  async downloadFile(attachment: AttachmentRecord): Promise<ArrayBuffer> {
    // Request signed download URL from your backend
    const { downloadUrl } = await fetch(
      `/api/attachments/${attachment.id}/download-url`
    ).then(r => r.json());
    
    // Download from cloud storage
    const response = await fetch(downloadUrl);
    return response.arrayBuffer();
  },
  
  async deleteFile(attachment: AttachmentRecord) {
    // Delete via your backend
    await fetch(`/api/attachments/${attachment.id}`, {
      method: 'DELETE'
    });
  }
};

// Optional (React Native and Node.js): a streaming transport for large files.
// It streams bytes directly between disk and network and owns
// upload/download/delete; configure it in place of remoteStorage.
// Created from the Expo, React Native FS, or Node.js local storage adapter.
// See "Transferring Large Files Without Buffering" below for a full example.
//
// const transportAdapter = localStorage.createTransportAdapter({
//   resolveUpload: async (attachment) => ({
//     url: await getSignedUploadUrl(attachment.filename)
//   }),
//   resolveDownload: async (attachment) => ({
//     url: await getSignedDownloadUrl(attachment.filename)
//   }),
//   deleteFile: async (attachment) => {
//     await deleteFromStorage(attachment.filename);
//   }
// });

Security Best Practice: Always use your backend to generate signed URLs and validate permissions. Never expose storage credentials directly to clients.

Initialize Attachment Queue

JavaScript/TypeScript

import { AttachmentQueue } from '@powersync/web';

const attachmentQueue = new AttachmentQueue({
  db: db,  // PowerSync database instance
  localStorage,
  remoteStorage,
  // Or a transportAdapter in place of remoteStorage (provide exactly one);
  // it owns all remote operations. See "Attachment Transport" above.
  // transportAdapter,
  
  // Define which attachments exist in your data model
  watchAttachments: (onUpdate) => {
    db.watch(
      `SELECT photo_id FROM users WHERE photo_id IS NOT NULL`,
      [],
      {
        onResult: async (result) => {
          const attachments = result.rows?._array.map(row => ({
            id: row.photo_id,
            // Names the file in local storage (<id>.jpg). Either fileExtension or filename is required
            fileExtension: 'jpg',
            // MIME type for remote transfer (the Content-Type). Optional, never inferred
            // from fileExtension, and preserved on the downloaded record (JS SDK only)
            mediaType: 'image/jpeg'
          })) ?? [];
          await onUpdate(attachments);
        }
      }
    );
  },
  
  // Optional configuration
  syncIntervalMs: 30000,      // Sync every 30 seconds
  downloadAttachments: true,  // Auto-download referenced files
  archivedCacheLimit: 100     // Keep 100 archived files before cleanup
});

// Start the sync process
await attachmentQueue.startSync();

The watchAttachments callback is crucial - it tells the queue which files your app needs based on your data model. The queue uses this to automatically download, upload, or archive files.

Watching Multiple Attachment Types

When watching multiple attachment types, you need to provide the fileExtension for each attachment. You can store this in your data model tables or derive it from other fields. Here are examples for both patterns:

Pattern 2: Single Queue with UNION

JavaScript/TypeScript

// Example: Watching users.photo_id, documents.document_id, and videos.video_id
// Assuming your tables store file extensions
const attachmentQueue = new AttachmentQueue({
  db: db,
  localStorage,
  remoteStorage,
  
  watchAttachments: (onUpdate) => {
    db.watch(
      `SELECT photo_id as id, photo_file_extension as file_extension
       FROM users 
       WHERE photo_id IS NOT NULL
       
       UNION ALL
       
       SELECT document_id as id, document_file_extension as file_extension
       FROM documents 
       WHERE document_id IS NOT NULL
       
       UNION ALL
       
       SELECT video_id as id, video_file_extension as file_extension
       FROM videos 
       WHERE video_id IS NOT NULL`,
      [],
      {
        onResult: async (result) => {
          const attachments = result.rows?._array.map(row => ({
            id: row.id,
            fileExtension: row.file_extension
          })) ?? [];
          await onUpdate(attachments);
        }
      }
    );
  },
  
  // ... other options
});

await attachmentQueue.startSync();

Pattern 3: Multiple Queues

JavaScript/TypeScript

// Create separate queues for different attachment types
const photoQueue = new AttachmentQueue({
  db: db,
  localStorage,
  remoteStorage,
  watchAttachments: (onUpdate) => {
    db.watch(
      `SELECT photo_id FROM users WHERE photo_id IS NOT NULL`,
      [],
      {
        onResult: async (result) => {
          const attachments = result.rows?._array.map(row => ({
            id: row.photo_id,
            fileExtension: 'jpg',
            mediaType: 'image/jpeg'  // Optional: preserved on the downloaded record
          })) ?? [];
          await onUpdate(attachments);
        }
      }
    );
  },
});

const documentQueue = new AttachmentQueue({
  db: db,
  localStorage,
  remoteStorage,
  watchAttachments: (onUpdate) => {
    db.watch(
      `SELECT document_id FROM documents WHERE document_id IS NOT NULL`,
      [],
      {
        onResult: async (result) => {
          const attachments = result.rows?._array.map(row => ({
            id: row.document_id,
            fileExtension: 'pdf',
            mediaType: 'application/pdf'  // Optional: preserved on the downloaded record
          })) ?? [];
          await onUpdate(attachments);
        }
      }
    );
  },
});

await Promise.all([
  photoQueue.startSync(),
  documentQueue.startSync()
]);

Upload an Attachment

JavaScript/TypeScript

async function uploadProfilePhoto(imageBlob: Blob, userId: string) {
  const arrayBuffer = await imageBlob.arrayBuffer();
  
  const attachment = await attachmentQueue.saveFile({
    data: arrayBuffer,
    fileExtension: 'jpg',
    mediaType: 'image/jpeg',
    
    // updateHook runs in same transaction, ensuring atomicity
    updateHook: async (tx, attachment) => {
      await tx.execute(
        'UPDATE users SET photo_id = ? WHERE id = ?',
        [attachment.id, userId]
      );
    }
  });
  
  return attachment;
}

// The queue will:
// 1. Save file locally immediately
// 2. Create attachment record with state QUEUED_UPLOAD
// 3. Update user record in same transaction
// 4. Automatically upload file in background
// 5. Update state to SYNCED when complete

// For files already on disk (e.g. a captured video or audio recording),
// saveFileFromUri queues the upload without reading the file into memory.
// Requires a streaming-capable local storage adapter (StreamingLocalStorageAdapter:
// Node.js, Expo, or React Native FS; not available on web).
async function attachRecording(localUri: string, recordingId: string) {
  return attachmentQueue.saveFileFromUri({
    localUri,  // path to the existing file
    fileExtension: 'm4a',
    mediaType: 'audio/mp4',
    updateHook: async (tx, attachment) => {
      await tx.execute(
        'UPDATE recordings SET audio_id = ? WHERE id = ?',
        [attachment.id, recordingId]
      );
    }
  });
}

The updateHook parameter is the recommended way to link attachments to your data model. It runs in the same database transaction, ensuring data consistency.

Download/Access an Attachment

JavaScript/TypeScript

import { AttachmentState } from '@powersync/web';

// Downloads happen automatically when watchAttachments references a file

async function getProfilePhotoUri(userId: string): Promise<string | null> {
  const user = await db.get(
    'SELECT photo_id FROM users WHERE id = ?',
    [userId]
  );
  
  if (!user?.photo_id) {
    return null;
  }
  
  const attachment = await db.get(
    'SELECT * FROM attachments WHERE id = ?',
    [user.photo_id]
  );
  
  if (!attachment) {
    return null;
  }
  
  if (attachment.state === AttachmentState.SYNCED && attachment.local_uri) {
    return attachment.local_uri;
  }
  
  return null;
}

// Example: display the image in React on web. On web, local_uri is an
// internal indexeddb:// reference, so read the bytes through the local
// storage adapter and convert them to an object URL. On React Native and
// Node.js, local_uri is a real file path and can be used directly
// (e.g. <Image source={{ uri: localUri }} /> in React Native).
function ProfilePhoto({ userId }: { userId: string }) {
  const [photoUrl, setPhotoUrl] = useState<string | null>(null);
  
  useEffect(() => {
    let objectUrl: string | null = null;
    
    const watch = db.watch(
      `SELECT a.local_uri, a.media_type, a.state 
       FROM users u 
       LEFT JOIN attachments a ON a.id = u.photo_id 
       WHERE u.id = ?`,
      [userId],
      {
        onResult: async (result) => {
          const row = result.rows?._array[0];
          if (row?.state === AttachmentState.SYNCED && row?.local_uri) {
            const buffer = await localStorage.readFile(row.local_uri);
            const nextUrl = URL.createObjectURL(
              new Blob([buffer], { type: row.media_type ?? 'image/jpeg' })
            );
            if (objectUrl) {
              URL.revokeObjectURL(objectUrl);
            }
            objectUrl = nextUrl;
            setPhotoUrl(nextUrl);
          }
        }
      }
    );
    
    return () => {
      watch.close();
      if (objectUrl) {
        URL.revokeObjectURL(objectUrl);
      }
    };
  }, [userId]);
  
  if (!photoUrl) {
    return <div>Loading photo...</div>;
  }
  
  return <img src={photoUrl} alt="Profile" />;
}

On the web SDK, local_uri is an internal indexeddb:// reference rather than a URL the browser can load. Passing it directly to an <img src> fails with net::ERR_UNKNOWN_URL_SCHEME. Read the file through the local storage adapter and convert it to an object URL first, as shown in the JavaScript/TypeScript example above. Native SDKs return a real file path that can be used directly.

Delete an Attachment

JavaScript/TypeScript

async function deleteProfilePhoto(userId: string, photoId: string) {
  await attachmentQueue.deleteFile({
    id: photoId,
    
    // updateHook ensures atomic deletion
    updateHook: async (tx, attachment) => {
      await tx.execute(
        'UPDATE users SET photo_id = NULL WHERE id = ?',
        [userId]
      );
    }
  });
  
  console.log('Photo queued for deletion');
  // The queue will:
  // 1. Delete from remote storage
  // 2. Delete local file
  // 3. Remove attachment record
}

// Alternative: Remove reference and let queue archive it automatically
async function removePhotoReference(userId: string) {
  await db.execute(
    'UPDATE users SET photo_id = NULL WHERE id = ?',
    [userId]
  );
  
  // The watchAttachments callback will detect this change
  // The queue will automatically archive the unreferenced attachment
  // After reaching archivedCacheLimit, it will be deleted
}

Advanced Topics

Error Handling

Implement custom error handling to control retry behavior:

JavaScript/TypeScript

import { AttachmentErrorHandler } from '@powersync/web';

const errorHandler: AttachmentErrorHandler = {
  async onDownloadError(attachment, error) {
    console.error(`Download failed: ${attachment.filename}`, error);
    
    // Return true to retry, false to archive
    if (error.message.includes('404')) {
      return false; // File doesn't exist, don't retry
    }
    return true; // Retry on network errors
  },
  
  async onUploadError(attachment, error) {
    console.error(`Upload failed: ${attachment.filename}`, error);
    return true; // Always retry uploads
  },
  
  async onDeleteError(attachment, error) {
    console.error(`Delete failed: ${attachment.filename}`, error);
    return true; // Retry deletes
  }
};

const queue = new AttachmentQueue({
  // ... other options
  errorHandler
});

Transferring Large Files Without Buffering

This section applies to the JavaScript/TypeScript SDK only.

The default attachment transport buffers the entire file in JS memory during a transfer. This limits the practical attachment size, particularly in React Native: a large video can exhaust the JS heap on lower-end devices. The Attachment Transport API removes this limit by streaming bytes directly between the file on disk and the network.

Streaming is opt-in. A local storage adapter paired with a remoteStorage always uses the default buffered path, on every platform. To stream instead, call the storage adapter’s createTransportAdapter method and pass the result as the queue’s transportAdapter:

• ExpoFileSystemStorageAdapter (@powersync/attachments-storage-react-native) - The transport streams with Expo’s native File.upload/File.downloadFileAsync. Using the transport requires Expo 56 or later; using only the storage adapter requires Expo 54
• ReactNativeFileSystemStorageAdapter (@powersync/attachments-storage-react-native) - The transport streams with uploadFiles/downloadFile from @dr.pogodin/react-native-fs, uploading as a raw binary PUT by default
• NodeFileSystemAdapter (@powersync/node) - The transport streams with fetch and Node.js filesystem streams

All three transports take the same options. resolveUpload and resolveDownload map an attachment to the HTTP request that transfers its bytes, typically a signed URL from your backend. deleteFile performs the remote delete, which is a plain remote call rather than a byte transfer.

import { AttachmentQueue } from '@powersync/react-native';
import { ExpoFileSystemStorageAdapter } from '@powersync/attachments-storage-react-native';

const localStorage = new ExpoFileSystemStorageAdapter();

// Streams bytes natively and owns upload/download/delete. No remoteStorage needed.
const transportAdapter = localStorage.createTransportAdapter({
  resolveUpload: async (attachment) => ({
    url: await getSignedUploadUrl(attachment.filename), // from your backend
    mimeType: attachment.mediaType ?? 'application/octet-stream'
  }),
  resolveDownload: async (attachment) => ({
    url: await getSignedDownloadUrl(attachment.filename)
  }),
  deleteFile: async (attachment) => {
    await deleteFromStorage(attachment.filename); // your backend or storage SDK call
  }
});

const attachmentQueue = new AttachmentQueue({
  db,
  localStorage,
  transportAdapter, // owns all remote operations; used in place of remoteStorage
  watchAttachments: (onUpdate) => {
    // Same as in Initialize Attachment Queue
  }
});

await attachmentQueue.startSync();

For files your app produces on disk (camera captures, recordings, exports), combine a native transport with saveFileFromUri. The file moves into managed storage and uploads without ever being read into memory; saveFile would read it into an ArrayBuffer just to write it back to disk.

Custom Storage Adapters

The following is an example of how to implement a custom storage adapter for IPFS:

JavaScript/TypeScript

import { LocalStorageAdapter, RemoteStorageAdapter } from '@powersync/web';

// Example: IPFS remote storage
class IPFSStorageAdapter implements RemoteStorageAdapter {
  async uploadFile(fileData: ArrayBuffer, attachment: AttachmentRecord) {
    // Upload to IPFS
    const cid = await ipfs.add(fileData);
    // Store CID in your backend for retrieval
    await fetch('/api/ipfs-cids', {
      method: 'POST',
      body: JSON.stringify({ attachmentId: attachment.id, cid })
    });
  }
  
  async downloadFile(attachment: AttachmentRecord): Promise<ArrayBuffer> {
    // Retrieve CID from backend
    const { cid } = await fetch(`/api/ipfs-cids/${attachment.id}`)
      .then(r => r.json());
    // Download from IPFS
    return ipfs.cat(cid);
  }
  
  async deleteFile(attachment: AttachmentRecord) {
    // IPFS is immutable, but you can unpin and remove from backend
    await fetch(`/api/ipfs-cids/${attachment.id}`, { method: 'DELETE' });
  }
}

Custom Transport Adapters

In the JavaScript/TypeScript SDK, you can also implement AttachmentTransportAdapter yourself. Because a transport owns the entire upload or download, it can do more than move bytes. Some use cases are:

• Resumable transfers - The queue retries a failed operation by calling the transport again on the next sync interval. A transport built on a resumable protocol such as tus or S3 multipart upload continues from the last confirmed offset instead of restarting from zero. Downloads can resume a partial file with HTTP Range requests
• Encryption - Encrypt files before upload and decrypt them after download for end-to-end encrypted attachments
• Platform-specific transfer APIs - Hand the transfer to an OS-level API, as the built-in React Native transports do

import {
  AttachmentRecord,
  AttachmentTransportAdapter,
  LocatedAttachmentRecord
} from '@powersync/web';

class ResumableTransportAdapter implements AttachmentTransportAdapter {
  async upload(attachment: LocatedAttachmentRecord): Promise<void> {
    // attachment.localUri points at the source file. Transfer it to remote
    // storage, e.g. in chunks that resume from the last confirmed offset
    // if a previous attempt was interrupted.
  }

  async download(attachment: LocatedAttachmentRecord): Promise<void> {
    // attachment.localUri is the destination path, assigned by the queue.
    // Fetch the remote file into it.
  }

  async delete(attachment: AttachmentRecord): Promise<void> {
    // Remove the file from remote storage.
  }
}

Throwing from any method marks the operation as failed; the queue retries it on the next sync interval, subject to your error handler.

Verification and Recovery

verifyAttachments() is always called internally during startSync().

This method does the following:

1. Verifies local files exist at expected paths
2. Repairs broken localUri references
3. Archives attachments with missing files
4. Requeues downloads for synced files with missing local copies

JavaScript/TypeScript

await attachmentQueue.verifyAttachments();

Cache Management

Control archived file retention:

JavaScript/TypeScript

const queue = new AttachmentQueue({
  // ... other options
  archivedCacheLimit: 200  // Keep 200 archived files; oldest deleted when limit reached
});

// For manually expiring the cache
queue.expireCache()

Offline-First Considerations

The attachment queue is designed for offline-first apps:

• Local-first operations - Files are saved locally immediately, synced later
• Automatic retry - Failed uploads/downloads retry when connection returns
• Queue persistence - Queue state survives app restarts
• Conflict-free - Files are immutable, identified by UUID
• Bandwidth efficient - Only syncs when needed, respects network conditions

Migrating From Deprecated Packages

If you are migrating from the now deprecated attachment helpers for Dart or JavaScript, follow the notes below:

powersync_attachments_helper (Dart)

A fairly simple migration from powersync_attachments_helper to the new utilities would be to adopt the new library with a different Attachment Queue table name and drop the legacy package. This means existing attachments are lost, but will be re-downloaded automatically.

@powersync/attachments (JS)

Import AttachmentTable and AttachmentQueue directly from your platform SDK (@powersync/web, @powersync/node, or @powersync/react-native), then remove @powersync/attachments from your dependencies.

React Native only: also install @powersync/attachments-storage-react-native plus either expo-file-system (Expo 54+) or @dr.pogodin/react-native-fs.

What changed:

Before (@powersync/attachments)	After (platform SDK)
AbstractAttachmentQueue subclass	AttachmentQueue instantiated directly
onAttachmentIdsChange(ids: string[])	watchAttachments — items must be { id, fileExtension }, not just IDs
newAttachmentRecord() + saveToQueue()	saveFile({ data, fileExtension, updateHook })
init()	startSync()
Single storage adapter	localStorage + remoteStorage (two separate adapters)
syncInterval	syncIntervalMs
cacheLimit	archivedCacheLimit
AttachmentTable option: name	viewName
AttachmentTable option: additionalColumns	Removed — use the built-in meta_data column (JSON string) instead
Error handlers return { retry: boolean }	Return Promise<boolean>; onDeleteError is now also required

Tip: use a different viewName (e.g. attachment_queue) to avoid a SQLite conflict with the old attachments table during the transition.

Data on existing users: the new local attachments table starts empty. Files already in remote storage will re-download automatically once referenced by your watchAttachments query. Files that were only ever stored locally and never uploaded have no remote copy and will not be recoverable.

Related Resources

• An Implementation Walkthrough Using The Flutter/Dart Attachment Helpers - Blog post on building offline-first uploads

---