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

[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 https://github.com/aws-amplify/amplify-js/pull/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?

[soberm]

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.

[anivar]

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.

[mhyassin]

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