Consulting & Development CouchDB Support & Services Greenkeeper Training

Copy Design Docs to Avoid Waiting For Indexes to be Built posted 08/09/2020 by The Neighbourhoodie CouchDB Team

This post is part of our CouchDB Tips Series that we publish every week. The team at Neighbourhoodie works on and with CouchDB every day and we are happy to pass on all the tips and tricks we learn along the way. If you like what you see, check out our Professional Services for CouchDB, including production support and training. If you want to continuously ensure that your CouchDB is running optimally, sign up for Opservatory, our 24/7 CouchDB analysis and diagnostics tool.

This advice is relevant for all query mechanisms in CouchDB: Views, Mango Queries, and even Search.

All query mechanisms in CouchDB use design docs to define which fields to use when querying your document. We call this the query definition. They look different for each of the mechanisms, but their function is the same in each case.

When changing the query definition of a design document, CouchDB will re-index all documents in your database before it can respond to any queries for them.

If you have a lot of documents in your database, going through all documents for re-indexing can take a while, minutes, hours, sometimes days.

During application development it is common to adjust how you query your database and adjusting your CouchDB query definitions is a common operation.

However, when deploying the latest version of your application, you don’t want to get into a situation where an end-user tries to use your application and then has a lengthy wait before CouchDB returns a result.

But you also don’t want to deploy the new design doc before the application is ready, because then the old version of your application no longer has the correct design docs to work correctly.

Luckily, the CouchDB developers have thought about this and there is a nice solution.

When deploying your new query definitions, you can deploy them under a differently named design document that is currently unused. For example, when your current design doc _id is _design/by-date, then you create a new design doc _design/by-date-deploy.

Then you wait for its index to be built and after that, when you deploy your app, you use a HTTP COPY request to copy the new design doc over the old design doc. This does not cause your index to be rebuilt, and your app can use the new index right away, while the old app could use its index up to the last moment of operation.


  1. upload your new view in a new design doc
  2. query your view and wait for the index build to finish
  3. HTTP COPY your new design doc to your old one.