WatermelonDB Model & Observation

Overview

This skill covers WatermelonDB models (database/models/ ), observation (reactive queries), and ensuring React re-renders when observed data changes. Use it when working with findAndObserve , query.observe() , withObservables , or any screen that subscribes to DB changes.

Observation & React Re-rendering

findAndObserve and same-reference emission

• findAndObserve(id) (on a collection): Fetches a record by ID, returns an Observable that emits immediately on subscribe and whenever the record is updated or deleted.

• When a model is updated (e.g. via model.update() or @writer methods), the observable emits the same object reference with updated properties — it does not emit a new model instance.

React useState bailout

• useState uses Object.is to decide whether to re-render. Passing the same reference (e.g. setPhrase(model) ) after an update means no re-render.

• Result: DB updates (text, note, language, etc.) don’t appear until the user navigates away and back, when a new subscription yields a fresh reference.

Fix: store a wrapper so each emit is a new reference

When subscribing to a single model (e.g. findAndObserve ) and storing it in React state, don’t store the raw model. Store a wrapper so every emission updates state with a new object:

const [phraseState, setPhraseState] = useState< { phrase: Phrase; _key: number } | null

(null);

useEffect(() => { if (!id) return; const sub = db.collections .get<Phrase>(PHRASE_TABLE) .findAndObserve(id) .subscribe((result) => { setPhraseState({ phrase: result, _key: result.updatedAt }); }); return () => sub.unsubscribe(); }, [id, db]);

const phrase = phraseState?.phrase ?? null;

• Use phrase (derived) everywhere in the component. Updates persisted to the DB will re-emit, update phraseState with a new wrapper, and trigger a re-render.

Query observe() and arrays

• query.observe() emits arrays of models. When the query result set changes, WatermelonDB typically emits a new array reference, so setState(results) usually triggers re-renders.

• If you build derived data (e.g. linked.filter(...) , assignments ) in the subscribe callback and setState that, you’re already passing new references — no extra wrapper needed.

withObservables (HOC)

• withObservables(triggerProps, getObservables) injects observable values as props and always passes a new state object into setState (e.g. { values, isFetching } ), so React re-renders on each emission even when model references are unchanged.

• Use it when you can observe a model (or query) passed as a prop: e.g. withObservables(['attempt'], ({ attempt }) => ({ attempt: attempt.observe(), ... })) . See AttemptCard in features/lesson/components/AttemptCard.tsx .

• For route params (e.g. id ) you typically subscribe manually in useEffect (e.g. findAndObserve(id) ). In that case, use the wrapper pattern above instead of storing the raw model.

Model patterns in this project

• Models: database/models/ (e.g. Phrase , Lesson , Attempt , Translation , Deck ). Use @field , @writer , and static helpers (e.g. Phrase.findOrCreatePhrase , Lesson.addLesson ).

• Observation: useDatabase() from @nozbe/watermelondb/react ; then collection.findAndObserve(id) or query.observe().subscribe(...) .

• Schema/tables: database/schema.ts ; collection access via db.collections.get<Model>(TABLE) .

Quick reference

Scenario Pattern Re-render guarantee

Single model by id (e.g. detail screen) findAndObserve

• wrapper state { model, _key }

Yes

Query results (list) query.observe()

• setState(results) or derived structures Yes (new array/refs)

Model passed as prop withObservables(['model'], ({ model }) => ({ model: model.observe() }))

Yes (HOC uses new state shape)

Resources

• DeepWiki: Nozbe/WatermelonDB — findAndObserve , observe() , withObservables , model updates.

• Project: PhraseDetailScreen , LessonDetailScreen , SetDetailScreen

(findAndObserve + wrapper); AttemptCard (withObservables).