WatermelonDB README

The project's README from github.com/Nozbe/WatermelonDB. As one markdown file: README.md.

WatermelonDB

A reactive database framework

Build powerful React and React Native apps that scale from hundreds to tens of thousands of records and remain fast ⚡️

MIT License npm Gurubase

WatermelonDB
⚡️ Launch your app instantly no matter how much data you have
📈 Highly scalable from hundreds to tens of thousands of records
😎 Lazy loaded. Only load data when you need it
🔄 Offline-first. Sync with your own backend
📱 Multiplatform. iOS, Android, Windows, web, and Node.js
⚛️ Optimized for React. Easily plug data into components
🧰 Framework-agnostic. Use JS API to plug into other UI frameworks
⏱ Fast. And getting faster with every release!
✅ Proven. Powers Nozbe since 2017 (and many others)
✨ Reactive. (Optional) RxJS API
🔗 Relational. Built on rock-solid SQLite foundation
⚠️ Static typing with Flow or TypeScript

Why Watermelon?

WatermelonDB is a new way of dealing with user data in React Native and React web apps.

It's optimized for building complex applications in React Native, and the number one goal is real-world performance. In simple words, your app must launch fast.

For simple apps, using Redux or MobX with a persistence adapter is the easiest way to go. But when you start scaling to thousands or tens of thousands of database records, your app will now be slow to launch (especially on slower Android devices). Loading a full database into JavaScript is expensive!

Watermelon fixes it by being lazy. Nothing is loaded until it's requested. And since all querying is performed directly on the rock-solid SQLite database on a separate native thread, most queries resolve in an instant.

But unlike using SQLite directly, Watermelon is fully observable. So whenever you change a record, all UI that depends on it will automatically re-render. For example, completing a task in a to-do app will re-render the task component, the list (to reorder), and all relevant task counters. Learn more.

React Native EU: Next-generation React Databases

📺 Next-generation React databases
(a talk about WatermelonDB)

Usage

Quick (over-simplified) example: an app with posts and comments.

First, you define Models:

class Post extends Model {
  @field('name') name
  @field('body') body
  @children('comments') comments
}

class Comment extends Model {
  @field('body') body
  @field('author') author
}

Then, you connect components to the data:

const Comment = ({ comment }) => (
  <View style={styles.commentBox}>
    <Text>{comment.body} — by {comment.author}</Text>
  </View>
)

// This is how you make your app reactive! ✨
const enhance = withObservables(['comment'], ({ comment }) => ({
  comment,
}))
const EnhancedComment = enhance(Comment)

And now you can render the whole Post:

const Post = ({ post, comments }) => (
  <View>
    <Text>{post.name}</Text>
    <Text>Comments:</Text>
    {comments.map(comment =>
      <EnhancedComment key={comment.id} comment={comment} />
    )}
  </View>
)

const enhance = withObservables(['post'], ({ post }) => ({
  post,
  comments: post.comments
}))

The result is fully reactive! Whenever a post or comment is added, changed, or removed, the right components will automatically re-render on screen. Doesn't matter if a change occurred in a totally different part of the app, it all just works out of the box!

➡️ Learn more: see full documentation

Who uses WatermelonDB

Nozbe Teams
CAPMO
Mattermost
Rocket Chat
Steady
Aerobotics
Smash Appz
HaloGo
SportsRecruits
Chatable
Todorant
Blast Workout
Dayful
Learn The Words
ezypack

Does your company or app use 🍉? Open a pull request and add your logo/icon with link here!

Contributing

We need you

WatermelonDB is an open-source project and it needs your help to thrive!

If there's a missing feature, a bug, or other improvement you'd like, we encourage you to contribute! Feel free to open an issue to get some guidance and see Contributing guide for details about project setup, testing, etc.

If you're just getting started, see good first issues that are easy to contribute to. If you make a non-trivial contribution, email me, and I'll send you a nice 🍉 sticker!

If you make or are considering making an app using WatermelonDB, please let us know!

Author and license

WatermelonDB was created by @Nozbe.

WatermelonDB's main author and maintainer is Radek Pietruszewski (website ⋅ 𝕏 (Twitter))

See all contributors.

WatermelonDB is available under the MIT license. See the LICENSE file for more info.

WatermelonDB (Nozbe/WatermelonDB)

reactive
Searching Database…

11.8K ·GitHub
WatermelonDB
What is this?WatermelonDB is a reactive, asynchronous database framework for building React and React Native apps that stay fast even when they hold tens of thousands of records.
Is this a database engine or a layer on top of one?It's a framework-agnostic JS API built on top of SQLite, giving you a model-based, ORM-like layer with lazy loading and reactive queries instead of a database engine of its own.
How do I add it to a React Native or React web project?You define Models describing your tables, then connect your React components to that data; WatermelonDB wires the two together so the right parts of the UI update when the underlying records change.
Do I need Flow or TypeScript to use it?No, plain JavaScript works since the core is a JS API, but the project supports static typing with Flow or TypeScript if you want it, and it depends on packages like @nozbe/sqlite and rxjs under the hood.
Is RxJS mandatory to get reactive updates?No, RxJS is optional — the reactive behavior works through WatermelonDB's own observable system, and RxJS is only an extra API on top for those who want it.
Which platforms can I target with it?It runs on iOS, Android, Windows, web, and Node.js, covering both React Native apps and React web apps from one codebase.
Does it work without a network connection?Yes, it's offline-first — data lives locally in SQLite and you sync it with your own backend whenever a connection is available.
Why not just use Redux or MobX with a persistence adapter?Those work fine for simple apps, but loading a whole database into JavaScript gets slow as records grow into the thousands. WatermelonDB avoids this by being lazy and querying SQLite directly on a separate native thread, so app launch stays fast at scale.
What happens in the UI when I update a record?Every component subscribed to that data automatically re-renders — for example, completing a to-do updates the task row, the reordered list, and any counters, even if they live in unrelated parts of the app.
Is WatermelonDB actually used in production?Yes, it has powered Nozbe's own apps since 2017 and is maintained by Radek Pietruszewski alongside other contributors.
What are similar projects?rxdb, typeorm, realm-swift, formily, instant, feathers, react-native-elements, spacedrive
Which topics is it in?persistence, rxjs, reactive, sync, orm, offline-first, react-native, real-time, offline, sqlite, local-first, hacktoberfest
Creator
Nozbe
Size
29.9 MB
Stars
11.8K
Updated
CommitAug 11
Age
8y
Commits · 90 Days