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)

Searching Database…

11.8K ·GitHub
WatermelonDB
这是什么？WatermelonDB 是一个响应式、异步的数据库框架，用于构建 React 和 React Native 应用。即使保存了数万条记录，它依然能保持流畅运行。
这是数据库引擎，还是构建在引擎之上的一层？它是一套与框架无关的 JS API，基于 SQLite 构建，提供基于模型、类似 ORM 的一层，支持惰性加载和响应式查询，本身并不是一个数据库引擎。
如何把它添加到 React Native 或 React 网页项目中？先定义描述数据表的 Models，然后把 React 组件与这些数据连接起来。WatermelonDB 会把两者衔接好，因此底层记录发生变化时，界面中相关的部分会自动更新。
使用它需要 Flow 或 TypeScript 吗？不需要，纯 JavaScript 即可使用，因为核心是一套 JS API。如果需要，项目也支持 Flow 或 TypeScript 的静态类型。底层还依赖 @nozbe/sqlite 和 rxjs 等包。
要获得响应式更新，必须使用 RxJS 吗？不必须，RxJS 是可选的。响应式行为由 WatermelonDB 自有的可观察（observable）系统实现，RxJS 只是为想要使用它的人额外提供的一层 API。
可以面向哪些平台开发？它可以运行在 iOS、Android、Windows、网页和 Node.js 上，一套代码即可同时覆盖 React Native 应用和 React 网页应用。
没有网络连接也能使用吗？可以，它支持离线优先。数据保存在本地的 SQLite 中，有网络连接时再与你自己的后端同步。
为什么不直接用 Redux 或 MobX 加上持久化适配器？这些方案用于简单应用没有问题，但随着记录增长到数千条，把整个数据库加载进 JavaScript 会变得很慢。WatermelonDB 通过惰性加载，并在独立的原生线程中直接查询 SQLite 来避免这个问题，因此规模变大时应用启动依然很快。
我更新一条记录时，界面会发生什么？所有订阅了该数据的组件都会自动重新渲染。例如，完成一个待办事项会更新任务行、重新排序后的列表以及所有计数器，即使它们位于应用中互不相关的部分。
WatermelonDB 真的用于生产环境吗？是的，自 2017 年起它就为 Nozbe 自家的应用提供支持，并由 Radek Pietruszewski 与其他贡献者共同维护。
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