1.3.1. /{db} — Apache CouchDB® 3.5 Documentation

# 1.3.1. `/{db}`

HEAD /{db}

  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.

  Parameters:

    - db – Database name

  Status Codes:

    - 200 OK – Database exists

    - 404 Not Found – Requested database not found

  Request:

      HEAD /test HTTP/1.1
      Host: localhost:5984

  Response:

      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)

GET /{db}

  Gets information about the specified database.

  Parameters:

    - db – Database name

  Request Headers:

    - Accept –

      - application/json

      - text/plain

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

  Response JSON Object:

    - cluster.n (number) – Replicas. The number of copies of every document.

    - cluster.q (number) – Shards. The number of range partitions.

    - cluster.r (number) – Read quorum. The number of consistent copies of a document that need to be read before a successful reply.

    - cluster.w (number) – Write quorum. The number of copies of a document that need to be written before a successful reply.

    - compact_running (boolean) – Set to `true` if the database compaction routine is operating on this database.

    - db_name (string) – The name of the database.

    - disk_format_version (number) – The version of the physical format used for the data when it is stored on disk.

    - doc_count (number) – A count of the documents in the specified database.

    - doc_del_count (number) – Number of deleted documents

    - instance_start_time (string) – Always `"0"`. (Returned for legacy reasons.)

    - purge_seq (string) – An opaque string that describes the purge state of the database. Do not rely on this string for counting the number of purge operations.

    - sizes.active (number) – The size of live data inside the database, in bytes.

    - sizes.external (number) – The uncompressed size of database contents in bytes.

    - sizes.file (number) – The size of the database file on disk in bytes. Views indexes are not included in the calculation.

    - update_seq (string) – An opaque string that describes the state of the database. Do not rely on this string for counting the number of updates.

    - props.partitioned (boolean) – (optional) If present and true, this indicates that the database is partitioned.

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – Unauthorized request to a protected API

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Requested database not found

  Request:

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

  Response:

      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,
          "db_name": "receipts",
          "disk_format_version": 6,
          "doc_count": 6146,
          "doc_del_count": 64637,
          "instance_start_time": "0",
          "props": {},
          "purge_seq": 0,
          "sizes": {
              "active": 65031503,
              "external": 66982448,
              "file": 137433211
          },
          "update_seq": "292786-g1AAAAF..."
      }

PUT /{db}

  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_$()+/-]*$`.

  Parameters:

    - db – Database name

  Query Parameters:

    - q (integer) – Shards, aka the number of range partitions. Default is 2, unless overridden in the `cluster config`.

    - n (integer) – Replicas. The number of copies of the database in the cluster. The default is 3, unless overridden in the `cluster config` .

    - partitioned (boolean) – Whether to create a partitioned database. Default is false.

  Request Headers:

    - Accept –

      - application/json

      - text/plain

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

    - Location – Database URI location

  Response JSON Object:

    - ok (boolean) – Operation status. Available in case of success

    - error (string) – Error type. Available if response code is `4xx`

    - reason (string) – Error description. Available if response code is `4xx`

  Status Codes:

    - 201 Created – Database created successfully (quorum is met)

    - 202 Accepted – Accepted (at least by one node)

    - 400 Bad Request – Invalid database name

    - 401 Unauthorized – CouchDB Server Administrator privileges required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 412 Precondition Failed – Database already exists

  Request:

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

  Response:

      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 `412` since the database already exists:

  Request:

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

  Response:

      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 `400`:

  Request:

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

  Request:

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

DELETE /{db}

  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.

  Parameters:

    - db – Database name

  Request Headers:

    - Accept –

      - application/json

      - text/plain

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

  Response JSON Object:

    - ok (boolean) – Operation status

  Status Codes:

    - 200 OK – Database removed successfully (quorum is met and database is deleted by at least one node)

    - 202 Accepted – Accepted (deleted by at least one of the nodes, quorum is not met yet)

    - 400 Bad Request – Invalid database name or forgotten document id by accident

    - 401 Unauthorized – CouchDB Server Administrator privileges required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Database doesn’t exist or invalid database name

  Request:

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

  Response:

      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
      }

POST /{db}

  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.

  Parameters:

    - db – Database name

  Request Headers:

    - Accept –

      - application/json

      - text/plain

    - Content-Type – application/json

  Query Parameters:

    - batch (string) – Stores document in batch mode Possible values: `ok`. Optional

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

    - Location – Document’s URI

  Response JSON Object:

    - id (string) – Document ID

    - ok (boolean) – Operation status

    - rev (string) – Revision info

  Status Codes:

    - 201 Created – Document created and stored on disk

    - 202 Accepted – Document data accepted, but not yet stored on disk

    - 400 Bad Request – Invalid database name

    - 401 Unauthorized – Write privileges required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Database doesn’t exist

    - 409 Conflict – A Conflicting Document with same ID already exists

  Request:

      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:

      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"
      }

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

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

>     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"
>     }

## 1.3.1.2. 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 202 Accepted response code immediately.

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 validation function or by other reasons, even if overall the batch was successfully submitted.

Request:

    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:

    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
    }