Skip to content

PouchDB and Offline-First

If you allow writes while offline, you move from request/response to replication – and the revision tree of PouchDB and CouchDB turns conflicts into a job for the domain model.

≈ 11 min readSoftwareArchitecture

PouchDB and Offline-First

Offline is treated as a special case: first finish building the application, then shortly before the release put a cache in front of it, catch failed requests, show a “You are offline” banner. This assumption holds exactly until the first write without a network. Reads can be cached – writes cannot. As soon as a user is allowed to change a record on the train, the question is no longer how to cache responses but: Where does the truth live while the connection is missing? And what happens if two devices have changed the same record in the meantime?

That makes offline-first not a feature checkbox you tick off at the end. It is an architecture decision that swaps out the application’s communication model: replication instead of request/response. The offline-first movement has been saying this for years – the term comes from the circle around hood.ie and offlinefirst.org, long before Progressive Web Apps brought the topic to a wide audience. Still, in everyday work it is often shortened to “service worker plus cache.” But the service worker solves only half of the task: it delivers the application itself without a network – HTML, JavaScript, CSS. The data is the real problem, and for that you need a different tool.

Replication instead of request/response#

In the request/response model, the server is the single source of truth. The client asks, the server answers, and without a connection there simply is no state. In this model, every offline feature is a detour: a queue for pending POSTs, a cache for stale responses, retry logic, lots of special cases that cut across the actual application.

In the replication model, this flips around. The application reads and writes exclusively locally, against a database in the browser. Synchronization is a separate process that runs in the background when a connection is available – and pauses when it is not. At first, the UI notices nothing of the network at all.

flowchart LR
  subgraph rr["Request/Response"]
    UI1["UI"] -->|"HTTP request<br/>blocks without network"| API["API server"]
    API --> DB1[("central<br/>database")]
  end
  subgraph repl["Replication"]
    UI2["UI"] -->|"read and write<br/>locally"| LOCAL[("PouchDB<br/>IndexedDB")]
    LOCAL <-->|"sync when<br/>network is available"| REMOTE[("CouchDB")]
  end

The difference shows first in perceived speed: local reads and writes take milliseconds, regardless of dead zones, latency or server load. But the real gain and the real price lie elsewhere. The replication model accepts that at times there are several valid views of the same data. In it, conflicts are not an operational accident but an expected consequence of the architecture – and that is exactly why they belong in the domain model, not in an error handler.

PouchDB in the browser, CouchDB at the other end#

PouchDB is a JavaScript database that builds on IndexedDB in the browser and replicates CouchDB’s HTTP API – including the CouchDB replication protocol. This protocol is openly documented and describes how two peers exchange their changes: read the changes feed, determine missing revisions, transfer documents, write a checkpoint. If the connection drops, the next run picks up at the last checkpoint, not at the beginning.

That you can set up bidirectional synchronization with this in a few lines almost seems suspicious on first contact:

const localNotes = new PouchDB('notes');
const remoteNotes = new PouchDB('https://couch.example.com/notes');

localNotes.sync(remoteNotes, { live: true, retry: true })
  .on('change', info => renderChange(info))
  .on('paused', () => setSyncStatus('idle'))
  .on('active', () => setSyncStatus('syncing'))
  .on('error', err => reportSyncError(err));

sync is nothing magical here, just two one-way replications, one in each direction. live keeps the changes feed open, retry bridges connection drops with backoff. The paused and active events work as an honest status display: paused means “everything transferred or no network right now,” active means “changes are flowing.” In small applications, I have truly never needed more sync code than this – the rest is conflict handling, more on that shortly.

Important for putting this in context, as of today with PouchDB 7 and CouchDB 2.x: the replication protocol is not an internal detail but an interface. Anything that speaks it can participate – a CouchDB cluster, a second browser tab, a Node process with express-pouchdb in front. Synchronization logic thus becomes infrastructure. What remains in the application is the domain question that no library can answer: What does it mean when two states diverge?

The revision tree#

The core of the model is the versioning of every single document. Every change creates a new revision, and every write must name the revision it wants to continue. If that does not match, the database rejects it immediately:

async function saveNote(note) {
  try {
    await localNotes.put(note);
  } catch (err) {
    if (err.status !== 409) throw err;
    // optimistic locking: fetch the current revision and retry once
    const current = await localNotes.get(note._id);
    await localNotes.put({ ...note, _rev: current._rev });
  }
}

This 409 is the immediate conflict: two writers on the same database, classic optimistic locking, easy to handle. The second case is more interesting. Two devices change the same document offline, both writes are perfectly valid locally, and only replication brings the states together. Then a revision tree with two branches appears in the document:

graph TD
  R1["Rev 1-a4f<br/>shared starting state"] --> R2A["Rev 2-c91<br/>changed on device A"]
  R1 --> R2B["Rev 2-b07<br/>changed on device B"]
  R2A --> R3["Rev 3-e12<br/>merge<br/>by the application"]
  R2B -. "losing branch<br/>is kept" .-> R3

In this situation, CouchDB and PouchDB deterministically choose a winner: the longer revision path wins; on a tie, the lexicographically higher revision hash. Deterministic means every node arrives at the same result without coordination – a cluster needs no consensus algorithm for that. It explicitly does not mean: correct for the domain. The losing branch is not deleted either but stays attached to the document as _conflicts. The database keeps both states and waits for someone to decide. That “someone” is the application.

Conflicts are the normal case#

This is where cache thinking finally parts ways with the replication model. If you retrofit offline capability, you treat conflicts as errors that should ideally not occur. If you replicate, you treat them as an ordinary event with a domain answer. The database cannot give that answer, because it does not know what the data means. Whether the longer text wins for a note, whether two shopping lists can be combined as sets or whether a human has to decide – that lives in the domain model, nowhere else.

The resolution itself is mechanically unspectacular: fetch the conflicting revisions, merge them, write the result, remove the losers.

async function resolveConflicts(id) {
  const winner = await localNotes.get(id, { conflicts: true });
  if (!winner._conflicts) return winner;

  const losers = await Promise.all(
    winner._conflicts.map(rev => localNotes.get(id, { rev }))
  );

  const merged = mergeNotes(winner, losers); // domain-specific merge
  await localNotes.put(merged);
  await Promise.all(
    losers.map(loser => localNotes.remove(loser._id, loser._rev))
  );
  return merged;
}

What matters is mergeNotes – and that this function exists at all. In code reviews, I have noticed that exactly this function is almost always missing: sync built in, demo running, and the conflict case gets pushed to later because it simply does not occur during development. A single developer with one device and stable Wi-Fi produces no conflicts. Two field reps with tablets in a dead zone produce them on day one. If the resolution is missing then, the deterministic algorithm silently wins, and from the user’s point of view the loser’s changes have vanished – not deleted, but invisible. That is the most expensive kind of bug: no crash, no log entry, just quiet data loss from the point of view of the person in front of the screen.

That is why a conflict strategy also needs a visibility strategy. A small indicator saying “three changes waiting to sync” costs little and noticeably changes trust in the application. Users forgive waiting times when they can see where they stand.

What this does to the data model#

Replication and conflicts feed back into how you split documents. A document is the unit that gets replicated and fought over – so it pays to split documents in a way that makes conflicts rare and, when they do occur, resolvable. A few rules have proven themselves for me:

  • One document per domain unit that a user edits in one go – no collective document for half the application state.
  • Meaningful IDs like note:2019-11-12 instead of pure random UUIDs where the domain allows it; that makes direct access predictable and saves you some indexes.
  • Append instead of overwrite where possible: if you write events as new documents instead of changing an existing one, you structurally get fewer conflicts.
  • Treat deletions as part of the model: deleted documents persist as _deleted revisions so that the deletion itself can be replicated.

For queries beyond key access, there are Mango queries via pouchdb-find, now part of the standard build:

await localNotes.createIndex({ index: { fields: ['updatedAt'] } });

const recent = await localNotes.find({
  selector: { updatedAt: { $gte: '2019-11-01' } },
  sort: [{ updatedAt: 'desc' }],
  limit: 20
});

On top of that comes a browser reality you should know about: IndexedDB storage is not guaranteed. The browser may clean up under pressure, and storage quotas differ significantly by platform. You can request persistent storage through navigator.storage.persist(), but I would not rely on it – the copy on the server remains the life insurance; the local database is the working state.

Two experiences of my own#

In 2016, I used graphql-pouch to try out how far the idea could be pushed: a GraphQL runtime directly on PouchDB, Schemas in GraphQL shorthand notation, as a standalone service with CouchDB synchronization and master/master replication. The prototype showed me two things. First, how much backend the replication protocol replaces: sync endpoints, retry logic, delta calculation – all code I never wrote because the protocol brings it along. Second, that the conflict question catches up with you on the server side too. As soon as two instances replicate against each other, the “server” carries the same revision trees as the browser. So the architecture decision does not disappear when you push it to the server side; it only changes location.

On the side, I have been maintaining the list awesome-pouchdb for a few years, where I collect tools, plugins and articles around PouchDB. The view of the ecosystem is itself a data point: a striking number of entries revolve around exactly the places where the model pinches – pouchdb-find for queries, express-pouchdb for your own sync endpoints, pouchdb-authentication for logging in against CouchDB. Where a community builds many tools, it is rarely a coincidence but a recurring problem.

Where I would not use it#

As convincing as the model is for notes, forms and field service scenarios – it has clear limits, and you should know them before the decision, not after:

  • Fine-grained access rights: CouchDB authorizes per database, not per document. The usual remedy is one database per user, which noticeably complicates operations and server-side analysis.
  • Large amounts of data that need central analysis: what the browser holds has to be replicated there. For dashboards over millions of rows, the approach is the wrong tool.
  • Strictly consistent processes: account balances, inventory levels, bookings with hard invariants need central coordination. You cannot configure away eventual consistency.
  • Data that must not leave the device but would – or, conversely, must not be on it in the first place. Replication distributes copies; that is its purpose.

Filtered replication can limit the amount of data per client, but it has its own price: the filter runs over the complete changes feed, and changing filters later is tedious. If you only want to synchronize a subset, you should take that into account early when splitting documents, for example with separate databases per tenant or project.

Bottom line#

You decide on offline-first at the beginning of a project, not at the end – because document splitting, conflict behavior and the permission model depend on it. PouchDB and CouchDB take the mechanics off your hands completely: replication protocol, revision trees, checkpoints, resumption after a drop. What they do not take off your hands is the domain answer to the one question everything hinges on: What should happen when two devices have changed the same thing? If you have an answer to that, you get, with surprisingly little code, an application that works in a dead zone just as well as in the office. If you do not, you get one anyway – only then a hash comparison decides about your users’ data.

Further reading#

Revised and translated from German with the help of AI.