1
.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
2
.. use this file except in compliance with the License. You may obtain a copy of
5
.. http://www.apache.org/licenses/LICENSE-2.0
7
.. Unless required by applicable law or agreed to in writing, software
8
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
9
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
10
.. License for the specific language governing permissions and limitations under
19
The CouchDB Miscellaneous interface provides the basic interface to a
20
CouchDB server for obtaining CouchDB information and getting and setting
21
configuration information.
23
A list of the available methods and URL paths are provided below:
25
+--------+-------------------------+-------------------------------------------+
26
| Method | Path | Description |
27
+========+=========================+===========================================+
28
| GET | / | Get the welcome message and version |
30
+--------+-------------------------+-------------------------------------------+
31
| GET | /_active_tasks | Obtain a list of the tasks running in the|
33
+--------+-------------------------+-------------------------------------------+
34
| GET | /_all_dbs | Get a list of all the DBs |
35
+--------+-------------------------+-------------------------------------------+
36
| GET | /_db_updates | A feed of database events |
37
+--------+-------------------------+-------------------------------------------+
38
| GET | /_log | Return the server log file |
39
+--------+-------------------------+-------------------------------------------+
40
| POST | /_replicate | Set or cancel replication |
41
+--------+-------------------------+-------------------------------------------+
42
| POST | /_restart | Restart the server |
43
+--------+-------------------------+-------------------------------------------+
44
| GET | /_stats | Return server statistics |
45
+--------+-------------------------+-------------------------------------------+
46
| GET | /_utils | CouchDB administration interface (Futon) |
47
+--------+-------------------------+-------------------------------------------+
48
| GET | /_uuids | Get generated UUIDs from the server |
49
+--------+-------------------------+-------------------------------------------+
50
| GET | /favicon.ico | Get the site icon |
51
+--------+-------------------------+-------------------------------------------+
56
* **Method**: ``GET /``
58
* **Response**: Welcome message and version
59
* **Admin Privileges Required**: no
63
Request completed successfully.
65
Accessing the root of a CouchDB instance returns meta information about
66
the instance. The response is a JSON structure containing information
67
about the server, including a welcome message and the version of the
70
.. code-block:: javascript
73
"couchdb" : "Welcome",
79
``GET /_active_tasks``
80
======================
82
* **Method**: ``GET /_active_tasks``
84
* **Response**: List of running tasks, including the task type, name, status
86
* **Admin Privileges Required**: yes
90
Request completed successfully.
92
You can obtain a list of active tasks by using the ``/_active_tasks``
93
URL. The result is a JSON array of the currently running tasks, with
94
each task being described with a single object. For example:
96
.. code-block:: javascript
100
"pid" : "<0.11599.0>",
101
"status" : "Copied 0 of 18369 changes (0%)",
103
"type" : "Database Compaction"
107
The returned structure includes the following fields for each task:
109
* **tasks** [array]: Active Task
112
* **status**: Task status message
113
* **task**: Task name
114
* **type**: Operation Type
116
For operation type, valid values include:
118
- ``Database Compaction``
122
- ``View Group Compaction``
124
- ``View Group Indexer``
129
* **Method**: ``GET /_all_dbs``
131
* **Response**: JSON list of DBs
132
* **Admin Privileges Required**: no
136
Request completed successfully.
138
Returns a list of all the databases in the CouchDB instance. For
143
GET http://couchdb:5984/_all_dbs
144
Accept: application/json
146
The return is a JSON array:
148
.. code-block:: javascript
161
* **Method**: ``GET /_db_updates``
163
* **Admin Privileges Required**: yes
164
* **Query ARguments**:
168
* **Descroption**: Format of the response feed
171
* **Default**: longpoll
172
* **Supported Values**:
174
* **longpoll**: Closes the connection after the first event.
175
* **continuous**: Send a line of JSON per event. Keeps the socket open until ``timeout``.
176
* **eventsource**: Like, ``continuous``, but sends the events in EventSource format. See http://dev.w3.org/html5/eventsource/ for details,
178
* **Argument**: timeout
180
* **Descroption**: Number of seconds until CouchDB closes the connection.
185
* **Argument**: heartbeat
187
* **Descroption**: Whether CouchDB will send a newline character (``\n``) on ``timeout``.
195
Request completed successfully.
197
Returns a list of all database events in the CouchDB instance.
199
A database event is one of `created`, `updated`, `deleted`.
205
GET http://couchdb:5984/_db_events?feed=continuous
206
Accept: application/json
208
.. code-block:: javascript
210
{"dbname":"my-database", "type":"created"}
211
{"dbname":"my-database", "type":"updated"}
212
{"dbname":"another-database", "type":"created"}
213
{"dbname":"my-database", "type":"deleted"}
214
{"dbname":"another-database", "type":"updated"}
221
* **Method**: ``GET /_log``
223
* **Response**: Log content
224
* **Admin Privileges Required**: yes
225
* **Query Arguments**:
227
* **Argument**: bytes
229
* **Description**: Bytes to be returned
234
* **Argument**: offset
236
* **Description**: Offset in bytes where the log tail should be started
244
Request completed successfully.
246
Gets the CouchDB log, equivalent to accessing the local log file of the
247
corresponding CouchDB instance.
249
When you request the log, the response is returned as plain (UTF-8)
250
text, with an HTTP ``Content-type`` header as ``text/plain``.
252
For example, the request:
256
GET http://couchdb:5984/_log
259
The raw text is returned:
263
[Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401
264
[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200
265
[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200
266
[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200
267
[Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200
269
If you want to pick out specific parts of the log information you can
270
use the ``bytes`` argument, which specifies the number of bytes to be
271
returned, and ``offset``, which specifies where the reading of the log
272
should start, counted back from the end. For example, if you use the
277
GET /_log?bytes=500&offset=2000
279
Reading of the log will start at 2000 bytes from the end of the log, and
280
500 bytes will be shown.
287
.. todo:: POST /_replicate :: what response is?
289
* **Method**: ``POST /_replicate``
290
* **Request**: Replication specification
292
* **Admin Privileges Required**: yes
293
* **Query Arguments**:
295
* **Argument**: bytes
297
* **Description**: Bytes to be returned
302
* **Argument**: offset
304
* **Description**: Offset in bytes where the log tail should be started
312
Replication request successfully completed
314
Continuous replication request has been accepted
316
Either the source or target DB is not found
318
JSON specification was invalid
320
Request, configure, or stop, a replication operation.
322
The specification of the replication request is controlled through the
323
JSON content of the request. The JSON should be an object with the
324
fields defining the source, target and other options. The fields of the
325
JSON request are shown in the table below:
327
* **cancel (optional)**: Cancels the replication
328
* **continuous (optional)**: Configure the replication to be continuous
329
* **create_target (optional)**: Creates the target database
330
* **doc_ids (optional)**: Array of document IDs to be synchronized
331
* **proxy (optional)**: Address of a proxy server through which replication
333
* **source**: Source database name or URL
334
* **target**: Target database name or URL
336
Replication Operation
337
---------------------
339
The aim of the replication is that at the end of the process, all active
340
documents on the source database are also in the destination database
341
and all documents that were deleted in the source databases are also
342
deleted (if they exist) on the destination database.
344
Replication can be described as either push or pull replication:
346
- *Pull replication* is where the ``source`` is the remote CouchDB
347
instance, and the ``destination`` is the local database.
349
Pull replication is the most useful solution to use if your source
350
database has a permanent IP address, and your destination (local)
351
database may have a dynamically assigned IP address (for example,
352
through DHCP). This is particularly important if you are replicating
353
to a mobile or other device from a central server.
355
- *Push replication* is where the ``source`` is a local database, and
356
``destination`` is a remote database.
358
Specifying the Source and Target Database
359
-----------------------------------------
361
You must use the URL specification of the CouchDB database if you want
362
to perform replication in either of the following two situations:
364
- Replication with a remote database (i.e. another instance of CouchDB
365
on the same host, or a different host)
367
- Replication with a database that requires authentication
369
For example, to request replication between a database local to the
370
CouchDB instance to which you send the request, and a remote database
371
you might use the following request:
375
POST http://couchdb:5984/_replicate
376
Content-Type: application/json
377
Accept: application/json
380
"source" : "recipes",
381
"target" : "http://coucdb-remote:5984/recipes",
385
In all cases, the requested databases in the ``source`` and ``target``
386
specification must exist. If they do not, an error will be returned
387
within the JSON object:
389
.. code-block:: javascript
392
"error" : "db_not_found"
393
"reason" : "could not open http://couchdb-remote:5984/ol1ka/",
396
You can create the target database (providing your user credentials
397
allow it) by adding the ``create_target`` field to the request object:
401
POST http://couchdb:5984/_replicate
402
Content-Type: application/json
403
Accept: application/json
406
"create_target" : true
407
"source" : "recipes",
408
"target" : "http://couchdb-remote:5984/recipes",
411
The ``create_target`` field is not destructive. If the database already
412
exists, the replication proceeds as normal.
417
You can request replication of a database so that the two databases can
418
be synchronized. By default, the replication process occurs one time and
419
synchronizes the two databases together. For example, you can request a
420
single synchronization between two databases by supplying the ``source``
421
and ``target`` fields within the request JSON content.
425
POST http://couchdb:5984/_replicate
426
Content-Type: application/json
427
Accept: application/json
430
"source" : "recipes",
431
"target" : "recipes-snapshot",
434
In the above example, the databases ``recipes`` and ``recipes-snapshot``
435
will be synchronized. These databases are local to the CouchDB instance
436
where the request was made. The response will be a JSON structure
437
containing the success (or failure) of the synchronization process, and
438
statistics about the process:
440
.. code-block:: javascript
447
"session_id" : "52c2370f5027043d286daca4de247db0",
448
"recorded_seq" : 1000,
449
"end_last_seq" : 1000,
450
"doc_write_failures" : 0,
451
"start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
452
"start_last_seq" : 0,
453
"end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
454
"missing_checked" : 0,
455
"docs_written" : 1000,
456
"missing_found" : 1000
459
"session_id" : "52c2370f5027043d286daca4de247db0",
460
"source_last_seq" : 1000
463
The structure defines the replication status, as described in the table
466
* **history [array]**: Replication History
468
* **doc_write_failures**: Number of document write failures
469
* **docs_read**: Number of documents read
470
* **docs_written**: Number of documents written to target
471
* **end_last_seq**: Last sequence number in changes stream
472
* **end_time**: Date/Time replication operation completed
473
* **missing_checked**: Number of missing documents checked
474
* **missing_found**: Number of missing documents found
475
* **recorded_seq**: Last recorded sequence number
476
* **session_id**: Session ID for this replication operation
477
* **start_last_seq**: First sequence number in changes stream
478
* **start_time**: Date/Time replication operation started
480
* **ok**: Replication status
481
* **session_id**: Unique session ID
482
* **source_last_seq**: Last sequence number read from source database
484
Continuous Replication
485
----------------------
487
Synchronization of a database with the previously noted methods happens
488
only once, at the time the replicate request is made. To have the target
489
database permanently replicated from the source, you must set the
490
``continuous`` field of the JSON object within the request to true.
492
With continuous replication changes in the source database are
493
replicated to the target database in perpetuity until you specifically
494
request that replication ceases.
498
POST http://couchdb:5984/_replicate
499
Content-Type: application/json
500
Accept: application/json
504
"source" : "recipes",
505
"target" : "http://couchdb-remote:5984/recipes",
508
Changes will be replicated between the two databases as long as a
509
network connection is available between the two instances.
512
Two keep two databases synchronized with each other, you need to set
513
replication in both directions; that is, you must replicate from
514
``databasea`` to ``databaseb``, and separately from ``databaseb`` to
517
Canceling Continuous Replication
518
--------------------------------
520
You can cancel continuous replication by adding the ``cancel`` field to
521
the JSON request object and setting the value to true. Note that the
522
structure of the request must be identical to the original for the
523
cancellation request to be honoured. For example, if you requested
524
continuous replication, the cancellation request must also contain the
525
``continuous`` field.
527
For example, the replication request:
531
POST http://couchdb:5984/_replicate
532
Content-Type: application/json
533
Accept: application/json
536
"source" : "recipes",
537
"target" : "http://couchdb-remote:5984/recipes",
538
"create_target" : true,
542
Must be canceled using the request:
546
POST http://couchdb:5984/_replicate
547
Content-Type: application/json
548
Accept: application/json
553
"create_target" : true,
554
"source" : "recipes",
555
"target" : "http://couchdb-remote:5984/recipes",
558
Requesting cancellation of a replication that does not exist results in
564
* **Method**: ``POST /_restart``
566
* **Response**: JSON status message
567
* **Admin Privileges Required**: yes
570
* **Header**: ``Content-Type``
572
* **Description**: Request content type
574
* **Value**: :mimetype:`application/json`
579
Replication request successfully completed
581
Restarts the CouchDB instance. You must be authenticated as a user with
582
administration privileges for this to work.
588
POST http://admin:password@couchdb:5984/_restart
590
The return value (if the server has not already restarted) is a JSON
591
status object indicating that the request has been received:
593
.. code-block:: javascript
599
If the server has already restarted, the header may be returned, but no
600
actual data is contained in the response.
605
* **Method**: ``GET /_stats``
607
* **Response**: Server statistics
608
* **Admin Privileges Required**: no
612
Request completed successfully.
614
The ``_stats`` method returns a JSON object containing the statistics
615
for the running server. The object is structured with top-level sections
616
collating the statistics for a range of entries, with each individual
617
statistic being easily identified, and the content of each statistic is
618
self-describing. For example, the request time statistics, within the
619
``couchdb`` section are structured as follows:
621
.. code-block:: javascript
628
"min" : "0.333333333333333",
630
"current" : "400.976",
633
"description" : "length of a request inside CouchDB without MochiWeb"
640
The fields provide the current, minimum and maximum, and a collection of
641
statistical means and quantities. The quantity in each case is not
642
defined, but the descriptions below provide
644
The statistics are divided into the following top-level sections:
646
- ``couchdb``: Describes statistics specific to the internals of CouchDB.
648
+-------------------------+-------------------------------------------------------+----------------+
649
| Statistic ID | Description | Unit |
650
+=========================+=======================================================+================+
651
| ``auth_cache_hits`` | Number of authentication cache hits | number |
652
+-------------------------+-------------------------------------------------------+----------------+
653
| ``auth_cache_misses`` | Number of authentication cache misses | number |
654
+-------------------------+-------------------------------------------------------+----------------+
655
| ``database_reads`` | Number of times a document was read from a database | number |
656
+-------------------------+-------------------------------------------------------+----------------+
657
| ``database_writes`` | Number of times a database was changed | number |
658
+-------------------------+-------------------------------------------------------+----------------+
659
| ``open_databases`` | Number of open databases | number |
660
+-------------------------+-------------------------------------------------------+----------------+
661
| ``open_os_files`` | Number of file descriptors CouchDB has open | number |
662
+-------------------------+-------------------------------------------------------+----------------+
663
| ``request_time`` | Length of a request inside CouchDB without MochiWeb | milliseconds |
664
+-------------------------+-------------------------------------------------------+----------------+
666
- ``httpd_request_methods``
668
+----------------+----------------------------------+----------+
669
| Statistic ID | Description | Unit |
670
+================+==================================+==========+
671
| ``COPY`` | Number of HTTP COPY requests | number |
672
+----------------+----------------------------------+----------+
673
| ``DELETE`` | Number of HTTP DELETE requests | number |
674
+----------------+----------------------------------+----------+
675
| ``GET`` | Number of HTTP GET requests | number |
676
+----------------+----------------------------------+----------+
677
| ``HEAD`` | Number of HTTP HEAD requests | number |
678
+----------------+----------------------------------+----------+
679
| ``POST`` | Number of HTTP POST requests | number |
680
+----------------+----------------------------------+----------+
681
| ``PUT`` | Number of HTTP PUT requests | number |
682
+----------------+----------------------------------+----------+
684
- ``httpd_status_codes``
686
+----------------+------------------------------------------------------+----------+
687
| Statistic ID | Description | Unit |
688
+================+======================================================+==========+
689
| ``200`` | Number of HTTP 200 OK responses | number |
690
+----------------+------------------------------------------------------+----------+
691
| ``201`` | Number of HTTP 201 Created responses | number |
692
+----------------+------------------------------------------------------+----------+
693
| ``202`` | Number of HTTP 202 Accepted responses | number |
694
+----------------+------------------------------------------------------+----------+
695
| ``301`` | Number of HTTP 301 Moved Permanently responses | number |
696
+----------------+------------------------------------------------------+----------+
697
| ``304`` | Number of HTTP 304 Not Modified responses | number |
698
+----------------+------------------------------------------------------+----------+
699
| ``400`` | Number of HTTP 400 Bad Request responses | number |
700
+----------------+------------------------------------------------------+----------+
701
| ``401`` | Number of HTTP 401 Unauthorized responses | number |
702
+----------------+------------------------------------------------------+----------+
703
| ``403`` | Number of HTTP 403 Forbidden responses | number |
704
+----------------+------------------------------------------------------+----------+
705
| ``404`` | Number of HTTP 404 Not Found responses | number |
706
+----------------+------------------------------------------------------+----------+
707
| ``405`` | Number of HTTP 405 Method Not Allowed responses | number |
708
+----------------+------------------------------------------------------+----------+
709
| ``409`` | Number of HTTP 409 Conflict responses | number |
710
+----------------+------------------------------------------------------+----------+
711
| ``412`` | Number of HTTP 412 Precondition Failed responses | number |
712
+----------------+------------------------------------------------------+----------+
713
| ``500`` | Number of HTTP 500 Internal Server Error responses | number |
714
+----------------+------------------------------------------------------+----------+
718
+----------------------------------+----------------------------------------------+----------+
719
| Statistic ID | Description | Unit |
720
+==================================+==============================================+==========+
721
| ``bulk_requests`` | Number of bulk requests | number |
722
+----------------------------------+----------------------------------------------+----------+
723
| ``clients_requesting_changes`` | Number of clients for continuous _changes | number |
724
+----------------------------------+----------------------------------------------+----------+
725
| ``requests`` | Number of HTTP requests | number |
726
+----------------------------------+----------------------------------------------+----------+
727
| ``temporary_view_reads`` | Number of temporary view reads | number |
728
+----------------------------------+----------------------------------------------+----------+
729
| ``view_reads`` | Number of view reads | number |
730
+----------------------------------+----------------------------------------------+----------+
732
You can also access individual statistics by quoting the statistics
733
sections and statistic ID as part of the URL path. For example, to get
734
the ``request_time`` statistics, you can use:
738
GET /_stats/couchdb/request_time
740
This returns an entire statistics object, as with the full request, but
741
containing only the request individual statistic. Hence, the returned
742
structure is as follows:
744
.. code-block:: javascript
752
"current" : 34697.803,
755
"description" : "length of a request inside CouchDB without MochiWeb"
764
* **Method**: ``GET /_utils``
766
* **Response**: Administration interface
767
* **Admin Privileges Required**: no
769
Accesses the built-in Futon administration interface for CouchDB.
774
* **Method**: ``GET /_uuids``
776
* **Response**: List of UUIDs
777
* **Admin Privileges Required**: no
778
* **Query Arguments**:
780
* **Argument**: count
782
* **Description**: Number of UUIDs to return
789
Request completed successfully.
791
Requests one or more Universally Unique Identifiers (UUIDs) from the
792
CouchDB instance. The response is a JSON object providing a list of
795
.. code-block:: javascript
799
"7e4b5a14b22ec1cf8e58b9cdd0000da3"
803
You can use the ``count`` argument to specify the number of UUIDs to be
804
returned. For example:
808
GET http://couchdb:5984/_uuids?count=5
812
.. code-block:: javascript
816
"c9df0cdf4442f993fc5570225b405a80",
817
"c9df0cdf4442f993fc5570225b405bd2",
818
"c9df0cdf4442f993fc5570225b405e42",
819
"c9df0cdf4442f993fc5570225b4061a0",
820
"c9df0cdf4442f993fc5570225b406a20"
824
The UUID type is determined by the UUID type setting in the CouchDB
825
configuration. See :ref:`api-put-config`.
827
For example, changing the UUID type to ``random``:
831
PUT http://couchdb:5984/_config/uuids/algorithm
832
Content-Type: application/json
837
When obtaining a list of UUIDs:
839
.. code-block:: javascript
843
"031aad7b469956cf2826fcb2a9260492",
844
"6ec875e15e6b385120938df18ee8e496",
845
"cff9e881516483911aa2f0e98949092d",
846
"b89d37509d39dd712546f9510d4a9271",
847
"2e0dbf7f6c4ad716f21938a016e4e59f"
854
* **Method**: ``GET /favicon.ico``
856
* **Response**: Binary content for the `favicon.ico` site icon
857
* **Admin Privileges Required**: no
861
Request completed successfully.
863
The requested content could not be found. The returned content will include
864
further information, as a JSON object, if available.
866
Returns the site icon. The return ``Content-Type`` header is
867
:mimetype:`image/x-icon`, and the content stream is the image data.
added
removed
share/doc/src/api/misc.rst
