Skip to content
This repository has been archived by the owner on Oct 17, 2022. It is now read-only.

Latest commit

 

History

History
2526 lines (2060 loc) · 93.5 KB

common.rst

File metadata and controls

2526 lines (2060 loc) · 93.5 KB
Raw

/

/_active_tasks

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

/_all_dbs

/_dbs_info

2.2

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.

/_cluster_setup

2.0

/_db_updates

1.4

/_membership

2.0

/_replicate

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://127.0.0.1:5984/db_a",
    "target": "http://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,
            "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,
            "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:

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.

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

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:

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.

/_scheduler/jobs

/_scheduler/docs

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

3.0.0 In error states the "info" field switched from being a string to being an object

/_node/{node-name}

/_node/{node-name}/_stats

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

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

  • couch_log: Logging subsystem
  • couch_replicator: Replication scheduler and subsystem
  • couchdb: Primary CouchDB database operations
  • fabric: Cluster-related operations
  • global_changes: Global changes feed
  • mem3: Node membership-related statistics
  • pread: CouchDB file-related exceptions
  • rexi: Cluster internal RPC-related statistics

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

  • counter: Monotonically increasing counter, resets on restart
  • histogram: Binned set of values with meaningful subdivisions. Scoped to the current collection interval <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:

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.

/_node/{node-name}/_prometheus

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

GET /_node/_local/_prometheus HTTP/1.1
Accept: text/plain
Host: localhost:17986

/_node/{node-name}/_system

/_node/{node-name}/_restart

/_search_analyze

Warning

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

3.0

Request:

POST /_search_analyze HTTP/1.1
Host: localhost:5984
Content-Type: application/json

{"analyzer":"english", "text":"running"}

Response:

{
    "tokens": [
        "run"
    ]
}

/_utils

/_up

2.0

/_uuids

2.0.0

The UUID type is determined by the :configUUID algorithm <uuids/algorithm> setting in the CouchDB configuration.

The UUID type may be changed at any time through the Configuration API <api/config/section/key>. 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"
    ]
}

/favicon.ico

/_reshard

2.4