English for RxDB Developers

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

1. Explain, in two sentences, the difference between a network error and a genuine replication conflict to a teammate debugging a sync issue.
2. Write a short PR description for adding a custom conflict handler that merges fields instead of using last-write-wins.
3. Draft a code review comment explaining why a schema change requires a migration strategy, not just an edited schema definition.

Related Resources

• English for Electric SQL
• English for Database Schema Migrations
• English for Database Migration Discussions

In Practice: Navigating Nuances – A Collaborative Review

Many of the terms we’ve covered – replication lag, conflict resolution strategies, reactive queries – can feel incredibly precise when you first encounter them. It’s easy to get bogged down in the technical definitions and lose sight of how they translate into real-world communication within a development team. That’s where understanding subtle nuances becomes crucial for non-native English speakers. Let’s consider a scenario: Sarah, a senior developer on the team, is reviewing a pull request submitted by David, who’s relatively new to RxDB and offline data synchronization.

David’s PR description read simply: “Fixed replication issue.” While technically accurate – the PR did address a reported lag in replicating changes from the server – it lacked crucial context. Sarah’s review comment wasn’t just about pointing out an error; it was about fostering collaboration and ensuring David understood why the fix was necessary. She wrote, “David, this is good work addressing the replication delay. Could you elaborate on the root cause in the commit message? Specifically, were there any bottlenecks during the data synchronization process that we identified in our monitoring logs – particularly around the rxdb.sync.start() operation? Adding details like ‘Resolved replication lag due to inefficient indexing’ will help future developers understand this fix quickly and prevent similar issues.” The difference is significant. “Fixed replication issue” feels terse and potentially dismissive, while Sarah’s comment invites a deeper conversation and demonstrates an understanding of the broader system. It also sets clear expectations for documentation – a key element of professional communication.

Furthermore, consider a Slack message David received from Mark, another developer: “Hey David, are you still seeing this sync lag?” While seemingly straightforward, it could be misinterpreted. David might not fully understand what “sync lag” means in the context of RxDB’s reactive queries and offline data synchronization. Providing more detail – perhaps referencing a specific query that was experiencing delays or linking to relevant documentation – would make the conversation much more productive. The goal is always to move beyond simple yes/no responses and engage in productive troubleshooting. It’s about clearly articulating problems, potential solutions, and expected outcomes.

The key is to remember that technical vocabulary isn’t just a collection of words; it’s a tool for precise communication. Building confidence comes from actively using these terms within context, asking clarifying questions when needed (“Could you explain what you mean by ‘reactive query performance’ in this scenario?”), and focusing on the impact of the changes being discussed – not just the technical implementation.

// Example: Monitoring RxDB sync status with a simple console log
import { rxdb } from './rxdb'; // Assuming your RxDB instance is named 'rxdb'

setInterval(() => {
  const syncStatus = rxdb.sync.status;
  console.log(`RxDB Sync Status: ${syncStatus}`);
}, 5000);