Choosing Between Continuous and Periodic Replication in CouchDB for Mobile Apps

Decision and Constraints

When building a distributed mobile application that must stay in sync with a central CouchDB server, the replication mode determines how data flows between devices and the backend. The key constraints are limited cellular bandwidth, frequent offline periods, a requirement for eventual consistency, and the desire for low update latency when a network connection is available.

Options Comparison

Trade‑offs

• Continuous delivers the freshest data with sub‑second latency but keeps an HTTP connection open, consuming more network data and device battery.
• Periodic reduces traffic and preserves power by limiting replication to defined intervals, at the cost of stale data that can be as old as the longest interval.
• One‑shot is the simplest to script but requires manual re‑triggering; if not scheduled regularly it risks missing changes that occur between runs.

Concrete Implementation (Continuous)

The following cURL request creates a continuous replication document from a local database mydb to a remote endpoint. Run it on the CouchDB node that will act as the replication manager (often the mobile client or a sync gateway).

curl -X POST http://admin:password@localhost:5984/_replicate -H "Content-Type: application/json" -d '{"source":"mydb","target":"http://mobile.example.com:5984/mydb","continuous":true,"create_target":true,"doc_ids":["doc1","doc2"]}'

This starts a replication doc that CouchDB manages until it is explicitly cancelled or encounters an unrecoverable error.

Validation Steps

1. Check that the replication task is active: curl http://localhost:5984/_active_tasks. Look for an entry where "type" is "replication" and "state" is "running" (or "completed" if the catch‑up phase finished).
2. Inspect the replication document itself: curl http://localhost:5984/_replicate/. Verify that "continuous": true and the source and target fields match the request.
3. Confirm data flow by inserting a test document in the source, then watching the target’s changes feed: curl http://mobile.example.com:5984/mydb/_changes?since=now&feed=longpoll. The new doc should appear within a few seconds when the device has network connectivity.

Limitations and Practical Checks

Continuous replication keeps a long‑lived HTTP connection open. If the mobile device switches networks or goes behind a NAT, idle timeouts may drop the connection. Ensure that any intermediate proxies or the mobile carrier’s NAT bindings are configured with sufficient keep‑alive intervals (e.g., TCP keep‑alive or application‑level heartbeats). Additionally, CouchDB’s MVCC model means that concurrent updates can create conflicting revisions; applications must examine the _conflicts field or implement application‑level merge logic to avoid silent data loss.

When to Choose Periodic

If the app can tolerate data that is up to a few minutes old and needs to preserve battery life, a periodic schedule is preferable. The same _replicate endpoint can be used with continuous:false and a scheduler (e.g., cron on the device or a background job) to trigger replication every desired interval. Validation follows the same steps, but you will see the replication task appear only briefly after each trigger.