You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2012/12/06 12:34:41 UTC
[27/50] [abbrv] import Couchbase docs
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fd643691/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
----------------------------------------------------------------------
diff --git a/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml b/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
new file mode 100644
index 0000000..8667927
--- /dev/null
+++ b/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
@@ -0,0 +1,9409 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<book id="couchdb-1-1">
+
+ <title>CouchDB 1.1 Manual</title>
+
+ <bookinfo>
+
+ <abstract>
+
+ <para>
+ This manual documents the CouchDB
+ 1.1 database system, including the installation,
+ functionality, and CouchDB API.
+ </para>
+
+ <para xml:base="../common/docbuilddate.xml">
+ <emphasis>Last document update</emphasis>: 21 Feb 2012 20:09;
+ <emphasis>Document built</emphasis>: 21 Feb 2012 20:9.
+</para>
+
+ </abstract>
+
+ </bookinfo>
+
+ <chapter id="couchdb-single-introduction">
+
+ <title>Introduction</title>
+
+ <para>
+ There are two interfaces to CouchDB, the built-in
+ Futon web-based interface and the CouchDB API accessed through the
+ HTTP REST interface. The former is the simplest way to view and
+ monitor your CouchDB installation and perform a
+ number of basic database and system operations. More information on
+ using the Futon interface can be found in
+ <xref linkend="couchdb-single-introduction-futon"/>.
+ </para>
+
+ <para>
+ The primary way to interact with the CouchDB API is to use a client
+ library or other interface that provides access to the underlying
+ functionality through your chosen language or platform. However,
+ since the API is supported through HTTP REST, you can interact with
+ your CouchDB with any solution that supports the
+ HTTP protocol.
+ </para>
+
+ <para>
+ There are a number of different tools that talk the HTTP protocol
+ and allow you to set and configure the necessary information. One
+ tool for this that allows for access from the command-line is
+ <command moreinfo="none">curl</command>. See
+ <xref linkend="couchdb-single-introduction-curl"/>.
+ </para>
+
+ <section id="couchdb-single-introduction-futon">
+
+ <title>Using Futon</title>
+
+ <para>
+ Futon is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the
+ functionality, including the ability to create, update, delete and
+ view documents and views, provides access to the configuration
+ parameters, and an interface for initiating replication.
+ </para>
+
+ <para>
+ The default view is the <guilabel moreinfo="none">Overview</guilabel> page which
+ provides you with a list of the databases. The basic structure of
+ the page is consistent regardless of the section you are in. The
+ main panel on the left provides the main interface to the
+ databases, configuration or replication systems. The side panel on
+ the right provides navigation to the main areas of Futon
+ interface:
+ </para>
+
+ <figure id="fig-ccouchdb-single-introduction-futon-overview" float="0">
+
+ <title>Futon Overview</title>
+
+ <mediaobject>
+
+ <imageobject>
+
+ <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-overview.png" format="PNG" lang="en"/>
+
+ </imageobject>
+
+ <textobject>
+
+ <phrase lang="en">Futon Overview</phrase>
+
+ </textobject>
+
+ </mediaobject>
+
+ </figure>
+
+ <para>
+ The main sections are:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <guibutton moreinfo="none">Overview</guibutton>
+ </para>
+
+ <para>
+ The main overview page, which provides a list of the databases
+ and provides the interface for querying the database and
+ creating and updating documents. See
+ <xref linkend="couchdb-single-introduction-futon-dbdocs"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guibutton moreinfo="none">Configuration</guibutton>
+ </para>
+
+ <para>
+ An interface into the configuration of your CouchDB installation. The interface allows you to edit the
+ different configurable parameters. For more details on
+ configuration, see
+ <xref linkend="couchdb-single-configuration"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guibutton moreinfo="none">Replicator</guibutton>
+ </para>
+
+ <para>
+ An interface to the replication system, enabling you to
+ initiate replication between local and remote databases. See
+ <xref linkend="couchdb-single-introduction-futon-replication"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guibutton moreinfo="none">Status</guibutton>
+ </para>
+
+ <para>
+ Displays a list of the running background tasks on the server.
+ Background tasks include view index building, compaction and
+ replication. The <guibutton moreinfo="none">Status</guibutton> page is an
+ interface to the
+ <link linkend="couchdb-api-misc_active-tasks_get">Active
+ Tasks</link> API call. See
+ <xref linkend="couchdb-api-misc_active-tasks_get"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guibutton moreinfo="none">Verify Installation</guibutton>
+ </para>
+
+ <para>
+ The <guibutton moreinfo="none">Verify Installation</guibutton> allows you to
+ check whether all of the components of your CouchDB installation are correctly installed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guibutton moreinfo="none">Test Suite</guibutton>
+ </para>
+
+ <para>
+ The <guibutton moreinfo="none">Test Suite</guibutton> section allows you to
+ run the built-in test suite. This executes a number of test
+ routines entirely within your browser to test the API and
+ functionality of your CouchDB installation. If
+ you select this page, you can run the tests by using the
+ <guibutton moreinfo="none">Run All</guibutton> button. This will execute all
+ the tests, which may take some time.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <section id="couchdb-single-introduction-futon-dbdocs">
+
+ <title>Managing Databases and Documents</title>
+
+ <para>
+ You can manage databases and documents within Futon using the
+ main <guibutton moreinfo="none">Overview</guibutton> section of the Futon
+ interface.
+ </para>
+
+ <para>
+ To create a new database, click the <guibutton moreinfo="none">Create Database
+ …</guibutton> button. You will be prompted for the
+ database name, as shown in the figure below.
+ </para>
+
+ <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-createdb" float="0">
+
+ <title>Creating a Database</title>
+
+ <mediaobject>
+
+ <imageobject>
+
+ <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-createdb.png" format="PNG" lang="en"/>
+
+ </imageobject>
+
+ <textobject>
+
+ <phrase lang="en">Creating a Database</phrase>
+
+ </textobject>
+
+ </mediaobject>
+
+ </figure>
+
+ <para>
+ Once you have created the database (or selected an existing
+ one), you will be shown a list of the current documents. If you
+ create a new document, or select an existing document, you will
+ be presented with the edit document display.
+ </para>
+
+ <para>
+ Editing documents within Futon requires selecting the document
+ and then editing (and setting) the fields for the document
+ individually before saving the document back into the database.
+ </para>
+
+ <para>
+ For example, the figure below shows the editor for a single
+ document, a newly created document with a single ID, the
+ document <literal moreinfo="none">_id</literal> field.
+ </para>
+
+ <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-editdoc" float="0">
+
+ <title>Editing a Document</title>
+
+ <mediaobject>
+
+ <imageobject>
+
+ <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editdoc.png" format="PNG" lang="en"/>
+
+ </imageobject>
+
+ <textobject>
+
+ <phrase lang="en">Editing a Document</phrase>
+
+ </textobject>
+
+ </mediaobject>
+
+ </figure>
+
+ <para>
+ To add a field to the document:
+ </para>
+
+ <orderedlist inheritnum="ignore" continuation="restarts">
+
+ <listitem>
+ <para>
+ Click <guibutton moreinfo="none">Add Field</guibutton>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In the fieldname box, enter the name of the field you want
+ to create. For example, <quote>company</quote>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Click the green tick next to the field name to confirm the
+ field name change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Double-click the corresponding <guilabel moreinfo="none">Value</guilabel>
+ cell.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Enter a company name, for example <quote>Example</quote>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Click the green tick next to the field value to confirm the
+ field value.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The document is still not saved as this point. You must
+ explicitly save the document by clicking the <guibutton moreinfo="none">Save
+ Document</guibutton> button at the top of the page. This
+ will save the document, and then display the new document
+ with the saved revision information (the
+ <literal moreinfo="none">_rev</literal> field).
+ </para>
+
+ <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-finaldoc" float="0">
+
+ <title>Edited Document</title>
+
+ <mediaobject>
+
+ <imageobject>
+
+ <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editeddoc.png" format="PNG" lang="en"/>
+
+ </imageobject>
+
+ <textobject>
+
+ <phrase lang="en">Edited Document</phrase>
+
+ </textobject>
+
+ </mediaobject>
+
+ </figure>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ The same basic interface is used for all editng operations
+ within Futon. You <emphasis>must</emphasis> rememmbr to save the
+ individual element (fieldname, value) using the green tick
+ button, before then saving the document.
+ </para>
+
+ </section>
+
+ <section id="couchdb-single-introduction-futon-replication">
+
+ <title>Configuring Replication</title>
+
+ <para>
+ When you click the <guibutton moreinfo="none">Replicator</guibutton> option
+ within the <guilabel moreinfo="none">Tools</guilabel> menu you are presented
+ with the Replicator screen. This allows you to start replication
+ between two databases by filling in or select the appropriate
+ options within the form provided.
+ </para>
+
+ <figure id="fig-ccouchdb-single-introduction-futon-replication-form" float="0">
+
+ <title>Replication Form</title>
+
+ <mediaobject>
+
+ <imageobject>
+
+ <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-replform.png" format="PNG" lang="en"/>
+
+ </imageobject>
+
+ <textobject>
+
+ <phrase lang="en">Replication Form</phrase>
+
+ </textobject>
+
+ </mediaobject>
+
+ </figure>
+
+ <para>
+ To start a replication process, either the select the local
+ database or enter a remote database name into the corresponding
+ areas of the form. Replication occurs from the database on the
+ left to the database on the right.
+ </para>
+
+ <para>
+ If you are specifying a remote database name, you must specify
+ the full URL of the remote database (including the host, port
+ number and database name). If the remote instance requires
+ authentication, you can specify the username and password as
+ part of the URL, for example
+ <literal moreinfo="none">http://username:pass@remotehost:5984/demo</literal>.
+ </para>
+
+ <para>
+ To enable continuous replication, click the
+ <guilabel moreinfo="none">Continuous</guilabel> checkbox.
+ </para>
+
+ <para>
+ To start the replication process, click the
+ <guibutton moreinfo="none">Replicate</guibutton> button. The replication process
+ should start and will continue in the background. If the
+ replication process will take a long time, you can monitor the
+ status of the replication using the
+ <guibutton moreinfo="none">Status</guibutton> option under the
+ <guilabel moreinfo="none">Tools</guilabel> menu.
+ </para>
+
+ <para>
+ Once replication has been completed, the page will show the
+ information returned when the replication process completes by
+ the API.
+ </para>
+
+ <para>
+ The <guilabel moreinfo="none">Replicator</guilabel> tool is an interface to the
+ underlying replication API. For more information, see
+ <xref linkend="couchdb-api-misc_replicate_post"/>.
+ For more information on replication, see
+ <xref linkend="couchdb-single-replication"/>.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="couchdb-single-introduction-curl">
+
+ <title>Using <command moreinfo="none">curl</command></title>
+
+ <para>
+ The <command moreinfo="none">curl</command> utility is a command line tool
+ available on Unix, Linux, Mac OS X and Windows and many other
+ platforms. <command moreinfo="none">curl</command> provides easy access to the
+ HTTP protocol (among others) directly from the command-line and is
+ therefore an ideal way of interacting with CouchDB
+ over the HTTP REST API.
+ </para>
+
+ <para>
+ For simple <literal moreinfo="none">GET</literal> requests you can supply the URL
+ of the request. For example, to get the database information:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl http://127.0.0.1:5984</userinput></programlisting>
+
+ <para>
+ This returns the database information (formatted in the output
+ below for clarity):
+ </para>
+
+<programlisting format="linespecific">{
+ "modules" : {
+ "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f"
+ },
+ "couchdb" : "Welcome",
+ "version" : "1.1.0",
+}</programlisting>
+
+ <note>
+ <para>
+ For some URLs, especially those that include special characters
+ such as ampersand, exclamation mark, or question mark, you
+ should quote the URL you are specifying on the command line. For
+ example:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl 'http://couchdb:5984/_uuids?count=5'</userinput></programlisting>
+ </note>
+
+ <para>
+ You can explicitly set the HTTP command using the
+ <option>-X</option> command line option. For example, when
+ creating a database, you set the name of the database in the URL
+ you send using a PUT request:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/demo</userinput>
+{"ok":true}</programlisting>
+
+ <para>
+ But to obtain the database information you use a
+ <literal moreinfo="none">GET</literal> request (with the return information
+ formatted for clarity):
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo</userinput>
+{
+ "compact_running" : false,
+ "doc_count" : 0,
+ "db_name" : "demo",
+ "purge_seq" : 0,
+ "committed_update_seq" : 0,
+ "doc_del_count" : 0,
+ "disk_format_version" : 5,
+ "update_seq" : 0,
+ "instance_start_time" : "1306421773496000",
+ "disk_size" : 79
+}</programlisting>
+
+ <para>
+ For certain operations, you must specify the content type of
+ request, which you do by specifying the
+ <literal moreinfo="none">Content-Type</literal> header using the
+ <option>-H</option> command-line option:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -H 'Content-type: application/json' http://127.0.0.1:5984/_uuids</userinput></programlisting>
+
+ <para>
+ You can also submit 'payload' data, that is, data in the body of
+ the HTTP request using the <option>-d</option> option. This is
+ useful if you need to submit JSON structures, for example document
+ data, as part of the request. For example, to submit a simple
+ document to the <literal moreinfo="none">demo</literal> database:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -H 'Content-type: application/json' \
+ -X POST http://127.0.0.1:5984/demo \
+ -d '{"company": "Example, Inc."}'</userinput>
+{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
+ "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}</programlisting>
+
+ <para>
+ In the above example, the argument after the <option>-d</option>
+ option is the JSON of the document we want to submit.
+ </para>
+
+ <para>
+ The document can be accessed by using the automatically generated
+ document ID that was returned:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8</userinput>
+{"_id":"8843faaf0b831d364278331bc3001bd8",
+ "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
+ "company":"Example, Inc."}</programlisting>
+
+ <para>
+ The API samples in the <xref linkend="couchdb-api-basics"/> show
+ the HTTP command, URL and any payload information that needs to be
+ submitted (and the expected return value). All of these examples
+ can be reproduced using <command moreinfo="none">curl</command> with the
+ command-line examples shown above.
+ </para>
+
+ </section>
+
+</chapter>
+
+ <chapter id="couchdb-single-features">
+
+ <title>Features and Functionality</title>
+
+ <para>
+
+ </para>
+
+ <section id="couchdb-single-features-httprange">
+
+ <title>HTTP Range Requests</title>
+
+ <para>
+ HTTP allows you to specify byte ranges for requests. This allows
+ the implementation of resumable downloads and skippable audio and
+ video streams alike. The following example uses a text file to
+ make the range request process easier.
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">cat file.txt</userinput>
+My hovercraft is full of eels!</programlisting>
+
+ <para>
+ Uploading this as an attachment to a <literal moreinfo="none">text</literal>
+ database using <command moreinfo="none">curl</command>:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
+ -H "Content-Type: application/octet-stream" -d@file.txt</userinput>
+{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}</programlisting>
+
+ <para>
+ Requesting the whole file works as normal:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput>
+My hovercraft is full of eels!</programlisting>
+
+ <para>
+ But to retrieve only the first 13 bytes using
+ <command moreinfo="none">curl</command>:
+ </para>
+
+<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput>
+My hovercraft</programlisting>
+
+ <para>
+ HTTP supports many ways to specify single and even multiple byte
+ rangers. See
+ <ulink url="http://tools.ietf.org/html/rfc2616#section-14.27">RFC
+ 2616</ulink>.
+ </para>
+
+ <note>
+ <para>
+ Databases that have been created with CouchDB 1.0.2 or earlier
+ will support range requests in 1.1.0, but they are using a
+ less-optimal algorithm. If you plan to make heavy use of this
+ feature, make sure to compact your database with CouchDB 1.1.0
+ to take advantage of a better algorithm to find byte ranges.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="couchdb-single-features-proxying">
+
+ <title>HTTP Proxying</title>
+
+ <para>
+ The HTTP proxy feature makes it easy to map and redirect different
+ content through your CouchDB URL. The proxy works by mapping a
+ pathname and passing all content after that prefix through to the
+ configured proxy address.
+ </para>
+
+ <para>
+ Configuration of the proxy redirect is handled through the
+ <literal moreinfo="none">[httpd_global_handlers]</literal> section of the CouchDB
+ configuration file (typically <filename moreinfo="none">local.ini</filename>). The
+ format is:
+ </para>
+
+<programlisting format="linespecific">[httpd_global_handlers]
+PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}</programlisting>
+
+ <para>
+ Where:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">PREFIX</literal>
+ </para>
+
+ <para>
+ Is the string that will be matched. The string can be any
+ valid qualifier, although to ensure that existing database
+ names are not overridden by a proxy configuration, you can use
+ an underscore prefix.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">DESTINATION</literal>
+ </para>
+
+ <para>
+ The fully-qualified URL to which the request should be sent.
+ The destination must include the <literal moreinfo="none">http</literal>
+ prefix. The content is used verbatim in the original request,
+ so you can also forward to servers on different ports and to
+ specific paths on the target host.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The proxy process then translates requests of the form:
+ </para>
+
+<programlisting format="linespecific">http://couchdb:5984/PREFIX/path</programlisting>
+
+ <para>
+ To:
+ </para>
+
+<programlisting format="linespecific">DESTINATION/path</programlisting>
+
+ <note>
+ <para>
+ Everything after <literal moreinfo="none">PREFIX</literal> including the
+ required forward slash will be appended to the
+ <literal moreinfo="none">DESTINATION</literal>.
+ </para>
+ </note>
+
+ <para>
+ The response is then communicated back to the original client.
+ </para>
+
+ <para>
+ For example, the following configuration:
+ </para>
+
+<programlisting format="linespecific">_google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}</programlisting>
+
+ <para>
+ Would forward all requests for
+ <literal moreinfo="none">http://couchdb:5984/_google</literal> to the Google
+ website.
+ </para>
+
+ <para>
+ The service can also be used to forward to related CouchDB
+ services, such as Lucene:
+ </para>
+
+<programlisting format="linespecific">[httpd_global_handlers]
+_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}</programlisting>
+
+ <note>
+ <para>
+ The proxy service is basic. If the request is not identified by
+ the <literal moreinfo="none">DESTINATION</literal>, or the remainder of the
+ <literal moreinfo="none">PATH</literal> specification is incomplete, the
+ original request URL is interpreted as if the
+ <literal moreinfo="none">PREFIX</literal> component of that URL does not exist.
+ </para>
+
+ <para>
+ For example, requesting
+ <literal moreinfo="none">http://couchdb:5984/_intranet/media</literal> when
+ <filename moreinfo="none">/media</filename> on the proxy destination does not
+ exist, will cause the request URL to be interpreted as
+ <literal moreinfo="none">http://couchdb:5984/media</literal>. Care should be
+ taken to ensure that both requested URLs and destination URLs
+ are able to cope
+ </para>
+ </note>
+
+ </section>
+
+ <section id="couchdb-single-features-commonjs">
+
+ <title>CommonJS support for map functions</title>
+
+ <para>
+ CommonJS support allows you to use CommonJS notation inside
+ <methodname>map</methodname> and <methodname>reduce</methodname>
+ functions, but only of libraries that are stored inside the views
+ part of the design doc.
+ </para>
+
+ <para>
+ So you could continue to access CommonJS code in design_doc.foo,
+ from your list functions etc, but we'd add the ability to require
+ CommonJS modules within map and reduce, but only from
+ <filename moreinfo="none">design_doc.views.lib</filename>.
+ </para>
+
+ <para>
+ There's no worry here about namespace collisions, as Couch just
+ plucks <literal moreinfo="none">views.*.map</literal> and
+ <literal moreinfo="none">views.*.reduce</literal> out of the design doc. So you
+ could have a view called <literal moreinfo="none">lib</literal> if you wanted, and
+ still have CommonJS stored in <literal moreinfo="none">views.lib.sha1</literal>
+ and <literal moreinfo="none">views.lib.stemmer</literal> if you wanted.
+ </para>
+
+ <para>
+ The implementation is simplified by enforcing that CommonJS
+ modules to be used in <methodname>map</methodname> functions be
+ stored in views.lib.
+ </para>
+
+ <para>
+ A sample design doc (taken from the test suite in Futon) is below:
+ </para>
+
+<programlisting format="linespecific">{
+ "views" : {
+ "lib" : {
+ "baz" : "exports.baz = 'bam';",
+ "foo" : {
+ "zoom" : "exports.zoom = 'yeah';",
+ "boom" : "exports.boom = 'ok';",
+ "foo" : "exports.foo = 'bar';"
+ }
+ },
+ "commonjs" : {
+ "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}"
+ }
+ },
+ "_id" : "_design/test"
+}</programlisting>
+
+ <para>
+ The <literal moreinfo="none">require()</literal> statement is relative to the
+ design document, but anything loaded form outside of
+ <literal moreinfo="none">views/lib</literal> will fail.
+ </para>
+
+ </section>
+
+ <section id="couchdb-single-features-etag">
+
+ <title>Granular ETag support</title>
+
+ <para>
+ ETags have been assigned to a map/reduce group (the collection of
+ views in a single design document). Any change to any of the
+ indexes for those views would generate a new ETag for all view
+ URL's in a single design doc, even if that specific view's results
+ had not changed.
+ </para>
+
+ <para>
+ In CouchDB 1.1 each <literal moreinfo="none">_view</literal> URL has it's own ETag
+ which only gets updated when changes are made to the database that
+ effect that index. If the index for that specific view does not
+ change, that view keeps the original ETag head (therefore sending
+ back 304 Not Modified more often).
+ </para>
+
+ </section>
+
+</chapter>
+
+ <chapter id="couchdb-single-replication">
+
+ <title>Replication</title>
+
+ <para>
+
+ </para>
+
+ <section id="couchdb-single-replication-replicatordb">
+
+ <title>Replicator Database</title>
+
+ <para>
+ A database where you
+ <literal moreinfo="none">PUT</literal>/<literal moreinfo="none">POST</literal> documents to
+ trigger replications and you <literal moreinfo="none">DELETE</literal> to cancel
+ ongoing replications. These documents have exactly the same
+ content as the JSON objects we used to <literal moreinfo="none">POST</literal> to
+ <literal moreinfo="none">_replicate</literal> (fields <literal moreinfo="none">source</literal>,
+ <literal moreinfo="none">target</literal>, <literal moreinfo="none">create_target</literal>,
+ <literal moreinfo="none">continuous</literal>, <literal moreinfo="none">doc_ids</literal>,
+ <literal moreinfo="none">filter</literal>, <literal moreinfo="none">query_params</literal>.
+ </para>
+
+ <para>
+ Replication documents can have a user defined
+ <literal moreinfo="none">_id</literal>. Design documents (and
+ <literal moreinfo="none">_local</literal> documents) added to the replicator
+ database are ignored.
+ </para>
+
+ <para>
+ The default name of this database is
+ <literal moreinfo="none">_replicator</literal>. The name can be changed in the
+ <filename moreinfo="none">local.ini</filename> configuration, section
+ <literal moreinfo="none">[replicator]</literal>, parameter <literal moreinfo="none">db</literal>.
+ </para>
+
+ <section id="couchdb-single-replication-replicatordb-basics">
+
+ <title>Basics</title>
+
+ <para>
+ Let's say you PUT the following document into _replicator:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "my_rep",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "create_target": true
+}</programlisting>
+
+ <para>
+ In the couch log you'll see 2 entries like these:
+ </para>
+
+<programlisting format="linespecific">[Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target`
+[Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)</programlisting>
+
+ <para>
+ As soon as the replication is triggered, the document will be
+ updated by CouchDB with 3 new fields:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "my_rep",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "create_target": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+}</programlisting>
+
+ <para>
+ Special fields set by the replicator start with the prefix
+ <literal moreinfo="none">_replication_</literal>.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">_replication_id</literal>
+ </para>
+
+ <para>
+ The ID internally assigned to the replication. This is also
+ the ID exposed by <literal moreinfo="none">/_active_tasks</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">_replication_state</literal>
+ </para>
+
+ <para>
+ The current state of the replication.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">_replication_state_time</literal>
+ </para>
+
+ <para>
+ A Unix timestamp (number of seconds since 1 Jan 1970) that
+ tells us when the current replication state (marked in
+ <literal moreinfo="none">_replication_state</literal>) was set.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ When the replication finishes, it will update the
+ <literal moreinfo="none">_replication_state</literal> field (and
+ <literal moreinfo="none">_replication_state_time</literal>) with the value
+ <literal moreinfo="none">completed</literal>, so the document will look like:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "my_rep",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "create_target": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "completed",
+ "_replication_state_time": 1297974122
+}</programlisting>
+
+ <para>
+ When an error happens during replication, the
+ <literal moreinfo="none">_replication_state</literal> field is set to
+ <literal moreinfo="none">error</literal> (and
+ <literal moreinfo="none">_replication_state</literal> gets updated of course).
+ </para>
+
+ <para>
+ When you PUT/POST a document to the
+ <literal moreinfo="none">_replicator</literal> database, CouchDB will attempt to
+ start the replication up to 10 times (configurable under
+ <literal moreinfo="none">[replicator]</literal>, parameter
+ <literal moreinfo="none">max_replication_retry_count</literal>). If it fails on
+ the first attempt, it waits 5 seconds before doing a second
+ attempt. If the second attempt fails, it waits 10 seconds before
+ doing a third attempt. If the third attempt fails, it waits 20
+ seconds before doing a fourth attempt (each attempt doubles the
+ previous wait period). When an attempt fails, the Couch log will
+ show you something like:
+ </para>
+
+<programlisting format="linespecific">[error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">></programlisting>
+
+ <note>
+ <para>
+ The <literal moreinfo="none">_replication_state</literal> field is only set to
+ <literal moreinfo="none">error</literal> when all the attempts were
+ unsuccessful.
+ </para>
+ </note>
+
+ <para>
+ There are only 3 possible values for the
+ <literal moreinfo="none">_replication_state</literal> field:
+ <literal moreinfo="none">triggered</literal>, <literal moreinfo="none">completed</literal> and
+ <literal moreinfo="none">error</literal>. Continuous replications never get
+ their state set to <literal moreinfo="none">completed</literal>.
+ </para>
+
+ </section>
+
+ <section id="couchdb-single-replication-replicatordb-docsame">
+
+ <title>Documents describing the same replication</title>
+
+ <para>
+ Lets suppose 2 documents are added to the
+ <literal moreinfo="none">_replicator</literal> database in the following order:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "doc_A",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar"
+}</programlisting>
+
+ <para>
+ and
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "doc_B",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar"
+}</programlisting>
+
+ <para>
+ Both describe exactly the same replication (only their
+ <literal moreinfo="none">_ids</literal> differ). In this case document
+ <literal moreinfo="none">doc_A</literal> triggers the replication, getting
+ updated by CouchDB with the fields
+ <literal moreinfo="none">_replication_state</literal>,
+ <literal moreinfo="none">_replication_state_time</literal> and
+ <literal moreinfo="none">_replication_id</literal>, just like it was described
+ before. Document <literal moreinfo="none">doc_B</literal> however, is only
+ updated with one field, the <literal moreinfo="none">_replication_id</literal>
+ so it will look like this:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "doc_B",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280"
+}</programlisting>
+
+ <para>
+ While document <literal moreinfo="none">doc_A</literal> will look like this:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "doc_A",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+}</programlisting>
+
+ <para>
+ Note that both document get exactly the same value for the
+ <literal moreinfo="none">_replication_id</literal> field. This way you can
+ identify which documents refer to the same replication - you can
+ for example define a view which maps replication IDs to document
+ IDs.
+ </para>
+
+ </section>
+
+ <section id="couchdb-single-replication-replicatordb-cancel">
+
+ <title>Canceling replications</title>
+
+ <para>
+ To cancel a replication simply <literal moreinfo="none">DELETE</literal> the
+ document which triggered the replication. The Couch log will
+ show you an entry like the following:
+ </para>
+
+<programlisting format="linespecific">[Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted</programlisting>
+
+ <note>
+ <para>
+ You need to <literal moreinfo="none">DELETE</literal> the document that
+ triggered the replication. <literal moreinfo="none">DELETE</literal>ing
+ another document that describes the same replication but did
+ not trigger it, will not cancel the replication.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="couchdb-single-replication-replicatordb-restart">
+
+ <title>Server restart</title>
+
+ <para>
+ When CouchDB is restarted, it checks its
+ <literal moreinfo="none">_replicator</literal> database and restarts any
+ replication that is described by a document that either has its
+ <literal moreinfo="none">_replication_state</literal> field set to
+ <literal moreinfo="none">triggered</literal> or it doesn't have yet the
+ <literal moreinfo="none">_replication_state</literal> field set.
+ </para>
+
+ <note>
+ <para>
+ Continuous replications always have a
+ <literal moreinfo="none">_replication_state</literal> field with the value
+ <literal moreinfo="none">triggered</literal>, therefore they're always
+ restarted when CouchDB is restarted.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="couchdb-single-replication-replicatordb-changing">
+
+ <title>Changing the Replicator Database</title>
+
+ <para>
+ Imagine your replicator database (default name is _replicator)
+ has the two following documents that represent pull replications
+ from servers A and B:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "rep_from_A",
+ "source": "http://aserver.com:5984/foo",
+ "target": "foo_a",
+ "continuous": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297971311
+}
+{
+ "_id": "rep_from_B",
+ "source": "http://bserver.com:5984/foo",
+ "target": "foo_b",
+ "continuous": true,
+ "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+}</programlisting>
+
+ <para>
+ Now without stopping and restarting CouchDB, you change the name
+ of the replicator database to
+ <literal moreinfo="none">another_replicator_db</literal>:
+ </para>
+
+<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"'
+"_replicator"</programlisting>
+
+ <para>
+ As soon as this is done, both pull replications defined before,
+ are stopped. This is explicitly mentioned in CouchDB's log:
+ </para>
+
+<programlisting format="linespecific">[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed
+[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200</programlisting>
+
+ <para>
+ Imagine now you add a replication document to the new replicator
+ database named <literal moreinfo="none">another_replicator_db</literal>:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "rep_from_X",
+ "source": "http://xserver.com:5984/foo",
+ "target": "foo_x",
+ "continuous": true
+}</programlisting>
+
+ <para>
+ From now own you have a single replication going on in your
+ system: a pull replication pulling from server X. Now you change
+ back the replicator database to the original one
+ <literal moreinfo="none">_replicator</literal>:
+ </para>
+
+<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"'
+"another_replicator_db"</programlisting>
+
+ <para>
+ Immediately after this operation, the replication pulling from
+ server X will be stopped and the replications defined in the
+ _replicator database (pulling from servers A and B) will be
+ resumed.
+ </para>
+
+ <para>
+ Changing again the replicator database to
+ <literal moreinfo="none">another_replicator_db</literal> will stop the pull
+ replications pulling from servers A and B, and resume the pull
+ replication pulling from server X.
+ </para>
+
+ </section>
+
+ <section id="couchdb-single-replication-replicatordb-replicating">
+
+ <title>Replicating the replicator database</title>
+
+ <para>
+ Imagine you have in server C a replicator database with the two
+ following pull replication documents in it:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "rep_from_A",
+ "source": "http://aserver.com:5984/foo",
+ "target": "foo_a",
+ "continuous": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297971311
+}
+{
+ "_id": "rep_from_B",
+ "source": "http://bserver.com:5984/foo",
+ "target": "foo_b",
+ "continuous": true,
+ "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+}</programlisting>
+
+ <para>
+ Now you would like to have the same pull replications going on
+ in server D, that is, you would like to have server D pull
+ replicating from servers A and B. You have two options:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Explicitly add two documents to server's D replicator
+ database
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Replicate server's C replicator database into server's D
+ replicator database
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Both alternatives accomplish exactly the same goal.
+ </para>
+
+ </section>
+
+ <section id="couchdb-single-replication-replicatordb-delegations">
+
+ <title>Delegations</title>
+
+ <para>
+ Replication documents can have a custom
+ <literal moreinfo="none">user_ctx</literal> property. This property defines the
+ user context under which a replication runs. For the old way of
+ triggering replications (POSTing to
+ <literal moreinfo="none">/_replicate/</literal>), this property was not needed
+ (it didn't exist in fact) - this is because at the moment of
+ triggering the replication it has information about the
+ authenticated user. With the replicator database, since it's a
+ regular database, the information about the authenticated user
+ is only present at the moment the replication document is
+ written to the database - the replicator database implementation
+ is like a _changes feed consumer (with
+ <literal moreinfo="none">?include_docs=true</literal>) that reacts to what was
+ written to the replicator database - in fact this feature could
+ be implemented with an external script/program. This
+ implementation detail implies that for non admin users, a
+ <literal moreinfo="none">user_ctx</literal> property, containing the user's name
+ and a subset of his/her roles, must be defined in the
+ replication document. This is ensured by the document update
+ validation function present in the default design document of
+ the replicator database. This validation function also ensure
+ that a non admin user can set a user name property in the
+ <literal moreinfo="none">user_ctx</literal> property that doesn't match his/her
+ own name (same principle applies for the roles).
+ </para>
+
+ <para>
+ For admins, the <literal moreinfo="none">user_ctx</literal> property is
+ optional, and if it's missing it defaults to a user context with
+ name null and an empty list of roles - this mean design
+ documents will not be written to local targets. If writing
+ design documents to local targets is desired, the a user context
+ with the roles <literal moreinfo="none">_admin</literal> must be set explicitly.
+ </para>
+
+ <para>
+ Also, for admins the <literal moreinfo="none">user_ctx</literal> property can be
+ used to trigger a replication on behalf of another user. This is
+ the user context that will be passed to local target database
+ document validation functions.
+ </para>
+
+ <note>
+ <para>
+ The <literal moreinfo="none">user_ctx</literal> property only has effect for
+ local endpoints.
+ </para>
+ </note>
+
+ <para>
+ Example delegated replication document:
+ </para>
+
+<programlisting format="linespecific">{
+ "_id": "my_rep",
+ "source": "http://bserver.com:5984/foo",
+ "target": "bar",
+ "continuous": true,
+ "user_ctx": {
+ "name": "joe",
+ "roles": ["erlanger", "researcher"]
+ }
+}</programlisting>
+
+ <para>
+ As stated before, for admins the user_ctx property is optional,
+ while for regular (non admin) users it's mandatory. When the
+ roles property of <literal moreinfo="none">user_ctx</literal> is missing, it
+ defaults to the empty list <literal moreinfo="none">[ ]</literal>.
+ </para>
+
+ </section>
+
+ </section>
+
+</chapter>
+
+
+
+ <chapter id="couchdb-api-basics">
+
+ <title>CouchDB API</title>
+
+ <para>
+ The CouchDB API is the primary method of interfacing to a CouchDB
+ instance. Requests are made using HTTP and requests are used to
+ request information from the database, store new data, and perform
+ views and formatting of the information stored within the documents.
+ </para>
+
+ <para>
+ Requests to the API can be categorised by the different areas of the
+ CouchDB system that you are accessing, and the HTTP method used to
+ send the request. Different methods imply different operations, for
+ example retrieval of information from the database is typically
+ handled by the <literal moreinfo="none">GET</literal> operation, while updates are
+ handled by either a <literal moreinfo="none">POST</literal> or
+ <literal moreinfo="none">PUT</literal> request. There are some differences between
+ the information that must be supplied for the different methods. For
+ a guide to the basic HTTP methods and request structure, see
+ <xref linkend="couchdb-api-introduction-requests"/>.
+ </para>
+
+ <para>
+ For nearly all operations, the submitted data, and the returned data
+ structure, is defined within a JavaScript Object Notation (JSON)
+ object. Basic information on the content and data types for JSON are
+ provided in <xref linkend="couchdb-api-introduction-json"/>.
+ </para>
+
+ <para>
+ Errors when accessing the CouchDB API are reported using standard
+ HTTP Status Codes. A guide to the generic codes returned by CouchDB
+ are provided in
+ <xref linkend="couchdb-api-introduction-returncodes"/>.
+ </para>
+
+ <para>
+ When accessing specific areas of the CouchDB API, specific
+ information and examples on the HTTP methods and request, JSON
+ structures, and error codes are provided. For a guide to the
+ different areas of the API, see
+ <xref linkend="couchdb-api-overview"/>.
+ </para>
+
+ <section id="couchdb-api-introduction-requests">
+
+ <title>Request Format and Responses</title>
+
+ <para>
+ CouchDB supports the following HTTP request methods:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">GET</literal>
+ </para>
+
+ <para>
+ Request the specified item. As with normal HTTP requests, the
+ format of the URL defines what is returned. With CouchDB this
+ can include static items, database documents, and
+ configuration and statistical information. In most cases the
+ information is returned in the form of a JSON document.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">HEAD</literal>
+ </para>
+
+ <para>
+ The <literal moreinfo="none">HEAD</literal> method is used to get the HTTP
+ header of a <literal moreinfo="none">GET</literal> request without the body of
+ the response.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">POST</literal>
+ </para>
+
+ <para>
+ Upload data. Within CouchDB <literal moreinfo="none">POST</literal> is used to
+ set values, including uploading documents, setting document
+ values, and starting certain administration commands.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">PUT</literal>
+ </para>
+
+ <para>
+ Used to put a specified resource. In CouchDB
+ <literal moreinfo="none">PUT</literal> is used to create new objects,
+ including databases, documents, views and design documents.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">DELETE</literal>
+ </para>
+
+ <para>
+ Deletes the specified resource, including documents, views,
+ and design documents.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">COPY</literal>
+ </para>
+
+ <para>
+ A special method that can be used to copy documents and
+ objects.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ If you use the an unsupported HTTP request type with a URL that
+ does not support the specified type, a 405 error will be returned,
+ listing the supported HTTP methods. For example:
+ </para>
+
+<programlisting format="linespecific">{
+ "error":"method_not_allowed",
+ "reason":"Only GET,HEAD allowed"
+}</programlisting>
+
+
+
+ <para>
+ The CouchDB design document API and the functions when returning
+ HTML (for example as part of a show or list) enables you to
+ include custom HTTP headers through the <literal moreinfo="none">headers</literal>
+ block of the return object. For more information, see
+ <xref linkend="couchdb-api-functional"/>.
+ </para>
+
+ </section>
+
+ <section id="couchdb-api-introduction-request-header">
+
+ <title>HTTP Headers</title>
+
+ <para>
+ Because CouchDB uses HTTP for all communication, you need to
+ ensure that the correct HTTP headers are supplied (and processed
+ on retrieval) so that you get the right format and encoding.
+ Different environments and clients will be more or less strict on
+ the effect of these HTTP headers (especially when not present).
+ Where possible you should be as specific as possible.
+ </para>
+
+ <section id="couchdb-api-introduction-request-header-request">
+
+ <title>Request Headers</title>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">Content-type</literal>
+ </para>
+
+ <para>
+ Specifies the content type of the information being supplied
+ within the request. The specification uses MIME type
+ specifications. For the majority of requests this will be
+ JSON (<literal moreinfo="none">application/json</literal>). For some
+ settings the MIME type will be plain text. When uploading
+ attachments it should be the corresponding MIME type for the
+ attachment or binary
+ (<literal moreinfo="none">application/octet-stream</literal>).
+ </para>
+
+ <para>
+ The use of the <literal moreinfo="none">Content-type</literal> on a request
+ is highly recommended.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">Accept</literal>
+ </para>
+
+ <para>
+ Specifies the list of accepted data types to be returned by
+ the server (i.e. that are accepted/understandable by the
+ client). The format should be a list of one or more MIME
+ types, separated by colons.
+ </para>
+
+ <para>
+ For the majority of requests the definition should be for
+ JSON data (<literal moreinfo="none">application/json</literal>). For
+ attachments you can either specify the MIME type explicitly,
+ or use <literal moreinfo="none">*/*</literal> to specify that all file types
+ are supported. If the <literal moreinfo="none">Accept</literal> header is
+ not supplied, then the <literal moreinfo="none">*/*</literal> MIME type is
+ assumed (i.e. client accepts all formats).
+ </para>
+
+ <para>
+ The use of <literal moreinfo="none">Accept</literal> in queries for CouchDB
+ is not required, but is highly recommended as it helps to
+ ensure that the data returned can be processed by the
+ client.
+ </para>
+
+ <para>
+ If you specify a data type using the
+ <literal moreinfo="none">Accept</literal> header, CouchDB will honor the
+ specified type in the <literal moreinfo="none">Content-type</literal> header
+ field returned. For example, if you explicitly request
+ <literal moreinfo="none">application/json</literal> in the
+ <literal moreinfo="none">Accept</literal> of a request, the returned HTTP
+ headers will use the value in the returned
+ <literal moreinfo="none">Content-type</literal> field.
+ </para>
+
+ <para>
+ For example, when sending a request without an explicit
+ <literal moreinfo="none">Accept</literal> header, or when specifying
+ <literal moreinfo="none">*/*</literal>:
+ </para>
+
+<programlisting format="linespecific">GET /recipes HTTP/1.1
+Host: couchdb:5984
+Accept: */*</programlisting>
+
+ <para>
+ The returned headers are:
+ </para>
+
+<programlisting format="linespecific">Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+Date: Thu, 13 Jan 2011 13:39:34 GMT
+Content-Type: text/plain;charset=utf-8
+Content-Length: 227
+Cache-Control: must-revalidate</programlisting>
+
+ <para>
+ Note that the returned content type is
+ <literal moreinfo="none">text/plain</literal> even though the information
+ returned by the request is in JSON format.
+ </para>
+
+ <para>
+ Explicitly specifying the <literal moreinfo="none">Accept</literal> header:
+ </para>
+
+<programlisting format="linespecific">GET /recipes HTTP/1.1
+Host: couchdb:5984
+Accept: application/json</programlisting>
+
+ <para>
+ The headers returned include the
+ <literal moreinfo="none">application/json</literal> content type:
+ </para>
+
+<programlisting format="linespecific">Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+Date: Thu, 13 Jan 2011 13:40:11 GMT
+Content-Type: application/json
+Content-Length: 227
+Cache-Control: must-revalidate</programlisting>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="couchdb-api-introduction-request-header-response">
+
+ <title>Response Headers</title>
+
+ <para>
+ Response headers are returned by the server when sending back
+ content and include a number of different header fields, many of
+ which are standard HTTP response header and have no significance
+ to CouchDB operation. The list of response headers important to
+ CouchDB are listed below.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">Content-type</literal>
+ </para>
+
+ <para>
+ Specifies the MIME type of the returned data. For most
+ request, the returned MIME type is
+ <literal moreinfo="none">text/plain</literal>. All text is encoded in
+ Unicode (UTF-8), and this is explicitly stated in the
+ returned <literal moreinfo="none">Content-type</literal>, as
+ <literal moreinfo="none">text/plain;charset=utf-8</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">Cache-control</literal>
+ </para>
+
+ <para>
+ The cache control HTTP response header provides a suggestion
+ for client caching mechanisms on how to treat the returned
+ information. CouchDB typically returns the
+ <literal moreinfo="none">must-revalidate</literal>, which indicates that the
+ information should be revalidated if possible. This is used
+ to ensure that the dynamic nature of the content is
+ correctly updated.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">Content-length</literal>
+ </para>
+
+ <para>
+ The length (in bytes) of the returned content.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">Etag</literal>
+ </para>
+
+ <para>
+ The <literal moreinfo="none">Etag</literal> HTTP header field is used to
+ show the revision for a document.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ </section>
+
+ <section id="couchdb-api-introduction-json">
+
+ <title>JSON Basics</title>
+
+ <para>
+ The majority of requests and responses to CouchDB use the
+ JavaScript Object Notation (JSON) for formatting the content and
+ structure of the data and responses.
+ </para>
+
+ <para>
+ JSON is used because it is the simplest and easiest to use
+ solution for working with data within a web browser, as JSON
+ structures can be evaluated and used as JavaScript objects within
+ the web browser environment. JSON also integrates with the
+ server-side JavaScript used within CouchDB.
+ </para>
+
+ <para>
+ JSON supports the same basic types as supported by JavaScript,
+ these are:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Number (either integer or floating-point).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ String; this should be enclosed by double-quotes and supports
+ Unicode characters and backslash escaping. For example:
+ </para>
+
+<programlisting format="linespecific">"A String"</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Boolean - a <literal moreinfo="none">true</literal> or
+ <literal moreinfo="none">false</literal> value. You can use these strings
+ directly. For example:
+ </para>
+
+<programlisting format="linespecific">{ "value": true}</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Array - a list of values enclosed in square brackets. For
+ example:
+ </para>
+
+<programlisting format="linespecific">["one", "two", "three"]</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Object - a set of key/value pairs (i.e. an associative array,
+ or hash). The key must be a string, but the value can be any
+ of the supported JSON values. For example:
+ </para>
+
+<programlisting format="linespecific">{
+ "servings" : 4,
+ "subtitle" : "Easy to make in advance, and then cook when ready",
+ "cooktime" : 60,
+ "title" : "Chicken Coriander"
+}</programlisting>
+
+ <para>
+ In CouchDB, the JSON object is used to represent a variety of
+ structures, including the main CouchDB document.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Parsing JSON into a JavaScript object is supported through the
+ <literal moreinfo="none">eval()</literal> function in JavaScript, or through
+ various libraries that will perform the parsing of the content
+ into a JavaScript object for you. Libraries for parsing and
+ generating JSON are available in many languages, including Perl,
+ Python, Ruby, Erlang and others.
+ </para>
+
+ <warning>
+ <para>
+ Care should be taken to ensure that your JSON structures are
+ valid, invalid structures will cause CouchDB to return an HTTP
+ status code of 500 (server error). See
+ <xref linkend="couchdb-api-introduction-returncode-500"/>
+ .
+ </para>
+ </warning>
+
+ </section>
+
+ <section id="couchdb-api-introduction-returncodes">
+
+ <title>HTTP Status Codes</title>
+
+ <para>
+ With the interface to CouchDB working through HTTP, error codes
+ and statuses are reported using a combination of the HTTP status
+ code number, and corresponding data in the body of the response
+ data.
+ </para>
+
+ <para>
+ A list of the error codes returned by CouchDB, and generic
+ descriptions of the related errors are provided below. The meaning
+ of different status codes for specific request types are provided
+ in the corresponding API call reference.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-200">
+ <literal moreinfo="none">200 - OK</literal>
+ </para>
+
+ <para>
+ Request completed successfully.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-201">
+ <literal moreinfo="none">201 - Created</literal>
+ </para>
+
+ <para>
+ Document created successfully.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-202">
+ <literal moreinfo="none">202 - Accepted</literal>
+ </para>
+
+ <para>
+ Request has been accepted, but the corresponding operation may
+ not have completed. This is used for background operations,
+ such as database compaction.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-304">
+ <literal moreinfo="none">304 - Not Modified</literal>
+ </para>
+
+ <para>
+ The additional content requested has not been modified. This
+ is used with the ETag system to identify the version of
+ information returned.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-400">
+ <literal moreinfo="none">400 - Bad Request</literal>
+ </para>
+
+ <para>
+ Bad request structure. The error can indicate an error with
+ the request URL, path or headers. Differences in the supplied
+ MD5 hash and content also trigger this error, as this may
+ indicate message corruption.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-401">
+ <literal moreinfo="none">401 - Unauthorized</literal>
+ </para>
+
+ <para>
+ The item requested was not available using the supplied
+ authorization, or authorization was not supplied.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-403">
+ <literal moreinfo="none">403 - Forbidden</literal>
+ </para>
+
+ <para>
+ The requested item or operation is forbidden.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-404">
+ <literal moreinfo="none">404 - Not Found</literal>
+ </para>
+
+ <para>
+ The requested content could not be found. The content will
+ include further information, as a JSON object, if available.
+ The structure will contain two keys, <literal moreinfo="none">error</literal>
+ and <literal moreinfo="none">reason</literal>. For example:
+ </para>
+
+<programlisting format="linespecific">{"error":"not_found","reason":"no_db_file"}</programlisting>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-405">
+ <literal moreinfo="none">405 - Resource Not Allowed</literal>
+ </para>
+
+ <para>
+ A request was made using an invalid HTTP request type for the
+ URL requested. For example, you have requested a
+ <literal moreinfo="none">PUT</literal> when a <literal moreinfo="none">POST</literal> is
+ required. Errors of this type can also triggered by invalid
+ URL strings.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-406">
+ <literal moreinfo="none">406 - Not Acceptable</literal>
+ </para>
+
+ <para>
+ The requested content type is not supported by the server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-409">
+ <literal moreinfo="none">409 - Conflict</literal>
+ </para>
+
+ <para>
+ Request resulted in an update conflict.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-412">
+ <literal moreinfo="none">412 - Precondition Failed</literal>
+ </para>
+
+ <para>
+ The request headers from the client and the capabilities of
+ the server do not match.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-415">
+ <literal moreinfo="none">415 - Bad Content Type</literal>
+ </para>
+
+ <para>
+ The content types supported, and the content type of the
+ information being requested or submitted indicate that the
+ content type is not supported.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-416">
+ <literal moreinfo="none">416 - Requested Range Not Satisfiable</literal>
+ </para>
+
+ <para>
+ The range specified in the request header cannot be satisfied
+ by the server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-417">
+ <literal moreinfo="none">417 - Expectation Failed</literal>
+ </para>
+
+ <para>
+ When sending documents in bulk, the bulk load operation
+ failed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="couchdb-api-introduction-returncode-500" xreflabel="HTTP Status Code 500">
+ <literal moreinfo="none">500 - Internal Server Error</literal>
+ </para>
+
+ <para>
+ The request was invalid, either because the supplied JSON was
+ invalid, or invalid information was supplied as part of the
+ request.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="couchdb-api-overview">
+
+ <title>CouchDB API Overview</title>
+
+ <para>
+ The components of the API URL path help determine the part of the
+ CouchDB server that is being accessed. The result is the structure
+ of the URL request both identifies and effectively describes the
+ area of the database you are accessing.
+ </para>
+
+ <para>
+ As with all URLs, the individual components are separated by a
+ forward slash.
+ </para>
+
+ <para>
+ As a general rule, URL components and JSON fields starting with
+ the <literal moreinfo="none">_</literal> (underscore) character represent a
+ special component or entity within the server or returned object.
+ For example, the URL fragment <literal moreinfo="none">/_all_dbs</literal> gets a
+ list of all of the databases in a CouchDB instance.
+ </para>
+
+ <para>
+ The remainder of the URL API structure can be divided up according
+ to the URL structure. The different sections are divided as
+ follows:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">/db</literal>
+ </para>
+
+ <para>
+ Database methods, related to adding, updating or deleting
+ databases, and setting database parameters and operations. For
+ more detailed information, see
+ <xref linkend="couchdb-api-db"/> .
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">/db/doc</literal>
+ </para>
+
+ <para>
+ Document methods, those that create, store, update or delete
+ CouchDB documents and their attachments. For more information,
+ see <xref linkend="couchdb-api-dbdoc"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">/db/_local/local-doc</literal>
+ </para>
+
+ <para>
+ Document methods, those that create, store, update or delete
+ CouchDB documents only within the local database. Local
+ documents are not synchronized with other databases. For more
+ information, see
+ <xref linkend="couchdb-api-localdb"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">/db/_design/design-doc</literal>
+ </para>
+
+ <para>
+ Design documents provide the methods and structure for
+ recovering information from a CouchDB database in the form of
+ views, shows and lists. For more information, see
+ <xref linkend="couchdb-api-design"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">/_special</literal>
+ </para>
+
+ <para>
+ Special methods that obtain or set information about the
+ CouchDB instance, including methods for configuring
+ replication, accessing the logs, and generate Universally
+ Unique IDs (UUIDs). For more information, see
+ <xref linkend="couchdb-api-misc"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal moreinfo="none">/_config</literal>
+ </para>
+
+ <para>
+ Methods for getting, and settings, CouchDB configuration
+ parameters. For more information, see
+ <xref linkend="couchdb-api-misc"/>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+
+
+ </section>
+
+</chapter>
+
+ <chapter id="couchdb-api-db">
+
+ <title>CouchDB API Server Database Methods</title>
+
+ <para>
+ The Database methods provide an interface to an entire database
+ withing CouchDB. These are database, rather than document, level
+ requests.
+ </para>
+
+ <para>
+ A list of the available methods and URL paths are provided below:
+ </para>
+
+ <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<table id="table-couchdb-api-db-summary"><title>Database API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_get">
+ Returns database information
+ </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_put">
+ Create a new database
+ </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_delete">
+ Delete an existing database
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_get">
+ Returns a built-in view of all documents in this database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_post">
+ Returns certain rows from the built-in view of all documents
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_bulk_docs</literal></entry><entry><link linkend="couchdb-api-db_db-bulk-docs_post">
+ Insert multiple documents in to the database in a single request
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_changes</literal></entry><entry><link linkend="couchdb-api-db_db-changes_get">
+ Returns changes for the given database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact</literal></entry><entry><link linkend="couchdb-api-db_db-compact_post">
+ Starts a compaction for the database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact/design-doc</literal></entry><entry><link linkend="couchdb-api-db_db-compact-design-doc_post">
+ Starts a compaction for all the views in the selected design
+ document
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_ensure_full_commit</literal></entry><entry><link linkend="couchdb-api-db_db-ensure-full-commit_post">
+ Makes sure all uncommitted changes are written and synchronized
+ to the disk
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_missing_revs</literal></entry><entry><link linkend="couchdb-api-db_db-missing-revs_post">
+ Given a list of document revisions, returns the document
+ revisions that do not exist in the database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_purge</literal></entry><entry><link linkend="couchdb-api-db_db-purge_post">
+ Purge some historical documents entirely from database history
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_revs_diff</literal></entry><entry><link linkend="couchdb-api-db_db-revs-diff_post">
+ Given a list of document revisions, returns differences between
+ the given revisions and ones that are in the database
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_get">
+ Gets the limit of historical revisions to store for a single
+ document in the database
+ </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_put">
+ Sets the limit of historical revisions to store for a single
+ document in the database
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_get">
+ Returns the special security object for the database
+ </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_put">
+ Sets the special security object for the database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_temp_view</literal></entry><entry><link linkend="couchdb-api-db_db-temp-view_post">
+ Execute a given view function for all documents and return the
+ result
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_view_cleanup</literal></entry><entry><link linkend="couchdb-api-db_db-view-cleanup_post">
+ Removes view files that are not used by any design document
+ </link></entry></row></tbody></tgroup></table>
+
+ <para>
+ For all the database methods, the database name within the URL path
+ should be the database name that you wish to perform the operation
+ on. For example, to obtain the meta information for the database
+ <literal moreinfo="none">recipes</literal>, you would use the HTTP request:
+ </para>
+
+<programlisting format="linespecific">GET /recipes</programlisting>
+
+ <para>
+ For clarity, the form below is used in the URL paths:
+ </para>
+
+<programlisting format="linespecific">GET /db</programlisting>
+
+ <para>
+ Where <literal moreinfo="none">db</literal> is the name of any database.
+ </para>
+
+ <section id="couchdb-api-db_db_get">
+
+ <title><literal moreinfo="none">GET /db</literal></title>
+
+ <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<informaltable><textobject><phrase>URL API GET /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo">
+ None
+ </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo">
+ Information about the database in JSON format
+ </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo">
+ The requested content could not be found. The returned content
+ will include further information, as a JSON object, if available.
+ </entry></row></tbody></tgroup></informaltable>
+
+ <para>
+ Gets information about the specified database. For example, to
+ retrieve the information for the database
+ <literal moreinfo="none">recipe</literal>:
+ </para>
+
+<programlisting role="httprequest" format="linespecific">GET http://couchdb:5984/recipes
+Accept: application/json</programlisting>
+
+ <para>
+ The JSON response contains meta information about the database. A
+ sample of the JSON returned for an empty database is provided
+ below:
+ </para>
+
+<programlisting role="httpresponse" format="linespecific">{
+ "compact_running" : false,
+ "committed_update_seq" : 375048,
+ "disk_format_version" : 5,
+ "disk_size" : 33153123,
+ "doc_count" : 18386,
+ "doc_del_count" : 0,
+ "db_name" : "recipes",
+ "instance_start_time" : "1290700340925570",
+ "purge_seq" : 10,
+ "update_seq" : 375048
+}</programlisting>
+
+ <para>
+ The elements of the returned structure are shown in the table
+ below:
+ </para>
+
+ <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//json/json.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<table id="table-couchdb-api-db-json-db-info" class="jsonstructure"><title>
+ CouchDB database information object
+ </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">committed_update_seq</literal> </entry><entry>
+ The number of committed update.
+ </entry></row><row><entry><literal moreinfo="none">compact_running</literal> </entry><entry>
+ Set to true if the database compaction routine is operating on
+ this database.
+ </entry></row><row><entry><literal moreinfo="none">db_name</literal> </entry><entry>
+ The name of the database.
+ </entry></row><row><entry><literal moreinfo="none">disk_format_version</literal> </entry><entry>
+ The version of the physical format used for the data when it is
+ stored on disk.
+ </entry></row><row><entry><literal moreinfo="none">disk_size</literal> </entry><entry>
+ Size in bytes of the data as stored on the disk. Views indexes
+ are not included in the calculation.
+ </entry></row><row><entry><literal moreinfo="none">doc_count</literal> </entry><entry>
+ A count of the documents in the specified database.
+ </entry></row><row><entry><literal moreinfo="none">doc_del_count</literal> </entry><entry>
+ Number of deleted documents
+ </entry></row><row><entry><literal moreinfo="none">instance_start_time</literal> </entry><entry>
+ Timestamp of when the database was created, expressed in
+ milliseconds since the epoch.
+ </entry></row><row><entry><literal moreinfo="none">purge_seq</literal> </entry><entry>
+ The number of purge operations on the database.
+ </entry></row><row><entry><literal moreinfo="none">update_seq</literal> </entry><entry>
+ The current number of updates to the database.
+ </entry></row></tbody></tgroup></table>
+
+ </section>
+
+ <section id="couchdb-api-db_db_put">
+
+ <title><literal moreinfo="none">PUT /db</literal></title>
+
+ <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<informaltable><textobject><phrase>URL API PUT /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo">
+ None
+ </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo">
+ JSON success statement
+ </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo">
+ Invalid database name
+ </entry></row><row><entry>412</entry><entry namest="info" nameend="addinfo">
+ Database already exists
+ </entry></row></tbody></tgroup></informaltable>
+
+ <para>
+ Creates a new database. The database name must be composed of one
+ or more of the following characters:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Lowercase characters (<literal moreinfo="none">a-z</literal>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Name must begin with a lowercase letter
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Digits (<literal moreinfo="none">0-9</literal>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Any of the characters <literal moreinfo="none">_</literal>,
+ <literal moreinfo="none">$</literal>, <literal moreinfo="none">(</literal>,
+ <literal moreinfo="none">)</literal>, <literal moreinfo="none">+</literal>,
+ <literal moreinfo="none">-</literal>, and <literal moreinfo="none">/</literal>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Trying to create a database that does not meet these requirements
+ will return an error quoting these restrictions.
+ </para>
+
+ <para>
+ To create the database <literal moreinfo="none">recipes</literal>:
+ </para>
+
+<programlisting format="linespecific">PUT http://couchdb:5984/recipes
+Content-Type: application/json</programlisting>
+
+ <para>
+ The returned content contains the JSON status:
+ </para>
+
+<programlisting format="linespecific">{
+ "ok" : true
+}</programlisting>
+
+ <para>
+ Anything should be treated as an error, and the problem should be
+ taken form the HTTP response code.
+ </para>
+
+ </section>
+
+ <section id="couchdb-api-db_db_delete">
+
+ <title><literal moreinfo="none">DELETE /db</literal></title>
+
+ <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<rem
<TRUNCATED>