1.2.1. /

GET /

Accessing the root of a CouchDB instance returns meta information about the instance. The response is a JSON structure containing information about the server, including a welcome message and the version of the server.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET / HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 179
  4. Content-Type: application/json
  5. Date: Sat, 10 Aug 2013 06:33:33 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.     "couchdb": "Welcome",
  10.     "uuid": "85fb71bf700c17267fef77535820e371",
  11.     "vendor": {
  12.         "name": "The Apache Software Foundation",
  13.         "version": "1.3.1"
  14.     },
  15.     "version": "1.3.1"
  16. }

1.2.2. /_active_tasks

Changed in version 2.1.0: Because of how the scheduling replicator works, continuous replication jobs could be periodically stopped and then started later. When they are not running they will not appear in the _active_tasks endpoint

GET /_active_tasks

List of running tasks, including the task type, name, status and process ID. The result is a JSON array of the currently running tasks, with each task being described with a single object. Depending on operation type set of response object fields might be different.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Response JSON Object

    • changes_done (number) – Processed changes

    • database (string) – Source database

    • pid (string) – Process ID

    • progress (number) – Current percentage progress

    • started_on (number) – Task start time as unix timestamp

    • status (string) – Task status message

    • task (string) – Task name

    • total_changes (number) – Total changes to process

    • type (string) – Operation Type

    • updated_on (number) – Unix timestamp of last operation update

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

  1. GET /_active_tasks HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 1690
  4. Content-Type: application/json
  5. Date: Sat, 10 Aug 2013 06:37:31 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. [
  9.     {
  10.         "changes_done": 64438,
  11.         "database": "mailbox",
  12.         "pid": "<0.12986.1>",
  13.         "progress": 84,
  14.         "started_on": 1376116576,
  15.         "total_changes": 76215,
  16.         "type": "database_compaction",
  17.         "updated_on": 1376116619
  18.     },
  19.     {
  20.         "changes_done": 14443,
  21.         "database": "mailbox",
  22.         "design_document": "c9753817b3ba7c674d92361f24f59b9f",
  23.         "pid": "<0.10461.3>",
  24.         "progress": 18,
  25.         "started_on": 1376116621,
  26.         "total_changes": 76215,
  27.         "type": "indexer",
  28.         "updated_on": 1376116650
  29.     },
  30.     {
  31.         "changes_done": 5454,
  32.         "database": "mailbox",
  33.         "design_document": "_design/meta",
  34.         "pid": "<0.6838.4>",
  35.         "progress": 7,
  36.         "started_on": 1376116632,
  37.         "total_changes": 76215,
  38.         "type": "indexer",
  39.         "updated_on": 1376116651
  40.     },
  41.     {
  42.         "checkpointed_source_seq": 68585,
  43.         "continuous": false,
  44.         "doc_id": null,
  45.         "doc_write_failures": 0,
  46.         "docs_read": 4524,
  47.         "docs_written": 4524,
  48.         "missing_revisions_found": 4524,
  49.         "pid": "<0.1538.5>",
  50.         "progress": 44,
  51.         "replication_id": "9bc1727d74d49d9e157e260bb8bbd1d5",
  52.         "revisions_checked": 4524,
  53.         "source": "mailbox",
  54.         "source_seq": 154419,
  55.         "started_on": 1376116644,
  56.         "target": "http://mailsrv:5984/mailbox",
  57.         "type": "replication",
  58.         "updated_on": 1376116651
  59.     }
  60. ]

1.2.3. /_all_dbs

GET /_all_dbs

Returns a list of all the databases in the CouchDB instance.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Query Parameters

    • descending (boolean) – Return the databases in descending order by key. Default is false.

    • endkey (json) – Stop returning databases when the specified key is reached.

    • end_key (json) – Alias for endkey param

    • limit (number) – Limit the number of the returned databases to the specified number.

    • skip (number) – Skip this number of databases before starting to return the results. Default is 0.

    • startkey (json) – Return databases starting with the specified key.

    • start_key (json) – Alias for startkey.

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET /_all_dbs HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 52
  4. Content-Type: application/json
  5. Date: Sat, 10 Aug 2013 06:57:48 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. [
  9.    "_users",
  10.    "contacts",
  11.    "docs",
  12.    "invoices",
  13.    "locations"
  14. ]

1.2.4. /_dbs_info

New in version 3.2.

GET /_dbs_info

Returns a list of all the databases information in the CouchDB instance.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Query Parameters

    • descending (boolean) – Return databases information in descending order by key. Default is false.

    • endkey (json) – Stop returning databases information when the specified key is reached.

    • end_key (json) – Alias for endkey param

    • limit (number) – Limit the number of the returned databases information to the specified number.

    • skip (number) – Skip this number of databases before starting to return the results. Default is 0.

    • startkey (json) – Return databases information starting with the specified key.

    • start_key (json) – Alias for startkey.

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET /_dbs_info HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Thu, 18 Nov 2021 14:37:35 GMT
  5. Server: CouchDB (Erlang OTP/23)
  7. [
  8.   {
  9.     "key": "animals",
  10.     "info": {
  11.       "db_name": "animals",
  12.       "update_seq": "52232",
  13.       "sizes": {
  14.         "file": 1178613587,
  15.         "external": 1713103872,
  16.         "active": 1162451555
  17.       },
  18.       "purge_seq": 0,
  19.       "doc_del_count": 0,
  20.       "doc_count": 52224,
  21.       "disk_format_version": 6,
  22.       "compact_running": false,
  23.       "cluster": {
  24.         "q": 8,
  25.         "n": 3,
  26.         "w": 2,
  27.         "r": 2
  28.       },
  29.       "instance_start_time": "0"
  30.     }
  31.   }
  32. ]

New in version 2.2.

POST /_dbs_info

Returns information of a list of the specified databases in the CouchDB instance. This enables you to request information about multiple databases in a single request, in place of multiple GET /{db} requests.

  • Request Headers

    Response Headers

    Request JSON Object

    • keys (array) – Array of database names to be requested

    Status Codes

Request:

  1. POST /_dbs_info HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984
  4. Content-Type: application/json
  6. {
  7.     "keys": [
  8.         "animals",
  9.         "plants"
  10.     ]
  11. }

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Sat, 20 Dec 2017 06:57:48 GMT
  5. Server: CouchDB (Erlang/OTP)
  7. [
  8.   {
  9.     "key": "animals",
  10.     "info": {
  11.       "db_name": "animals",
  12.       "update_seq": "52232",
  13.       "sizes": {
  14.         "file": 1178613587,
  15.         "external": 1713103872,
  16.         "active": 1162451555
  17.       },
  18.       "purge_seq": 0,
  19.       "doc_del_count": 0,
  20.       "doc_count": 52224,
  21.       "disk_format_version": 6,
  22.       "compact_running": false,
  23.       "cluster": {
  24.         "q": 8,
  25.         "n": 3,
  26.         "w": 2,
  27.         "r": 2
  28.       },
  29.       "instance_start_time": "0"
  30.     }
  31.   },
  32.   {
  33.     "key": "plants",
  34.     "info": {
  35.       "db_name": "plants",
  36.       "update_seq": "303",
  37.       "sizes": {
  38.         "file": 3872387,
  39.         "external": 2339,
  40.         "active": 67475
  41.       },
  42.       "purge_seq": 0,
  43.       "doc_del_count": 0,
  44.       "doc_count": 11,
  45.       "disk_format_version": 6,
  46.       "compact_running": false,
  47.       "cluster": {
  48.         "q": 8,
  49.         "n": 3,
  50.         "w": 2,
  51.         "r": 2
  52.       },
  53.       "instance_start_time": "0"
  54.     }
  55.   }
  56. ]

Note

The supported number of the specified databases in the list can be limited by modifying the max_db_number_for_dbs_info_req entry in configuration file. The default limit is 100. Increasing the limit, while possible, creates load on the server so it is advisable to have more requests with 100 dbs, rather than a few requests with 1000s of dbs at a time.

1.2.5. /_cluster_setup

New in version 2.0.

GET /_cluster_setup

Returns the status of the node or cluster, per the cluster setup wizard.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Query Parameters

    • ensure_dbs_exist (array) – List of system databases to ensure exist on the node/cluster. Defaults to ["_users","_replicator"].

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Response JSON Object

    • state (string) – Current state of the node and/or cluster (see below)

    Status Codes

    • 200 OK – Request completed successfully

The state returned indicates the current node or cluster state, and is one of the following:

  • cluster_disabled: The current node is completely unconfigured.

  • single_node_disabled: The current node is configured as a single (standalone) node ([cluster] n=1), but either does not have a server-level admin user defined, or does not have the standard system databases created. If the ensure_dbs_exist query parameter is specified, the list of databases provided overrides the default list of standard system databases.

  • single_node_enabled: The current node is configured as a single (standalone) node, has a server-level admin user defined, and has the ensure_dbs_exist list (explicit or default) of databases created.

  • cluster_enabled: The current node has [cluster] n > 1, is not bound to 127.0.0.1 and has a server-level admin user defined. However, the full set of standard system databases have not been created yet. If the ensure_dbs_exist query parameter is specified, the list of databases provided overrides the default list of standard system databases.

  • cluster_finished: The current node has [cluster] n > 1, is not bound to 127.0.0.1, has a server-level admin user defined and has the ensure_dbs_exist list (explicit or default) of databases created.

Request:

  1. GET /_cluster_setup HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. X-CouchDB-Body-Time: 0
  3. X-Couch-Request-ID: 5c058bdd37
  4. Server: CouchDB/2.1.0-7f17678 (Erlang OTP/17)
  5. Date: Sun, 30 Jul 2017 06:33:18 GMT
  6. Content-Type: application/json
  7. Content-Length: 29
  8. Cache-Control: must-revalidate
  10. {"state":"cluster_enabled"}

POST /_cluster_setup

Configure a node as a single (standalone) node, as part of a cluster, or finalise a cluster.

  • Request Headers

    Request JSON Object

    • action (string) –

      • enable_single_node: Configure the current node as a single, standalone CouchDB server.

      • enable_cluster: Configure the local or remote node as one node, preparing it to be joined to a new CouchDB cluster.

      • add_node: Add the specified remote node to this cluster’s list of nodes, joining it to the cluster.

      • finish_cluster: Finalise the cluster by creating the standard system databases.

    • bind_address (string) – The IP address to which to bind the current node. The special value 0.0.0.0 may be specified to bind to all interfaces on the host. (enable_cluster and enable_single_node only)

    • username (string) – The username of the server-level administrator to create. (enable_cluster and enable_single_node only), or the remote server’s administrator username (add_node)

    • password (string) – The password for the server-level administrator to create. (enable_cluster and enable_single_node only), or the remote server’s administrator username (add_node)

    • port (number) – The TCP port to which to bind this node (enable_cluster and enable_single_node only) or the TCP port to which to bind a remote node (add_node only).

    • node_count (number) – The total number of nodes to be joined into the cluster, including this one. Used to determine the value of the cluster’s n, up to a maximum of 3. (enable_cluster only)

    • remote_node (string) – The IP address of the remote node to setup as part of this cluster’s list of nodes. (enable_cluster only)

    • remote_current_user (string) – The username of the server-level administrator authorized on the remote node. (enable_cluster only)

    • remote_current_password (string) – The password of the server-level administrator authorized on the remote node. (enable_cluster only)

    • host (string) – The remote node IP of the node to add to the cluster. (add_node only)

    • ensure_dbs_exist (array) – List of system databases to ensure exist on the node/cluster. Defaults to ["_users","_replicator"].

No example request/response included here. For a worked example, please see The Cluster Setup API.

1.2.6. /_db_updates

New in version 1.4.

GET /_db_updates

Returns a list of all database events in the CouchDB instance. The existence of the _global_changes database is required to use this endpoint.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Query Parameters

    • feed (string) –

      • normal: Returns all historical DB changes, then closes the connection. Default.

      • longpoll: Closes the connection after the first event.

      • continuous: Send a line of JSON per event. Keeps the socket open until timeout.

      • eventsource: Like, continuous, but sends the events in EventSource format.

    • timeout (number) – Number of seconds until CouchDB closes the connection. Default is 60.

    • heartbeat (number) – Period in milliseconds after which an empty line is sent in the results. Only applicable for longpoll, continuous, and eventsource feeds. Overrides any timeout to keep the feed alive indefinitely. Default is 60000. May be true to use default value.

    • since (string) – Return only updates since the specified sequence ID. If the sequence ID is specified but does not exist, all changes are returned. May be the string now to begin showing only new updates.

    Response Headers

    Response JSON Object

    • results (array) – An array of database events. For longpoll and continuous modes, the entire response is the contents of the results array.

    • last_seq (string) – The last sequence ID reported.

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

The results field of database updates:

  • JSON Object

    • db_name (string) – Database name.

    • type (string) – A database event is one of created, updated, deleted.

    • seq (json) – Update sequence of the event.

Request:

  1. GET /_db_updates HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Sat, 18 Mar 2017 19:01:35 GMT
  5. Etag: "C1KU98Y6H0LGM7EQQYL6VSL07"
  6. Server: CouchDB/2.0.0 (Erlang OTP/17)
  7. Transfer-Encoding: chunked
  8. X-Couch-Request-ID: ad87efc7ff
  9. X-CouchDB-Body-Time: 0
  11. {
  12.     "results":[
  13.         {"db_name":"mailbox","type":"created","seq":"1-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZExFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4h"},
  14.         {"db_name":"mailbox","type":"deleted","seq":"2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60"},
  15.     ],
  16.     "last_seq": "2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60"
  17. }

1.2.7. /_membership

New in version 2.0.

GET /_membership

Displays the nodes that are part of the cluster as cluster_nodes. The field all_nodes displays all nodes this node knows about, including the ones that are part of the cluster. The endpoint is useful when setting up a cluster, see Node Management

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET /_membership HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Sat, 11 Jul 2015 07:02:41 GMT
  5. Server: CouchDB (Erlang/OTP)
  6. Content-Length: 142
  8. {
  9.     "all_nodes": [
  10.         "node1@127.0.0.1",
  11.         "node2@127.0.0.1",
  12.         "node3@127.0.0.1"
  13.     ],
  14.     "cluster_nodes": [
  15.         "node1@127.0.0.1",
  16.         "node2@127.0.0.1",
  17.         "node3@127.0.0.1"
  18.     ]
  19. }

1.2.8. /_replicate

POST /_replicate

Request, configure, or stop, a replication operation.

  • Request Headers

    Request JSON Object

    • cancel (boolean) – Cancels the replication

    • continuous (boolean) – Configure the replication to be continuous

    • create_target (boolean) – Creates the target database. Required administrator’s privileges on target server.

    • create_target_params (object) – An object that contains parameters to be used when creating the target database. Can include the standard q and n parameters.

    • doc_ids (array) – Array of document IDs to be synchronized. doc_ids, filter, and selector are mutually exclusive.

    • filter (string) – The name of a filter function. doc_ids, filter, and selector are mutually exclusive.

    • selector (json) – A selector to filter documents for synchronization. Has the same behavior as the selector objects in replication documents. doc_ids, filter, and selector are mutually exclusive.

    • source_proxy (string) – Address of a proxy server through which replication from the source should occur (protocol can be “http” or “socks5”)

    • target_proxy (string) – Address of a proxy server through which replication to the target should occur (protocol can be “http” or “socks5”)

    • source (string/object) – Fully qualified source database URL or an object which contains the full URL of the source database with additional parameters like headers. Eg: ‘http://example.com/source_db_name’ or {“url”:”url in here”, “headers”: {“header1”:”value1”, …}} . For backwards compatibility, CouchDB 3.x will auto-convert bare database names by prepending the address and port CouchDB is listening on, to form a complete URL. This behaviour is deprecated in 3.x and will be removed in CouchDB 4.0.

    • target (string/object) – Fully qualified target database URL or an object which contains the full URL of the target database with additional parameters like headers. Eg: ‘http://example.com/target_db_name’ or {“url”:”url in here”, “headers”: {“header1”:”value1”, …}} . For backwards compatibility, CouchDB 3.x will auto-convert bare database names by prepending the address and port CouchDB is listening on, to form a complete URL. This behaviour is deprecated in 3.x and will be removed in CouchDB 4.0.

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Response JSON Object

    • history (array) – Replication history (see below)

    • ok (boolean) – Replication status

    • replication_id_version (number) – Replication protocol version

    • session_id (string) – Unique session ID

    • source_last_seq (number) – Last sequence number read from source database

    Status Codes

The specification of the replication request is controlled through the JSON content of the request. The JSON should be an object with the fields defining the source, target and other options.

The Replication history is an array of objects with following structure:

  • JSON Object

    • doc_write_failures (number) – Number of document write failures

    • docs_read (number) – Number of documents read

    • docs_written (number) – Number of documents written to target

    • end_last_seq (number) – Last sequence number in changes stream

    • end_time (string) – Date/Time replication operation completed in RFC 2822 format

    • missing_checked (number) – Number of missing documents checked

    • missing_found (number) – Number of missing documents found

    • recorded_seq (number) – Last recorded sequence number

    • session_id (string) – Session ID for this replication operation

    • start_last_seq (number) – First sequence number in changes stream

    • start_time (string) – Date/Time replication operation started in RFC 2822 format

Note

As of CouchDB 2.0.0, fully qualified URLs are required for both the replication source and target parameters.

Request

  1. POST /_replicate HTTP/1.1
  2. Accept: application/json
  3. Content-Length: 80
  4. Content-Type: application/json
  5. Host: localhost:5984
  7. {
  8.     "source": "http://127.0.0.1:5984/db_a",
  9.     "target": "http://127.0.0.1:5984/db_b"
  10. }

Response

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 692
  4. Content-Type: application/json
  5. Date: Sun, 11 Aug 2013 20:38:50 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.     "history": [
  10.         {
  11.             "doc_write_failures": 0,
  12.             "docs_read": 10,
  13.             "docs_written": 10,
  14.             "end_last_seq": 28,
  15.             "end_time": "Sun, 11 Aug 2013 20:38:50 GMT",
  16.             "missing_checked": 10,
  17.             "missing_found": 10,
  18.             "recorded_seq": 28,
  19.             "session_id": "142a35854a08e205c47174d91b1f9628",
  20.             "start_last_seq": 1,
  21.             "start_time": "Sun, 11 Aug 2013 20:38:50 GMT"
  22.         },
  23.         {
  24.             "doc_write_failures": 0,
  25.             "docs_read": 1,
  26.             "docs_written": 1,
  27.             "end_last_seq": 1,
  28.             "end_time": "Sat, 10 Aug 2013 15:41:54 GMT",
  29.             "missing_checked": 1,
  30.             "missing_found": 1,
  31.             "recorded_seq": 1,
  32.             "session_id": "6314f35c51de3ac408af79d6ee0c1a09",
  33.             "start_last_seq": 0,
  34.             "start_time": "Sat, 10 Aug 2013 15:41:54 GMT"
  35.         }
  36.     ],
  37.     "ok": true,
  38.     "replication_id_version": 3,
  39.     "session_id": "142a35854a08e205c47174d91b1f9628",
  40.     "source_last_seq": 28
  41. }

1.2.8.1. Replication Operation

The aim of the replication is that at the end of the process, all active documents on the source database are also in the destination database and all documents that were deleted in the source databases are also deleted (if they exist) on the destination database.

Replication can be described as either push or pull replication:

  • Pull replication is where the source is the remote CouchDB instance, and the target is the local database.

    Pull replication is the most useful solution to use if your source database has a permanent IP address, and your destination (local) database may have a dynamically assigned IP address (for example, through DHCP). This is particularly important if you are replicating to a mobile or other device from a central server.

  • Push replication is where the source is a local database, and target is a remote database.

1.2.8.2. Specifying the Source and Target Database

You must use the URL specification of the CouchDB database if you want to perform replication in either of the following two situations:

  • Replication with a remote database (i.e. another instance of CouchDB on the same host, or a different host)

  • Replication with a database that requires authentication

For example, to request replication between a database local to the CouchDB instance to which you send the request, and a remote database you might use the following request:

  1. POST http://couchdb:5984/_replicate HTTP/1.1
  2. Content-Type: application/json
  3. Accept: application/json
  5. {
  6.     "source" : "recipes",
  7.     "target" : "http://coucdb-remote:5984/recipes",
  8. }

In all cases, the requested databases in the source and target specification must exist. If they do not, an error will be returned within the JSON object:

  1. {
  2.     "error" : "db_not_found"
  3.     "reason" : "could not open http://couchdb-remote:5984/ol1ka/",
  4. }

You can create the target database (providing your user credentials allow it) by adding the create_target field to the request object:

  1. POST http://couchdb:5984/_replicate HTTP/1.1
  2. Content-Type: application/json
  3. Accept: application/json
  5. {
  6.     "create_target" : true
  7.     "source" : "recipes",
  8.     "target" : "http://couchdb-remote:5984/recipes",
  9. }

The create_target field is not destructive. If the database already exists, the replication proceeds as normal.

1.2.8.3. Single Replication

You can request replication of a database so that the two databases can be synchronized. By default, the replication process occurs one time and synchronizes the two databases together. For example, you can request a single synchronization between two databases by supplying the source and target fields within the request JSON content.

  1. POST http://couchdb:5984/_replicate HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  5. {
  6.     "source" : "recipes",
  7.     "target" : "recipes-snapshot",
  8. }

In the above example, the databases recipes and recipes-snapshot will be synchronized. These databases are local to the CouchDB instance where the request was made. The response will be a JSON structure containing the success (or failure) of the synchronization process, and statistics about the process:

  1. {
  2.     "ok" : true,
  3.     "history" : [
  4.         {
  5.             "docs_read" : 1000,
  6.             "session_id" : "52c2370f5027043d286daca4de247db0",
  7.             "recorded_seq" : 1000,
  8.             "end_last_seq" : 1000,
  9.             "doc_write_failures" : 0,
  10.             "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
  11.             "start_last_seq" : 0,
  12.             "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
  13.             "missing_checked" : 0,
  14.             "docs_written" : 1000,
  15.             "missing_found" : 1000
  16.         }
  17.     ],
  18.     "session_id" : "52c2370f5027043d286daca4de247db0",
  19.     "source_last_seq" : 1000
  20. }

1.2.8.4. Continuous Replication

Synchronization of a database with the previously noted methods happens only once, at the time the replicate request is made. To have the target database permanently replicated from the source, you must set the continuous field of the JSON object within the request to true.

With continuous replication changes in the source database are replicated to the target database in perpetuity until you specifically request that replication ceases.

  1. POST http://couchdb:5984/_replicate HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  5. {
  6.     "continuous" : true
  7.     "source" : "recipes",
  8.     "target" : "http://couchdb-remote:5984/recipes",
  9. }

Changes will be replicated between the two databases as long as a network connection is available between the two instances.

Note

Two keep two databases synchronized with each other, you need to set replication in both directions; that is, you must replicate from source to target, and separately from target to source.

1.2.8.5. Canceling Continuous Replication

You can cancel continuous replication by adding the cancel field to the JSON request object and setting the value to true. Note that the structure of the request must be identical to the original for the cancellation request to be honoured. For example, if you requested continuous replication, the cancellation request must also contain the continuous field.

For example, the replication request:

  1. POST http://couchdb:5984/_replicate HTTP/1.1
  2. Content-Type: application/json
  3. Accept: application/json
  5. {
  6.     "source" : "recipes",
  7.     "target" : "http://couchdb-remote:5984/recipes",
  8.     "create_target" : true,
  9.     "continuous" : true
  10. }

Must be canceled using the request:

  1. POST http://couchdb:5984/_replicate HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  5. {
  6.     "cancel" : true,
  7.     "continuous" : true
  8.     "create_target" : true,
  9.     "source" : "recipes",
  10.     "target" : "http://couchdb-remote:5984/recipes",
  11. }

Requesting cancellation of a replication that does not exist results in a 404 error.

1.2.9. /_scheduler/jobs

GET /_scheduler/jobs

List of replication jobs. Includes replications created via /_replicate endpoint as well as those created from replication documents. Does not include replications which have completed or have failed to start because replication documents were malformed. Each job description will include source and target information, replication id, a history of recent event, and a few other things.

  • Request Headers

    Response Headers

    Query Parameters

    • limit (number) – How many results to return

    • skip (number) – How many result to skip starting at the beginning, ordered by replication ID

    Response JSON Object

    • offset (number) – How many results were skipped

    • total_rows (number) – Total number of replication jobs

    • id (string) – Replication ID.

    • database (string) – Replication document database

    • doc_id (string) – Replication document ID

    • history (list) – Timestamped history of events as a list of objects

    • pid (string) – Replication process ID

    • node (string) – Cluster node where the job is running

    • source (string) – Replication source

    • target (string) – Replication target

    • start_time (string) – Timestamp of when the replication was started

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

  1. GET /_scheduler/jobs HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 1690
  4. Content-Type: application/json
  5. Date: Sat, 29 Apr 2017 05:05:16 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.     "jobs": [
  10.         {
  11.             "database": "_replicator",
  12.             "doc_id": "cdyno-0000001-0000003",
  13.             "history": [
  14.                 {
  15.                     "timestamp": "2017-04-29T05:01:37Z",
  16.                     "type": "started"
  17.                 },
  18.                 {
  19.                     "timestamp": "2017-04-29T05:01:37Z",
  20.                     "type": "added"
  21.                 }
  22.             ],
  23.             "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous",
  24.             "info": {
  25.                 "changes_pending": 0,
  26.                 "checkpointed_source_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ",
  27.                 "doc_write_failures": 0,
  28.                 "docs_read": 113,
  29.                 "docs_written": 113,
  30.                 "missing_revisions_found": 113,
  31.                 "revisions_checked": 113,
  32.                 "source_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ",
  33.                 "through_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ"
  34.             },
  35.             "node": "node1@127.0.0.1",
  36.             "pid": "<0.1850.0>",
  37.             "source": "http://myserver.com/foo",
  38.             "start_time": "2017-04-29T05:01:37Z",
  39.             "target": "http://adm:*****@localhost:15984/cdyno-0000003/",
  40.             "user": null
  41.         },
  42.         {
  43.             "database": "_replicator",
  44.             "doc_id": "cdyno-0000001-0000002",
  45.             "history": [
  46.                 {
  47.                     "timestamp": "2017-04-29T05:01:37Z",
  48.                     "type": "started"
  49.                 },
  50.                 {
  51.                     "timestamp": "2017-04-29T05:01:37Z",
  52.                     "type": "added"
  53.                 }
  54.             ],
  55.             "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
  56.             "info": {
  57.                 "changes_pending": null,
  58.                 "checkpointed_source_seq": 0,
  59.                 "doc_write_failures": 0,
  60.                 "docs_read": 12,
  61.                 "docs_written": 12,
  62.                 "missing_revisions_found": 12,
  63.                 "revisions_checked": 12,
  64.                 "source_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg",
  65.                 "through_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg"
  66.             },
  67.             "node": "node2@127.0.0.1",
  68.             "pid": "<0.1757.0>",
  69.             "source": "http://myserver.com/foo",
  70.             "start_time": "2017-04-29T05:01:37Z",
  71.             "target": "http://adm:*****@localhost:15984/cdyno-0000002/",
  72.             "user": null
  73.         }
  74.     ],
  75.     "offset": 0,
  76.     "total_rows": 2
  77.  }

1.2.10. /_scheduler/docs

Changed in version 2.1.0: Use this endpoint to monitor the state of document-based replications. Previously needed to poll both documents and _active_tasks to get a complete state summary

Changed in version 3.0.0: In error states the “info” field switched from being a string to being an object

GET /_scheduler/docs

List of replication document states. Includes information about all the documents, even in completed and failed states. For each document it returns the document ID, the database, the replication ID, source and target, and other information.

  • Request Headers

    Response Headers

    Query Parameters

    • limit (number) – How many results to return

    • skip (number) – How many result to skip starting at the beginning, if ordered by document ID

    Response JSON Object

    • offset (number) – How many results were skipped

    • total_rows (number) – Total number of replication documents.

    • id (string) – Replication ID, or null if state is completed or failed

    • state (string) – One of following states (see Replication states for descriptions): initializing, running, completed, pending, crashing, error, failed

    • database (string) – Database where replication document came from

    • doc_id (string) – Replication document ID

    • node (string) – Cluster node where the job is running

    • source (string) – Replication source

    • target (string) – Replication target

    • start_time (string) – Timestamp of when the replication was started

    • last_updated (string) – Timestamp of last state update

    • info (object) – Will contain additional information about the state. For errors, this will be an object with an "error" field and string value. For success states, see below.

    • error_count (number) – Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress.

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

The info field of a scheduler doc:

  • JSON Object

    • revisions_checked (number) – The count of revisions which have been checked since this replication began.

    • missing_revisions_found (number) – The count of revisions which were found on the source, but missing from the target.

    • docs_read (number) – The count of docs which have been read from the source.

    • docs_written (number) – The count of docs which have been written to the target.

    • changes_pending (number) – The count of changes not yet replicated.

    • doc_write_failures (number) – The count of docs which failed to be written to the target.

    • checkpointed_source_seq (object) – The source sequence id which was last successfully replicated.

Request:

  1. GET /_scheduler/docs HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  3. Date: Sat, 29 Apr 2017 05:10:08 GMT
  4. Server: Server: CouchDB (Erlang/OTP)
  5. Transfer-Encoding: chunked
  7. {
  8.     "docs": [
  9.         {
  10.             "database": "_replicator",
  11.             "doc_id": "cdyno-0000001-0000002",
  12.             "error_count": 0,
  13.             "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
  14.             "info": {
  15.                 "changes_pending": 15,
  16.                 "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg",
  17.                 "doc_write_failures": 0,
  18.                 "docs_read": 67,
  19.                 "docs_written": 67,
  20.                 "missing_revisions_found": 67,
  21.                 "revisions_checked": 67,
  22.                 "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8",
  23.                 "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8"
  24.             },
  25.             "last_updated": "2017-04-29T05:01:37Z",
  26.             "node": "node2@127.0.0.1",
  27.             "source_proxy": null,
  28.             "target_proxy": null,
  29.             "source": "http://myserver.com/foo",
  30.             "start_time": "2017-04-29T05:01:37Z",
  31.             "state": "running",
  32.             "target": "http://adm:*****@localhost:15984/cdyno-0000002/"
  33.         },
  34.         {
  35.             "database": "_replicator",
  36.             "doc_id": "cdyno-0000001-0000003",
  37.             "error_count": 0,
  38.             "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous",
  39.             "info": {
  40.                 "changes_pending": null,
  41.                 "checkpointed_source_seq": 0,
  42.                 "doc_write_failures": 0,
  43.                 "docs_read": 12,
  44.                 "docs_written": 12,
  45.                 "missing_revisions_found": 12,
  46.                 "revisions_checked": 12,
  47.                 "source_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg",
  48.                 "through_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg"
  49.             },
  50.             "last_updated": "2017-04-29T05:01:37Z",
  51.             "node": "node1@127.0.0.1",
  52.             "source_proxy": null,
  53.             "target_proxy": null,
  54.             "source": "http://myserver.com/foo",
  55.             "start_time": "2017-04-29T05:01:37Z",
  56.             "state": "running",
  57.             "target": "http://adm:*****@localhost:15984/cdyno-0000003/"
  58.         }
  59.     ],
  60.     "offset": 0,
  61.     "total_rows": 2
  62. }

GET /_scheduler/docs/{replicator_db}

Get information about replication documents from a replicator database. The default replicator database is _replicator but other replicator databases can exist if their name ends with the suffix /_replicator.

Note

As a convenience slashes (/) in replicator db names do not have to be escaped. So /_scheduler/docs/other/_replicator is valid and equivalent to /_scheduler/docs/other%2f_replicator

  • Request Headers

    Response Headers

    Query Parameters

    • limit (number) – How many results to return

    • skip (number) – How many result to skip starting at the beginning, if ordered by document ID

    Response JSON Object

    • offset (number) – How many results were skipped

    • total_rows (number) – Total number of replication documents.

    • id (string) – Replication ID, or null if state is completed or failed

    • state (string) – One of following states (see Replication states for descriptions): initializing, running, completed, pending, crashing, error, failed

    • database (string) – Database where replication document came from

    • doc_id (string) – Replication document ID

    • node (string) – Cluster node where the job is running

    • source (string) – Replication source

    • target (string) – Replication target

    • start_time (string) – Timestamp of when the replication was started

    • last_update (string) – Timestamp of last state update

    • info (object) – Will contain additional information about the state. For errors, this will be an object with an "error" field and string value. For success states, see below.

    • error_count (number) – Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress.

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

The info field of a scheduler doc:

  • JSON Object

    • revisions_checked (number) – The count of revisions which have been checked since this replication began.

    • missing_revisions_found (number) – The count of revisions which were found on the source, but missing from the target.

    • docs_read (number) – The count of docs which have been read from the source.

    • docs_written (number) – The count of docs which have been written to the target.

    • changes_pending (number) – The count of changes not yet replicated.

    • doc_write_failures (number) – The count of docs which failed to be written to the target.

    • checkpointed_source_seq (object) – The source sequence id which was last successfully replicated.

Request:

  1. GET /_scheduler/docs/other/_replicator HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  3. Date: Sat, 29 Apr 2017 05:10:08 GMT
  4. Server: Server: CouchDB (Erlang/OTP)
  5. Transfer-Encoding: chunked
  7. {
  8.     "docs": [
  9.         {
  10.             "database": "other/_replicator",
  11.             "doc_id": "cdyno-0000001-0000002",
  12.             "error_count": 0,
  13.             "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
  14.             "info": {
  15.                 "changes_pending": 0,
  16.                 "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg",
  17.                 "doc_write_failures": 0,
  18.                 "docs_read": 67,
  19.                 "docs_written": 67,
  20.                 "missing_revisions_found": 67,
  21.                 "revisions_checked": 67,
  22.                 "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8",
  23.                 "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8"
  24.             },
  25.             "last_updated": "2017-04-29T05:01:37Z",
  26.             "node": "node2@127.0.0.1",
  27.             "source_proxy": null,
  28.             "target_proxy": null,
  29.             "source": "http://myserver.com/foo",
  30.             "start_time": "2017-04-29T05:01:37Z",
  31.             "state": "running",
  32.             "target": "http://adm:*****@localhost:15984/cdyno-0000002/"
  33.         }
  34.     ],
  35.     "offset": 0,
  36.     "total_rows": 1
  37. }

GET /_scheduler/docs/{replicator_db}/{docid}

Note

As a convenience slashes (/) in replicator db names do not have to be escaped. So /_scheduler/docs/other/_replicator is valid and equivalent to /_scheduler/docs/other%2f_replicator

  • Request Headers

    Response Headers

    Response JSON Object

    • id (string) – Replication ID, or null if state is completed or failed

    • state (string) – One of following states (see Replication states for descriptions): initializing, running, completed, pending, crashing, error, failed

    • database (string) – Database where replication document came from

    • doc_id (string) – Replication document ID

    • node (string) – Cluster node where the job is running

    • source (string) – Replication source

    • target (string) – Replication target

    • start_time (string) – Timestamp of when the replication was started

    • last_update (string) – Timestamp of last state update

    • info (object) – Will contain additional information about the state. For errors, this will be an object with an "error" field and string value. For success states, see below.

    • error_count (number) – Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress.

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

The info field of a scheduler doc:

  • JSON Object

    • revisions_checked (number) – The count of revisions which have been checked since this replication began.

    • missing_revisions_found (number) – The count of revisions which were found on the source, but missing from the target.

    • docs_read (number) – The count of docs which have been read from the source.

    • docs_written (number) – The count of docs which have been written to the target.

    • changes_pending (number) – The count of changes not yet replicated.

    • doc_write_failures (number) – The count of docs which failed to be written to the target.

    • checkpointed_source_seq (object) –

    • The source sequence id which was last

      successfully replicated.

    Request:

  1. GET /_scheduler/docs/other/_replicator/cdyno-0000001-0000002 HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  3. Date: Sat, 29 Apr 2017 05:10:08 GMT
  4. Server: Server: CouchDB (Erlang/OTP)
  5. Transfer-Encoding: chunked
  7. {
  8.     "database": "other/_replicator",
  9.     "doc_id": "cdyno-0000001-0000002",
  10.     "error_count": 0,
  11.     "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
  12.     "info": {
  13.         "changes_pending": 0,
  14.         "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg",
  15.         "doc_write_failures": 0,
  16.         "docs_read": 67,
  17.         "docs_written": 67,
  18.         "missing_revisions_found": 67,
  19.         "revisions_checked": 67,
  20.         "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8",
  21.         "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8"
  22.     },
  23.     "last_updated": "2017-04-29T05:01:37Z",
  24.     "node": "node2@127.0.0.1",
  25.     "source_proxy": null,
  26.     "target_proxy": null,
  27.     "source": "http://myserver.com/foo",
  28.     "start_time": "2017-04-29T05:01:37Z",
  29.     "state": "running",
  30.     "target": "http://adm:*****@localhost:15984/cdyno-0000002/"
  31. }

1.2.11. /_node/{node-name}

GET /_node/{node-name}

The /_node/{node-name} endpoint can be used to confirm the Erlang node name of the server that processes the request. This is most useful when accessing /_node/_local to retrieve this information. Repeatedly retrieving this information for a CouchDB endpoint can be useful to determine if a CouchDB cluster is correctly proxied through a reverse load balancer.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET /_node/_local HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 27
  4. Content-Type: application/json
  5. Date: Tue, 28 Jan 2020 19:25:51 GMT
  6. Server: CouchDB (Erlang OTP)
  7. X-Couch-Request-ID: 5b8db6c677
  8. X-CouchDB-Body-Time: 0
  10. {"name":"node1@127.0.0.1"}

1.2.12. /_node/{node-name}/_stats

GET /_node/{node-name}/_stats

The _stats resource returns a JSON object containing the statistics for the running server. The object is structured with top-level sections collating the statistics for a range of entries, with each individual statistic being easily identified, and the content of each statistic is self-describing.

Statistics are sampled internally on a configurable interval. When monitoring the _stats endpoint, you need to use a polling frequency of at least twice this to observe accurate results. For example, if the interval is 10 seconds, poll _stats at least every 5 seconds.

The literal string _local serves as an alias for the local node name, so for all stats URLs, {node-name} may be replaced with _local, to interact with the local node’s statistics.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET /_node/_local/_stats/couchdb/request_time HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 187
  4. Content-Type: application/json
  5. Date: Sat, 10 Aug 2013 11:41:11 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.   "value": {
  10.     "min": 0,
  11.     "max": 0,
  12.     "arithmetic_mean": 0,
  13.     "geometric_mean": 0,
  14.     "harmonic_mean": 0,
  15.     "median": 0,
  16.     "variance": 0,
  17.     "standard_deviation": 0,
  18.     "skewness": 0,
  19.     "kurtosis": 0,
  20.     "percentile": [
  21.       [
  22.         50,
  23.         0
  24.       ],
  25.       [
  26.         75,
  27.         0
  28.       ],
  29.       [
  30.         90,
  31.         0
  32.       ],
  33.       [
  34.         95,
  35.         0
  36.       ],
  37.       [
  38.         99,
  39.         0
  40.       ],
  41.       [
  42.         999,
  43.         0
  44.       ]
  45.     ],
  46.     "histogram": [
  47.       [
  48.         0,
  49.         0
  50.       ]
  51.     ],
  52.     "n": 0
  53.   },
  54.   "type": "histogram",
  55.   "desc": "length of a request inside CouchDB without MochiWeb"
  56. }

The fields provide the current, minimum and maximum, and a collection of statistical means and quantities. The quantity in each case is not defined, but the descriptions below provide sufficient detail to determine units.

Statistics are reported by ‘group’. The statistics are divided into the following top-level sections:

  • couch_log: Logging subsystem

  • couch_replicator: Replication scheduler and subsystem

  • couchdb: Primary CouchDB database operations

  • fabric: Cluster-related operations

  • global_changes: Global changes feed

  • mem3: Node membership-related statistics

  • pread: CouchDB file-related exceptions

  • rexi: Cluster internal RPC-related statistics

The type of the statistic is included in the type field, and is one of the following:

  • counter: Monotonically increasing counter, resets on restart

  • histogram: Binned set of values with meaningful subdivisions. Scoped to the current collection interval.

  • gauge: Single numerical value that can go up and down

You can also access individual statistics by quoting the statistics sections and statistic ID as part of the URL path. For example, to get the request_time statistics within the couchdb section for the target node, you can use:

  1. GET /_node/_local/_stats/couchdb/request_time HTTP/1.1

This returns an entire statistics object, as with the full request, but containing only the requested individual statistic.

1.2.13. /_node/{node-name}/_prometheus

GET /_node/{node-name}/_prometheus

The _prometheus resource returns a text/plain response that consolidates our /_node/{node-name}/_stats, and /_node/{node-name}/_system endpoints. The format is determined by Prometheus. The format version is 2.0.

Request:

  1. GET /_node/_local/_prometheus HTTP/1.1
  2. Accept: text/plain
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 187
  4. Content-Type: text/plain; version=2.0
  5. Date: Sat, 10 May 2020 11:41:11 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. # TYPE couchdb_couch_log_requests_total counter
  9. couchdb_couch_log_requests_total{level="alert"} 0
  10. couchdb_couch_log_requests_total{level="critical"} 0
  11. couchdb_couch_log_requests_total{level="debug"} 0
  12. couchdb_couch_log_requests_total{level="emergency"} 0
  13. couchdb_couch_log_requests_total{level="error"} 0
  14. couchdb_couch_log_requests_total{level="info"} 8
  15. couchdb_couch_log_requests_total{level="notice"} 51
  16. couchdb_couch_log_requests_total{level="warning"} 0
  17. # TYPE couchdb_couch_replicator_changes_manager_deaths_total counter
  18. couchdb_couch_replicator_changes_manager_deaths_total 0
  19. # TYPE couchdb_couch_replicator_changes_queue_deaths_total counter
  20. couchdb_couch_replicator_changes_queue_deaths_total 0
  21. # TYPE couchdb_couch_replicator_changes_read_failures_total counter
  22. couchdb_couch_replicator_changes_read_failures_total 0
  23. # TYPE couchdb_couch_replicator_changes_reader_deaths_total counter
  24. couchdb_couch_replicator_changes_reader_deaths_total 0
  25. # TYPE couchdb_couch_replicator_checkpoints_failure_total counter
  26. couchdb_couch_replicator_checkpoints_failure_total 0
  27. # TYPE couchdb_couch_replicator_checkpoints_total counter
  28. couchdb_couch_replicator_checkpoints_total 0
  29. # TYPE couchdb_couch_replicator_cluster_is_stable gauge
  30. couchdb_couch_replicator_cluster_is_stable 1
  31. # TYPE couchdb_couch_replicator_connection_acquires_total counter
  32. couchdb_couch_replicator_connection_acquires_total 0
  33. # TYPE couchdb_couch_replicator_connection_closes_total counter
  34. couchdb_couch_replicator_connection_closes_total 0
  35. # TYPE couchdb_couch_replicator_connection_creates_total counter
  36. couchdb_couch_replicator_connection_creates_total 0
  37. # TYPE couchdb_couch_replicator_connection_owner_crashes_total counter
  38. couchdb_couch_replicator_connection_owner_crashes_total 0
  39. # TYPE couchdb_couch_replicator_connection_releases_total counter
  40. couchdb_couch_replicator_connection_releases_total 0
  41. # TYPE couchdb_couch_replicator_connection_worker_crashes_total counter
  42. couchdb_couch_replicator_connection_worker_crashes_total 0
  43. # TYPE couchdb_couch_replicator_db_scans_total counter
  44. couchdb_couch_replicator_db_scans_total 1
  45. # TYPE couchdb_couch_replicator_docs_completed_state_updates_total counter
  46. couchdb_couch_replicator_docs_completed_state_updates_total 0
  47. # TYPE couchdb_couch_replicator_docs_db_changes_total counter
  48. couchdb_couch_replicator_docs_db_changes_total 0
  49. # TYPE couchdb_couch_replicator_docs_dbs_created_total counter
  50. couchdb_couch_replicator_docs_dbs_created_total 0
  51. # TYPE couchdb_couch_replicator_docs_dbs_deleted_total counter
  52. couchdb_couch_replicator_docs_dbs_deleted_total 0
  53. # TYPE couchdb_couch_replicator_docs_dbs_found_total counter
  54. couchdb_couch_replicator_docs_dbs_found_total 2
  55. # TYPE couchdb_couch_replicator_docs_failed_state_updates_total counter
  56. couchdb_couch_replicator_docs_failed_state_updates_total 0
  57. # TYPE couchdb_couch_replicator_failed_starts_total counter
  58. couchdb_couch_replicator_failed_starts_total 0
  59. # TYPE couchdb_couch_replicator_jobs_adds_total counter
  60. couchdb_couch_replicator_jobs_adds_total 0
  61. # TYPE couchdb_couch_replicator_jobs_crashed gauge
  62. couchdb_couch_replicator_jobs_crashed 0
  63. # TYPE couchdb_couch_replicator_jobs_crashes_total counter
  64. couchdb_couch_replicator_jobs_crashes_total 0
  65. # TYPE couchdb_couch_replicator_jobs_duplicate_adds_total counter
  66. couchdb_couch_replicator_jobs_duplicate_adds_total 0
  67. # TYPE couchdb_couch_replicator_jobs_pending gauge
  68. couchdb_couch_replicator_jobs_pending 0
  69. # TYPE couchdb_couch_replicator_jobs_removes_total counter
  70. couchdb_couch_replicator_jobs_removes_total 0
  71. # TYPE couchdb_couch_replicator_jobs_running gauge
  72. couchdb_couch_replicator_jobs_running 0
  73. # TYPE couchdb_couch_replicator_jobs_starts_total counter
  74. couchdb_couch_replicator_jobs_starts_total 0
  75. # TYPE couchdb_couch_replicator_jobs_stops_total counter
  76. couchdb_couch_replicator_jobs_stops_total 0
  77. # TYPE couchdb_couch_replicator_jobs_total gauge
  78. couchdb_couch_replicator_jobs_total 0
  79. # TYPE couchdb_couch_replicator_requests_total counter
  80. couchdb_couch_replicator_requests_total 0
  81. # TYPE couchdb_couch_replicator_responses_failure_total counter
  82. couchdb_couch_replicator_responses_failure_total 0
  83. # TYPE couchdb_couch_replicator_responses_total counter
  84. couchdb_couch_replicator_responses_total 0
  85. # TYPE couchdb_couch_replicator_stream_responses_failure_total counter
  86. couchdb_couch_replicator_stream_responses_failure_total 0
  87. # TYPE couchdb_couch_replicator_stream_responses_total counter
  88. couchdb_couch_replicator_stream_responses_total 0
  89. # TYPE couchdb_couch_replicator_worker_deaths_total counter
  90. couchdb_couch_replicator_worker_deaths_total 0
  91. # TYPE couchdb_couch_replicator_workers_started_total counter
  92. couchdb_couch_replicator_workers_started_total 0
  93. # TYPE couchdb_auth_cache_requests_total counter
  94. couchdb_auth_cache_requests_total 0
  95. # TYPE couchdb_auth_cache_misses_total counter
  96. couchdb_auth_cache_misses_total 0
  97. # TYPE couchdb_collect_results_time_seconds summary
  98. couchdb_collect_results_time_seconds{quantile="0.5"} 0.0
  99. couchdb_collect_results_time_seconds{quantile="0.75"} 0.0
  100. couchdb_collect_results_time_seconds{quantile="0.9"} 0.0
  101. couchdb_collect_results_time_seconds{quantile="0.95"} 0.0
  102. couchdb_collect_results_time_seconds{quantile="0.99"} 0.0
  103. couchdb_collect_results_time_seconds{quantile="0.999"} 0.0
  104. couchdb_collect_results_time_seconds_sum 0.0
  105. couchdb_collect_results_time_seconds_count 0
  106. # TYPE couchdb_couch_server_lru_skip_total counter
  107. couchdb_couch_server_lru_skip_total 0
  108. # TYPE couchdb_database_purges_total counter
  109. couchdb_database_purges_total 0
  110. # TYPE couchdb_database_reads_total counter
  111. couchdb_database_reads_total 0
  112. # TYPE couchdb_database_writes_total counter
  113. couchdb_database_writes_total 0
  114. # TYPE couchdb_db_open_time_seconds summary
  115. couchdb_db_open_time_seconds{quantile="0.5"} 0.0
  116. couchdb_db_open_time_seconds{quantile="0.75"} 0.0
  117. couchdb_db_open_time_seconds{quantile="0.9"} 0.0
  118. couchdb_db_open_time_seconds{quantile="0.95"} 0.0
  119. couchdb_db_open_time_seconds{quantile="0.99"} 0.0
  120. couchdb_db_open_time_seconds{quantile="0.999"} 0.0
  121. couchdb_db_open_time_seconds_sum 0.0
  122. couchdb_db_open_time_seconds_count 0
  123. # TYPE couchdb_dbinfo_seconds summary
  124. couchdb_dbinfo_seconds{quantile="0.5"} 0.0
  125. couchdb_dbinfo_seconds{quantile="0.75"} 0.0
  126. couchdb_dbinfo_seconds{quantile="0.9"} 0.0
  127. couchdb_dbinfo_seconds{quantile="0.95"} 0.0
  128. couchdb_dbinfo_seconds{quantile="0.99"} 0.0
  129. couchdb_dbinfo_seconds{quantile="0.999"} 0.0
  130. couchdb_dbinfo_seconds_sum 0.0
  131. couchdb_dbinfo_seconds_count 0
  132. # TYPE couchdb_document_inserts_total counter
  133. couchdb_document_inserts_total 0
  134. # TYPE couchdb_document_purges_failure_total counter
  135. couchdb_document_purges_failure_total 0
  136. # TYPE couchdb_document_purges_success_total counter
  137. couchdb_document_purges_success_total 0
  138. # TYPE couchdb_document_purges_total_total counter
  139. couchdb_document_purges_total_total 0
  140. # TYPE couchdb_document_writes_total counter
  141. couchdb_document_writes_total 0
  142. # TYPE couchdb_httpd_aborted_requests_total counter
  143. couchdb_httpd_aborted_requests_total 0
  144. # TYPE couchdb_httpd_all_docs_timeouts_total counter
  145. couchdb_httpd_all_docs_timeouts_total 0
  146. # TYPE couchdb_httpd_bulk_docs_seconds summary
  147. couchdb_httpd_bulk_docs_seconds{quantile="0.5"} 0.0
  148. couchdb_httpd_bulk_docs_seconds{quantile="0.75"} 0.0
  149. couchdb_httpd_bulk_docs_seconds{quantile="0.9"} 0.0
  150. couchdb_httpd_bulk_docs_seconds{quantile="0.95"} 0.0
  151. couchdb_httpd_bulk_docs_seconds{quantile="0.99"} 0.0
  152. couchdb_httpd_bulk_docs_seconds{quantile="0.999"} 0.0
  153. couchdb_httpd_bulk_docs_seconds_sum 0.0
  154. couchdb_httpd_bulk_docs_seconds_count 0
  155. ...remaining couchdb metrics from _stats and _system

If an additional port config option is specified, then a client can call this API using that port which does not require authentication. This option is false``(OFF) by default. When the option ``true``(ON), the default ports for a 3 node cluster are ``17986, 27986, 37986. See Configuration of Prometheus Endpoint for details.

  1. GET /_node/_local/_prometheus HTTP/1.1
  2. Accept: text/plain
  3. Host: localhost:17986

1.2.14. /_node/{node-name}/_system

GET /_node/{node-name}/_system

The _system resource returns a JSON object containing various system-level statistics for the running server. The object is structured with top-level sections collating the statistics for a range of entries, with each individual statistic being easily identified, and the content of each statistic is self-describing.

The literal string _local serves as an alias for the local node name, so for all stats URLs, {node-name} may be replaced with _local, to interact with the local node’s statistics.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET /_node/_local/_system HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 187
  4. Content-Type: application/json
  5. Date: Sat, 10 Aug 2013 11:41:11 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.   "uptime": 259,
  10.   "memory": {
  11.   ...
  12. }

These statistics are generally intended for CouchDB developers only.

1.2.15. /_node/{node-name}/_restart

POST /_node/{node-name}/_restart

This API is to facilitate integration testing only it is not meant to be used in production

  • Status Codes

    • 200 OK – Request completed successfully

1.2.16. /_search_analyze

Warning

Search endpoints require a running search plugin connected to each cluster node. See Search Plugin Installation for details.

New in version 3.0.

POST /_search_analyze

Tests the results of Lucene analyzer tokenization on sample text.

  • Parameters

    • field – Type of analyzer

    • text – Analyzer token you want to test

    Status Codes

Request:

  1. POST /_search_analyze HTTP/1.1
  2. Host: localhost:5984
  3. Content-Type: application/json
  5. {"analyzer":"english", "text":"running"}

Response:

  1. {
  2.     "tokens": [
  3.         "run"
  4.     ]
  5. }

1.2.17. /_utils

GET /_utils

Accesses the built-in Fauxton administration interface for CouchDB.

GET /_utils/

1.2.18. /_up

New in version 2.0.

GET /_up

Confirms that the server is up, running, and ready to respond to requests. If maintenance_mode is true or nolb, the endpoint will return a 404 response.

  • Response Headers

    Status Codes

    • 200 OK – Request completed successfully

    • 404 Not Found – The server is unavailable for requests at this time.

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 16
  4. Content-Type: application/json
  5. Date: Sat, 17 Mar 2018 04:46:26 GMT
  6. Server: CouchDB/2.2.0-f999071ec (Erlang OTP/19)
  7. X-Couch-Request-ID: c57a3b2787
  8. X-CouchDB-Body-Time: 0
  10. {"status":"ok"}

1.2.19. /_uuids

Changed in version 2.0.0.

GET /_uuids

Requests one or more Universally Unique Identifiers (UUIDs) from the CouchDB instance. The response is a JSON object providing a list of UUIDs.

  • Request Headers

    • Accept –

      • application/json

      • text/plain

    Query Parameters

    • count (number) – Number of UUIDs to return. Default is 1.

    Response Headers

    • Content-Type –

      • application/json

      • text/plain; charset=utf-8

    • ETag – Response hash

    Status Codes

Request:

  1. GET /_uuids?count=10 HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Length: 362
  3. Content-Type: application/json
  4. Date: Sat, 10 Aug 2013 11:46:25 GMT
  5. ETag: "DGRWWQFLUDWN5MRKSLKQ425XV"
  6. Expires: Fri, 01 Jan 1990 00:00:00 GMT
  7. Pragma: no-cache
  8. Server: CouchDB (Erlang/OTP)
  10. {
  11.     "uuids": [
  12.         "75480ca477454894678e22eec6002413",
  13.         "75480ca477454894678e22eec600250b",
  14.         "75480ca477454894678e22eec6002c41",
  15.         "75480ca477454894678e22eec6003b90",
  16.         "75480ca477454894678e22eec6003fca",
  17.         "75480ca477454894678e22eec6004bef",
  18.         "75480ca477454894678e22eec600528f",
  19.         "75480ca477454894678e22eec6005e0b",
  20.         "75480ca477454894678e22eec6006158",
  21.         "75480ca477454894678e22eec6006161"
  22.     ]
  23. }

The UUID type is determined by the UUID algorithm setting in the CouchDB configuration.

The UUID type may be changed at any time through the Configuration API. For example, the UUID type could be changed to random by sending this HTTP request:

  1. PUT http://couchdb:5984/_node/nonode@nohost/_config/uuids/algorithm HTTP/1.1
  2. Content-Type: application/json
  3. Accept: */*
  5. "random"

You can verify the change by obtaining a list of UUIDs:

  1. {
  2.     "uuids" : [
  3.         "031aad7b469956cf2826fcb2a9260492",
  4.         "6ec875e15e6b385120938df18ee8e496",
  5.         "cff9e881516483911aa2f0e98949092d",
  6.         "b89d37509d39dd712546f9510d4a9271",
  7.         "2e0dbf7f6c4ad716f21938a016e4e59f"
  8.     ]
  9. }

1.2.20. /favicon.ico

GET /favicon.ico

Binary content for the favicon.ico site icon.

  • Response Headers

    Status Codes

    • 200 OK – Request completed successfully

    • 404 Not Found – The requested content could not be found

1.2.21. /_reshard

New in version 2.4.

GET /_reshard

Returns a count of completed, failed, running, stopped, and total jobs along with the state of resharding on the cluster.

  • Request Headers

    Response Headers

    Response JSON Object

    • state (string) – stopped or running

    • state_reason (string) – null or string describing additional information or reason associated with the state

    • completed (number) – Count of completed resharding jobs

    • failed (number) – Count of failed resharding jobs

    • running (number) – Count of running resharding jobs

    • stopped (number) – Count of stopped resharding jobs

    • total (number) – Total count of resharding jobs

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

  1. GET /_reshard HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  5.     "completed": 21,
  6.     "failed": 0,
  7.     "running": 3,
  8.     "state": "running",
  9.     "state_reason": null,
  10.     "stopped": 0,
  11.     "total": 24
  12. }

GET /_reshard/state

Returns the resharding state and optional information about the state.

  • Request Headers

    Response Headers

    Response JSON Object

    • state (string) – stopped or running

    • state_reason (string) – Additional information or reason associated with the state

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

  1. GET /_reshard/state HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  5.     "reason": null,
  6.     "state": "running"
  7. }

PUT /_reshard/state

Change the resharding state on the cluster. The states are stopped or running. This starts and stops global resharding on all the nodes of the cluster. If there are any running jobs, they will be stopped when the state changes to stopped. When the state changes back to running those job will continue running.

  • Request Headers

    Response Headers

    Request JSON Object

    • state (string) – stopped or running

    • state_reason (string) – Optional string describing additional information or reason associated with the state

    Response JSON Object

    • ok (boolean) – true

    Status Codes

    • 200 OK – Request completed successfully

    • 400 Bad Request – Invalid request. Could be a bad or missing state name.

    • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

  1. PUT /_reshard/state HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984
  5. {
  6.     "state": "stopped",
  7.     "reason": "Rebalancing in progress"
  8. }

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  5.     "ok": true
  6. }

GET /_reshard/jobs

Note

The shape of the response and the total_rows and offset field in particular are meant to be consistent with the _scheduler/jobs endpoint.

  • Request Headers

    Response Headers

    Response JSON Object

    • jobs (list) – Array of json objects, one for each resharding job. For the fields of each job see the /_reshard/job/{jobid} endpoint.

    • offset (number) – Offset in the list of jobs object. Currently hard-coded at 0.

    • total_rows (number) – Total number of resharding jobs on the cluster.

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

  1. GET /_reshard/jobs HTTP/1.1
  2. Accept: application/json

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  5.     "jobs": [
  6.         {
  7.             "history": [
  8.                 {
  9.                     "detail": null,
  10.                     "timestamp": "2019-03-28T15:28:02Z",
  11.                     "type": "new"
  12.                 },
  13.                 {
  14.                     "detail": "initial_copy",
  15.                     "timestamp": "2019-03-28T15:28:02Z",
  16.                     "type": "running"
  17.                 },
  18.                 ...
  19.             ],
  20.             "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a",
  21.             "job_state": "completed",
  22.             "node": "node1@127.0.0.1",
  23.             "source": "shards/00000000-1fffffff/d1.1553786862",
  24.             "split_state": "completed",
  25.             "start_time": "2019-03-28T15:28:02Z",
  26.             "state_info": {},
  27.             "target": [
  28.                 "shards/00000000-0fffffff/d1.1553786862",
  29.                 "shards/10000000-1fffffff/d1.1553786862"
  30.             ],
  31.             "type": "split",
  32.             "update_time": "2019-03-28T15:28:08Z"
  33.         },
  34.         ...
  35.     ],
  36.     "offset": 0,
  37.     "total_rows": 24
  38. }

GET /_reshard/jobs/{jobid}

Get information about the resharding job identified by jobid.

  • Request Headers

    Response Headers

    Response JSON Object

    • id (string) – Job ID.

    • type (string) – Currently only split is implemented.

    • job_state (string) – The running state of the job. Could be one of new, running, stopped, completed or failed.

    • split_state (string) – State detail specific to shard splitting. It indicates how far has shard splitting progressed, and can be one of new, initial_copy, topoff1, build_indices, topoff2, copy_local_docs, update_shardmap, wait_source_close, topoff3, source_delete or completed.

    • state_info (object) – Optional additional info associated with the current state.

    • source (string) – For split jobs this will be the source shard.

    • target (list) – For split jobs this will be a list of two or more target shards.

    • history (list) – List of json objects recording a job’s state transition history.

    Status Codes

    • 200 OK – Request completed successfully

    • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

  1. GET /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1
  2. Accept: application/json

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  6.     "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a",
  7.     "job_state": "completed",
  8.     "node": "node1@127.0.0.1",
  9.     "source": "shards/00000000-1fffffff/d1.1553786862",
  10.     "split_state": "completed",
  11.     "start_time": "2019-03-28T15:28:02Z",
  12.     "state_info": {},
  13.     "target": [
  14.         "shards/00000000-0fffffff/d1.1553786862",
  15.         "shards/10000000-1fffffff/d1.1553786862"
  16.     ],
  17.     "type": "split",
  18.     "update_time": "2019-03-28T15:28:08Z",
  19.     "history": [
  20.         {
  21.             "detail": null,
  22.             "timestamp": "2019-03-28T15:28:02Z",
  23.             "type": "new"
  24.         },
  25.         {
  26.             "detail": "initial_copy",
  27.             "timestamp": "2019-03-28T15:28:02Z",
  28.             "type": "running"
  29.         },
  30.         ...
  31.     ]
  32. }

POST /_reshard/jobs

Depending on what fields are specified in the request, one or more resharding jobs will be created. The response is a json array of results. Each result object represents a single resharding job for a particular node and range. Some of the responses could be successful and some could fail. Successful results will have the "ok": true key and and value, and failed jobs will have the "error": "{error_message}" key and value.

  • Request Headers

    Response Headers

    Request JSON Object

    • type (string) – Type of job. Currently only "split" is accepted.

    • db (string) – Database to split. This is mutually exclusive with the "shard” field.

    • node (string) – Split shards on a particular node. This is an optional parameter. The value should be one of the nodes returned from the _membership endpoint.

    • range (string) – Split shards copies in the given range. The range format is hhhhhhhh-hhhhhhhh where h is a hexadecimal digit. This format is used since this is how the ranges are represented in the file system. This is parameter is optional and is mutually exclusive with the "shard" field.

    • shard (string) – Split a particular shard. The shard should be specified as "shards/{range}/{db}.{suffix}". Where range has the hhhhhhhh-hhhhhhhh format, db is the database name, and suffix is the shard (timestamp) creation suffix.

    • error (string) – Error message if a job could be not be created.

    • node – Cluster node where the job was created and is running.

    Response JSON Object

    • ok (boolean) – true if job created successfully.

    Status Codes

Request:

  1.  POST /_reshard/jobs HTTP/1.1
  2.  Accept: application/json
  3.  Content-Type: application/json
  5. {
  6.     "db": "db3",
  7.     "range": "80000000-ffffffff",
  8.     "type": "split"
  9. }

Response:

  1. HTTP/1.1 201 Created
  2. Content-Type: application/json
  4. [
  5.     {
  6.         "id": "001-30d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df557",
  7.         "node": "node1@127.0.0.1",
  8.         "ok": true,
  9.         "shard": "shards/80000000-ffffffff/db3.1554148353"
  10.     },
  11.     {
  12.         "id": "001-c2d734360b4cb3ff8b3feaccb2d787bf81ce2e773489eddd985ddd01d9de8e01",
  13.         "node": "node2@127.0.0.1",
  14.         "ok": true,
  15.         "shard": "shards/80000000-ffffffff/db3.1554148353"
  16.     }
  17. ]

DELETE /_reshard/jobs/{jobid}

If the job is running, stop the job and then remove it.

  • Response JSON Object

    • ok (boolean) – true if the job was removed successfully.

    Status Codes

Request:

  1. DELETE /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  5.     "ok": true
  6. }

GET /_reshard/jobs/{jobid}/state

Returns the running state of a resharding job identified by jobid.

  • Request Headers

    Response Headers

    Request JSON Object

    • state (string) – One of new, running, stopped, completed or failed.

    • state_reason (string) – Additional information associated with the state

    Status Codes

Request:

  1. GET /_reshard/jobs/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  5.     "reason": null,
  6.     "state": "running"
  7. }

PUT /_reshard/jobs/{jobid}/state

Change the state of a particular resharding job identified by jobid. The state can be changed from stopped to running or from running to stopped. If an individual job is stopped via this API it will stay stopped even after the global resharding state is toggled from stopped to running. If the job is already completed its state will stay completed.

  • Request Headers

    Response Headers

    Request JSON Object

    • state (string) – stopped or running

    • state_reason (string) – Optional string describing additional information or reason associated with the state

    Response JSON Object

    • ok (boolean) – true

    Status Codes

Request:

  1. PUT /_reshard/state/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984
  5. {
  6.     "state": "stopped",
  7.     "reason": "Rebalancing in progress"
  8. }

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  4. {
  5.      "ok": true
  6. }