How do you migrate data between CouchDB versions or instances?

CouchDB provides several migration paths depending on whether you are upgrading in place, moving to a new cluster, or changing data structure during migration.

1. Replication-based migration (zero-downtime, recommended)

# Step 1: Replicate from old instance to new
curl -X POST http://admin:pass@new-couch:5984/_replicator \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "migrate-orders",
    "source": "http://admin:pass@old-couch:5984/orders",
    "target": "http://admin:pass@new-couch:5984/orders",
    "continuous": true,
    "create_target": true
  }'

# Step 2: Monitor until caught up
curl http://admin:pass@new-couch:5984/_scheduler/docs

# Step 3: Stop writes to old instance, verify new instance is current
# (compare document counts and last seq numbers)

# Step 4: Switch application connection string to new instance
# Step 5: Stop the replication job and decommission old instance

2. In-place upgrade (CouchDB 1.x to 2.x/3.x) — CouchDB 2.x reads CouchDB 1.x database files directly (the on-disk format is forward-compatible). Install the new version over the old one, point it at the same data directory. However, the cluster setup and configuration format changed significantly — review the upgrade guide for your specific version pair.

3. Document transformation during migration — if the schema changes (adding required fields, renaming fields), write a migration script that reads from the source using _all_docs or _changes, transforms each document, and writes to the target via _bulk_docs. Process in batches of 100-500 documents to avoid memory pressure.

# Estimate progress: compare total_rows on both sides
curl http://admin:pass@old:5984/orders/ | python3 -c "import sys,json; d=json.load(sys.stdin); print('old:', d['doc_count'])"
curl http://admin:pass@new:5984/orders/ | python3 -c "import sys,json; d=json.load(sys.stdin); print('new:', d['doc_count'])"

Always verify the migration by comparing document counts, running a sample of queries on both instances, and doing a test cutover before the production switch.