WatermelonDB

https://watermelondb.dev/docs
Admin
WatermelonDB is a reactive database framework for React and React Native apps that enables fast...
Tokens:70,084
Snippets:594
Trust Score:7.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Babel plugins for Web

Source: https://watermelondb.dev/docs/Installation

Install the required Babel plugins for decorators, class properties, and async/await support using yarn or npm.

```bash
yarn add --dev @babel/plugin-proposal-decorators  
yarn add --dev @babel/plugin-proposal-class-properties  
yarn add --dev @babel/plugin-transform-runtime  
  
# (or with npm:)  
npm install -D @babel/plugin-proposal-decorators  
npm install -D @babel/plugin-proposal-class-properties  
npm install -D @babel/plugin-transform-runtime  
```

--------------------------------

### Install Babel plugin for decorators

Source: https://watermelondb.dev/docs/Installation

Install the required Babel plugin for ES6 decorators support.

```bash
yarn add --dev @babel/plugin-proposal-decorators  
  
# (or with npm:)  
npm install -D @babel/plugin-proposal-decorators
```

--------------------------------

### Update native demo

Source: https://watermelondb.dev/docs/Implementation/Publishing

Update dependencies and start the native demo application.

```bash
cd examples/native  
yarn upgrade-interactive --latest  
yarn dev  
yarn start:ios  
yarn start:android  
```

--------------------------------

### Install metro-minify-terser

Source: https://watermelondb.dev/docs/Sync/Troubleshoot

Run this command to install the metro-minify-terser package, which is required to fix the React Native / UglifyES bug when importing Watermelon Sync.

```bash
yarn add metro-minify-terser  

```

--------------------------------

### Clone WatermelonDB source and install dependencies

Source: https://watermelondb.dev/docs/CONTRIBUTING

Downloads the WatermelonDB repository and installs its dependencies with Yarn.

```bash
git clone https://github.com/Nozbe/WatermelonDB.git  
cd WatermelonDB  
yarn  
```

--------------------------------

### Install better-sqlite3 peer dependency

Source: https://watermelondb.dev/docs/Installation

Commands to install the better-sqlite3 dependency using yarn or npm for NodeJS projects.

```bash
yarn add --dev better-sqlite3  
  
# (or with npm:)  
npm install -D better-sqlite3
```

--------------------------------

### Using synchronize() in your app

Source: https://watermelondb.dev/docs/Sync/Frontend

Example implementation of the synchronize function, including pullChanges and pushChanges handlers that communicate with a backend.

```javascript
import { synchronize } from '@nozbe/watermelondb/sync'  
  
async function mySync() {  
  await synchronize({  
    database,  
    pullChanges: async ({ lastPulledAt, schemaVersion, migration }) => {  
      const urlParams = `last_pulled_at=${lastPulledAt}&schema_version=${schemaVersion}&migration=${encodeURIComponent(  
        JSON.stringify(migration),  
      )}`  
      const response = await fetch(`https://my.backend/sync?${urlParams}`)  
      if (!response.ok) {  
        throw new Error(await response.text())  
      }  
  
      const { changes, timestamp } = await response.json()  
      return { changes, timestamp }  
    },  
    pushChanges: async ({ changes, lastPulledAt }) => {  
      const response = await fetch(`https://my.backend/sync?last_pulled_at=${lastPulledAt}`, {  
        method: 'POST',  
        body: JSON.stringify(changes),  
      })  
      if (!response.ok) {  
        throw new Error(await response.text())  
      }  
    },  
    migrationsEnabledAtVersion: 1,  
  })  
}  
```

--------------------------------

### Install WatermelonDB

Source: https://watermelondb.dev/docs/Installation

Add the WatermelonDB package to your project using yarn or npm.

```bash
yarn add @nozbe/watermelondb  
  
# (or with npm:)  
npm install @nozbe/watermelondb
```

--------------------------------

### Add simdjson to Podfile

Source: https://watermelondb.dev/docs/CHANGELOG

Required installation step for iOS in version 0.23.

```ruby
pod 'simdjson', path: '../node_modules/@nozbe/simdjson'
```

--------------------------------

### Define a database schema in model/schema.js

Source: https://watermelondb.dev/docs/Schema

Example of defining a schema with 'posts' and 'comments' tables using appSchema and tableSchema.

```javascript
// model/schema.js  
import { appSchema, tableSchema } from '@nozbe/watermelondb'  
  
export const mySchema = appSchema({  
  version: 1,  
  tables: [  
    tableSchema({  
      name: 'posts',  
      columns: [  
        { name: 'title', type: 'string' },  
        { name: 'subtitle', type: 'string', isOptional: true },  
        { name: 'body', type: 'string' },  
        { name: 'is_pinned', type: 'boolean' },  
      ]  
    }),  
    tableSchema({  
      name: 'comments',  
      columns: [  
        { name: 'body', type: 'string' },  
        { name: 'post_id', type: 'string', isIndexed: true },  
      ]  
    }),  
  ]  
})  
```

--------------------------------

### Create migrations file with schemaMigrations

Source: https://watermelondb.dev/docs/Advanced/Migrations

Initial setup for WatermelonDB migrations. Creates a migrations file that imports schemaMigrations and exports an empty migrations array. This file is later hooked into the SQLiteAdapter.

```javascript
// app/model/migrations.js  
  
import { schemaMigrations } from '@nozbe/watermelondb/Schema/migrations'  
  
export default schemaMigrations({  
  migrations: [  
    // We'll add migration definitions here later  
  ],  
})  

```

--------------------------------

### JSI crash backtrace example

Source: https://watermelondb.dev/docs/Installation

Example crash log showing a SIGSEGV error after updating React Native, likely due to broken libc++_shared. Run './gradlew clean' from native/android to fix.

```text
signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 0x79193ac4a9  
(...)  
backtrace:  
      (...)  
      watermelondb::createMethod(facebook::jsi::Runtime&, facebook::jsi::Object&, char const*, unsigned int, std::__ndk1::function<facebook::jsi::Value (facebook::jsi::Runtime&, facebook::jsi::Value const*)>)+88  
      watermelondb::Database::install(facebook::jsi::Runtime*)+96)  
      (...)  

```

--------------------------------

### Set up database with LokiJSAdapter for web

Source: https://watermelondb.dev/docs/Setup

Configures the WatermelonDB database for web using LokiJSAdapter instead of SQLiteAdapter. Includes optional useWebWorker, useIncrementalIndexedDB, dbName, and event handlers for quota exceeded and setup errors.

```javascript
import LokiJSAdapter from '@nozbe/watermelondb/adapters/lokijs'  
  
const adapter = new LokiJSAdapter({  
  schema,  
  // (You might want to comment out migrations for development purposes -- see Migrations documentation)  
  migrations,  
  useWebWorker: false,  
  useIncrementalIndexedDB: true,  
  // dbName: 'myapp', // optional db name  
  
  // --- Optional, but recommended event handlers:  
  
  onQuotaExceededError: (error) => {  
    // Browser ran out of disk space -- offer the user to reload the app or log out  
  },  
  onSetUpError: (error) => {  
    // Database failed to load -- offer the user to reload the app or log out  
  },  
  extraIncrementalIDBOptions: {  
    onDidOverwrite: () => {  
      // Called when this adapter is forced to overwrite contents of IndexedDB.  
      // This happens if there's another open tab of the same app that's making changes.  
      // Try to synchronize the app now, and if user is offline, alert them that if they close this  
      // tab, some data may be lost  
    },  
    onversionchange: () => {  
      // database was deleted in another browser tab (user logged out), so we must make sure we delete  
      // it in this tab as well - usually best to just refresh the page  
      if (checkIfUserIsLoggedIn()) {  
        window.location.reload()  
      }  
    },  
  }  
})  
  
// The rest is the same!  

```

--------------------------------

### Example of a changes object

Source: https://watermelondb.dev/docs/Sync/Backend

Shows the structure of a changes object with raw records for projects and tasks, including created, updated, and deleted arrays. Note that property names follow the Schema format (e.g., `is_favorite`).

```javascript
{
  projects: {
    created: [
      { id: 'aaaa', name: 'Foo', is_favorite: true },
      { id: 'bbbb', name: 'Bar', is_favorite: false },
    ],
    updated: [
      { id: 'ccc', name: 'Baz', is_favorite: true },
    ],
    deleted: ['ddd'],
  },
  tasks: {
    created: [],
    updated: [
      { id: 'tttt', name: 'Buy eggs' },
    ],
    deleted: [],
  },
  ...
}
```

--------------------------------

### Fetch Current Data with fetch and fetchCount

Source: https://watermelondb.dev/docs/Query

Use fetch and fetchCount to get the current list or count without observing future changes. Shortcut syntax is available for both.

```javascript
const comments = await post.comments.fetch()  
const verifiedCommentCount = await post.verifiedComments.fetchCount()  
  
// Shortcut syntax:  
const comments = await post.comments  
const verifiedCommentCount = await post.verifiedComments.count  

```

--------------------------------

### Q.on with multiple conditions on related table

Source: https://watermelondb.dev/docs/Query

Pass an array of conditions as the second argument to Q.on to apply multiple conditions on the related table. The example queries comments under posts written by John and either published or belonging to draftBlog.

```javascript
database.get('comments').query(  
  Q.on('posts', [  
    Q.where('author_id', john.id)  
    Q.or(  
      Q.where('published', true),  
      Q.where('blog_id', draftBlog.id),  
    )  
  ]),  
)  

```

--------------------------------

### Deploy web demo

Source: https://watermelondb.dev/docs/Implementation/Publishing

Deploy the updated web demo using now.

```bash
now  
now alias watermelondb-xxxxxxxxx.now.sh watermelondb  
```

--------------------------------

### Basic Turbo Login Implementation

Source: https://watermelondb.dev/docs/Sync/Frontend

Demonstrates how to configure synchronize with unsafeTurbo and handle raw text responses for the initial sync.

```javascript
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,  
  // ...  
})  
```

--------------------------------

### Initialize DatabaseProvider

Source: https://watermelondb.dev/docs/Components

Wrap your application with the DatabaseProvider to pass the database instance down the component tree without prop drilling.

```javascript
import { DatabaseProvider } from '@nozbe/watermelondb/react'  
  
// ...  
  
const database = new Database({  
  adapter,  
  modelClasses: [Blog, Post, Comment],  
})  
  
render(  
  <DatabaseProvider database={database}>  
    <Root />  
  </DatabaseProvider>, document.getElementById('application')  
)  
  
```

--------------------------------

### Build for manual testing

Source: https://watermelondb.dev/docs/Implementation/Publishing

Build the project to manually verify changes in a real application.

```bash
yarn build  
```

--------------------------------

### Update web demo

Source: https://watermelondb.dev/docs/Implementation/Publishing

Update dependencies and verify the web demo application.

```bash
cd ../web  
yarn upgrade-interactive --latest  
yarn dev  
# check out if web works  
```

--------------------------------

### Basic LocalStorage Operations

Source: https://watermelondb.dev/docs/Advanced/LocalStorage

Demonstrates setting, retrieving, and removing values using the database.localStorage API.

```javascript
// setting a value  
await database.localStorage.set("user_id", "abcdef")  
  
// retrieving a value  
const userId = await database.localStorage.get("user_id") // string or undefined if no value for this key  
  
// removing a value  
await database.localStorage.remove("user_id")
```

--------------------------------

### Define boolean columns

Source: https://watermelondb.dev/docs/Schema

Naming convention for boolean columns, which should start with is_.

```javascript
{ name: 'is_pinned', type: 'boolean' }  
```

--------------------------------

### Get a collection

Source: https://watermelondb.dev/docs/CRUD

Retrieve a Collection object for a given table name using database.get().

```javascript
const postsCollection = database.get('posts')  
```

--------------------------------

### Basic withObservables usage

Source: https://watermelondb.dev/docs/Components

Demonstrates the structure of withObservables, mapping input props to observable streams for a post and its comment count.

```javascript
withObservables(['post'], ({ post }) => ({  
  post: post.observe(),  
  commentCount: post.comments.observeCount()  
}))  
```

--------------------------------

### Get a relation ID

Source: https://watermelondb.dev/docs/Relation

Access the ID of a related record directly using the id property.

```javascript
const authorId = comment.author.id  
```

--------------------------------

### Use UUID generator with setGenerator

Source: https://watermelondb.dev/docs/Advanced/ProTips

To generate UUIDs, install the `uuid` package and pass its `v4` function to `setGenerator`.

```typescript
import { v4 as uuidv4 } from 'uuid';  
  
setGenerator(() => uuidv4());  

```

--------------------------------

### Publish package

Source: https://watermelondb.dev/docs/Implementation/Publishing

Publish the package using npm. Use the --skip-checks flag only for prereleases.

```bash
npm run release  
  
# skips checks (only use on prerelease)  
npm run release --skip-checks  
```

--------------------------------

### Register WatermelonDBJSIPackage in MainApplication.java

Source: https://watermelondb.dev/docs/Installation

Registers the WatermelonDB JSI package in the React Native host. Required for JSI installation on Android.

```java
// ...  
import com.nozbe.watermelondb.jsi.WatermelonDBJSIPackage; // ⬅️ This!  
import com.facebook.react.bridge.JSIModulePackage; // ⬅️ This!  
// ...  
private final ReactNativeHost mReactNativeHost =  
   new ReactNativeHost(this) {  
     // ...  

     @Override  
     protected JSIModulePackage getJSIModulePackage() {  
       return new WatermelonDBJSIPackage(); // ⬅️ This!  
     }  
   }  

```

--------------------------------

### Disable logging with logger.silence()

Source: https://watermelondb.dev/docs/Advanced/Logging

Import the logger from '@nozbe/watermelondb/utils/common/logger' and call silence() before app start, typically in database.js, to disable all logging.

```javascript
import logger from '@nozbe/watermelondb/utils/common/logger';  
logger.silence();  

```

--------------------------------

### Add Proguard rule for WatermelonDB JSI

Source: https://watermelondb.dev/docs/Installation

Keeps WatermelonDB JSI classes when using Proguard. Required for JSI installation on Android.

```proguard
-keep class com.nozbe.watermelondb.** { *; }  

```

--------------------------------

### Set up database with SQLiteAdapter in index.native.js

Source: https://watermelondb.dev/docs/Setup

Configures the WatermelonDB database for React Native (iOS/Android) and NodeJS using SQLiteAdapter. Includes optional dbName, jsi flag, and onSetUpError handler.

```javascript
import { Platform } from 'react-native'  
import { Database } from '@nozbe/watermelondb'  
import SQLiteAdapter from '@nozbe/watermelondb/adapters/sqlite'  
  
import schema from './model/schema'  
import migrations from './model/migrations'  
// import Post from './model/Post' // ⬅️ You'll import your Models here  
  
// First, create the adapter to the underlying database:  
const adapter = new SQLiteAdapter({  
  schema,  
  // (You might want to comment it out for development purposes -- see Migrations documentation)  
  migrations,  
  // (optional database name or file system path)  
  // dbName: 'myapp',  
  // (recommended option, should work flawlessly out of the box on iOS. On Android,  
  // additional installation steps have to be taken - disable if you run into issues...)  
  jsi: true, /* Platform.OS === 'ios' */  
  // (optional, but you should implement this method)  
  onSetUpError: error => {  
    // Database failed to load -- offer the user to reload the app or log out  
  }  
})  
  
// Then, make a Watermelon database from it!  
const database = new Database({  
  adapter,  
  modelClasses: [  
    // Post, // ⬅️ You'll add Models to Watermelon here  
  ],  
})  

```

--------------------------------

### Q.where with Q.column comparison

Source: https://watermelondb.dev/docs/Query

Queries records where a column value is compared to another column value instead of a constant. Example: comments with more likes than dislikes.

```APIDOC
## Q.where with Q.column comparison

### Description
Queries records where a column value is compared to another column value instead of a constant. Example: comments with more likes than dislikes.

### Method
query

### Parameters
- **table** (string) - Required - The table name (e.g., 'comments').
- **query** (Query) - Required - The query built with Q.where and Q.gt.

### Example
```
database.get('comments').query(  
  Q.where('likes', Q.gt(Q.column('dislikes')))  
)  
```
```

--------------------------------

### Custom queries with @lazy and Q.where

Source: https://watermelondb.dev/docs/Model

Extend a @children query with additional constraints using @lazy and Q.where. The example filters comments to only verified ones.

```javascript
import { children } from '@nozbe/watermelondb/decorators'  
import { Q } from '@nozbe/watermelondb'  
  
class Post extends Model {  
  static table = 'posts'  
  static associations = {  
    comments: { type: 'has_many', foreignKey: 'post_id' },  
  }  
  
  @children('comments') comments  
  @lazy verifiedComments = this.comments.extend(  
    Q.where('is_verified', true)  
  )  
}  

```

--------------------------------

### Initialize Database with actionsEnabled

Source: https://watermelondb.dev/docs/CHANGELOG

The Database constructor now requires the actionsEnabled option to be explicitly set to true or false.

```javascript
const database = new Database({  
  adapter: ...,  
  modelClasses: [...],  
  actionsEnabled: true  
})  

```

--------------------------------

### Query records

Source: https://watermelondb.dev/docs/CRUD

Query records using query().fetch() to get all records, or query().fetchCount() to count matching records. Use Q.where() to filter.

```javascript
const allPosts = await database.get('posts').query().fetch()  
const numberOfStarredPosts = await database.get('posts').query(  
  Q.where('is_starred', true)  
).fetchCount()  
```

--------------------------------

### Using SyncLogger and plain object for sync logging

Source: https://watermelondb.dev/docs/Sync/Frontend

Shows how to add logging to `synchronize()` by passing a `log` object. The first part uses the built-in `SyncLogger` to keep logs in memory and access them via `logger.logs` or `logger.formattedLogs`. The second part shows passing a plain object to `synchronize()` and reading `log.startedAt` and `log.finishedAt`. Note: logs may contain private user information; censor before displaying or sending.

```javascript
// Using built-in SyncLogger  
import SyncLogger from '@nozbe/watermelondb/sync/SyncLogger'  
const logger = new SyncLogger(10 /* limit of sync logs to keep in memory */ )  
await synchronize({ database, log: logger.newLog(), ... })  
  
// this returns all logs (censored and safe to use in production code)  
console.log(logger.logs)  
// same, but pretty-formatted to a string (a user can easy copy this for diagnostic purposes)  
console.log(logger.formattedLogs)  
  
  
// You don't have to use SyncLogger, just pass a plain object to synchronize()  
const log = {}  
await synchronize({ database, log, ... })  
console.log(log.startedAt)  
console.log(log.finishedAt)  
```

--------------------------------

### Add WatermelonDB JSI to android/settings.gradle

Source: https://watermelondb.dev/docs/Installation

Adds the WatermelonDB JSI native module to Gradle settings. Required for optional JSI installation to enable synchronous operations.

```gradle
include ':watermelondb-jsi'  
project(':watermelondb-jsi').projectDir =  
    new File(rootProject.projectDir, '../node_modules/@nozbe/watermelondb/native/android-jsi')  

```

--------------------------------

### Writer methods with @writer

Source: https://watermelondb.dev/docs/Model

Define methods that modify the database. Must be marked with @writer. The example shows a method that updates a comment's isSpam field.

```javascript
import { writer } from '@nozbe/watermelondb/decorators'  
  
class Comment extends Model {  
  static table = 'comments'  
  
  @field('is_spam') isSpam  
  
  @writer async markAsSpam() {  
    await this.update(comment => {  
      comment.isSpam = true  
    })  
  }  
}  

```

--------------------------------

### Create model/migrations.js with schemaMigrations

Source: https://watermelondb.dev/docs/Setup

Defines the migrations schema with an empty migrations array. This file is required for the next steps.

```javascript
import { schemaMigrations } from '@nozbe/watermelondb/Schema/migrations'  
  
export default schemaMigrations({  
  migrations: [  
    // We'll add migration definitions here later  
  ],  
})  

```

--------------------------------

### Add JSI dependency and packaging options to android/app/build.gradle

Source: https://watermelondb.dev/docs/Installation

Adds the WatermelonDB JSI project as a dependency and ensures libc++_shared is picked first. Required for JSI installation on Android.

```gradle
// ...  
android {  
  // ...  
  packagingOptions {  
     pickFirst '**/libc++_shared.so' // ⬅️ This (if missing)  
  }  
}  

dependencies {  
    // ...  
    implementation project(':watermelondb-jsi') // ⬅️ This!  
}  

```

--------------------------------

### Run React Native Windows autolinking

Source: https://watermelondb.dev/docs/Installation

Execute the autolinking command to set up WatermelonDB for React Native Windows.

```bash
npx react-native autolink-windows
```

--------------------------------

### Create a new record

Source: https://watermelondb.dev/docs/CRUD

Use create() with a builder function to set field values. Always await the returned Promise before accessing the record.

```javascript
const newPost = await database.get('posts').create(post => {  
  post.title = 'New post'  
  post.body = 'Lorem ipsum...'  
})  
```

--------------------------------

### Check unsynced changes with hasUnsyncedChanges

Source: https://watermelondb.dev/docs/Sync/Frontend

Use this function to check if there are any unsynced changes. It requires a database instance and returns a promise. The example shows a typical frontend usage.

```javascript
import { hasUnsyncedChanges } from '@nozbe/watermelondb/sync'  
  
async function checkUnsyncedChanges() {  
  const database = useDatabase()  
  await hasUnsyncedChanges({ database })  
}  

```
Tokens:
Raw