Watermelondb

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

Resources

• DeepWiki: Nozbe/WatermelonDB — findAndObserve, observe(), withObservables, model updates.
• Project: PhraseDetailScreen, LessonDetailScreen, SetDetailScreen (findAndObserve + wrapper); AttemptCard (withObservables).