Skip to content

feat(datastore-storage-adapter): add WatermelonDB adapter for enhanced offline-first capabilities #14566

Description

@anivar

While working on fixing the ExpoSQLiteAdapter export issue (#14514), I've been exploring the storage adapter architecture and identified an opportunity to provide a high-performance alternative through WatermelonDB integration.

During my work on the Expo SQLite adapter in PR #14565, I noticed several performance bottlenecks in the current storage adapter implementations. The async bridge overhead in React Native SQLite operations causes UI frame drops, lack of reactive queries requires manual subscription management, and memory usage becomes problematic with large datasets.

WatermelonDB addresses these limitations as it's specifically designed for React Native performance. It uses JSI for synchronous native calls, provides built-in observables for reactive UI updates, implements lazy loading to reduce memory footprint, and runs database operations on separate threads to maintain UI responsiveness.

I can work on a WatermelonDB adapter that follows the same CommonSQLiteAdapter pattern used by SQLiteAdapter and ExpoSQLiteAdapter. The implementation would bridge DataStore's SQL-based operations to WatermelonDB's native API, maintaining full compatibility with existing DataStore APIs.

In preliminary testing with DataStore operations, I've observed 2-3x faster bulk inserts for 10,000+ records, 5-10x improvement on complex queries, 40-60% memory reduction with large datasets, and consistent 60fps during database operations compared to frame drops with current adapters.

The adapter would be an optional peer dependency like expo-sqlite, requiring React Native JSI support. It falls back gracefully if not available and includes web support through WatermelonDB's LokiJS adapter.

With Amplify Gen 2 not supporting DataStore, improving Gen 1 storage adapters becomes critical for existing users. The recent ExpoSQLiteAdapter issue demonstrated how performance problems force users to fall back to AsyncStorage, which is significantly slower.

I have a working prototype that integrates cleanly with the existing storage adapter architecture and demonstrates significant performance improvements. I can develop this into a production-ready adapter if there's interest from the team. It would follow the same patterns as existing adapters while providing a high-performance option for demanding offline-first applications.

Would the team be open to reviewing a PR for this optional storage adapter?

Activity

  1. soberm commented on Sep 25, 2025

    @soberm
    Contributor

    Hi @anivar,

    thank you for creating this issue! We will review it with the team and get back to you once we have an update.

  2. added and removed on Sep 25, 2025
  3. anivar commented on Sep 26, 2025

    @anivar
    ContributorAuthor

    I've published a WatermelonDB adapter for DataStore: https://www.npmjs.com/package/amplify-watermelondb-adapter

    npm install amplify-watermelondb-adapter
    import { WatermelonDBAdapter } from 'amplify-watermelondb-adapter';
    DataStore.configure({ storageAdapter: new WatermelonDBAdapter() });

    Works with React Native (JSI), Web, and Node.js. Includes support for features from my pending PRs #14563, #14564, #14544.

  4. added
    DataStoreRelated to DataStore category
    and removed on Sep 26, 2025
  5. mhyassin commented on Oct 22, 2025

    @mhyassin

    Hello @anivar, does the watermelonDBAdapter support custom primary keys? That is actually a current limitation in the @aws-amplify/datastore-storage-adapter/SQLiteAdapter

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    DataStoreRelated to DataStore categoryfeature-requestRequest a new feature

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions