| .. Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| .. use this file except in compliance with the License. You may obtain a copy of |
| .. the License at |
| .. |
| .. http://www.apache.org/licenses/LICENSE-2.0 |
| .. |
| .. Unless required by applicable law or agreed to in writing, software |
| .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| .. License for the specific language governing permissions and limitations under |
| .. the License. |
| |
| .. _api/server/root: |
| |
| ===== |
| ``/`` |
| ===== |
| |
| .. http:get:: / |
| :synopsis: Returns the welcome message and version information |
| |
| 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET / HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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" |
| } |
| |
| .. _api/server/active_tasks: |
| |
| ================== |
| ``/_active_tasks`` |
| ================== |
| |
| .. versionchanged:: 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 |
| |
| .. versionchanged:: 3.3 Added `"bulk_get_attempts"` and `"bulk_get_docs"` fields for replication jobs. |
| |
| .. http:get:: /_active_tasks |
| :synopsis: Obtains a list of the tasks running in the server |
| |
| 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>json number changes_done: Processed changes |
| :>json string database: Source database |
| :>json string pid: Process ID |
| :>json number progress: Current percentage progress |
| :>json number started_on: Task start time as unix timestamp |
| :>json string status: Task status message |
| :>json string task: Task name |
| :>json number total_changes: Total changes to process |
| :>json string type: Operation Type |
| :>json number updated_on: Unix timestamp of last operation update |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_active_tasks HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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 |
| } |
| ] |
| |
| .. _api/server/all_dbs: |
| |
| ============= |
| ``/_all_dbs`` |
| ============= |
| |
| .. http:get:: /_all_dbs |
| :synopsis: Returns a list of all the databases |
| |
| Returns a list of all the databases in the CouchDB instance. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :query boolean descending: Return the databases in descending order by key. |
| Default is ``false``. |
| :query json endkey: Stop returning databases when the specified key is |
| reached. |
| :query json end_key: Alias for ``endkey`` param |
| :query number limit: Limit the number of the returned databases to the |
| specified number. |
| :query number skip: Skip this number of databases before starting to return |
| the results. Default is ``0``. |
| :query json startkey: Return databases starting with the specified key. |
| :query json start_key: Alias for ``startkey``. |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_all_dbs HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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" |
| ] |
| |
| .. _api/server/dbs_info: |
| |
| ============== |
| ``/_dbs_info`` |
| ============== |
| |
| .. versionadded:: 3.2 |
| |
| .. http:get:: /_dbs_info |
| :synopsis: Returns all databases information |
| |
| Returns a list of all the databases information in the CouchDB instance. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :query boolean descending: Return databases information in descending order |
| by key. Default is ``false``. |
| :query json endkey: Stop returning databases information when the specified |
| key is reached. |
| :query json end_key: Alias for ``endkey`` param |
| :query number limit: Limit the number of the returned databases information |
| to the specified number. |
| :query number skip: Skip this number of databases before starting to return |
| the results. Default is ``0``. |
| :query json startkey: Return databases information starting with the |
| specified key. |
| :query json start_key: Alias for ``startkey``. |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_dbs_info HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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" |
| } |
| } |
| ] |
| |
| .. versionadded:: 2.2 |
| |
| .. http:post:: /_dbs_info |
| :synopsis: Returns information of a list of the specified databases |
| |
| 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| :<json array keys: Array of database names to be requested |
| :code 200: Request completed successfully |
| :code 400: Missing keys or exceeded keys in request |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| POST /_dbs_info HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| Content-Type: application/json |
| |
| { |
| "keys": [ |
| "animals", |
| "plants" |
| ] |
| } |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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. |
| |
| .. _api/server/cluster_setup: |
| |
| =================== |
| ``/_cluster_setup`` |
| =================== |
| |
| .. versionadded:: 2.0 |
| .. http:get:: /_cluster_setup |
| :synopsis: Return the status of the cluster setup wizard |
| |
| Returns the status of the node or cluster, per the cluster setup wizard. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :query array ensure_dbs_exist: List of system databases to ensure exist |
| on the node/cluster. Defaults to |
| ``["_users","_replicator"]``. |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>json string state: Current ``state`` of the node and/or cluster (see |
| below) |
| :code 200: 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**: |
| |
| .. code-block:: http |
| |
| GET /_cluster_setup HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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"} |
| |
| .. http:post:: /_cluster_setup |
| :synopsis: Sets up a node as a single node or as part of a cluster. |
| |
| Configure a node as a single (standalone) node, as part of a cluster, |
| or finalise a cluster. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :<header Content-Type: :mimetype:`application/json` |
| :<json string action: - **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. |
| :<json string bind_address: 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) |
| :<json string username: 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) |
| :<json string password: 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) |
| :<json number port: 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). |
| :<json number node_count: 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) |
| :<json string remote_node: The IP address of the remote node to setup as |
| part of this cluster's list of nodes. (enable_cluster only) |
| :<json string remote_current_user: The username of the server-level |
| administrator authorized on the remote node. (enable_cluster only) |
| :<json string remote_current_password: The password of the server-level |
| administrator authorized on the remote node. (enable_cluster only) |
| :<json string host: The remote node IP of the node to add to the cluster. |
| (add_node only) |
| :<json array ensure_dbs_exist: 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* :ref:`cluster/setup/api`. |
| |
| .. _api/server/db_updates: |
| |
| ================ |
| ``/_db_updates`` |
| ================ |
| |
| .. versionadded:: 1.4 |
| |
| .. http:get:: /_db_updates |
| :synopsis: Return the server changes of databases |
| |
| Returns a list of all database events in the CouchDB instance. The |
| existence of the ``_global_changes`` database is required to use this |
| endpoint. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :query string feed: - **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 |
| <http://dev.w3.org/html5/eventsource/>`_ format. |
| :query number timeout: Number of *milliseconds* until CouchDB closes the |
| connection. Default is ``60000``. |
| :query number heartbeat: 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. |
| :query string since: 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. |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>header Transfer-Encoding: ``chunked`` |
| :>json array results: An array of database events. For ``longpoll`` and |
| ``continuous`` modes, the entire response is the contents of the |
| ``results`` array. |
| :>json string last_seq: The last sequence ID reported. |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| The ``results`` field of database updates: |
| |
| :json string db_name: Database name. |
| :json string type: A database event is one of ``created``, ``updated``, |
| ``deleted``. |
| :json json seq: Update sequence of the event. |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_db_updates HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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" |
| } |
| |
| .. _api/server/membership: |
| |
| ================ |
| ``/_membership`` |
| ================ |
| |
| .. versionadded:: 2.0 |
| |
| .. http:get:: /_membership |
| :synopsis: Returns a list of nodes |
| |
| 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 :ref:`cluster/nodes` |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_membership HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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" |
| ] |
| } |
| |
| .. _api/server/replicate: |
| |
| =============== |
| ``/_replicate`` |
| =============== |
| |
| .. versionchanged:: 3.3 Added `"bulk_get_attempts"` and `"bulk_get_docs"` fields to the replication history response object. |
| |
| .. http:post:: /_replicate |
| :synopsis: Starts or cancels the replication |
| |
| Request, configure, or stop, a replication operation. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :<header Content-Type: :mimetype:`application/json` |
| :<json boolean cancel: Cancels the replication |
| :<json boolean continuous: Configure the replication to be continuous |
| :<json boolean create_target: Creates the target database. |
| Required administrator's privileges on target server. |
| :<json object create_target_params: An object that contains parameters |
| to be used when creating the target database. Can include the |
| standard ``q`` and ``n`` parameters. |
| :<json boolean winning_revs_only: Replicate winning revisions only. |
| :<json array doc_ids: Array of document IDs to be synchronized. |
| ``doc_ids``, ``filter``, and ``selector`` are mutually exclusive. |
| :<json string filter: The name of a :ref:`filter function <filterfun>`. |
| ``doc_ids``, ``filter``, and ``selector`` are mutually exclusive. |
| :<json json selector: A :ref:`selector <find/selectors>` to filter |
| documents for synchronization. Has the same behavior as the |
| :ref:`selector objects <selectorobj>` in replication documents. |
| ``doc_ids``, ``filter``, and ``selector`` are mutually exclusive. |
| :<json string source_proxy: Address of a proxy server through which |
| replication from the source should occur (protocol can be "http" or |
| "socks5") |
| :<json string target_proxy: Address of a proxy server through which |
| replication to the target should occur (protocol can be "http" or |
| "socks5") |
| :<json string/object source: 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. |
| :<json string/object target: 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. |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>json array history: Replication history (see below) |
| :>json boolean ok: Replication status |
| :>json number replication_id_version: Replication protocol version |
| :>json string session_id: Unique session ID |
| :>json number source_last_seq: Last sequence number read from source |
| database |
| :code 200: Replication request successfully completed |
| :code 202: Continuous replication request has been accepted |
| :code 400: Invalid JSON data |
| :code 401: CouchDB Server Administrator privileges required |
| :code 404: Either the source or target DB is not found or attempt to |
| cancel unknown replication task |
| :code 500: 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 number doc_write_failures: Number of document write failures |
| :json number docs_read: Number of documents read |
| :json number docs_written: Number of documents written to target |
| :json number bulk_get_attempts: The total count of attempted doc revisions |
| fetched with ``_bulk_get``. |
| :json number bulk_get_docs: The total count of successful docs fetched with |
| ``_bulk_get``. |
| :json number end_last_seq: Last sequence number in changes stream |
| :json string end_time: Date/Time replication operation completed in |
| :rfc:`2822` format |
| :json number missing_checked: Number of missing documents checked |
| :json number missing_found: Number of missing documents found |
| :json number recorded_seq: Last recorded sequence number |
| :json string session_id: Session ID for this replication operation |
| :json number start_last_seq: First sequence number in changes stream |
| :json string start_time: 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** |
| |
| .. code-block:: http |
| |
| POST /_replicate HTTP/1.1 |
| Accept: application/json |
| Content-Length: 80 |
| Content-Type: application/json |
| Host: localhost:5984 |
| |
| { |
| "source": "http://127.0.0.1:5984/db_a", |
| "target": "http://127.0.0.1:5984/db_b" |
| } |
| |
| **Response** |
| |
| .. code-block:: http |
| |
| 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 |
| } |
| |
| 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. |
| |
| 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: |
| |
| .. code-block:: http |
| |
| 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: |
| |
| .. code-block:: javascript |
| |
| { |
| "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: |
| |
| .. code-block:: http |
| |
| 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. |
| |
| 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. |
| |
| .. code-block:: http |
| |
| 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: |
| |
| .. code-block:: javascript |
| |
| { |
| "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 |
| } |
| |
| 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. |
| |
| .. code-block:: http |
| |
| 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``. |
| |
| 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: |
| |
| .. code-block:: http |
| |
| 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: |
| |
| .. code-block:: http |
| |
| 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. |
| |
| .. _api/server/_scheduler/jobs: |
| |
| ==================== |
| ``/_scheduler/jobs`` |
| ==================== |
| |
| .. http:get:: /_scheduler/jobs |
| :synopsis: Retrieve information about replication jobs |
| |
| List of replication jobs. Includes replications created via |
| :ref:`api/server/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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| :query number limit: How many results to return |
| :query number skip: How many result to skip starting at the beginning, |
| ordered by replication ID |
| :>json number offset: How many results were skipped |
| :>json number total_rows: Total number of replication jobs |
| :>json string id: Replication ID. |
| :>json string database: Replication document database |
| :>json string doc_id: Replication document ID |
| :>json list history: Timestamped history of events as a list of objects |
| :>json string pid: Replication process ID |
| :>json string node: Cluster node where the job is running |
| :>json string source: Replication source |
| :>json string target: Replication target |
| :>json string start_time: Timestamp of when the replication was started |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_scheduler/jobs HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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 |
| } |
| |
| .. _api/server/_scheduler/docs: |
| |
| ==================== |
| ``/_scheduler/docs`` |
| ==================== |
| |
| .. versionchanged:: 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 |
| |
| .. versionchanged:: 3.0.0 In error states the `"info"` field switched |
| from being a string to being an object |
| |
| .. versionchanged:: 3.3 Added `"bulk_get_attempts"` and `"bulk_get_docs"` the |
| `"info"` object. |
| |
| .. http:get:: /_scheduler/docs |
| :synopsis: Retrieve information about replication documents from the |
| ``_replicator`` database. |
| |
| 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| :query number limit: How many results to return |
| :query number skip: How many result to skip starting at the beginning, if |
| ordered by document ID |
| :>json number offset: How many results were skipped |
| :>json number total_rows: Total number of replication documents. |
| :>json string id: Replication ID, or ``null`` if state is ``completed`` or |
| ``failed`` |
| :>json string state: One of following states (see :ref:`replicator/states` |
| for descriptions): ``initializing``, ``running``, |
| ``completed``, ``pending``, ``crashing``, ``error``, |
| ``failed`` |
| :>json string database: Database where replication document came from |
| :>json string doc_id: Replication document ID |
| :>json string node: Cluster node where the job is running |
| :>json string source: Replication source |
| :>json string target: Replication target |
| :>json string start_time: Timestamp of when the replication was started |
| :>json string last_updated: Timestamp of last state update |
| :>json object info: 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. |
| :>json number error_count: 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. |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| The ``info`` field of a scheduler doc: |
| |
| :json number revisions_checked: The count of revisions which have been |
| checked since this replication began. |
| :json number missing_revisions_found: The count of revisions which were |
| found on the source, but missing from the target. |
| :json number docs_read: The count of docs which have been read from the |
| source. |
| :json number docs_written: The count of docs which have been written to the |
| target. |
| :json number bulk_get_attempts: The total count of attempted doc revisions |
| fetched with ``_bulk_get``. |
| :json number bulk_get_docs: The total count of successful docs fetched with |
| ``_bulk_get``. |
| :json number changes_pending: The count of changes not yet replicated. |
| :json number doc_write_failures: The count of docs which failed to be |
| written to the target. |
| :json object checkpointed_source_seq: The source sequence id which was last |
| successfully replicated. |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_scheduler/docs HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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 |
| } |
| |
| .. http:get:: /_scheduler/docs/{replicator_db} |
| :synopsis: Retrieve information about replication documents from a specific |
| replicator database. |
| |
| 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`` |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| :query number limit: How many results to return |
| :query number skip: How many result to skip starting at the beginning, if |
| ordered by document ID |
| :>json number offset: How many results were skipped |
| :>json number total_rows: Total number of replication documents. |
| :>json string id: Replication ID, or ``null`` if state is ``completed`` or |
| ``failed`` |
| :>json string state: One of following states (see :ref:`replicator/states` |
| for descriptions): ``initializing``, ``running``, |
| ``completed``, ``pending``, ``crashing``, ``error``, |
| ``failed`` |
| :>json string database: Database where replication document came from |
| :>json string doc_id: Replication document ID |
| :>json string node: Cluster node where the job is running |
| :>json string source: Replication source |
| :>json string target: Replication target |
| :>json string start_time: Timestamp of when the replication was started |
| :>json string last_update: Timestamp of last state update |
| :>json object info: 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. |
| :>json number error_count: 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. |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| The ``info`` field of a scheduler doc: |
| |
| :json number revisions_checked: The count of revisions which have been |
| checked since this replication began. |
| :json number missing_revisions_found: The count of revisions which were |
| found on the source, but missing from the target. |
| :json number docs_read: The count of docs which have been read from the |
| source. |
| :json number docs_written: The count of docs which have been written to the |
| target. |
| :json number bulk_get_attempts: The total count of attempted doc revisions |
| fetched with ``_bulk_get``. |
| :json number bulk_get_docs: The total count of successful docs fetched with |
| ``_bulk_get``. |
| :json number changes_pending: The count of changes not yet replicated. |
| :json number doc_write_failures: The count of docs which failed to be |
| written to the target. |
| :json object checkpointed_source_seq: The source sequence id which was last |
| successfully replicated. |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_scheduler/docs/other/_replicator HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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 |
| } |
| |
| .. http:get:: /_scheduler/docs/{replicator_db}/{docid} |
| :synopsis: Retrieve information about a particular replication document |
| |
| .. 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`` |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| :>json string id: Replication ID, or ``null`` if state is ``completed`` or |
| ``failed`` |
| :>json string state: One of following states (see :ref:`replicator/states` |
| for descriptions): ``initializing``, ``running``, |
| ``completed``, ``pending``, ``crashing``, ``error``, |
| ``failed`` |
| :>json string database: Database where replication document came from |
| :>json string doc_id: Replication document ID |
| :>json string node: Cluster node where the job is running |
| :>json string source: Replication source |
| :>json string target: Replication target |
| :>json string start_time: Timestamp of when the replication was started |
| :>json string last_update: Timestamp of last state update |
| :>json object info: 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. |
| :>json number error_count: 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. |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| The ``info`` field of a scheduler doc: |
| |
| :json number revisions_checked: The count of revisions which have been |
| checked since this replication began. |
| :json number missing_revisions_found: The count of revisions which were |
| found on the source, but missing from the target. |
| :json number docs_read: The count of docs which have been read from the |
| source. |
| :json number docs_written: The count of docs which have been written to the |
| target. |
| :json number bulk_get_attempts: The total count of attempted doc revisions |
| fetched with ``_bulk_get``. |
| :json number bulk_get_docs: The total count of successful docs fetched with |
| ``_bulk_get``. |
| :json number changes_pending: The count of changes not yet replicated. |
| :json number doc_write_failures: The count of docs which failed to be |
| written to the target. |
| :json object checkpointed_source_seq: The source sequence id which was last |
| successfully replicated. |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_scheduler/docs/other/_replicator/cdyno-0000001-0000002 HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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/" |
| } |
| |
| .. _api/server/name: |
| |
| ====================== |
| ``/_node/{node-name}`` |
| ====================== |
| |
| .. http:get:: /_node/{node-name} |
| :synopsis: Returns 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_node/_local HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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"} |
| |
| .. _api/server/stats: |
| |
| ============================= |
| ``/_node/{node-name}/_stats`` |
| ============================= |
| |
| .. http:get:: /_node/{node-name}/_stats |
| :synopsis: Returns server statistics |
| |
| 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 :ref:`configurable interval |
| <config/stats>`. 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 :ref:`interval <config/stats>` 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_node/_local/_stats/couchdb/request_time HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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 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 :ref:`collection interval <config/stats>`. |
| - ``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: |
| |
| .. code-block:: http |
| |
| 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. |
| |
| .. _api/server/prometheus: |
| |
| ================================== |
| ``/_node/{node-name}/_prometheus`` |
| ================================== |
| |
| .. http:get:: /_node/{node-name}/_prometheus |
| :synopsis: Returns server statistics in prometheus format |
| |
| The ``_prometheus`` resource returns a text/plain response that consolidates our |
| :ref:`api/server/stats`, and :ref:`api/server/system` endpoints. The format is |
| determined by `Prometheus <https://prometheus.io/docs/introduction/overview/>`_. |
| The format version is 2.0. |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_node/_local/_prometheus HTTP/1.1 |
| Accept: text/plain |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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_cluster_is_stable gauge |
| couchdb_couch_replicator_cluster_is_stable 1 |
| # 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_created_total counter |
| couchdb_couch_replicator_docs_dbs_created_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 :ref:`Configuration of Prometheus Endpoint <config/prometheus>` for details. |
| |
| .. code-block:: http |
| |
| GET /_node/_local/_prometheus HTTP/1.1 |
| Accept: text/plain |
| Host: localhost:17986 |
| |
| .. _api/server/system: |
| |
| ============================== |
| ``/_node/{node-name}/_system`` |
| ============================== |
| |
| .. http:get:: /_node/{node-name}/_system |
| :synopsis: Returns system-level server statistics |
| |
| 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_node/_local/_system HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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. |
| |
| .. _api/server/restart: |
| |
| =============================== |
| ``/_node/{node-name}/_restart`` |
| =============================== |
| |
| .. http:post:: /_node/{node-name}/_restart |
| :synopsis: Restarts CouchDB application on a given node |
| |
| This API is to facilitate integration testing only |
| it is not meant to be used in production |
| |
| :code 200: Request completed successfully |
| |
| .. _api/server/search_analyze: |
| |
| ========================================== |
| ``/_search_analyze`` |
| ========================================== |
| |
| .. warning:: |
| Search endpoints require a running search plugin connected to each cluster |
| node. See :ref:`Search Plugin Installation <install/search>` for details. |
| |
| .. versionadded:: 3.0 |
| |
| .. http:post:: /_search_analyze |
| :synopsis: Tests the results of analyzer tokenization |
| |
| Tests the results of Lucene analyzer tokenization on sample text. |
| |
| :param field: Type of analyzer |
| :param text: Analyzer token you want to test |
| :code 200: Request completed successfully |
| :code 400: Request body is wrong (malformed or missing one of the mandatory fields) |
| :code 500: A server error (or other kind of error) occurred |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| POST /_search_analyze HTTP/1.1 |
| Host: localhost:5984 |
| Content-Type: application/json |
| |
| {"analyzer":"english", "text":"running"} |
| |
| **Response**: |
| |
| .. code-block:: javascript |
| |
| { |
| "tokens": [ |
| "run" |
| ] |
| } |
| |
| .. _api/server/utils: |
| |
| =========== |
| ``/_utils`` |
| =========== |
| |
| .. http:get:: /_utils |
| :synopsis: Redirects to /_utils/ |
| |
| Accesses the built-in Fauxton administration interface for CouchDB. |
| |
| :>header Location: New URI location |
| :code 301: Redirects to :get:`/_utils/` |
| |
| .. http:get:: /_utils/ |
| :synopsis: CouchDB administration interface (Fauxton) |
| |
| :>header Content-Type: :mimetype:`text/html` |
| :>header Last-Modified: Static files modification timestamp |
| :code 200: Request completed successfully |
| |
| .. _api/server/up: |
| |
| ======== |
| ``/_up`` |
| ======== |
| |
| .. versionadded:: 2.0 |
| |
| .. http:get:: /_up |
| :synopsis: Health check endpoint |
| |
| Confirms that the server is up, running, and ready to respond to requests. |
| If :config:option:`maintenance_mode <couchdb/maintenance_mode>` is |
| ``true`` or ``nolb``, the endpoint will return a 404 response. |
| |
| :>header Content-Type: :mimetype:`application/json` |
| :code 200: Request completed successfully |
| :code 404: The server is unavailable for requests at this time. |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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"} |
| |
| .. _api/server/uuids: |
| |
| =========== |
| ``/_uuids`` |
| =========== |
| |
| .. versionchanged:: 2.0.0 |
| |
| .. http:get:: /_uuids |
| :synopsis: Generates a list of UUIDs from the server |
| |
| Requests one or more Universally Unique Identifiers (UUIDs) from the |
| CouchDB instance. The response is a JSON object providing a list of UUIDs. |
| |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :query number count: Number of UUIDs to return. Default is ``1``. |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>header ETag: Response hash |
| :code 200: Request completed successfully |
| :code 400: Requested more UUIDs than is :config:option:`allowed |
| <uuids/max_count>` to retrieve |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_uuids?count=10 HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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 :config:option:`UUID algorithm |
| <uuids/algorithm>` setting in the CouchDB configuration. |
| |
| The UUID type may be changed at any time through the |
| :ref:`Configuration API <api/config/section/key>`. For example, the UUID type |
| could be changed to ``random`` by sending this HTTP request: |
| |
| .. code-block:: http |
| |
| 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: |
| |
| .. code-block:: javascript |
| |
| { |
| "uuids" : [ |
| "031aad7b469956cf2826fcb2a9260492", |
| "6ec875e15e6b385120938df18ee8e496", |
| "cff9e881516483911aa2f0e98949092d", |
| "b89d37509d39dd712546f9510d4a9271", |
| "2e0dbf7f6c4ad716f21938a016e4e59f" |
| ] |
| } |
| |
| .. _api/server/favicon: |
| |
| ================ |
| ``/favicon.ico`` |
| ================ |
| |
| .. http:get:: /favicon.ico |
| :synopsis: Returns the site icon |
| |
| Binary content for the `favicon.ico` site icon. |
| |
| :>header Content-Type: :mimetype:`image/x-icon` |
| :code 200: Request completed successfully |
| :code 404: The requested content could not be found |
| |
| .. _api/server/reshard: |
| |
| ============= |
| ``/_reshard`` |
| ============= |
| |
| .. versionadded:: 2.4 |
| |
| .. http:get:: /_reshard |
| :synopsis: Retrieve summary information about resharding on the cluster |
| |
| Returns a count of completed, failed, running, stopped, and total jobs |
| along with the state of resharding on the cluster. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :>json string state: ``stopped`` or ``running`` |
| :>json string state_reason: ``null`` or string describing additional |
| information or reason associated with the state |
| :>json number completed: Count of completed resharding jobs |
| :>json number failed: Count of failed resharding jobs |
| :>json number running: Count of running resharding jobs |
| :>json number stopped: Count of stopped resharding jobs |
| :>json number total: Total count of resharding jobs |
| |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_reshard HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "completed": 21, |
| "failed": 0, |
| "running": 3, |
| "state": "running", |
| "state_reason": null, |
| "stopped": 0, |
| "total": 24 |
| } |
| |
| .. http:get:: /_reshard/state |
| :synopsis: Retrieve the state of resharding on the cluster |
| |
| Returns the resharding state and optional information about the state. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :>json string state: ``stopped`` or ``running`` |
| :>json string state_reason: Additional information or reason associated |
| with the state |
| |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_reshard/state HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "reason": null, |
| "state": "running" |
| } |
| |
| .. http:put:: /_reshard/state |
| :synopsis: Change resharding state on the cluster |
| |
| 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :<json string state: ``stopped`` or ``running`` |
| :<json string state_reason: Optional string describing additional |
| information or reason associated with the state |
| |
| :>json boolean ok: ``true`` |
| |
| :code 200: Request completed successfully |
| :code 400: Invalid request. Could be a bad or missing state name. |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| PUT /_reshard/state HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| { |
| "state": "stopped", |
| "reason": "Rebalancing in progress" |
| } |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "ok": true |
| } |
| |
| .. http:get:: /_reshard/jobs |
| :synopsis: Retrieve information about all the resharding jobs on the cluster |
| |
| .. 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :>json list jobs: Array of json objects, one for each resharding job. For |
| the fields of each job see the /_reshard/job/{jobid} |
| endpoint. |
| :>json number offset: Offset in the list of jobs object. Currently |
| hard-coded at ``0``. |
| :>json number total_rows: Total number of resharding jobs on the cluster. |
| |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_reshard/jobs HTTP/1.1 |
| Accept: application/json |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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 |
| } |
| |
| .. http:get:: /_reshard/jobs/{jobid} |
| :synopsis: Retrieve information about a particular resharding job |
| |
| Get information about the resharding job identified by ``jobid``. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :>json string id: Job ID. |
| :>json string type: Currently only ``split`` is implemented. |
| :>json string job_state: The running state of the job. Could be one of |
| ``new``, ``running``, ``stopped``, ``completed`` |
| or ``failed``. |
| :>json string split_state: 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``. |
| :>json object state_info: Optional additional info associated with the |
| current state. |
| :>json string source: For ``split`` jobs this will be the source shard. |
| :>json list target: For ``split`` jobs this will be a list of two or more |
| target shards. |
| :>json list history: List of json objects recording a job's state |
| transition history. |
| |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1 |
| Accept: application/json |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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" |
| }, |
| ... |
| ] |
| } |
| |
| .. http:post:: /_reshard/jobs |
| :synopsis: Create one or more resharding 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. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :<json string type: Type of job. Currently only ``"split"`` is accepted. |
| |
| :<json string db: Database to split. This is mutually exclusive with the |
| ``"shard``" field. |
| |
| :<json string node: Split shards on a particular node. This is an optional |
| parameter. The value should be one of the nodes |
| returned from the ``_membership`` endpoint. |
| |
| :<json string range: 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. |
| |
| :<json string shard: 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. |
| |
| :>json boolean ok: ``true`` if job created successfully. |
| |
| :<json string error: Error message if a job could be not be created. |
| |
| :<json string node: Cluster node where the job was created and is running. |
| |
| :code 201: One or more jobs were successfully created |
| :code 400: Invalid request. Parameter validation might have failed. |
| :code 401: CouchDB Server Administrator privileges required |
| :code 404: Db, node, range or shard was not found |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| POST /_reshard/jobs HTTP/1.1 |
| Accept: application/json |
| Content-Type: application/json |
| |
| { |
| "db": "db3", |
| "range": "80000000-ffffffff", |
| "type": "split" |
| } |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| 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" |
| } |
| ] |
| |
| .. http:delete:: /_reshard/jobs/{jobid} |
| :synopsis: Remove a resharding job |
| |
| If the job is running, stop the job and then remove it. |
| |
| :>json boolean ok: ``true`` if the job was removed successfully. |
| |
| :code 200: The job was removed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| :code 404: The job was not found |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| DELETE /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "ok": true |
| } |
| |
| .. http:get:: /_reshard/jobs/{jobid}/state |
| :synopsis: Retrieve the state of a single resharding job |
| |
| Returns the running state of a resharding job identified by ``jobid``. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :<json string state: One of ``new``, ``running``, ``stopped``, |
| ``completed`` or ``failed``. |
| |
| :<json string state_reason: Additional information associated with the |
| state |
| |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| :code 404: The job was not found |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /_reshard/jobs/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "reason": null, |
| "state": "running" |
| } |
| |
| .. http:put:: /_reshard/jobs/{jobid}/state |
| :synopsis: Change the state of a resharding job |
| |
| 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``. |
| |
| :<header Accept: - :mimetype:`application/json` |
| :>header Content-Type: - :mimetype:`application/json` |
| |
| :<json string state: ``stopped`` or ``running`` |
| :<json string state_reason: Optional string describing additional |
| information or reason associated with the state |
| |
| :>json boolean ok: ``true`` |
| |
| :code 200: Request completed successfully |
| :code 400: Invalid request. Could be a bad state name, for example. |
| :code 401: CouchDB Server Administrator privileges required |
| :code 404: The job was not found |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| PUT /_reshard/state/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| { |
| "state": "stopped", |
| "reason": "Rebalancing in progress" |
| } |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Content-Type: application/json |
| |
| { |
| "ok": true |
| } |