English for RxDB Developers
Vocabulary for developers building offline-first apps with RxDB — replication, conflict resolution, reactive queries, and storage adapters — for teams discussing local-first data in English.
RxDB is a client-side, offline-first NoSQL database for JavaScript apps that syncs with a backend through a replication layer, staying usable even when the network is unavailable. Because it combines database vocabulary (schemas, indexes) with distributed-systems vocabulary (replication, conflicts), review discussions can get imprecise fast. Here’s the English you need to talk about it clearly.
Offline-First and Replication
Offline-first — an architecture where the app reads and writes to a local database first, treating network sync as a background concern rather than a blocking requirement for basic functionality.
“The app should stay fully usable on a flight — that’s the whole point of going offline-first, so don’t add a network check before this write.”
Replication — the ongoing, bidirectional process of syncing local database changes to a remote server and pulling remote changes back down.
“Replication is still running in the background even after the initial sync — don’t assume the data is ‘done’ just because the first load finished.”
Checkpoint — a marker RxDB stores to remember how far replication has progressed, so a resumed sync only pulls changes since the last checkpoint instead of the entire dataset.
“We lost the checkpoint on that migration, which is why every client re-pulled the full collection — that’s the bug, not a server-side issue.”
Conflict Resolution
Conflict — a situation where the same document was modified both locally (offline) and remotely (by another client) before replication reconciled them.
“Two people edited the same ticket while offline — that’s a genuine conflict, and the resolution strategy decides which version wins, not a race condition in our code.”
Conflict handler — the function that decides how to merge or choose between two conflicting versions of a document during replication.
“The default conflict handler just takes ‘last write wins’ — for this collection we actually need a custom one that merges fields instead of overwriting.”
Revision (rev) — the version identifier RxDB attaches to each document state, used to detect whether a document has changed since it was last read.
“That write failed because the revision you sent doesn’t match the current one — someone else’s change landed first.”
Reactive Queries and Storage
Reactive query — a query that automatically re-emits new results whenever the underlying data changes, rather than requiring the app to manually re-fetch.
“You don’t need to refetch after that insert — the component is already subscribed to a reactive query, so it’ll update on its own.”
Storage adapter — the pluggable backend RxDB uses to actually persist data locally (IndexedDB, SQLite, in-memory), swappable without changing application-level query code.
“We’re not tied to IndexedDB — swapping the storage adapter for SQLite on mobile didn’t touch a single query in the app.”
Schema migration — the process of transforming existing local documents to match a new schema version when the app updates, run automatically on startup.
“Bump the schema version and write a migration strategy — you can’t just change the field type in place, existing local data needs to be transformed.”
Common Mistakes
- Saying “the data didn’t sync” without specifying whether replication stalled, a conflict wasn’t resolved, or the checkpoint got corrupted — each has a different root cause.
- Treating every simultaneous edit as a bug rather than an expected conflict that the conflict handler is meant to resolve.
- Forgetting to bump the schema version after a field type change, then being confused why existing users hit a startup crash that new installs don’t.
Practice Exercise
- Explain, in two sentences, the difference between a network error and a genuine replication conflict to a teammate debugging a sync issue.
- Write a short PR description for adding a custom conflict handler that merges fields instead of using last-write-wins.
- Draft a code review comment explaining why a schema change requires a migration strategy, not just an edited schema definition.