What does PouchDB's db.sync(remote, {live: true, retry: true}) do in an offline-first app?

## What PouchDB is PouchDB is a database that runs inside the client — in a browser on IndexedDB, or in Node on LevelDB — and speaks the CouchDB replication protocol. Because that protocol is nothing but a defined sequence of HTTP calls, PouchDB can be a full replication peer of a real CouchDB server. This is the whole basis of the offline-first pattern: the application talks only to the local database, and a background process keeps the local database and the server converged. ## What sync actually starts A CouchDB replication moves changes in **one** direction. `db.sync(remote, opts)` therefore starts two of them — the equivalent of `db.replicate.to(remote, opts)` and `db.replicate.from(remote, opts)` — and returns one handle that aggregates both. Each direction keeps its own checkpoint, so they resume independently. ## The two options that matter most **`live: true`** means the replication does not finish when it has drained the backlog; it keeps following the change feed and replicates each new change as it appears. Without it, sync is a one-shot catch-up that completes and stops, which is what you want for an explicit "sync now" button and not what you want for a background process. **`retry: true`** governs what happens when the connection breaks. Without it, a network failure ends the replication with an `error` event and you must restart it yourself. With it, PouchDB backs off and reconnects on its own, which for a mobile client — where losing the network is normal rather than exceptional — is almost always the right setting. ## The events The returned object is an event emitter, and reading the events correctly is most of the skill: - **`change`** — fires per replicated batch, in either direction, carrying which documents moved. This is the hook for refreshing UI state. - **`active`** — the replication has work to do and is transferring. - **`paused`** — the replication has gone quiet. **This is the trap**: it fires both when sync is fully caught up and idle, *and* when a connection failed and PouchDB is waiting to retry. The argument tells you which (an error argument means it is a retry wait, no argument means simply idle). Wiring an "offline" badge to a bare `paused` gives you a badge that lights up whenever sync succeeds. - **`denied`** — a single document could not be written to the remote, typically because of validation or per-database permissions. The rest of the replication keeps going, so an unhandled `denied` is a silent partial failure. - **`error`** — a fatal problem; with `retry: true` this becomes rare, since recoverable failures turn into retry waits instead. - **`complete`** — fires when the replication finishes. With `live: true` that only happens after you call `cancel()`. ## Cancelling The handle has `cancel()`. A live sync is a long-lived resource: in a single-page app you must cancel it when the component or the session that owns it goes away, or you will accumulate parallel syncs that all write to the same local database. ## What the user experiences offline The application reads and writes the local PouchDB instance only. Those operations succeed with no network, at local-storage latency, which is why the UI stays responsive on a bad connection. When the device reconnects, each direction resumes from its checkpoint and transfers only what is missing, using the same `_revs_diff` negotiation a server-to-server replication uses. ## Conflicts are part of the deal Because the device accepts writes while disconnected, another user can change the same document on the server in the meantime. When the two directions meet, both versions are kept as leaf revisions of the document's revision tree, and PouchDB and CouchDB independently pick the same winner. The application sees only the winner unless it asks for conflicts explicitly. An offline-first app with no conflict-handling code has not avoided the problem; it has silently accepted whichever version the tie-break rule prefers. ## Filtering the sync `sync` accepts a `filter` (a design-document filter function on the server), a `selector`, or a `doc_ids` list, so a device can pull a subset rather than an entire database. Two cautions come with it. First, filters on business fields do not match deletion tombstones, so deletions can silently fail to propagate unless the filter passes `_deleted`. Second, a filter is not a security boundary: it shapes what a replication transfers, not what the client is allowed to read. Confidentiality between users needs separate databases with their own permissions, not a clever filter. ## Practical checklist Use `live` and `retry` together for background sync. Handle `denied` — do not let per-document rejections vanish. Distinguish idle from retrying when reading `paused`. Cancel the handle on teardown. And decide up front what happens when two devices edit the same document, because with offline clients that is not a rare edge case.