.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

.. _best-practices/views:

====================
View recommendations
====================

Here are some tips and tricks for working with CouchDB's (JavaScript-based)
views.

Deploying a view change in a live environment
---------------------------------------------

It is possible to change the definition of a view, build the index, then make
those changes go live without causing downtime for your application. The trick
to making this work is that CouchDB's JavaScript view index files are based on
the contents of the design document - not its name, ``_id`` or revision. This
means that two design documents with identical view code will share the same
on-disk view index files.

Here is a worked example, assuming your ``/db/_design/ddoc`` needs to be updated.

1. Upload the old design doc to ``/db/_design/ddoc-old`` (or copy the document)
   if you want an easy way to rollback in case of problems. The ``ddoc-old``
   document will reference the same view indexes already built for ``_design/ddoc``.

2. Upload the updated design doc to ``/db/_design/ddoc-new``.

3. Query a view in the new design document to trigger secondary index generation.
   You can track the indexing progress via the ``/_active_tasks`` endpoint, or
   through the :ref:`fauxton` web interface.

4. When the index is done being built, re-upload the updated design document to
   ``/db/_design/ddoc`` (or copy the document). The ``ddoc`` document will now
   reference the same view indexes already built for ``_design/ddoc-new``.

5. Delete ``/db/_design/ddoc-new`` and/or ``/db/_design/ddoc-old`` at your
   discretion. Don't forget to trigger :ref:`compact/views/cleanup` to reclaim
   disk space after deleting ``ddoc-old``.

The :ref:`COPY <api/doc/copy>` HTTP verb can be used to copy the design document
with a single command:

.. code-block:: bash

    curl -X COPY <URL of source design document> -H "Destination: <ID of destination design document>"