Writers, Readers, and batching
Think of this guide as a part two of Create, Read, Update, Delete.
As mentioned previously, you can't just modify WatermelonDB's database anywhere. All changes must be done within a Writer.
There are two ways of defining a writer: inline and by defining a writer method.
Inline writers
Here is an inline writer, you can invoke it anywhere you have access to the database
object:
// Note: function passed to `database.write()` MUST be asynchronous
const newPost = await database.write(async => {
const post = await database.get('posts').create(post => {
post.title = 'New post'
post.body = 'Lorem ipsum...'
})
const comment = await database.get('comments').create(comment => {
comment.post.set(post)
comment.author.id = someUserId
comment.body = 'Great post!'
})
// Note: Value returned from the wrapped function will be returned to `database.write` caller
return post
})
Writer methods
Writer methods can be defined on Model
subclasses by using the @writer
decorator:
import { writer } from '@nozbe/watermelondb/decorators'
class Post extends Model {
// ...
@writer async addComment(body, author) {
const newComment = await this.collections.get('comments').create(comment => {
comment.post.set(this)
comment.author.set(author)
comment.body = body
})
return newComment
}
}
We highly recommend defining writer methods on Models
to organize all code that changes the database in one place, and only use inline writers sporadically.
Note that this is the same as defining a simple method that wraps all work in database.write()
- using @writer
is simply more convenient.
Note:
- Always mark actions as
async
and remember toawait
on.create()
and.update()
- You can use
this.collections
to accessDatabase.collections
Another example: updater action on Comment
:
class Comment extends Model {
// ...
@field('is_spam') isSpam
@writer async markAsSpam() {
await this.update(comment => {
comment.isSpam = true
})
}
}
Now we can create a comment and immediately mark it as spam:
const comment = await post.addComment('Lorem ipsum', someUser)
await comment.markAsSpam()
Batch updates
When you make multiple changes in a writer, it's best to batch them.
Batching means that the app doesn't have to go back and forth with the database (sending one command, waiting for the response, then sending another), but instead sends multiple commands in one big batch. This is faster, safer, and can avoid subtle bugs in your app
Take an action that changes a Post
into spam:
class Post extends Model {
// ...
@writer async createSpam() {
await this.update(post => {
post.title = `7 ways to lose weight`
})
await this.collections.get('comments').create(comment => {
comment.post.set(this)
comment.body = "Don't forget to comment, like, and subscribe!"
})
}
}
Let's modify it to use batching:
class Post extends Model {
// ...
@writer async createSpam() {
await this.batch(
this.prepareUpdate(post => {
post.title = `7 ways to lose weight`
}),
this.collections.get('comments').prepareCreate(comment => {
comment.post.set(this)
comment.body = "Don't forget to comment, like, and subscribe!"
})
)
}
}
Note:
- You can call
await this.batch
within@writer
methods only. You can also calldatabase.batch()
within adatabase.write()
block. - Pass the list of prepared operations as arguments:
- Instead of calling
await record.update()
, passrecord.prepareUpdate()
— note lack ofawait
- Instead of
await collection.create()
, usecollection.prepareCreate()
- Instead of
await record.markAsDeleted()
, userecord.prepareMarkAsDeleted()
- Instead of
await record.destroyPermanently()
, userecord.prepareDestroyPermanently()
- Advanced: you can pass
collection.prepareCreateFromDirtyRaw({ put your JSON here })
- You can pass falsy values (null, undefined, false) to batch — they will simply be ignored.
- You can also pass a single array argument instead of a list of arguments
- Instead of calling
Delete action
When you delete, say, a Post
, you generally want all Comment
s that belong to it to be deleted as well.
To do this, override markAsDeleted()
(or destroyPermanently()
if you don't sync) to explicitly delete all children as well.
class Post extends Model {
static table = 'posts'
static associations = {
comments: { type: 'has_many', foreignKey: 'post_id' },
}
@children('comments') comments
async markAsDeleted() {
await this.comments.destroyAllPermanently()
await super.markAsDeleted()
}
}
Then to actually delete the post:
database.write(async () => {
await post.markAsDeleted()
})
Note:
- Use
Query.destroyAllPermanently()
on all dependent@children
you want to delete - Remember to call
super.markAsDeleted
— at the end of the method!
Advanced: Why are readers and writers necessary?
WatermelonDB is highly asynchronous, which is a BIG challange in terms of achieving consistent data. Read this only if you are curious:
Why are readers and writers necessary?
Advanced: Readers
Readers are an advanced feature you'll rarely need.
Because WatermelonDB is asynchronous, if you make multiple separate queries, normally you have no guarantee that no records were created, updated, or deleted between fetching these queries.
Code within a Reader, however, has a guarantee that for the duration of the Reader, no changes will be made to the database (more precisely, no Writer can execute during Reader's work).
For example, if you were writing a custom XML data export feature for your app, you'd want the information there to be fully consistent. Therefore, you'd wrap all queries within a Reader:
database.read(async () => {
// no changes will happen to the database until this function exits
})
// alternatively:
class Blog extends Model {
// ...
@reader async exportBlog() {
const posts = await this.posts.fetch()
const comments = await this.allComments.fetch()
// ...
}
}
Advanced: nesting writers or readers
If you try to call a Writer from another Writer, you'll notice that it won't work. This is because while a Writer is running, no other Writer can run simultaneously. To override this behavior, wrap the Writer call in this.callWriter
:
class Comment extends Model {
// ...
@writer async appendToPost() {
const post = await this.post.fetch()
// `appendToBody` is an `@writer` on `Post`, so we call callWriter to allow it
await this.callWriter(() => post.appendToBody(this.body))
}
}
// alternatively:
database.write(async writer => {
const post = await database.get('posts').find('abcdef')
await writer.callWriter(() => post.appendToBody('Lorem ipsum...')) // appendToBody is a @writer
})
The same is true with Readers - use callReader
to nest readers.
Next steps
➡️ Now that you've mastered all basics of Watermelon, go create some powerful apps — or keep reading advanced guides