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.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.