/mobile-storage-watermelondb

name: mobile-storage-watermelondb
description: WatermelonDB reactive local database for React Native - schema, models, decorators, reactive queries, relations, writers/readers, batch operations, migrations, sync

WatermelonDB Patterns

> **Quick Guide:** Use WatermelonDB for offline-first React Native apps with large local datasets. Define schemas with `appSchema`/`tableSchema`, models with decorators (`@field`, `@text`, `@date`, `@readonly`, `@relation`, `@children`). All writes MUST go through `@writer` methods or `database.write()`. Connect components reactively with `withObservables` from `@nozbe/watermelondb/react`. Use `batch()` for multi-record operations. Lazy loading means nothing is loaded until requested -- queries run on a native SQLite thread.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST wrap ALL database modifications in `@writer` methods or `database.write()` -- writes outside a writer throw at runtime)**

**(You MUST keep schema version and migration `toVersion` in sync -- migrations cannot be newer than the schema version)**

**(You MUST use `@immutableRelation` for relations that never change after creation -- it provides extra safety and performance over `@relation`)**

**(You MUST use `prepareCreate`/`prepareUpdate`/`prepareMarkAsDeleted` inside `batch()` -- never `await` individual operations in a batch)**

</critical_requirements>

---

**Auto-detection:** WatermelonDB, @nozbe/watermelondb, appSchema, tableSchema, @field, @text, @date, @readonly, @json, @nochange, @writer, @reader, @relation, @immutableRelation, @children, @lazy, withObservables, useDatabase, DatabaseProvider, observe, observeWithColumns, synchronize, pullChanges, pushChanges, schemaMigrations, Q.where, Q.on, database.write, database.batch, markAsDeleted, destroyPermanently

**When to use:**

• Building offline-first React Native apps with large local datasets (thousands+ records)
• Defining relational data models with typed fields and relations
• Connecting React components to live-updating database queries
• Syncing local data with a remote server via `synchronize()`
• Migrating database schema across app versions
• Performing bulk operations with `batch()`

**Key patterns covered:**

• Schema definition with `appSchema`/`tableSchema` and column types
• Model classes with field decorators (`@field`, `@text`, `@date`, `@readonly`, `@json`)
• Relations (`@relation`, `@immutableRelation`, `@children`, `@lazy`)
• Writers/readers for safe database mutations and reads
• Reactive components with `withObservables` and `observe()`/`observeWithColumns()`
• Query API with `Q.where`, `Q.on`, `Q.sortBy`, `Q.like`, `Q.oneOf`
• Batch operations for multi-record create/update/delete
• Schema migrations with `schemaMigrations`/`addColumns`/`createTable`
• Sync protocol with `synchronize()`, `pullChanges`, `pushChanges`

**When NOT to use:**

• Simple key-value storage (use a key-value store)
• Apps with small datasets that fit comfortably in memory
• Data that only lives on the server with no offline requirement
• Non-relational storage needs (flat preferences, tokens)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Schema, models, decorators, CRUD, queries, reactive components
• [examples/sync.md](examples/sync.md) - Sync protocol, migrations, batch operations
• [reference.md](reference.md) - API tables, decision framework, decorator reference

---

<philosophy>

Philosophy

WatermelonDB is a **reactive, lazy-loading** database built on SQLite for React Native apps that need to handle thousands of records without blocking the JS thread. The key insight: nothing is loaded until requested, and all querying runs on a separate native SQLite thread.

**Core principles:**

1. **Lazy by default** -- records are not loaded into JS memory until accessed. A collection with 10,000 records costs nothing until you query it. 2. **Reactive** -- `observe()` and `withObservables` push updates to components automatically when underlying data changes. No manual refetching. 3. **Schema-first** -- define your database structure with `appSchema`/`tableSchema`, then create Model classes that map to those tables via decorators. 4. **Writers enforce safety** -- all mutations must go through `@writer` or `database.write()`. This guarantees mutual exclusion -- only one writer runs at a time, preventing race conditions. 5. **Sync-ready** -- built-in `synchronize()` handles pull/push with conflict resolution, designed for offline-first architectures.

**Performance characteristics:**

| Scenario | Behavior | | ------------------------- | --------------------------------------------------- | | 10,000 records in a table | Zero JS cost until queried | | Complex query | Runs on native SQLite thread, resolves instantly | | List re-rendering | `observe()` emits only when matching records change | | Bulk operations | `batch()` groups into single native transaction |

**v0.27+ architecture:** All React helpers consolidated under `@nozbe/watermelondb/react` (replaces `@nozbe/with-observables`, `@nozbe/watermelondb/DatabaseProvider`, `@nozbe/watermelondb/hooks`). v0.28 requires React Native 0.74+ and Node.js 18+.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Schema Definition

Schemas define the database structure. Column types are `string`, `number`, or `boolean`. Use `isOptional: true` for nullable columns and `isIndexed: true` for query-heavy columns.

import { appSchema, tableSchema } from "@nozbe/watermelondb";

export const schema = appSchema({
  version: 1,
  tables: [
    tableSchema({
      name: "posts",
      columns: [
        { name: "title", type: "string" },
        { name: "body", type: "string" },
        { name: "subtitle", type: "string", isOptional: true },
        { name: "is_pinned", type: "boolean" },