# WatermelonDB — Reactive Database for React Native Apps

> A high-performance reactive database framework for React Native and React web apps, built on top of SQLite with lazy loading and sync primitives.

## Install

Save in your project root:

# WatermelonDB — Reactive Database for React Native Apps

## Quick Use
```bash
npm install @nozbe/watermelondb
npm install @nozbe/with-observables
```
```js
import { Database } from '@nozbe/watermelondb';
import SQLiteAdapter from '@nozbe/watermelondb/adapters/sqlite';

const adapter = new SQLiteAdapter({ schema, migrations });
const database = new Database({ adapter, modelClasses: [Post, Comment] });
```

## 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

---
Source: https://tokrepo.com/en/workflows/5792a73b-429a-11f1-9bc6-00163e2b0d79
Author: AI Open Source