🍉⚡ amplify-watermelondb-adapter

A WatermelonDB adapter for AWS Amplify DataStore

This adapter integrates WatermelonDB as a storage adapter for AWS Amplify DataStore, providing an alternative to the default SQLite adapter.

🎯 Overview

About AWS Amplify DataStore

AWS Amplify DataStore provides a programming model for leveraging shared and distributed data:

🔄 Automatic sync between cloud and local data
🔐 Built-in auth and conflict resolution
📊 GraphQL API integration
🌐 Cross-platform support - Web, React Native, iOS, Android

About WatermelonDB

WatermelonDB is a reactive database framework built for React and React Native applications:

😎 Lazy loading - Records load on demand
⚡ Native SQLite performance with JSI on React Native
✨ Fully reactive - UI updates automatically when data changes
📈 Designed for scale - Handles large datasets efficiently

Integration

This adapter allows you to use WatermelonDB as the storage engine for Amplify DataStore:

// Standard DataStore setup
import { DataStore } from '@aws-amplify/datastore';
import { SQLiteAdapter } from '@aws-amplify/datastore-storage-adapter';

DataStore.configure({
  storageAdapter: SQLiteAdapter
});

// With WatermelonDB adapter
import { WatermelonDBAdapter } from 'amplify-watermelondb-adapter';

DataStore.configure({
  storageAdapter: new WatermelonDBAdapter()
});

🚀 Platform Support

The adapter automatically selects the optimal storage engine for each platform:

Platform	Storage Engine	Features
React Native iOS/Android	JSI + SQLite	Native performance with JSI bridge
Web	LokiJS + IndexedDB	Browser-optimized with IndexedDB persistence
Node.js	better-sqlite3	Server-grade SQLite performance
Fallback	In-Memory	Development and testing scenarios

💡 Use Cases

This adapter is suitable for applications that:

📱 Use DataStore for offline-first functionality
📈 Work with large datasets or complex queries
⚡ Need reactive UI updates when data changes
🔄 Want WatermelonDB's performance benefits
🏗️ Require cross-platform compatibility

🛠️ Installation

npm install amplify-watermelondb-adapter @nozbe/watermelondb
# or
yarn add amplify-watermelondb-adapter @nozbe/watermelondb

🎯 Quick Start

Zero Configuration Setup

import { configureDataStoreWithWatermelonDB } from 'amplify-watermelondb-adapter';

// That's it! DataStore now uses WatermelonDB
configureDataStoreWithWatermelonDB();

// Use DataStore as normal - but faster!
const todos = await DataStore.query(Todo);

Migration from Existing Apps

Already using DataStore? Migration takes 2 minutes:

import { createFallbackConfiguration } from 'amplify-watermelondb-adapter';
import { SQLiteAdapter } from '@aws-amplify/datastore-storage-adapter';

// Your existing configuration
const config = {
  authProviders: { /* your auth */ },
  syncExpressions: [ /* your rules */ ]
};

// Automatic upgrade with fallback safety net
createFallbackConfiguration(
  config,
  SQLiteAdapter, // Falls back if needed
  { enableDebugLogging: true }
);

🔥 Advanced Features

🏢 Multi-Tenant Support

Integrates subscription variables from Amplify PR #14564 for multi-tenant GraphQL filtering.

import { WatermelonDBAdapter } from 'amplify-watermelondb-adapter';

const adapter = new WatermelonDBAdapter();

// Configure subscription variables for multi-tenant filtering
adapter.setSubscriptionVariables({
  tenantId: 'tenant-456',
  userId: 'user-789'
});

// Dynamic schema switching
adapter.setAlternativeSchema(alternativeSchema, () => {
  // Your logic to determine which schema to use
  return shouldUseAlternative() ? 'alternative' : 'primary';
});

📡 WebSocket Health Monitoring

Implements connection health monitoring from Amplify PR #14563 with auto-reconnection capabilities.

// Monitor WebSocket connection health
adapter.startWebSocketHealthMonitoring({
  interval: 30000, // 30 seconds
  onHealthCheck: (isHealthy) => {
    console.log(`WebSocket health: ${isHealthy ? '✅' : '❌'}`);
  },
  onReconnect: () => {
    console.log('Attempting WebSocket reconnection...');
  }
});

// Track keep-alive timestamps for debugging
adapter.trackKeepAlive(); // Stores in AsyncStorage

📊 Performance Monitoring

import { getWatermelonDBMetrics } from 'amplify-watermelondb-adapter';

// Monitor your performance gains
const metrics = getWatermelonDBMetrics();
console.log(`Dispatcher: ${metrics.dispatcherType}`); // "jsi" on RN
console.log(`Cache hits: ${metrics.cacheHitRate}%`); // Track efficiency

🎛️ Fine-Tuning

new WatermelonDBAdapter({
  // Optimize for your use case
  cacheMaxSize: 500,        // More cache for read-heavy apps
  cacheTTL: 60 * 60 * 1000, // 1 hour for stable data
  batchSize: 5000,          // Larger batches for bulk imports
  conflictStrategy: 'ACCEPT_REMOTE' // Your sync strategy
});

🔍 Enhanced Query Operators

Supports 'in' and 'notIn' operators from Amplify PR #14544 for advanced filtering.

// Query with 'in' operator
const priorityTasks = await DataStore.query(Todo, todo =>
  todo.priority.in([1, 2, 3])
);

// Query with 'notIn' operator
const nonUrgentTasks = await DataStore.query(Todo, todo =>
  todo.status.notIn(['urgent', 'critical'])
);

🔄 Reactive Queries

// WatermelonDB's magic: truly reactive queries
DataStore.observe(Todo).subscribe(msg => {
  // Component auto-updates when ANY todo changes
  // Even from different screens or background sync!
});

✨ Features

Core Features

🍉 WatermelonDB Integration - Seamlessly integrates with WatermelonDB's reactive architecture
🔌 Drop-in replacement - Minimal configuration changes required
📚 Full TypeScript - Complete type safety and IntelliSense
🔄 Automatic fallback - Falls back to in-memory storage if initialization fails
⚙️ Configurable - Customizable cache, batch size, and conflict resolution
🛠️ Development-friendly - Comprehensive error handling and debugging support
🍉 JSI Performance - Leverages WatermelonDB's JSI dispatcher on React Native
🚀 Cross-platform - Works on iOS, Android, Web, and Node.js
💾 Smart Caching - Built-in LRU cache with configurable TTL

🆕 Latest Features

🏢 Multi-Tenant Support - Dynamic schema switching for multi-tenant applications
📡 Subscription Variables - Filter GraphQL subscriptions per tenant/user (Amplify PR #14564)
🔌 WebSocket Health Monitoring - Auto-reconnection with health checks (Amplify PR #14563)
📝 Keep-Alive Tracking - Debug connection issues with AsyncStorage timestamps
🔍 Enhanced Operators - Full support for 'in' and 'notIn' query operators (Amplify PR #14544)

🎓 Examples

🍉 E-commerce App

// Query products with WatermelonDB's reactive performance
const products = await DataStore.query(Product,
  p => p.inStock.eq(true),
  { limit: 1000 }
);

🍉 Chat Application

// Real-time messaging with reactive updates
DataStore.observe(Message, m =>
  m.conversationId.eq(currentChat)
).subscribe(update => {
  // UI updates automatically when data changes
});

📊 Technical Specifications

Adapter performance characteristics from automated tests:

🍉 WatermelonDB Adapter Performance Metrics
==========================================

Operation                 | Average Time
--------------------------|-------------
Adapter Creation          | 0.03ms
Config Validation         | 0.05ms
Dispatcher Detection      | 0.01ms
Schema Version Lookup     | 0.02ms
Memory (1000 instances)   | 2.65MB
Concurrent Creation       | 500 adapters in 0.96ms

🔗 Compatibility

Compatible with:

🍉 AWS Amplify DataStore - v4.x and v5.x
🍉 GraphQL subscriptions - Full support
🍉 Multi-auth rules - All authentication strategies
🍉 Conflict resolution - Version-based and custom strategies
🍉 Schema migrations - Automatic schema handling
🍉 DataStore Selective Sync - Predicate-based syncing

📦 What's Included

🍉 WatermelonDBAdapter - Core adapter implementation
🔧 Integration helpers - Easy setup utilities
📊 Performance monitoring - Metrics collection
🔄 Migration tools - Upgrade from SQLiteAdapter
📚 TypeScript definitions - Full type safety
🎯 Examples - Real-world usage patterns

🚦 Getting Started

🍉 Install the package

npm install amplify-watermelondb-adapter @nozbe/watermelondb

🍉 Configure DataStore

import { configureDataStoreWithWatermelonDB } from 'amplify-watermelondb-adapter';
configureDataStoreWithWatermelonDB();

🍉 Start using DataStore - Same API, WatermelonDB performance!

📋 API Reference

New Methods

Method	Description
`setSubscriptionVariables(vars)`	Set GraphQL subscription filtering variables for multi-tenant support
`getSubscriptionVariables()`	Get current subscription variables
`setAlternativeSchema(schema, selector)`	Configure alternative schema for runtime switching
`startWebSocketHealthMonitoring(options)`	Start monitoring WebSocket connection health
`stopWebSocketHealthMonitoring()`	Stop WebSocket health monitoring
`trackKeepAlive()`	Store keep-alive timestamp in AsyncStorage

Core Methods

Method	Description
`setup(schema, ...)`	Initialize adapter with DataStore schema
`query(model, predicate, pagination)`	Query records with optional filtering
`save(model, condition)`	Save or update a model instance
`delete(model, condition)`	Delete model(s)
`observe(model, predicate)`	Subscribe to real-time changes
`batchSave(model, items)`	Efficiently save multiple items

📖 Documentation

🤔 FAQ

Q: Is this production-ready? A: Yes! The adapter has comprehensive test coverage and follows production-grade patterns.

Q: Does it support all DataStore features? A: Yes! The adapter implements the complete DataStore storage interface.

Q: What if WatermelonDB fails to initialize? A: The adapter automatically falls back to in-memory storage to prevent app crashes.

Q: What platforms are supported? A: iOS, Android, Web, and Node.js with automatic platform detection.

🛟 Support

🙏 Acknowledgments

🍉 AWS Amplify - For the DataStore framework
🍉 WatermelonDB - For the reactive database architecture
🍉 React Native - For cross-platform mobile development

📄 License

MIT License - See LICENSE file for details.

🍉 Built with WatermelonDB's reactive performance for Amplify DataStore 🍉

Bringing WatermelonDB's ⚡ performance to AWS Amplify DataStore 🍉

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
__tests__		__tests__
examples		examples
src		src
test		test
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
COMPATIBILITY.md		COMPATIBILITY.md
CONTRIBUTING.md		CONTRIBUTING.md
IMPROVEMENTS.md		IMPROVEMENTS.md
LICENSE		LICENSE
LICENSE-APACHE		LICENSE-APACHE
PRODUCTION_CHECKLIST.md		PRODUCTION_CHECKLIST.md
README.md		README.md
jest.config.js		jest.config.js
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

License

Licenses found

anivar/amplify-watermelondb-adapter

Folders and files

Latest commit

History

Repository files navigation