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.
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
_design/by-date, then you create a new design doc
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.