You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by dc...@apache.org on 2012/12/03 14:33:19 UTC
[25/33] Transmogrify Couchbase XML to .rst and support Sphinx
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/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
deleted file mode 100644
index 8667927..0000000
--- a/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
+++ /dev/null
@@ -1,9409 +0,0 @@
-<?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"/>
-
<TRUNCATED>