WatermelonDB — Reactive Database for React Native Apps

Introduction

WatermelonDB is a reactive database framework purpose-built for React Native and React web applications that need to handle thousands of records without sacrificing UI performance. It stores data in SQLite on mobile and IndexedDB/LokiJS on the web, only loading what the UI actually needs through lazy evaluation.

What WatermelonDB Does

• Provides a reactive data layer that re-renders components only when their observed records change
• Stores data in SQLite (mobile) or LokiJS/IndexedDB (web) with a unified API
• Lazy-loads records so large datasets do not block app startup
• Includes a sync engine for pulling and pushing changes to a remote server
• Supports schema migrations for evolving database structure across app versions

Architecture Overview

WatermelonDB defines models as JavaScript classes mapped to database tables. Queries return observable collections; when a record changes, only the subscribed components re-render. On React Native, a JSI-based SQLite adapter runs queries on a native thread, keeping the JS thread free. The sync protocol sends only changed records since the last pull timestamp.

Self-Hosting & Configuration

• Install the npm packages and configure the native SQLite adapter for React Native
• Define schemas and models in JavaScript; migrations handle upgrades
• The sync adapter expects a server endpoint that implements pull/push with a last-synced timestamp
• On web, choose between LokiJS (in-memory with persistence) or IndexedDB adapters
• Enable the JSI adapter on React Native for significantly faster query performance

Key Features

• Lazy record loading prevents large datasets from blocking the UI thread
• Observable-based reactivity integrates naturally with React component lifecycle
• Built-in sync protocol with conflict resolution for offline-first apps
• JSI-powered SQLite adapter delivers near-native query speed on mobile
• Automatic batching groups writes into single transactions for efficiency

Comparison with Similar Tools

• Realm — custom storage engine with its own sync service; WatermelonDB sits on SQLite and lets you bring your own backend
• RxDB — targets all JS runtimes; WatermelonDB is optimized specifically for React component reactivity
• SQLite direct — raw SQL without reactive bindings; WatermelonDB adds model layer, observables, and sync
• Firebase — cloud-first with vendor lock-in; WatermelonDB is local-first with pluggable sync

FAQ

Q: Does WatermelonDB work on the web? A: Yes. It supports LokiJS and IndexedDB adapters for browser environments alongside its SQLite adapter for React Native.

Q: How does sync work? A: You implement a pull and push endpoint. WatermelonDB sends a last-synced timestamp; the server returns created, updated, and deleted records since that time.

Q: Can I use it without React? A: The core database works independently, but the reactive layer is designed around React observables and higher-order components.

Q: How many records can it handle? A: WatermelonDB is tested with hundreds of thousands of records. Lazy loading ensures the app stays fast regardless of total data size.

Sources

• https://github.com/Nozbe/WatermelonDB
• https://watermelondb.dev