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

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

.. http:head:: /{db}
    :synopsis: Checks the database existence

    Returns the HTTP Headers containing a minimal amount of information
    about the specified database. Since the response body is empty, using the
    HEAD method is a lightweight way to check if the database exists already or
    not.

    :param db: Database name
    :code 200: Database exists
    :code 404: Requested database not found

    **Request**:

    .. code-block:: http

        HEAD /test HTTP/1.1
        Host: localhost:5984

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Type: application/json
        Date: Mon, 12 Aug 2013 01:27:41 GMT
        Server: CouchDB (Erlang/OTP)

.. http:get:: /{db}
    :synopsis: Returns the database information

    Gets information about the specified database.

    :param db: Database name
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>json number cluster.n: Replicas. The number of copies of every document.
    :>json number cluster.q: Shards. The number of range partitions.
    :>json number cluster.r: Read quorum. The number of consistent copies
      of a document that need to be read before a successful reply.
    :>json number cluster.w: Write quorum. The number of copies of a document
      that need to be written before a successful reply.
    :>json boolean compact_running: Set to ``true`` if the database compaction
      routine is operating on this database.
    :>json string db_name: The name of the database.
    :>json number disk_format_version: The version of the physical format used
      for the data when it is stored on disk.
    :>json number data_size: *Deprecated.* Use ``sizes.active`` instead.
    :>json number disk_size: *Deprecated.* Use ``sizes.file`` instead.
    :>json number doc_count: A count of the documents in the specified
      database.
    :>json number doc_del_count: Number of deleted documents
    :>json string instance_start_time: Always ``"0"``. (Returned for legacy
      reasons.)
    :>json object other: Used by Cloudant. *Deprecated.*
    :>json number purge_seq: The number of purge operations on the database.
    :>json number sizes.active: The size of live data inside the database, in
      bytes.
    :>json number sizes.external: The uncompressed size of database contents
      in bytes.
    :>json number sizes.file: The size of the database file on disk in bytes.
      Views indexes are not included in the calculation.
    :>json string update_seq: An opaque string that describes the state
      of the database. Do not rely on this string for counting the number
      of updates.
    :code 200: Request completed successfully
    :code 404: Requested database not found

    **Request**:

    .. code-block:: http

        GET /receipts HTTP/1.1
        Accept: application/json
        Host: localhost:5984

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Length: 258
        Content-Type: application/json
        Date: Mon, 12 Aug 2013 01:38:57 GMT
        Server: CouchDB (Erlang/OTP)

        {
            "cluster": {
                "n": 3,
                "q": 8,
                "r": 2,
                "w": 2
            },
            "compact_running": false,
            "data_size": 65031503,
            "db_name": "receipts",
            "disk_format_version": 6,
            "disk_size": 137433211,
            "doc_count": 6146,
            "doc_del_count": 64637,
            "instance_start_time": "0",
            "other": {
                "data_size": 66982448
            },
            "purge_seq": 0,
            "sizes": {
                "active": 65031503,
                "external": 66982448,
                "file": 137433211
            },
            "update_seq": "292786-g1AAAAF..."
        }

.. http:put:: /{db}
    :synopsis: Creates a new database

    Creates a new database. The database name ``{db}`` must be composed by
    following next rules:

    -  Name must begin with a lowercase letter (``a-z``)

    -  Lowercase characters (``a-z``)

    -  Digits (``0-9``)

    -  Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and
       ``/``.

    If you're familiar with `Regular Expressions`_, the rules above could be
    written as ``^[a-z][a-z0-9_$()+/-]*$``.

    :param db: Database name
    :query integer q: Shards, aka the number of range partitions. Default is
      8, unless overridden in the :config:option:`cluster config <cluster/q>`.
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>header Location: Database URI location
    :>json boolean ok: Operation status. Available in case of success
    :>json string error: Error type. Available if response code is ``4xx``
    :>json string reason: Error description. Available if response code is
      ``4xx``
    :code 201: Database created successfully
    :code 400: Invalid database name
    :code 401: CouchDB Server Administrator privileges required
    :code 412: Database already exists

    **Request**:

    .. code-block:: http

        PUT /db HTTP/1.1
        Accept: application/json
        Host: localhost:5984

    **Response**:

    .. code-block:: http

        HTTP/1.1 201 Created
        Cache-Control: must-revalidate
        Content-Length: 12
        Content-Type: application/json
        Date: Mon, 12 Aug 2013 08:01:45 GMT
        Location: http://localhost:5984/db
        Server: CouchDB (Erlang/OTP)

        {
            "ok": true
        }

    If we repeat the same request to CouchDB, it will response with :code:`412`
    since the database already exists:

    **Request**:

    .. code-block:: http

        PUT /db HTTP/1.1
        Accept: application/json
        Host: localhost:5984

    **Response**:

    .. code-block:: http

        HTTP/1.1 412 Precondition Failed
        Cache-Control: must-revalidate
        Content-Length: 95
        Content-Type: application/json
        Date: Mon, 12 Aug 2013 08:01:16 GMT
        Server: CouchDB (Erlang/OTP)

        {
            "error": "file_exists",
            "reason": "The database could not be created, the file already exists."
        }

    If an invalid database name is supplied, CouchDB returns response with
    :code:`400`:

    **Request**:

    .. code-block:: http

        PUT /_db HTTP/1.1
        Accept: application/json
        Host: localhost:5984

    **Request**:

    .. code-block:: http

        HTTP/1.1 400 Bad Request
        Cache-Control: must-revalidate
        Content-Length: 194
        Content-Type: application/json
        Date: Mon, 12 Aug 2013 08:02:10 GMT
        Server: CouchDB (Erlang/OTP)

        {
            "error": "illegal_database_name",
            "reason": "Name: '_db'. Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
        }

.. http:delete:: /{db}
    :synopsis: Deletes an existing database

    Deletes the specified database, and all the documents and attachments
    contained within it.

    .. note::
        To avoid deleting a database, CouchDB will respond with the HTTP status
        code 400 when the request URL includes a ?rev= parameter. This suggests
        that one wants to delete a document but forgot to add the document id
        to the URL.

    :param db: Database name
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>json boolean ok: Operation status
    :code 200: Database removed successfully
    :code 400: Invalid database name or forgotten document id by accident
    :code 401: CouchDB Server Administrator privileges required
    :code 404: Database doesn't exist or invalid database name

    **Request**:

    .. code-block:: http

        DELETE /db HTTP/1.1
        Accept: application/json
        Host: localhost:5984

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Length: 12
        Content-Type: application/json
        Date: Mon, 12 Aug 2013 08:54:00 GMT
        Server: CouchDB (Erlang/OTP)

        {
            "ok": true
        }

.. http:post:: /{db}
    :synopsis: Creates a new document with generated ID if _id is not specified

    Creates a new document in the specified database, using the supplied JSON
    document structure.

    If the JSON structure includes the ``_id`` field, then the document will be
    created with the specified document ID.

    If the ``_id`` field is not specified, a new unique ID will be generated,
    following whatever UUID algorithm is configured for that server.

    :param db: Database name
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :<header Content-Type: :mimetype:`application/json`
    :<header X-Couch-Full-Commit: Overrides server's
      :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
      are: ``false`` and ``true``. *Optional*.

    :query string batch: Stores document in :ref:`batch mode
      <api/doc/batch-writes>` Possible values: ``ok``. *Optional*

    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>header Location: Document's URI

    :>json string id: Document ID
    :>json boolean ok: Operation status
    :>json string rev: Revision info

    :code 201: Document created and stored on disk
    :code 202: Document data accepted, but not yet stored on disk
    :code 400: Invalid database name
    :code 401: Write privileges required
    :code 404: Database doesn't exist
    :code 409: A Conflicting Document with same ID already exists

    **Request**:

    .. code-block:: http

        POST /db HTTP/1.1
        Accept: application/json
        Content-Length: 81
        Content-Type: application/json

        {
            "servings": 4,
            "subtitle": "Delicious with fresh bread",
            "title": "Fish Stew"
        }

    **Response**:

    .. code-block:: http

        HTTP/1.1 201 Created
        Cache-Control: must-revalidate
        Content-Length: 95
        Content-Type: application/json
        Date: Tue, 13 Aug 2013 15:19:25 GMT
        Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d
        Server: CouchDB (Erlang/OTP)

        {
            "id": "ab39fe0993049b84cfa81acd6ebad09d",
            "ok": true,
            "rev": "1-9c65296036141e575d32ba9c034dd3ee"
        }

Specifying the Document ID
==========================

The document ID can be specified by including the ``_id`` field in the
JSON of the submitted record. The following request will create the same
document with the ID ``FishStew``.

    **Request**:

    .. code-block:: http

        POST /db HTTP/1.1
        Accept: application/json
        Content-Length: 98
        Content-Type: application/json

        {
            "_id": "FishStew",
            "servings": 4,
            "subtitle": "Delicious with fresh bread",
            "title": "Fish Stew"
        }

    **Response**:

    .. code-block:: http

        HTTP/1.1 201 Created
        Cache-Control: must-revalidate
        Content-Length: 71
        Content-Type: application/json
        Date: Tue, 13 Aug 2013 15:19:25 GMT
        ETag: "1-9c65296036141e575d32ba9c034dd3ee"
        Location: http://localhost:5984/db/FishStew
        Server: CouchDB (Erlang/OTP)

        {
            "id": "FishStew",
            "ok": true,
            "rev": "1-9c65296036141e575d32ba9c034dd3ee"
        }

.. _api/doc/batch-writes:

Batch Mode Writes
=================

You can write documents to the database at a higher rate by using the batch
option. This collects document writes together in memory (on a per-user basis)
before they are committed to disk. This increases the risk of the documents not
being stored in the event of a failure, since the documents are not written to
disk immediately.

Batch mode is not suitable for critical data, but may be ideal for applications
such as log data, when the risk of some data loss due to a crash is acceptable.

To use batch mode, append the ``batch=ok`` query argument to the URL of a
:post:`/{db}`, :put:`/{db}/{docid}`, or :delete:`/{db}/{docid}` request. The
CouchDB server will respond with an HTTP :statuscode:`202` response code
immediately.

Documents in the batch may be manually flushed by using the
:post:`/{db}/_ensure_full_commit` endpoint.

.. note::
    Creating or updating documents with batch mode doesn't guarantee that all
    documents will be successfully stored on disk. For example, individual
    documents may not be saved due to conflicts, rejection by
    :ref:`validation function <vdufun>` or by other reasons, even if overall
    the batch was successfully submitted.

**Request**:

.. code-block:: http

    POST /db?batch=ok HTTP/1.1
    Accept: application/json
    Content-Length: 98
    Content-Type: application/json

    {
        "_id": "FishStew",
        "servings": 4,
        "subtitle": "Delicious with fresh bread",
        "title": "Fish Stew"
    }

**Response**:

.. code-block:: http

    HTTP/1.1 202 Accepted
    Cache-Control: must-revalidate
    Content-Length: 28
    Content-Type: application/json
    Date: Tue, 13 Aug 2013 15:19:25 GMT
    Location: http://localhost:5984/db/FishStew
    Server: CouchDB (Erlang/OTP)

    {
        "id": "FishStew",
        "ok": true
    }

.. _Regular Expressions: http://en.wikipedia.org/wiki/Regular_expression