.. 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.


.. _api/db/compact:

``/db/_compact``
================

.. http:post:: /{db}/_compact
  :synopsis: Starts a compaction for the database

  Request compaction of the specified database. Compaction compresses the
  disk database file by performing the following operations:

  -  Writes a new, optimised, version of the database file, removing any unused
     sections from the new version during write. Because a new file is
     temporarily created for this purpose, you may require up to twice the current
     storage space of the specified database in order for the compaction
     routine to complete.

  -  Removes old revisions of documents from the database, up to the
     per-database limit specified by the ``_revs_limit`` database
     parameter.

  Compaction can only be requested on an individual database; you cannot
  compact all the databases for a CouchDB instance. The compaction process
  runs as a background process.

  You can determine if the compaction process is operating on a database
  by obtaining the database meta information, the ``compact_running``
  value of the returned database structure will be set to true. See
  :get:`/{db}`.

  You can also obtain a list of running processes to determine whether
  compaction is currently running. See :ref:`api/server/active_tasks`.

  :param db: Database name
  :<header Accept: - :mimetype:`application/json`
                   - :mimetype:`text/plain`
  :<header Content-Type: :mimetype:`application/json`
  :>header Content-Type: - :mimetype:`application/json`
                         - :mimetype:`text/plain; charset=utf-8`
  :>json boolean ok: Operation status
  :code 202: Compaction request has been accepted
  :code 400: Invalid database name
  :code 401: CouchDB Server Administrator privileges required
  :code 415: Bad :header:`Content-Type` value

  **Request**:

  .. code-block:: http

    POST /db/_compact HTTP/1.1
    Accept: application/json
    Content-Type: application/json
    Host: localhost:5984

  **Response**:

  .. code-block:: http

    HTTP/1.1 202 Accepted
    Cache-Control: must-revalidate
    Content-Length: 12
    Content-Type: application/json
    Date: Mon, 12 Aug 2013 09:27:43 GMT
    Server: CouchDB (Erlang/OTP)

    {
        "ok": true
    }


.. _api/db/compact/ddoc:

``/db/_compact/design-doc``
===========================

.. http:post:: /{db}/_compact/{ddoc}
  :synopsis: Starts a compaction for all the views in the selected design document

  Compacts the view indexes associated with the specified design document.
  If may be that compacting a large view can return more storage than
  compacting the actual db. Thus, you can use this in place of the full
  database compaction if you know a specific set of view indexes have been
  affected by a recent database change.

  :param db: Database name
  :param ddoc: Design document name
  :<header Accept: - :mimetype:`application/json`
                   - :mimetype:`text/plain`
  :<header Content-Type: :mimetype:`application/json`
  :>header Content-Type: - :mimetype:`application/json`
                         - :mimetype:`text/plain; charset=utf-8`
  :>json boolean ok: Operation status
  :code 202: Compaction request has been accepted
  :code 400: Invalid database name
  :code 401: CouchDB Server Administrator privileges required
  :code 404: Design document not found
  :code 415: Bad :header:`Content-Type` value

  **Request**:

  .. code-block:: http

    POST /db/_compact/posts HTTP/1.1
    Accept: application/json
    Content-Type: application/json
    Host: localhost:5984

  **Response**:

  .. code-block:: http

    HTTP/1.1 202 Accepted
    Cache-Control: must-revalidate
    Content-Length: 12
    Content-Type: application/json
    Date: Mon, 12 Aug 2013 09:36:44 GMT
    Server: CouchDB (Erlang/OTP)

    {
        "ok": true
    }

    .. note::

      View indexes are stored in a separate ``.couch`` file based on
      a hash of the design document's relevant functions, in a sub directory
      of where the main ``.couch`` database files are located.

.. _api/db/ensure_full_commit:

``/db/_ensure_full_commit``
===========================

.. http:post:: /{db}/_ensure_full_commit
  :synopsis: Makes sure all uncommitted changes are written and synchronized to the disk

  Commits any recent changes to the specified database to disk. You should
  call this if you want to ensure that recent changes have been flushed.
  This function is likely not required, assuming you have the recommended
  configuration setting of ``delayed_commits=false``, which requires CouchDB
  to ensure changes are written to disk before a 200 or similar result is
  returned.

  :param db: Database name
  :<header Accept: - :mimetype:`application/json`
                   - :mimetype:`text/plain`
  :<header Content-Type: :mimetype:`application/json`
  :>header Content-Type: - :mimetype:`application/json`
                         - :mimetype:`text/plain; charset=utf-8`
  :>json string instance_start_time: Timestamp of when the database was opened,
    expressed in microseconds since the epoch.
  :>json boolean ok: Operation status
  :code 201: Commit completed successfully
  :code 400: Invalid database name
  :code 415: Bad :header:`Content-Type` value

  **Request**:

  .. code-block:: http

    POST /db/_ensure_full_commit HTTP/1.1
    Accept: application/json
    Content-Type: application/json
    Host: localhost:5984

  **Response**:

  .. code-block:: http

    HTTP/1.1 201 Created
    Cache-Control: must-revalidate
    Content-Length: 53
    Content-Type: application/json
    Date: Mon, 12 Aug 2013 10:22:19 GMT
    Server: CouchDB (Erlang/OTP)

    {
        "instance_start_time": "1376269047459338",
        "ok": true
    }


.. _api/db/view_cleanup:

``/db/_view_cleanup``
=====================

.. http:post:: /{db}/_view_cleanup
  :synopsis: Removes view files that are not used by any design document

  Removes view index files that are no longer required by CouchDB as a result
  of changed views within design documents. As the view filename is based on
  a hash of the view functions, over time old views will remain, consuming
  storage. This call cleans up the cached view output on disk for a given view.

  :param db: Database name
  :<header Accept: - :mimetype:`application/json`
                   - :mimetype:`text/plain`
  :<header Content-Type: :mimetype:`application/json`
  :>header Content-Type: - :mimetype:`application/json`
                         - :mimetype:`text/plain; charset=utf-8`
  :>json boolean ok: Operation status
  :code 202: Compaction request has been accepted
  :code 400: Invalid database name
  :code 401: CouchDB Server Administrator privileges required
  :code 415: Bad :header:`Content-Type` value

  **Request**:

  .. code-block:: http

    POST /db/_view_cleanup HTTP/1.1
    Accept: application/json
    Content-Type: application/json
    Host: localhost:5984

  **Response**:

  .. code-block:: http

    HTTP/1.1 202 Accepted
    Cache-Control: must-revalidate
    Content-Length: 12
    Content-Type: application/json
    Date: Mon, 12 Aug 2013 09:27:43 GMT
    Server: CouchDB (Erlang/OTP)

    {
        "ok": true
    }
