# NitromelonDB

> NitromelonDB (npm: `nitromelondb`) is a reactive, lazy-loading SQLite database for React Native, web, Node.js and Electron. It's a maintained fork of WatermelonDB with the same model: schema, `Model` classes with decorators, observable queries, and offline-first sync with your own backend. Native SQLite runs through Nitro Modules on the React Native New Architecture.

Things to get right when writing code with NitromelonDB:

- Import from `nitromelondb` (`nitromelondb/decorators`, `nitromelondb/hooks`, `nitromelondb/adapters/sqlite`), not `@nozbe/watermelondb`. Existing WatermelonDB schemas, models and SQLite files keep working; see Migrating from WatermelonDB.
- React Native New Architecture only (RN 0.83+). Expo is supported through the `nitromelondb` config plugin in development builds and EAS; Expo Go is not.
- Models use legacy decorators: `@babel/plugin-proposal-decorators` with `{ legacy: true }`.
- Every create, update and delete must run inside a writer: `database.write(async () => ...)` or a `@writer` method on a model.
- Don't call `database.write()` / `database.read()` (or a `@writer` / `@reader` method) from inside another writer or reader and wait for it; that deadlocks. Use `writer.callWriter(() => ...)` / `reader.callReader(() => ...)`. Pass `experimentalDetectNestedWriters: __DEV__` to `new Database()` to turn the mistake into an error during development.
- For UI, observe instead of fetching once: `withObservables` or the hooks in `nitromelondb/hooks` (`useQuery`, `useRecord`, `useWriter`).
- For whole jobs, use the agent skills in the repository's `skills/` folder (`npx skills add StasDoskalenko/NitromelonDB`): `nitromelondb-install` (a new install: packages, platform setup, schema, models, Database and a data layer on hooks), `nitromelondb-schema` (design the schema, and every later change with its migration), `nitromelondb-sync` (backend endpoints and the app's sync engine), `nitromelondb-migrate-from-watermelondb`, `nitromelondb-migrate-decorators`, `nitromelondb-audit` (setup gaps and misuse) and `nitromelondb-indexes` (missing indexes, with the migration). See Agent skills. For writing app code by hand, follow Performance: Building a fast app.
- Each link below points to a plain Markdown version of the page. `llms-full.txt` next to this file has the full text of every page except the Optional section.

## About

- [Check out the README](https://stasdoskalenko.github.io/NitromelonDB/docs/README.md): What NitromelonDB is, why the fork exists, how to install it, and its features.
- [Migrating from WatermelonDB](https://stasdoskalenko.github.io/NitromelonDB/docs/Migrating.md): Move an app from @nozbe/watermelondb to nitromelondb: swap packages and imports, remove the old native setup, update the adapter, and rebuild.
- [Agent skills](https://stasdoskalenko.github.io/NitromelonDB/docs/AgentSkills.md): Skills for AI coding agents (Claude Code, Cursor, Codex and others): install NitromelonDB in an app, design and change its schema, build sync, migrate from WatermelonDB, move to standard decorators, audit an app's setup, and find missing indexes.

## Setup

- [Installation](https://stasdoskalenko.github.io/NitromelonDB/docs/Installation.md): Install NitromelonDB on bare React Native, Expo (including Expo web), web bundlers, Windows, Node.js and Electron. Requirements and troubleshooting.
- [Setup](https://stasdoskalenko.github.io/NitromelonDB/docs/Setup.md): Create the adapter and the Database for React Native, Node.js, Electron and the web, and initialize the database.
- [Schema](https://stasdoskalenko.github.io/NitromelonDB/docs/Schema.md): Define the database schema: tables, column types, naming conventions, special columns, indexing, and unsafe SQL.
- [Model](https://stasdoskalenko.github.io/NitromelonDB/docs/Model.md): Define Model classes: associations, fields, dates, derived fields, relations, children, custom queries and writer methods.
- [Migrations](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/Migrations.md): Schema migrations: add tables and columns to an existing database, the migration workflow, the migrations API, and unsafe SQL migrations.

## Usage

- [Relations](https://stasdoskalenko.github.io/NitromelonDB/docs/Relation.md): Relations between records: relation and immutableRelation, observing, fetching and assigning, and many-to-many.
- [Create, Read, Update, Delete](https://stasdoskalenko.github.io/NitromelonDB/docs/CRUD.md): Read, create, update and delete records, delete everything matching a query, reset the database on logout, and run unsafe raw SQL.
- [Connecting Components](https://stasdoskalenko.github.io/NitromelonDB/docs/Components.md): Connect React components to the database with withObservables: reactive records, lists, relations and counts, plus DatabaseProvider and useDatabase.
- [React Hooks](https://stasdoskalenko.github.io/NitromelonDB/docs/Hooks.md): React hooks from nitromelondb/hooks: useQuery, useRecord, useWriter, useAtomicWriter, useObservable and useDatabaseReady, and which one to use.
- [Querying](https://stasdoskalenko.github.io/NitromelonDB/docs/Query.md): Query API: Q conditions and operators, LIKE, AND / OR nesting, conditions on related tables (JOINs), advanced clauses, and observing queries.
- [Writers, Readers, Batching](https://stasdoskalenko.github.io/NitromelonDB/docs/Writers.md): All changes must run inside database.write() or a @writer method. Batching, deletes, readers, and nesting with callWriter() / callReader().

## Sync

- [Intro](https://stasdoskalenko.github.io/NitromelonDB/docs/Sync/Intro.md): Overview of syncing NitromelonDB with your own backend, and where to start.
- [Frontend](https://stasdoskalenko.github.io/NitromelonDB/docs/Sync/Frontend.md): Call synchronize() in the app: pullChanges / pushChanges, paginated pulls, unsynced changes, migration syncs, Turbo Login, logging, and replacement sync.
- [Backend](https://stasdoskalenko.github.io/NitromelonDB/docs/Sync/Backend.md): Implement the pull and push endpoints on your server: the changes object format and server-side change tracking.
- [Limitations](https://stasdoskalenko.github.io/NitromelonDB/docs/Sync/Limitations.md): Known limitations of the current sync protocol.
- [FAQ](https://stasdoskalenko.github.io/NitromelonDB/docs/Sync/FAQ.md): Sync FAQ: building your own sync from the primitives, syncing a lot of data, and local vs remote IDs.
- [Troubleshoot](https://stasdoskalenko.github.io/NitromelonDB/docs/Sync/Troubleshoot.md): Fixes for sync problems: a release build failure (UglifyES), interrupted paginated pulls, and the paginated pull warnings.
- [Contribute](https://stasdoskalenko.github.io/NitromelonDB/docs/Sync/Contribute.md): How to help improve NitromelonDB sync.

## Advanced

- [Automatic create/update tracking](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/CreateUpdateTracking.md): Add created_at / updated_at columns that NitromelonDB fills in automatically on create and update.
- [Advanced Fields](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/AdvancedFields.md): Field decorators beyond the basics: @json, @nochange, @readonly, and custom observable fields.
- [Decorators](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/StandardDecorators.md): NitromelonDB models work with legacy decorators (the default, no Babel setup on Expo) and with standard TC39 decorators and the accessor keyword. Setup for both, moving between them, and what to do when decorators don't work.
- [Custom Collections](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/CustomCollections.md): Subclass Collection to add table-level methods: writer and reader rules, the constructor contract, and TypeScript typing.
- [Flow](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/Flow.md): Flow types are no longer shipped. NitromelonDB is written in TypeScript.
- [LocalStorage](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/LocalStorage.md): A simple key/value store inside the database, similar to localStorage, for small bits of app state.
- [Database seeding](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/Seeding.md): databaseSeed(): populate initial or demo data tied to schema versions, with retries, onError / onDone hooks, and readiness APIs.
- [Pro Tips](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/ProTips.md): Database viewer, checking the SQLite version, prepopulating a database on native, and overriding the record ID generator.
- [Observability](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/Observability.md): Make nested writers, stuck readers and writers, and queue problems fail loudly: detection, stuck warnings, logging, and a setup checklist.
- [Logging](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/Logging.md): Disable or override NitromelonDB's built-in logging.
- [Detect nested writers (deadlock prevention)](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/DetectNestedWriters.md): experimentalDetectNestedWriters turns a forgotten callWriter() / callReader() into an error instead of a deadlock. What it detects, how it works per platform, caveats and performance.
- [Performance](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/Performance.md): Build a fast NitromelonDB app: observing, lists, writes, batching, indexes, setup and sync patterns, and storing whole numbers as integers (opt-in).
- [iOS - Sharing database across targets](https://stasdoskalenko.github.io/NitromelonDB/docs/Advanced/SharingDatabaseAcrossTargets.md): Share one database between iOS targets (app extensions, widgets) through an App Group, from JS or from native code.

## Optional

- [Architecture](https://stasdoskalenko.github.io/NitromelonDB/docs/Implementation/Architecture.md): Internal architecture: the base objects (Database, Collection, Model, Query, adapters) and helper functions.
- [Database Adapters](https://stasdoskalenko.github.io/NitromelonDB/docs/Implementation/DatabaseAdapters.md): How database adapters work and how to add a new platform or database.
- [Publishing NitromelonDB](https://stasdoskalenko.github.io/NitromelonDB/docs/Implementation/Publishing.md): How NitromelonDB releases are prepared and published to npm through GitHub Actions.
- [Sync implementation](https://stasdoskalenko.github.io/NitromelonDB/docs/Implementation/SyncImpl.md): Sync internals: general design, the sync procedure, migration syncs, and implementing sync from scratch.
- [wa-sqlite web adapter](https://stasdoskalenko.github.io/NitromelonDB/docs/Implementation/WaSQLiteAdapter.md): Internals of the wa-sqlite web adapter: platform selection, worker architecture, persistence, and initialization ordering.
- [Roadmap](https://stasdoskalenko.github.io/NitromelonDB/docs/Roadmap.md): WatermelonDB's roadmap toward 1.0, inherited from upstream.
- [Contributing](https://stasdoskalenko.github.io/NitromelonDB/docs/CONTRIBUTING.md): Contributing to NitromelonDB: running it in development, tests, native code, and Maestro e2e.
- [Changelog](https://stasdoskalenko.github.io/NitromelonDB/docs/CHANGELOG.md): Release notes for every NitromelonDB version.