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:
application/json
text/plain; charset=utf-8
- Status Codes:
200 OK – Request completed successfully
Request:
GET / HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 179 Content-Type: application/json Date: Sat, 10 Aug 2013 06:33:33 GMT Server: CouchDB (Erlang/OTP) { "couchdb": "Welcome", "uuid": "85fb71bf700c17267fef77535820e371", "vendor": { "name": "The Apache Software Foundation", "version": "1.3.1" }, "version": "1.3.1" }
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
Changed in version 3.3: Added “bulk_get_attempts” and “bulk_get_docs” fields for replication jobs.
- 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:
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:
GET /_active_tasks HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 1690 Content-Type: application/json Date: Sat, 10 Aug 2013 06:37:31 GMT Server: CouchDB (Erlang/OTP) [ { "changes_done": 64438, "database": "mailbox", "pid": "<0.12986.1>", "progress": 84, "started_on": 1376116576, "total_changes": 76215, "type": "database_compaction", "updated_on": 1376116619 }, { "changes_done": 14443, "database": "mailbox", "design_document": "c9753817b3ba7c674d92361f24f59b9f", "pid": "<0.10461.3>", "progress": 18, "started_on": 1376116621, "total_changes": 76215, "type": "indexer", "updated_on": 1376116650 }, { "changes_done": 5454, "database": "mailbox", "design_document": "_design/meta", "pid": "<0.6838.4>", "progress": 7, "started_on": 1376116632, "total_changes": 76215, "type": "indexer", "updated_on": 1376116651 }, { "checkpointed_source_seq": 68585, "continuous": false, "doc_id": null, "doc_write_failures": 0, "bulk_get_attempts": 4524, "bulk_get_docs": 4524, "docs_read": 4524, "docs_written": 4524, "missing_revisions_found": 4524, "pid": "<0.1538.5>", "progress": 44, "replication_id": "9bc1727d74d49d9e157e260bb8bbd1d5", "revisions_checked": 4524, "source": "mailbox", "source_seq": 154419, "started_on": 1376116644, "target": "http://mailsrv:5984/mailbox", "type": "replication", "updated_on": 1376116651 } ]
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
paramlimit (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:
application/json
text/plain; charset=utf-8
- Status Codes:
200 OK – Request completed successfully
Request:
GET /_all_dbs HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 52 Content-Type: application/json Date: Sat, 10 Aug 2013 06:57:48 GMT Server: CouchDB (Erlang/OTP) [ "_users", "contacts", "docs", "invoices", "locations" ]
1.2.4. /_dbs_info
¶
Added 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
paramlimit (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:
application/json
text/plain; charset=utf-8
- Status Codes:
200 OK – Request completed successfully
Request:
GET /_dbs_info HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Thu, 18 Nov 2021 14:37:35 GMT Server: CouchDB (Erlang OTP/23) [ { "key": "animals", "info": { "db_name": "animals", "update_seq": "52232", "sizes": { "file": 1178613587, "external": 1713103872, "active": 1162451555 }, "purge_seq": 0, "doc_del_count": 0, "doc_count": 52224, "disk_format_version": 6, "compact_running": false, "cluster": { "q": 8, "n": 3, "w": 2, "r": 2 }, "instance_start_time": "0" } } ]
Added 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:
Accept –
application/json
- Response Headers:
application/json
- Request JSON Object:
keys (array) – Array of database names to be requested
- Status Codes:
200 OK – Request completed successfully
400 Bad Request – Missing keys or exceeded keys in request
Request:
POST /_dbs_info HTTP/1.1 Accept: application/json Host: localhost:5984 Content-Type: application/json { "keys": [ "animals", "plants" ] }
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Sat, 20 Dec 2017 06:57:48 GMT Server: CouchDB (Erlang/OTP) [ { "key": "animals", "info": { "db_name": "animals", "update_seq": "52232", "sizes": { "file": 1178613587, "external": 1713103872, "active": 1162451555 }, "purge_seq": 0, "doc_del_count": 0, "doc_count": 52224, "disk_format_version": 6, "compact_running": false, "cluster": { "q": 8, "n": 3, "w": 2, "r": 2 }, "instance_start_time": "0" } }, { "key": "plants", "info": { "db_name": "plants", "update_seq": "303", "sizes": { "file": 3872387, "external": 2339, "active": 67475 }, "purge_seq": 0, "doc_del_count": 0, "doc_count": 11, "disk_format_version": 6, "compact_running": false, "cluster": { "q": 8, "n": 3, "w": 2, "r": 2 }, "instance_start_time": "0" } } ]
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
¶
Added 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:
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 theensure_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 theensure_dbs_exist
list (explicit or default) of databases created.cluster_enabled
: The current node has[cluster] n
> 1, is not bound to127.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 theensure_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 to127.0.0.1
, has a server-level admin user defined and has theensure_dbs_exist
list (explicit or default) of databases created.
Request:
GET /_cluster_setup HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK X-CouchDB-Body-Time: 0 X-Couch-Request-ID: 5c058bdd37 Server: CouchDB/2.1.0-7f17678 (Erlang OTP/17) Date: Sun, 30 Jul 2017 06:33:18 GMT Content-Type: application/json Content-Length: 29 Cache-Control: must-revalidate {"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:
Accept –
application/json
text/plain
Content-Type – application/json
- 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
¶
Added 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 milliseconds until CouchDB closes the connection. Default is
60000
.heartbeat (number) – Period in milliseconds after which an empty line is sent in the results. Only applicable for
longpoll
,continuous
, andeventsource
feeds. Overrides any timeout to keep the feed alive indefinitely. Default is60000
. May betrue
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:
application/json
text/plain; charset=utf-8
Transfer-Encoding –
chunked
- Response JSON Object:
results (array) – An array of database events. For
longpoll
andcontinuous
modes, the entire response is the contents of theresults
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 Parameters:
db_name (string) – Database name.
type (string) – A database event is one of
created
,updated
,deleted
.seq (json) – Update sequence of the event.
Request:
GET /_db_updates HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Sat, 18 Mar 2017 19:01:35 GMT Etag: "C1KU98Y6H0LGM7EQQYL6VSL07" Server: CouchDB/2.0.0 (Erlang OTP/17) Transfer-Encoding: chunked X-Couch-Request-ID: ad87efc7ff X-CouchDB-Body-Time: 0 { "results":[ {"db_name":"mailbox","type":"created","seq":"1-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZExFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4h"}, {"db_name":"mailbox","type":"deleted","seq":"2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60"} ], "last_seq": "2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60" }
1.2.7. /_membership
¶
Added in version 2.0.
- GET /_membership¶
Displays the nodes that are part of the cluster as
cluster_nodes
. The fieldall_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:
application/json
text/plain; charset=utf-8
- Status Codes:
200 OK – Request completed successfully
Request:
GET /_membership HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Sat, 11 Jul 2015 07:02:41 GMT Server: CouchDB (Erlang/OTP) Content-Length: 142 { "all_nodes": [ "node1@127.0.0.1", "node2@127.0.0.1", "node3@127.0.0.1" ], "cluster_nodes": [ "node1@127.0.0.1", "node2@127.0.0.1", "node3@127.0.0.1" ] }
1.2.8. /_replicate
¶
Changed in version 3.3: Added “bulk_get_attempts” and “bulk_get_docs” fields to the replication history response object.
- POST /_replicate¶
Request, configure, or stop, a replication operation.
- Request Headers:
Accept –
application/json
text/plain
Content-Type – application/json
- 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
andn
parameters.winning_revs_only (boolean) – Replicate winning revisions only.
doc_ids (array) – Array of document IDs to be synchronized.
doc_ids
,filter
, andselector
are mutually exclusive.filter (string) – The name of a filter function.
doc_ids
,filter
, andselector
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
, andselector
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:
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:
200 OK – Replication request successfully completed
202 Accepted – Continuous replication request has been accepted
400 Bad Request – Invalid JSON data
401 Unauthorized – CouchDB Server Administrator privileges required
404 Not Found – Either the source or target DB is not found or attempt to cancel unknown replication task
500 Internal Server Error – JSON specification was invalid
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 Parameters:
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
bulk_get_attempts (number) – The total count of attempted doc revisions fetched with
_bulk_get
.bulk_get_docs (number) – The total count of successful docs fetched with
_bulk_get
.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
POST /_replicate HTTP/1.1
Accept: application/json
Content-Length: 80
Content-Type: application/json
Host: localhost:5984
{
"source": "http://adm:pass@127.0.0.1:5984/db_a",
"target": "http://adm:pass@127.0.0.1:5984/db_b"
}
Response
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 692
Content-Type: application/json
Date: Sun, 11 Aug 2013 20:38:50 GMT
Server: CouchDB (Erlang/OTP)
{
"history": [
{
"doc_write_failures": 0,
"docs_read": 10,
"bulk_get_attempts": 10,
"bulk_get_docs": 10,
"docs_written": 10,
"end_last_seq": 28,
"end_time": "Sun, 11 Aug 2013 20:38:50 GMT",
"missing_checked": 10,
"missing_found": 10,
"recorded_seq": 28,
"session_id": "142a35854a08e205c47174d91b1f9628",
"start_last_seq": 1,
"start_time": "Sun, 11 Aug 2013 20:38:50 GMT"
},
{
"doc_write_failures": 0,
"docs_read": 1,
"bulk_get_attempts": 1,
"bulk_get_docs": 1,
"docs_written": 1,
"end_last_seq": 1,
"end_time": "Sat, 10 Aug 2013 15:41:54 GMT",
"missing_checked": 1,
"missing_found": 1,
"recorded_seq": 1,
"session_id": "6314f35c51de3ac408af79d6ee0c1a09",
"start_last_seq": 0,
"start_time": "Sat, 10 Aug 2013 15:41:54 GMT"
}
],
"ok": true,
"replication_id_version": 3,
"session_id": "142a35854a08e205c47174d91b1f9628",
"source_last_seq": 28
}
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 thetarget
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, andtarget
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:
POST http://couchdb:5984/_replicate HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"source" : "recipes",
"target" : "http://coucdb-remote:5984/recipes",
}
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:
{
"error" : "db_not_found"
"reason" : "could not open http://couchdb-remote:5984/ol1ka/",
}
You can create the target database (providing your user credentials allow it)
by adding the create_target
field to the request object:
POST http://couchdb:5984/_replicate HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"create_target" : true
"source" : "recipes",
"target" : "http://couchdb-remote:5984/recipes",
}
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.
POST http://couchdb:5984/_replicate HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"source" : "recipes",
"target" : "recipes-snapshot",
}
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:
{
"ok" : true,
"history" : [
{
"docs_read" : 1000,
"bulk_get_attempts": 1000,
"bulk_get_docs": 1000,
"session_id" : "52c2370f5027043d286daca4de247db0",
"recorded_seq" : 1000,
"end_last_seq" : 1000,
"doc_write_failures" : 0,
"start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
"start_last_seq" : 0,
"end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
"missing_checked" : 0,
"docs_written" : 1000,
"missing_found" : 1000
}
],
"session_id" : "52c2370f5027043d286daca4de247db0",
"source_last_seq" : 1000
}
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.
POST http://couchdb:5984/_replicate HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"continuous" : true
"source" : "recipes",
"target" : "http://couchdb-remote:5984/recipes",
}
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:
POST http://couchdb:5984/_replicate HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"source" : "recipes",
"target" : "http://couchdb-remote:5984/recipes",
"create_target" : true,
"continuous" : true
}
Must be canceled using the request:
POST http://couchdb:5984/_replicate HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"cancel" : true,
"continuous" : true
"create_target" : true,
"source" : "recipes",
"target" : "http://couchdb-remote:5984/recipes",
}
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:
Accept –
application/json
- Response Headers:
application/json
- 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:
GET /_scheduler/jobs HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 1690 Content-Type: application/json Date: Sat, 29 Apr 2017 05:05:16 GMT Server: CouchDB (Erlang/OTP) { "jobs": [ { "database": "_replicator", "doc_id": "cdyno-0000001-0000003", "history": [ { "timestamp": "2017-04-29T05:01:37Z", "type": "started" }, { "timestamp": "2017-04-29T05:01:37Z", "type": "added" } ], "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous", "info": { "changes_pending": 0, "checkpointed_source_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ", "doc_write_failures": 0, "docs_read": 113, "docs_written": 113, "bulk_get_attempts": 113, "bulk_get_docs": 113, "missing_revisions_found": 113, "revisions_checked": 113, "source_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ", "through_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ" }, "node": "node1@127.0.0.1", "pid": "<0.1850.0>", "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "target": "http://adm:*****@localhost:15984/cdyno-0000003/", "user": null }, { "database": "_replicator", "doc_id": "cdyno-0000001-0000002", "history": [ { "timestamp": "2017-04-29T05:01:37Z", "type": "started" }, { "timestamp": "2017-04-29T05:01:37Z", "type": "added" } ], "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": null, "checkpointed_source_seq": 0, "doc_write_failures": 0, "docs_read": 12, "docs_written": 12, "bulk_get_attempts": 12, "bulk_get_docs": 12, "missing_revisions_found": 12, "revisions_checked": 12, "source_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg", "through_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg" }, "node": "node2@127.0.0.1", "pid": "<0.1757.0>", "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "target": "http://adm:*****@localhost:15984/cdyno-0000002/", "user": null } ], "offset": 0, "total_rows": 2 }
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
Changed in version 3.3: Added “bulk_get_attempts” and “bulk_get_docs” the “info” object.
- GET /_scheduler/docs¶
List of replication document states. Includes information about all the documents, even in
completed
andfailed
states. For each document it returns the document ID, the database, the replication ID, source and target, and other information.- Request Headers:
Accept –
application/json
- Response Headers:
application/json
- 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 iscompleted
orfailed
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 Parameters:
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.
bulk_get_attempts (number) – The total count of attempted doc revisions fetched with
_bulk_get
.bulk_get_docs (number) – The total count of successful docs fetched with
_bulk_get
.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:
GET /_scheduler/docs HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Content-Type: application/json Date: Sat, 29 Apr 2017 05:10:08 GMT Server: Server: CouchDB (Erlang/OTP) Transfer-Encoding: chunked { "docs": [ { "database": "_replicator", "doc_id": "cdyno-0000001-0000002", "error_count": 0, "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": 15, "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg", "doc_write_failures": 0, "docs_read": 67, "bulk_get_attempts": 67, "bulk_get_docs": 67, "docs_written": 67, "missing_revisions_found": 67, "revisions_checked": 67, "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8", "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node2@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000002/" }, { "database": "_replicator", "doc_id": "cdyno-0000001-0000003", "error_count": 0, "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous", "info": { "changes_pending": null, "checkpointed_source_seq": 0, "doc_write_failures": 0, "bulk_get_attempts": 12, "bulk_get_docs": 12, "docs_read": 12, "docs_written": 12, "missing_revisions_found": 12, "revisions_checked": 12, "source_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg", "through_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node1@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000003/" } ], "offset": 0, "total_rows": 2 }
- 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:
Accept –
application/json
- Response Headers:
application/json
- 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 iscompleted
orfailed
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 Parameters:
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.
bulk_get_attempts (number) – The total count of attempted doc revisions fetched with
_bulk_get
.bulk_get_docs (number) – The total count of successful docs fetched with
_bulk_get
.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:
GET /_scheduler/docs/other/_replicator HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Content-Type: application/json Date: Sat, 29 Apr 2017 05:10:08 GMT Server: Server: CouchDB (Erlang/OTP) Transfer-Encoding: chunked { "docs": [ { "database": "other/_replicator", "doc_id": "cdyno-0000001-0000002", "error_count": 0, "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": 0, "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg", "doc_write_failures": 0, "docs_read": 67, "bulk_get_attempts": 67, "bulk_get_docs": 67, "docs_written": 67, "missing_revisions_found": 67, "revisions_checked": 67, "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8", "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node2@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000002/" } ], "offset": 0, "total_rows": 1 }
- 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:
Accept –
application/json
- Response Headers:
application/json
- Response JSON Object:
id (string) – Replication ID, or
null
if state iscompleted
orfailed
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 Parameters:
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.
bulk_get_attempts (number) – The total count of attempted doc revisions fetched with
_bulk_get
.bulk_get_docs (number) – The total count of successful docs fetched with
_bulk_get
.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:
GET /_scheduler/docs/other/_replicator/cdyno-0000001-0000002 HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Content-Type: application/json Date: Sat, 29 Apr 2017 05:10:08 GMT Server: Server: CouchDB (Erlang/OTP) Transfer-Encoding: chunked { "database": "other/_replicator", "doc_id": "cdyno-0000001-0000002", "error_count": 0, "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": 0, "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg", "doc_write_failures": 0, "docs_read": 67, "bulk_get_attempts": 67, "bulk_get_docs": 67, "docs_written": 67, "missing_revisions_found": 67, "revisions_checked": 67, "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8", "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node2@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000002/" }
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:
application/json
text/plain; charset=utf-8
- Status Codes:
200 OK – Request completed successfully
Request:
GET /_node/_local HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 27 Content-Type: application/json Date: Tue, 28 Jan 2020 19:25:51 GMT Server: CouchDB (Erlang OTP) X-Couch-Request-ID: 5b8db6c677 X-CouchDB-Body-Time: 0 {"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:
application/json
text/plain; charset=utf-8
- Status Codes:
200 OK – Request completed successfully
Request:
GET /_node/_local/_stats/couchdb/request_time HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 187 Content-Type: application/json Date: Sat, 10 Aug 2013 11:41:11 GMT Server: CouchDB (Erlang/OTP) { "value": { "min": 0, "max": 0, "arithmetic_mean": 0, "geometric_mean": 0, "harmonic_mean": 0, "median": 0, "variance": 0, "standard_deviation": 0, "skewness": 0, "kurtosis": 0, "percentile": [ [ 50, 0 ], [ 75, 0 ], [ 90, 0 ], [ 95, 0 ], [ 99, 0 ], [ 999, 0 ] ], "histogram": [ [ 0, 0 ] ], "n": 0 }, "type": "histogram", "desc": "length of a request inside CouchDB without MochiWeb" }
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 subsystemcouch_replicator
: Replication scheduler and subsystemcouchdb
: Primary CouchDB database operationsfabric
: Cluster-related operationsglobal_changes
: Global changes feedmem3
: Node membership-related statisticspread
: CouchDB file-related exceptionsrexi
: 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 restarthistogram
: 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:
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:
GET /_node/_local/_prometheus HTTP/1.1 Accept: text/plain Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 187 Content-Type: text/plain; version=2.0 Date: Sat, 10 May 2020 11:41:11 GMT Server: CouchDB (Erlang/OTP) # TYPE couchdb_couch_log_requests_total counter couchdb_couch_log_requests_total{level="alert"} 0 couchdb_couch_log_requests_total{level="critical"} 0 couchdb_couch_log_requests_total{level="debug"} 0 couchdb_couch_log_requests_total{level="emergency"} 0 couchdb_couch_log_requests_total{level="error"} 0 couchdb_couch_log_requests_total{level="info"} 8 couchdb_couch_log_requests_total{level="notice"} 51 couchdb_couch_log_requests_total{level="warning"} 0 # TYPE couchdb_couch_replicator_changes_manager_deaths_total counter couchdb_couch_replicator_changes_manager_deaths_total 0 # TYPE couchdb_couch_replicator_changes_queue_deaths_total counter couchdb_couch_replicator_changes_queue_deaths_total 0 # TYPE couchdb_couch_replicator_changes_read_failures_total counter couchdb_couch_replicator_changes_read_failures_total 0 # TYPE couchdb_couch_replicator_changes_reader_deaths_total counter couchdb_couch_replicator_changes_reader_deaths_total 0 # TYPE couchdb_couch_replicator_checkpoints_failure_total counter couchdb_couch_replicator_checkpoints_failure_total 0 # TYPE couchdb_couch_replicator_checkpoints_total counter couchdb_couch_replicator_checkpoints_total 0 # TYPE couchdb_couch_replicator_connection_acquires_total counter couchdb_couch_replicator_connection_acquires_total 0 # TYPE couchdb_couch_replicator_connection_closes_total counter couchdb_couch_replicator_connection_closes_total 0 # TYPE couchdb_couch_replicator_connection_creates_total counter couchdb_couch_replicator_connection_creates_total 0 # TYPE couchdb_couch_replicator_connection_owner_crashes_total counter couchdb_couch_replicator_connection_owner_crashes_total 0 # TYPE couchdb_couch_replicator_connection_releases_total counter couchdb_couch_replicator_connection_releases_total 0 # TYPE couchdb_couch_replicator_connection_worker_crashes_total counter couchdb_couch_replicator_connection_worker_crashes_total 0 # TYPE couchdb_couch_replicator_db_scans_total counter couchdb_couch_replicator_db_scans_total 1 # TYPE couchdb_couch_replicator_docs_completed_state_updates_total counter couchdb_couch_replicator_docs_completed_state_updates_total 0 # TYPE couchdb_couch_replicator_docs_db_changes_total counter couchdb_couch_replicator_docs_db_changes_total 0 # TYPE couchdb_couch_replicator_docs_dbs_deleted_total counter couchdb_couch_replicator_docs_dbs_deleted_total 0 # TYPE couchdb_couch_replicator_docs_dbs_found_total counter couchdb_couch_replicator_docs_dbs_found_total 2 # TYPE couchdb_couch_replicator_docs_failed_state_updates_total counter couchdb_couch_replicator_docs_failed_state_updates_total 0 # TYPE couchdb_couch_replicator_failed_starts_total counter couchdb_couch_replicator_failed_starts_total 0 # TYPE couchdb_couch_replicator_jobs_adds_total counter couchdb_couch_replicator_jobs_adds_total 0 # TYPE couchdb_couch_replicator_jobs_crashed gauge couchdb_couch_replicator_jobs_crashed 0 # TYPE couchdb_couch_replicator_jobs_crashes_total counter couchdb_couch_replicator_jobs_crashes_total 0 # TYPE couchdb_couch_replicator_jobs_duplicate_adds_total counter couchdb_couch_replicator_jobs_duplicate_adds_total 0 # TYPE couchdb_couch_replicator_jobs_pending gauge couchdb_couch_replicator_jobs_pending 0 # TYPE couchdb_couch_replicator_jobs_removes_total counter couchdb_couch_replicator_jobs_removes_total 0 # TYPE couchdb_couch_replicator_jobs_running gauge couchdb_couch_replicator_jobs_running 0 # TYPE couchdb_couch_replicator_jobs_starts_total counter couchdb_couch_replicator_jobs_starts_total 0 # TYPE couchdb_couch_replicator_jobs_stops_total counter couchdb_couch_replicator_jobs_stops_total 0 # TYPE couchdb_couch_replicator_jobs_total gauge couchdb_couch_replicator_jobs_total 0 # TYPE couchdb_couch_replicator_requests_total counter couchdb_couch_replicator_requests_total 0 # TYPE couchdb_couch_replicator_responses_failure_total counter couchdb_couch_replicator_responses_failure_total 0 # TYPE couchdb_couch_replicator_responses_total counter couchdb_couch_replicator_responses_total 0 # TYPE couchdb_couch_replicator_stream_responses_failure_total counter couchdb_couch_replicator_stream_responses_failure_total 0 # TYPE couchdb_couch_replicator_stream_responses_total counter couchdb_couch_replicator_stream_responses_total 0 # TYPE couchdb_couch_replicator_worker_deaths_total counter couchdb_couch_replicator_worker_deaths_total 0 # TYPE couchdb_couch_replicator_workers_started_total counter couchdb_couch_replicator_workers_started_total 0 # TYPE couchdb_auth_cache_requests_total counter couchdb_auth_cache_requests_total 0 # TYPE couchdb_auth_cache_misses_total counter couchdb_auth_cache_misses_total 0 # TYPE couchdb_collect_results_time_seconds summary couchdb_collect_results_time_seconds{quantile="0.5"} 0.0 couchdb_collect_results_time_seconds{quantile="0.75"} 0.0 couchdb_collect_results_time_seconds{quantile="0.9"} 0.0 couchdb_collect_results_time_seconds{quantile="0.95"} 0.0 couchdb_collect_results_time_seconds{quantile="0.99"} 0.0 couchdb_collect_results_time_seconds{quantile="0.999"} 0.0 couchdb_collect_results_time_seconds_sum 0.0 couchdb_collect_results_time_seconds_count 0 # TYPE couchdb_couch_server_lru_skip_total counter couchdb_couch_server_lru_skip_total 0 # TYPE couchdb_database_purges_total counter couchdb_database_purges_total 0 # TYPE couchdb_database_reads_total counter couchdb_database_reads_total 0 # TYPE couchdb_database_writes_total counter couchdb_database_writes_total 0 # TYPE couchdb_db_open_time_seconds summary couchdb_db_open_time_seconds{quantile="0.5"} 0.0 couchdb_db_open_time_seconds{quantile="0.75"} 0.0 couchdb_db_open_time_seconds{quantile="0.9"} 0.0 couchdb_db_open_time_seconds{quantile="0.95"} 0.0 couchdb_db_open_time_seconds{quantile="0.99"} 0.0 couchdb_db_open_time_seconds{quantile="0.999"} 0.0 couchdb_db_open_time_seconds_sum 0.0 couchdb_db_open_time_seconds_count 0 # TYPE couchdb_dbinfo_seconds summary couchdb_dbinfo_seconds{quantile="0.5"} 0.0 couchdb_dbinfo_seconds{quantile="0.75"} 0.0 couchdb_dbinfo_seconds{quantile="0.9"} 0.0 couchdb_dbinfo_seconds{quantile="0.95"} 0.0 couchdb_dbinfo_seconds{quantile="0.99"} 0.0 couchdb_dbinfo_seconds{quantile="0.999"} 0.0 couchdb_dbinfo_seconds_sum 0.0 couchdb_dbinfo_seconds_count 0 # TYPE couchdb_document_inserts_total counter couchdb_document_inserts_total 0 # TYPE couchdb_document_purges_failure_total counter couchdb_document_purges_failure_total 0 # TYPE couchdb_document_purges_success_total counter couchdb_document_purges_success_total 0 # TYPE couchdb_document_purges_total_total counter couchdb_document_purges_total_total 0 # TYPE couchdb_document_writes_total counter couchdb_document_writes_total 0 # TYPE couchdb_httpd_aborted_requests_total counter couchdb_httpd_aborted_requests_total 0 # TYPE couchdb_httpd_all_docs_timeouts_total counter couchdb_httpd_all_docs_timeouts_total 0 # TYPE couchdb_httpd_bulk_docs_seconds summary couchdb_httpd_bulk_docs_seconds{quantile="0.5"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.75"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.9"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.95"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.99"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.999"} 0.0 couchdb_httpd_bulk_docs_seconds_sum 0.0 couchdb_httpd_bulk_docs_seconds_count 0 ...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 is true
(ON), the default ports for a 3 node cluster
are 17986
, 27986
, 37986
.
See Configuration of Prometheus Endpoint for details.
GET /_node/_local/_prometheus HTTP/1.1
Accept: text/plain
Host: localhost:17986
1.2.14. /_node/{node-name}/_smoosh/status
¶
Added in version 3.4.
- GET /_node/{node-name}/_smoosh/status¶
This prints the state of each channel, how many jobs they are currently running and how many jobs are enqueued (as well as the lowest and highest priority of those enqueued items). The idea is to provide, at a glance, sufficient insight into
smoosh
that an operator can assess whethersmoosh
is adequately targeting the reclaimable space in the cluster.In general, a healthy status output will have items in the
ratio_dbs
andratio_views
channels. Owing to the default settings, theslack_dbs
andslack_views
will almost certainly have items in them. Historically, we’ve not found that the slack channels, on their own, are particularly adept at keeping things well compacted.- Status Codes:
200 OK – Request completed successfully
401 Unauthorized – CouchDB Server Administrator privileges required
Request:
GET /_node/_local/_smoosh/status HTTP/1.1 Host: 127.0.0.1:5984 Accept: */*
Response:
HTTP/1.1 200 OK Content-Type: application/json { "channels": { "slack_dbs": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "ratio_dbs": { "starting": 0, "waiting": { "size": 56, "min": 1.125, "max": 11.0625 }, "active": 0 }, "ratio_views": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "upgrade_dbs": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "slack_views": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "upgrade_views": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "index_cleanup": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 } } }
1.2.15. /_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:
application/json
text/plain; charset=utf-8
- Status Codes:
200 OK – Request completed successfully
Request:
GET /_node/_local/_system HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 187 Content-Type: application/json Date: Sat, 10 Aug 2013 11:41:11 GMT Server: CouchDB (Erlang/OTP) { "uptime": 259, "memory": {} }
These statistics are generally intended for CouchDB developers only.
1.2.16. /_node/{node-name}/_restart
¶
1.2.17. /_node/{node-name}/_versions
¶
- GET /_node/{node-name}/_versions¶
The
_versions
resource returns a JSON object containing various system-level informations for the running server.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 informations.- Request Headers:
Accept –
application/json
text/plain
- Response Headers:
application/json
- Status Codes:
200 OK – Request completed successfully
Request:
GET /_node/_local/_versions HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 368 Content-Type: application/json Date: Sat, 03 Sep 2022 08:12:12 GMT Server: CouchDB/3.2.2-ea382cf (Erlang OTP/25) { "javascript_engine": { "version": "91", "name": "spidermonkey" }, "erlang": { "version": "25.0.4", "supported_hashes": [ "sha", "sha224", "sha256", ] }, "collation_driver": { "name": "libicu", "library_version": "70.1", "collator_version": "153.112", "collation_algorithm_version": "14" } }
1.2.18. /_search_analyze
¶
Warning
Search endpoints require a running search plugin connected to each cluster node. See Search Plugin Installation for details.
Added in version 3.0.
- POST /_search_analyze¶
Tests the results of Lucene analyzer tokenization on sample text.
- Parameters:
analyzer – Type of analyzer
text – Analyzer token you want to test
- Status Codes:
200 OK – Request completed successfully
400 Bad Request – Request body is wrong (malformed or missing one of the mandatory fields)
500 Internal Server Error – A server error (or other kind of error) occurred
Request:
POST /_search_analyze HTTP/1.1
Host: localhost:5984
Content-Type: application/json
{"analyzer":"english", "text":"running"}
Response:
{
"tokens": [
"run"
]
}
1.2.19. /_nouveau_analyze
¶
Warning
Nouveau is an experimental feature. Future releases might change how the endpoints work and might invalidate existing indexes.
Warning
Nouveau endpoints require a running nouveau server. See Nouveau Server Installation for details.
Added in version 3.4.0.
- POST /_nouveau_analyze¶
Tests the results of Lucene analyzer tokenization on sample text.
- Parameters:
analyzer – Name of analyzer
text – Analyzer token you want to test
- Status Codes:
200 OK – Request completed successfully
400 Bad Request – Request body is wrong (malformed or missing one of the mandatory fields)
500 Internal Server Error – A server error (or other kind of error) occurred
Request:
POST /_nouveau_analyze HTTP/1.1
Host: localhost:5984
Content-Type: application/json
{"analyzer":"english", "text":"running"}
Response:
{
"tokens": [
"run"
]
}
1.2.20. /_utils
¶
- GET /_utils¶
Accesses the built-in Fauxton administration interface for CouchDB.
- Response Headers:
Location – New URI location
- Status Codes:
301 Moved Permanently – Redirects to
GET /_utils/
- GET /_utils/¶
- Response Headers:
Content-Type – text/html
Last-Modified – Static files modification timestamp
- Status Codes:
200 OK – Request completed successfully
1.2.21. /_up
¶
Added in version 2.0.
- GET /_up¶
Confirms that the server is up, running, and ready to respond to requests. If
maintenance_mode
istrue
ornolb
, the endpoint will return a 404 response.- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – Request completed successfully
404 Not Found – The server is unavailable for requests at this time.
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 16 Content-Type: application/json Date: Sat, 17 Mar 2018 04:46:26 GMT Server: CouchDB/2.2.0-f999071ec (Erlang OTP/19) X-Couch-Request-ID: c57a3b2787 X-CouchDB-Body-Time: 0 {"status":"ok"}
1.2.22. /_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:
application/json
text/plain; charset=utf-8
ETag – Response hash
- Status Codes:
200 OK – Request completed successfully
400 Bad Request – Requested more UUIDs than is
allowed
to retrieve
Request:
GET /_uuids?count=10 HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Content-Length: 362 Content-Type: application/json Date: Sat, 10 Aug 2013 11:46:25 GMT ETag: "DGRWWQFLUDWN5MRKSLKQ425XV" Expires: Fri, 01 Jan 1990 00:00:00 GMT Pragma: no-cache Server: CouchDB (Erlang/OTP) { "uuids": [ "75480ca477454894678e22eec6002413", "75480ca477454894678e22eec600250b", "75480ca477454894678e22eec6002c41", "75480ca477454894678e22eec6003b90", "75480ca477454894678e22eec6003fca", "75480ca477454894678e22eec6004bef", "75480ca477454894678e22eec600528f", "75480ca477454894678e22eec6005e0b", "75480ca477454894678e22eec6006158", "75480ca477454894678e22eec6006161" ] }
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:
PUT http://couchdb:5984/_node/nonode@nohost/_config/uuids/algorithm HTTP/1.1
Content-Type: application/json
Accept: */*
"random"
You can verify the change by obtaining a list of UUIDs:
{
"uuids" : [
"031aad7b469956cf2826fcb2a9260492",
"6ec875e15e6b385120938df18ee8e496",
"cff9e881516483911aa2f0e98949092d",
"b89d37509d39dd712546f9510d4a9271",
"2e0dbf7f6c4ad716f21938a016e4e59f"
]
}
1.2.23. /favicon.ico
¶
- GET /favicon.ico¶
Binary content for the favicon.ico site icon.
- Response Headers:
Content-Type – image/x-icon
- Status Codes:
200 OK – Request completed successfully
404 Not Found – The requested content could not be found
1.2.24. /_reshard
¶
Added 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:
Accept –
application/json
- Response Headers:
application/json
- Response JSON Object:
state (string) –
stopped
orrunning
state_reason (string) –
null
or string describing additional information or reason associated with the statecompleted (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:
GET /_reshard HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Content-Type: application/json { "completed": 21, "failed": 0, "running": 3, "state": "running", "state_reason": null, "stopped": 0, "total": 24 }
- GET /_reshard/state¶
Returns the resharding state and optional information about the state.
- Request Headers:
Accept –
application/json
- Response Headers:
application/json
- Response JSON Object:
state (string) –
stopped
orrunning
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:
GET /_reshard/state HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Content-Type: application/json { "reason": null, "state": "running" }
- PUT /_reshard/state¶
Change the resharding state on the cluster. The states are
stopped
orrunning
. 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 tostopped
. When the state changes back torunning
those job will continue running.- Request Headers:
Accept –
application/json
- Response Headers:
application/json
- Request JSON Object:
state (string) –
stopped
orrunning
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:
PUT /_reshard/state HTTP/1.1 Accept: application/json Host: localhost:5984 { "state": "stopped", "reason": "Rebalancing in progress" }
Response:
HTTP/1.1 200 OK Content-Type: application/json { "ok": true }
- GET /_reshard/jobs¶
Note
The shape of the response and the
total_rows
andoffset
field in particular are meant to be consistent with the_scheduler/jobs
endpoint.- Request Headers:
Accept –
application/json
- Response Headers:
application/json
- 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:
GET /_reshard/jobs HTTP/1.1 Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "jobs": [ { "history": [ { "detail": null, "timestamp": "2019-03-28T15:28:02Z", "type": "new" }, { "detail": "initial_copy", "timestamp": "2019-03-28T15:28:02Z", "type": "running" } ], "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a", "job_state": "completed", "node": "node1@127.0.0.1", "source": "shards/00000000-1fffffff/d1.1553786862", "split_state": "completed", "start_time": "2019-03-28T15:28:02Z", "state_info": {}, "target": [ "shards/00000000-0fffffff/d1.1553786862", "shards/10000000-1fffffff/d1.1553786862" ], "type": "split", "update_time": "2019-03-28T15:28:08Z" } ], "offset": 0, "total_rows": 24 }
- GET /_reshard/jobs/{jobid}¶
Get information about the resharding job identified by
jobid
.- Request Headers:
Accept –
application/json
- Response Headers:
application/json
- 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
orfailed
.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
orcompleted
.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:
GET /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1 Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a", "job_state": "completed", "node": "node1@127.0.0.1", "source": "shards/00000000-1fffffff/d1.1553786862", "split_state": "completed", "start_time": "2019-03-28T15:28:02Z", "state_info": {}, "target": [ "shards/00000000-0fffffff/d1.1553786862", "shards/10000000-1fffffff/d1.1553786862" ], "type": "split", "update_time": "2019-03-28T15:28:08Z", "history": [ { "detail": null, "timestamp": "2019-03-28T15:28:02Z", "type": "new" }, { "detail": "initial_copy", "timestamp": "2019-03-28T15:28:02Z", "type": "running" } ] }
- 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:
Accept –
application/json
- Response Headers:
application/json
- 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
whereh
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}"
. Whererange
has thehhhhhhhh-hhhhhhhh
format,db
is the database name, andsuffix
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:
201 Created – One or more jobs were successfully created
400 Bad Request – Invalid request. Parameter validation might have failed.
401 Unauthorized – CouchDB Server Administrator privileges required
404 Not Found – Db, node, range or shard was not found
Request:
POST /_reshard/jobs HTTP/1.1 Accept: application/json Content-Type: application/json { "db": "db3", "range": "80000000-ffffffff", "type": "split" }
Response:
HTTP/1.1 201 Created Content-Type: application/json [ { "id": "001-30d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df557", "node": "node1@127.0.0.1", "ok": true, "shard": "shards/80000000-ffffffff/db3.1554148353" }, { "id": "001-c2d734360b4cb3ff8b3feaccb2d787bf81ce2e773489eddd985ddd01d9de8e01", "node": "node2@127.0.0.1", "ok": true, "shard": "shards/80000000-ffffffff/db3.1554148353" } ]
- 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:
200 OK – The job was removed successfully
401 Unauthorized – CouchDB Server Administrator privileges required
404 Not Found – The job was not found
Request:
DELETE /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1
Response:
HTTP/1.1 200 OK Content-Type: application/json { "ok": true }
- GET /_reshard/jobs/{jobid}/state¶
Returns the running state of a resharding job identified by
jobid
.- Request Headers:
Accept –
application/json
- Response Headers:
application/json
- Request JSON Object:
state (string) – One of
new
,running
,stopped
,completed
orfailed
.state_reason (string) – Additional information associated with the state
- Status Codes:
200 OK – Request completed successfully
401 Unauthorized – CouchDB Server Administrator privileges required
404 Not Found – The job was not found
Request:
GET /_reshard/jobs/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Content-Type: application/json { "reason": null, "state": "running" }
- PUT /_reshard/jobs/{jobid}/state¶
Change the state of a particular resharding job identified by
jobid
. The state can be changed fromstopped
torunning
or fromrunning
tostopped
. If an individual job isstopped
via this API it will staystopped
even after the global resharding state is toggled fromstopped
torunning
. If the job is alreadycompleted
its state will staycompleted
.- Request Headers:
Accept –
application/json
- Response Headers:
application/json
- Request JSON Object:
state (string) –
stopped
orrunning
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 state name, for example.
401 Unauthorized – CouchDB Server Administrator privileges required
404 Not Found – The job was not found
Request:
PUT /_reshard/state/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1 Accept: application/json Host: localhost:5984 { "state": "stopped", "reason": "Rebalancing in progress" }
Response:
HTTP/1.1 200 OK Content-Type: application/json { "ok": true }