WatermelonDB Model & Observation

Overview

database/models/

findAndObserve

query.observe()

withObservables

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

findAndObserve

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

id

findAndObserve

{ model, _key }

query.observe()

setState(results)

withObservables(['model'], ({ model }) => ({ model: model.observe() }))

Resources

• DeepWiki: Nozbe/WatermelonDB —

  findAndObserve

  ,

  observe()

  ,

  withObservables

  , model updates.
• Project:

  PhraseDetailScreen

  ,

  LessonDetailScreen

  ,

  SetDetailScreen

  (findAndObserve + wrapper);

  AttemptCard

  (withObservables).