WatermelonDB

WatermelonDB is a reactive database framework designed for React and React Native applications that need to scale from hundreds to tens of thousands of records while maintaining high performance.

Unlike traditional approaches (like Redux or MobX with persistence) that load the entire database into JavaScript memory—which can cause slow app launches—WatermelonDB is lazy loaded. It only loads data when it is explicitly requested. Most querying is performed directly on a SQLite foundation on a separate native thread, ensuring the main thread remains responsive.

Key Features:

• Scalability: Handles large datasets efficiently.
• Lazy Loading: Minimizes initial load time and memory usage.
• Offline-first: Supports synchronization with your own backend.
• Multiplatform: Works on iOS, Android, Windows, web, and Node.js.
• Reactive: Uses an observable pattern (optionally via RxJS) so UI components automatically re-render when underlying data changes.

WatermelonDB query operators (like Q.gt, Q.lt, Q.oneOf, Q.notIn, Q.like) follow SQLite semantics, which differ from JavaScript regarding null values.

Key Rules:

• No null comparisons: Standard operators do not match null. For example, Q.where('likes', Q.lt(10)) will include records where likes is 0, but not where likes is null.
• Column comparisons: Q.where('likes', Q.gt(Q.column('dislikes'))) will only return records where both columns are non-null.
• oneOf / notIn: To include null values in a oneOf query, you must explicitly use Q.or with a null check. Similarly, notIn will not match records where the column is null.

The Solution: Q.weakGt

If you need to treat null as being less than any number (matching JavaScript behavior), use the Q.weakGt operator. For weakGt, any number is considered greater than null.

// To include nulls in a oneOf query:
postsCollection.query(
  Q.or(
    Q.where('status', Q.oneOf(['published', 'draft'])),
    Q.where('status', null)
  )
)

// Using weakGt to allow null comparisons:
// This WILL match comments where likes is 5 and dislikes is null
commentsCollection.query(
  Q.where('likes', Q.weakGt(Q.column('dislikes')))
)

Turbo Login is an advanced optimization for the initial (login) sync that can be up to 5.3x faster and more memory-efficient. It is intended for very large datasets.

Constraints & Requirements:

• Use Case: Only for the first sync when the database is empty. Using it on an existing database is a serious error.
• Data Format: pullChanges must return the raw JSON text via the syncJson key, rather than a parsed object.
• Environment: Only works with SQLiteAdapter with JSI enabled. It does NOT work on the web or when Chrome Remote Debugging is enabled.
• API Status: Marked as unsafe (the API may change).

Implementation Pattern: Set unsafeTurbo: true in the synchronize options. In pullChanges, if useTurbo is true, return { syncJson: rawJsonText } instead of the standard { changes, timestamp } object.

Handling Extra Data: Since you cannot process JSON in pullChanges during a Turbo sync, use the onDidPullChanges callback to process additional metadata or messages sent from the server.

const isFirstSync = ...
const useTurbo = isFirstSync

await synchronize({
  database,
  pullChanges: async ({ lastPulledAt, schemaVersion, migration }) => {
    const response = await fetch(`https://my.backend/sync?${...}`)
    if (!response.ok) {
      throw new Error(await response.text())
    }

    if (useTurbo) {
      // NOTE: DO NOT parse JSON, we want raw text
      const json = await response.text()
      return { syncJson: json }
    } else {
      const { changes, timestamp } = await response.json()
      return { changes, timestamp }
    }
  },
  unsafeTurbo: useTurbo,
  onDidPullChanges: async ({ messages }) => {
    if (messages) {
      messages.forEach((message) => {
        alert(message)
      })
    }
  },
})

Understanding how WatermelonDB handles schema mismatches and failures is critical for data safety:

• No migrations used: If you change the schema version without providing migrations, the database will be cleared (reset) at launch.
• Migration failure: If a migration fails (e.g., trying to create a table that already exists), the database will fail to initialize and roll back to the previous version rather than resetting. This prevents accidental data loss.
• Newer database version: If the database on the device has a version newer than the version defined in your code, the database will be reset.
• Missing migration path: If a user's database version is higher than the latest available migration (e.g., user is on v4, but your migrations only go up to v3), the database will be reset.

Rolling back changes in development

If you make a mistake during development, follow this order to reset the database to its previous state:

1. Comment out changes in schema.js.
2. Comment out changes in migrations.js.
3. Decrement the schema version number in schema.js to its original value.
4. Refresh the app.

All database modifications (create, update, delete) must be performed within a Writer. If you attempt to modify data outside of a writer, the operation will fail.

There are two ways to implement a writer:

1. Inline via database.write(): Wrap your logic in an async callback passed to database.write().
2. Model Decorator via @writer: Define a method on your Model class and decorate it with @writer from @nozbe/watermelondb/decorators. This is the preferred way to encapsulate model-specific logic.

Note: Refer to the Writers documentation for more details.

// Option 1: Using database.write()
await database.write(async () => {
  const someComment = await database.get('comments').find(commentId)
  await someComment.update((comment) => {
    comment.isSpam = true
  })
})

// Option 2: Using @writer decorator on a Model
import { writer } from '@nozbe/watermelondb/decorators'

class Comment extends Model {
  @writer async markAsSpam() {
    await this.update(comment => {
      comment.isSpam = true
    })
  }
}