From commits-return-8723-apmail-couchdb-commits-archive=couchdb.apache.org@couchdb.apache.org Fri Sep 14 10:17:42 2012 Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id AB985DFC6 for ; Fri, 14 Sep 2012 10:17:41 +0000 (UTC) Received: (qmail 95112 invoked by uid 500); 14 Sep 2012 10:17:28 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 93992 invoked by uid 500); 14 Sep 2012 10:17:17 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 91037 invoked by uid 99); 14 Sep 2012 10:17:00 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 14 Sep 2012 10:17:00 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id ACF8036843; Fri, 14 Sep 2012 10:16:59 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: dch@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [19/49] Clean up imported .rst Message-Id: <20120914101659.ACF8036843@tyr.zones.apache.org> Date: Fri, 14 Sep 2012 10:16:59 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/api/misc.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/api/misc.rst b/share/sphinx-docs/api/misc.rst new file mode 100644 index 0000000..b2e2684 --- /dev/null +++ b/share/sphinx-docs/api/misc.rst @@ -0,0 +1,793 @@ +.. _api-misc: + +===================== +Miscellaneous Methods +===================== + +The CouchDB Miscellaneous interface provides the basic interface to a +CouchDB server for obtaining CouchDB information and getting and setting +configuration information. + +A list of the available methods and URL paths are provided below: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | / | Get the welcome message and version | +| | | information | ++--------+-------------------------+-------------------------------------------+ +| GET | /_active_tasks | Obtain a list of the tasks running in the| +| | | server | ++--------+-------------------------+-------------------------------------------+ +| GET | /_all_dbs | Get a list of all the DBs | ++--------+-------------------------+-------------------------------------------+ +| GET | /_log | Return the server log file | ++--------+-------------------------+-------------------------------------------+ +| POST | /_replicate | Set or cancel replication | ++--------+-------------------------+-------------------------------------------+ +| POST | /_restart | Restart the server | ++--------+-------------------------+-------------------------------------------+ +| GET | /_stats | Return server statistics | ++--------+-------------------------+-------------------------------------------+ +| GET | /_utils | CouchDB administration interface (Futon) | ++--------+-------------------------+-------------------------------------------+ +| GET | /_uuids | Get generated UUIDs from the server | ++--------+-------------------------+-------------------------------------------+ +| GET | /favicon.ico | Get the site icon | ++--------+-------------------------+-------------------------------------------+ + +``GET /`` +========= + +* **Method**: ``GET /`` +* **Request**: None +* **Response**: Welcome message and version +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + +Accessing the root of a CouchDB instance returns meta information about +the instance. The response is a JSON structure containing information +about the server, including a welcome message and the version of the +server. + +.. code-block:: javascript + + { + "couchdb" : "Welcome", + "version" : "1.0.1" + } + +.. _active-tasks: + +``GET /_active_tasks`` +====================== + +* **Method**: ``GET /_active_tasks`` +* **Request**: None +* **Response**: List of running tasks, including the task type, name, status + and process ID +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +You can obtain a list of active tasks by using the ``/_active_tasks`` +URL. The result is a JSON array of the currently running tasks, with +each task being described with a single object. For example: + +.. code-block:: javascript + + [ + { + "pid" : "<0.11599.0>", + "status" : "Copied 0 of 18369 changes (0%)", + "task" : "recipes", + "type" : "Database Compaction" + } + ] + +The returned structure includes the following fields for each task: + +* **tasks** [array]: Active Task + + * **pid**:Process ID + * **status**: Task status message + * **task**: Task name + * **type**: Operation Type + +For operation type, valid values include: + +- ``Database Compaction`` + +- ``Replication`` + +- ``View Group Compaction`` + +- ``View Group Indexer`` + +``GET /_all_dbs`` +================= + +* **Method**: ``GET /_all_dbs`` +* **Request**: None +* **Response**: JSON list of DBs +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + +Returns a list of all the databases in the CouchDB instance. For +example: + +.. code-block:: http + + GET http://couchdb:5984/_all_dbs + Accept: application/json + +The return is a JSON array: + +.. code-block:: javascript + + [ + "_users", + "contacts", + "docs", + "invoices", + "locations" + ] + +``GET /_log`` +============= + +* **Method**: ``GET /_log`` +* **Request**: None +* **Response**: Log content +* **Admin Privileges Required**: yes +* **Query Arguments**: + + * **Argument**: bytes + + * **Description**: Bytes to be returned + * **Optional**: yes + * **Type**: numeric + * **Default**: 1000 + + * **Argument**: offset + + * **Description**: Offset in bytes where the log tail should be started + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + +* **Return Codes**: + + * **200**: + Request completed successfully. + +Gets the CouchDB log, equivalent to accessing the local log file of the +corresponding CouchDB instance. + +When you request the log, the response is returned as plain (UTF-8) +text, with an HTTP ``Content-type`` header as ``text/plain``. + +For example, the request: + +.. code-block:: http + + GET http://couchdb:5984/_log + Accept: */* + +The raw text is returned: + +.. code-block:: text + + [Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401 + [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200 + [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200 + [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200 + [Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200 + +If you want to pick out specific parts of the log information you can +use the ``bytes`` argument, which specifies the number of bytes to be +returned, and ``offset``, which specifies where the reading of the log +should start, counted back from the end. For example, if you use the +following request: + +.. code-block:: http + + GET /_log?bytes=500&offset=2000 + +Reading of the log will start at 2000 bytes from the end of the log, and +500 bytes will be shown. + +.. _replicate: + +``POST /_replicate`` +==================== + +.. todo:: POST /_replicate :: what response is? + +* **Method**: ``POST /_replicate`` +* **Request**: Replication specification +* **Response**: TBD +* **Admin Privileges Required**: yes +* **Query Arguments**: + + * **Argument**: bytes + + * **Description**: Bytes to be returned + * **Optional**: yes + * **Type**: numeric + * **Default**: 1000 + + * **Argument**: offset + + * **Description**: Offset in bytes where the log tail should be started + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + +* **Return Codes**: + + * **200**: + Replication request successfully completed + * **202**: + Continuous replication request has been accepted + * **404**: + Either the source or target DB is not found + * **500**: + JSON specification was invalid + +Request, configure, or stop, a replication operation. + +The specification of the replication request is controlled through the +JSON content of the request. The JSON should be an object with the +fields defining the source, target and other options. The fields of the +JSON request are shown in the table below: + +* **cancel (optional)**: Cancels the replication +* **continuous (optional)**: Configure the replication to be continuous +* **create_target (optional)**: Creates the target database +* **doc_ids (optional)**: Array of document IDs to be synchronized +* **proxy (optional)**: Address of a proxy server through which replication + should occur +* **source**: Source database name or URL +* **target**: Target database name or URL + +Replication Operation +--------------------- + +The aim of the replication is that at the end of the process, all active +documents on the source database are also in the destination database +and all documents that were deleted in the source databases are also +deleted (if they exist) on the destination database. + +Replication can be described as either push or pull replication: + +- *Pull replication* is where the ``source`` is the remote CouchDB + instance, and the ``destination`` is the local database. + + Pull replication is the most useful solution to use if your source + database has a permanent IP address, and your destination (local) + database may have a dynamically assigned IP address (for example, + through DHCP). This is particularly important if you are replicating + to a mobile or other device from a central server. + +- *Push replication* is where the ``source`` is a local database, and + ``destination`` is a remote database. + +Specifying the Source and Target Database +----------------------------------------- + +You must use the URL specification of the CouchDB database if you want +to perform replication in either of the following two situations: + +- Replication with a remote database (i.e. another instance of CouchDB + on the same host, or a different host) + +- Replication with a database that requires authentication + +For example, to request replication between a database local to the +CouchDB instance to which you send the request, and a remote database +you might use the following request: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "source" : "recipes", + "target" : "http://coucdb-remote:5984/recipes", + } + + +In all cases, the requested databases in the ``source`` and ``target`` +specification must exist. If they do not, an error will be returned +within the JSON object: + +.. code-block:: javascript + + { + "error" : "db_not_found" + "reason" : "could not open http://couchdb-remote:5984/ol1ka/", + } + +You can create the target database (providing your user credentials +allow it) by adding the ``create_target`` field to the request object: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "create_target" : true + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + } + +The ``create_target`` field is not destructive. If the database already +exists, the replication proceeds as normal. + +Single Replication +------------------ + +You can request replication of a database so that the two databases can +be synchronized. By default, the replication process occurs one time and +synchronizes the two databases together. For example, you can request a +single synchronization between two databases by supplying the ``source`` +and ``target`` fields within the request JSON content. + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "source" : "recipes", + "target" : "recipes-snapshot", + } + +In the above example, the databases ``recipes`` and ``recipes-snapshot`` +will be synchronized. These databases are local to the CouchDB instance +where the request was made. The response will be a JSON structure +containing the success (or failure) of the synchronization process, and +statistics about the process: + +.. code-block:: javascript + + { + "ok" : true, + "history" : [ + { + "docs_read" : 1000, + "session_id" : "52c2370f5027043d286daca4de247db0", + "recorded_seq" : 1000, + "end_last_seq" : 1000, + "doc_write_failures" : 0, + "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT", + "start_last_seq" : 0, + "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT", + "missing_checked" : 0, + "docs_written" : 1000, + "missing_found" : 1000 + } + ], + "session_id" : "52c2370f5027043d286daca4de247db0", + "source_last_seq" : 1000 + } + +The structure defines the replication status, as described in the table +below: + +* **history [array]**: Replication History + + * **doc_write_failures**: Number of document write failures + * **docs_read**: Number of documents read + * **docs_written**: Number of documents written to target + * **end_last_seq**: Last sequence number in changes stream + * **end_time**: Date/Time replication operation completed + * **missing_checked**: Number of missing documents checked + * **missing_found**: Number of missing documents found + * **recorded_seq**: Last recorded sequence number + * **session_id**: Session ID for this replication operation + * **start_last_seq**: First sequence number in changes stream + * **start_time**: Date/Time replication operation started + +* **ok**: Replication status +* **session_id**: Unique session ID +* **source_last_seq**: Last sequence number read from source database + +Continuous Replication +---------------------- + +Synchronization of a database with the previously noted methods happens +only once, at the time the replicate request is made. To have the target +database permanently replicated from the source, you must set the +``continuous`` field of the JSON object within the request to true. + +With continuous replication changes in the source database are +replicated to the target database in perpetuity until you specifically +request that replication ceases. + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "continuous" : true + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + } + +Changes will be replicated between the two databases as long as a +network connection is available between the two instances. + +.. note:: + Two keep two databases synchronized with each other, you need to set + replication in both directions; that is, you must replicate from + ``databasea`` to ``databaseb``, and separately from ``databaseb`` to + ``databasea``. + +Canceling Continuous Replication +-------------------------------- + +You can cancel continuous replication by adding the ``cancel`` field to +the JSON request object and setting the value to true. Note that the +structure of the request must be identical to the original for the +cancellation request to be honoured. For example, if you requested +continuous replication, the cancellation request must also contain the +``continuous`` field. + +For example, the replication request: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + "create_target" : true, + "continuous" : true + } + +Must be canceled using the request: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "cancel" : true, + "continuous" : true + "create_target" : true, + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + } + +Requesting cancellation of a replication that does not exist results in +a 404 error. + +``POST /_restart`` +================== + +* **Method**: ``POST /_restart`` +* **Request**: None +* **Response**: JSON status message +* **Admin Privileges Required**: yes +* **HTTP Headers**: + + * **Header**: ``Content-Type`` + + * **Description**: Request content type + * **Optional**: no + * **Value**: :mimetype:`application/json` + +* **Return Codes**: + + * **200**: + Replication request successfully completed + +Restarts the CouchDB instance. You must be authenticated as a user with +administration privileges for this to work. + +For example: + +.. code-block:: http + + POST http://admin:password@couchdb:5984/_restart + +The return value (if the server has not already restarted) is a JSON +status object indicating that the request has been received: + +.. code-block:: javascript + + { + "ok" : true, + } + +If the server has already restarted, the header may be returned, but no +actual data is contained in the response. + +``GET /_stats`` +=============== + +* **Method**: ``GET /_stats`` +* **Request**: None +* **Response**: Server statistics +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + +The ``_stats`` method returns a JSON object containing the statistics +for the running server. The object is structured with top-level sections +collating the statistics for a range of entries, with each individual +statistic being easily identified, and the content of each statistic is +self-describing. For example, the request time statistics, within the +``couchdb`` section are structured as follows: + +.. code-block:: javascript + + { + "couchdb" : { + ... + "request_time" : { + "stddev" : "27.509", + "min" : "0.333333333333333", + "max" : "152", + "current" : "400.976", + "mean" : "10.837", + "sum" : "400.976", + "description" : "length of a request inside CouchDB without MochiWeb" + }, + ... + } + } + + +The fields provide the current, minimum and maximum, and a collection of +statistical means and quantities. The quantity in each case is not +defined, but the descriptions below provide + +The statistics are divided into the following top-level sections: + +- ``couchdb``: Describes statistics specific to the internals of CouchDB. + + +-------------------------+-------------------------------------------------------+----------------+ + | Statistic ID | Description | Unit | + +=========================+=======================================================+================+ + | ``auth_cache_hits`` | Number of authentication cache hits | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``auth_cache_misses`` | Number of authentication cache misses | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``database_reads`` | Number of times a document was read from a database | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``database_writes`` | Number of times a database was changed | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``open_databases`` | Number of open databases | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``open_os_files`` | Number of file descriptors CouchDB has open | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``request_time`` | Length of a request inside CouchDB without MochiWeb | milliseconds | + +-------------------------+-------------------------------------------------------+----------------+ + +- ``httpd_request_methods`` + + +----------------+----------------------------------+----------+ + | Statistic ID | Description | Unit | + +================+==================================+==========+ + | ``COPY`` | Number of HTTP COPY requests | number | + +----------------+----------------------------------+----------+ + | ``DELETE`` | Number of HTTP DELETE requests | number | + +----------------+----------------------------------+----------+ + | ``GET`` | Number of HTTP GET requests | number | + +----------------+----------------------------------+----------+ + | ``HEAD`` | Number of HTTP HEAD requests | number | + +----------------+----------------------------------+----------+ + | ``POST`` | Number of HTTP POST requests | number | + +----------------+----------------------------------+----------+ + | ``PUT`` | Number of HTTP PUT requests | number | + +----------------+----------------------------------+----------+ + +- ``httpd_status_codes`` + + +----------------+------------------------------------------------------+----------+ + | Statistic ID | Description | Unit | + +================+======================================================+==========+ + | ``200`` | Number of HTTP 200 OK responses | number | + +----------------+------------------------------------------------------+----------+ + | ``201`` | Number of HTTP 201 Created responses | number | + +----------------+------------------------------------------------------+----------+ + | ``202`` | Number of HTTP 202 Accepted responses | number | + +----------------+------------------------------------------------------+----------+ + | ``301`` | Number of HTTP 301 Moved Permanently responses | number | + +----------------+------------------------------------------------------+----------+ + | ``304`` | Number of HTTP 304 Not Modified responses | number | + +----------------+------------------------------------------------------+----------+ + | ``400`` | Number of HTTP 400 Bad Request responses | number | + +----------------+------------------------------------------------------+----------+ + | ``401`` | Number of HTTP 401 Unauthorized responses | number | + +----------------+------------------------------------------------------+----------+ + | ``403`` | Number of HTTP 403 Forbidden responses | number | + +----------------+------------------------------------------------------+----------+ + | ``404`` | Number of HTTP 404 Not Found responses | number | + +----------------+------------------------------------------------------+----------+ + | ``405`` | Number of HTTP 405 Method Not Allowed responses | number | + +----------------+------------------------------------------------------+----------+ + | ``409`` | Number of HTTP 409 Conflict responses | number | + +----------------+------------------------------------------------------+----------+ + | ``412`` | Number of HTTP 412 Precondition Failed responses | number | + +----------------+------------------------------------------------------+----------+ + | ``500`` | Number of HTTP 500 Internal Server Error responses | number | + +----------------+------------------------------------------------------+----------+ + +- ``httpd`` + + +----------------------------------+----------------------------------------------+----------+ + | Statistic ID | Description | Unit | + +==================================+==============================================+==========+ + | ``bulk_requests`` | Number of bulk requests | number | + +----------------------------------+----------------------------------------------+----------+ + | ``clients_requesting_changes`` | Number of clients for continuous _changes | number | + +----------------------------------+----------------------------------------------+----------+ + | ``requests`` | Number of HTTP requests | number | + +----------------------------------+----------------------------------------------+----------+ + | ``temporary_view_reads`` | Number of temporary view reads | number | + +----------------------------------+----------------------------------------------+----------+ + | ``view_reads`` | Number of view reads | number | + +----------------------------------+----------------------------------------------+----------+ + +You can also access individual statistics by quoting the statistics +sections and statistic ID as part of the URL path. For example, to get +the ``request_time`` statistics, you can use: + +.. code-block:: http + + GET /_stats/couchdb/request_time + +This returns an entire statistics object, as with the full request, but +containing only the request individual statistic. Hence, the returned +structure is as follows: + +.. code-block:: javascript + + { + "couchdb" : { + "request_time" : { + "stddev" : 7454.305, + "min" : 1, + "max" : 34185, + "current" : 34697.803, + "mean" : 1652.276, + "sum" : 34697.803, + "description" : "length of a request inside CouchDB without MochiWeb" + } + } + } + + +``GET /_utils`` +=============== + +* **Method**: ``GET /_utils`` +* **Request**: None +* **Response**: Administration interface +* **Admin Privileges Required**: no + +Accesses the built-in Futon administration interface for CouchDB. + +``GET /_uuids`` +=============== + +* **Method**: ``GET /_uuids`` +* **Request**: None +* **Response**: List of UUIDs +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: count + + * **Description**: Number of UUIDs to return + * **Optional**: yes + * **Type**: numeric + +* **Return Codes**: + + * **200**: + Request completed successfully. + +Requests one or more Universally Unique Identifiers (UUIDs) from the +CouchDB instance. The response is a JSON object providing a list of +UUIDs. For example: + +.. code-block:: javascript + + { + "uuids" : [ + "7e4b5a14b22ec1cf8e58b9cdd0000da3" + ] + } + +You can use the ``count`` argument to specify the number of UUIDs to be +returned. For example: + +.. code-block:: http + + GET http://couchdb:5984/_uuids?count=5 + +Returns: + +.. code-block:: javascript + + { + "uuids" : [ + "c9df0cdf4442f993fc5570225b405a80", + "c9df0cdf4442f993fc5570225b405bd2", + "c9df0cdf4442f993fc5570225b405e42", + "c9df0cdf4442f993fc5570225b4061a0", + "c9df0cdf4442f993fc5570225b406a20" + ] + } + +The UUID type is determined by the UUID type setting in the CouchDB +configuration. See :ref:`api-put-config`. + +For example, changing the UUID type to ``random``: + +.. code-block:: http + + PUT http://couchdb:5984/_config/uuids/algorithm + Content-Type: application/json + Accept: */* + + "random" + +When obtaining a list of UUIDs: + +.. code-block:: javascript + + { + "uuids" : [ + "031aad7b469956cf2826fcb2a9260492", + "6ec875e15e6b385120938df18ee8e496", + "cff9e881516483911aa2f0e98949092d", + "b89d37509d39dd712546f9510d4a9271", + "2e0dbf7f6c4ad716f21938a016e4e59f" + ] + } + +``GET /favicon.ico`` +==================== + +* **Method**: ``GET /favicon.ico`` +* **Request**: None +* **Response**: Binary content for the `favicon.ico` site icon +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + * **404**: + The requested content could not be found. The returned content will include + further information, as a JSON object, if available. + +Returns the site icon. The return ``Content-Type`` header is +:mimetype:`image/x-icon`, and the content stream is the image data. http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/api/reference.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/api/reference.rst b/share/sphinx-docs/api/reference.rst new file mode 100644 index 0000000..0bbe2cb --- /dev/null +++ b/share/sphinx-docs/api/reference.rst @@ -0,0 +1,16 @@ +API Reference +============= + +Contents: + +.. toctree:: + :maxdepth: 2 + + configuration + authn + database + documents + design + misc + local + dbmaint http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/changes.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/changes.rst b/share/sphinx-docs/changes.rst new file mode 100644 index 0000000..8c7d5c0 --- /dev/null +++ b/share/sphinx-docs/changes.rst @@ -0,0 +1,28 @@ +.. _changes: + +============ +Changes Feed +============ + +  + +Polling +======= + +  + +Long Polling +============ + +  + +Continuous +========== + +  + +Filters +======= + +  + http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/conf.py ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/conf.py b/share/sphinx-docs/conf.py new file mode 100644 index 0000000..b493bc9 --- /dev/null +++ b/share/sphinx-docs/conf.py @@ -0,0 +1,242 @@ +# -*- coding: utf-8 -*- +# +# CouchDB documentation build configuration file, created by +# sphinx-quickstart on Tue Jul 31 20:52:16 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.todo'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'CouchDB' +copyright = u'2012, Developers' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.3.0' +# The full version, including alpha/beta/rc tags. +release = '1.3.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'CouchDBdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'CouchDB.tex', u'CouchDB Documentation', + u'Developers', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'couchdb', u'CouchDB Documentation', + [u'Developers'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'CouchDB', u'CouchDB Documentation', + u'Developers', 'CouchDB', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/configuring.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/configuring.rst b/share/sphinx-docs/configuring.rst new file mode 100644 index 0000000..b87e9e1 --- /dev/null +++ b/share/sphinx-docs/configuring.rst @@ -0,0 +1,490 @@ +.. _configuring: + +=================== +Configuring CouchDB +=================== + +.. todo:: Configuring CouchDB + +CouchDB Configuration Files +=========================== + +.. todo:: CouchDB Configuration Files + +Configuration File Locations +============================ + +CouchDB reads files from the following locations, in the following +order. + +1. ``PREFIX/default.ini`` + +2. ``PREFIX/default.d/*`` + +3. ``PREFIX/local.ini`` + +4. ``PREFIX/local.d/*`` + +Settings in successive documents override the settings in earlier +entries. For example, setting the ``bind_address`` parameter in +``local.ini`` would override any setting in ``default.ini``. + +.. warning:: + The ``default.ini`` file may be overwritten during an upgrade or + re-installation, so localised changes should be made to the + ``local.ini`` file or files within the ``local.d`` directory. + +MochiWeb Server Options +======================= + +Server options for the MochiWeb component of CouchDB can be added to the +configuration files. Settings should be added to the ``server_options`` +option of the ``[httpd]`` section of ``local.ini``. For example: + +.. code-block:: ini + + [httpd] + server_options = [{backlog, 128}, {acceptor_pool_size, 16}] + + +OS Daemons +========== + +CouchDB now supports starting external processes. The support is simple +and enables CouchDB to start each configured OS daemon. If the daemon +stops at any point, CouchDB will restart it (with protection to ensure +regularly failing daemons are not repeatedly restarted). + +The daemon starting process is one-to-one; for each each configured +daemon in the configuration file, CouchDB will start exactly one +instance. If you need to run multiple instances, then you must create +separate individual configurations. Daemons are configured within the +``[os_daemons]`` section of your configuration file (``local.ini``). The +format of each configured daemon is: + +.. code-block:: ini + + NAME = PATH ARGS + +Where ``NAME`` is an arbitrary (and unique) name to identify the daemon; +``PATH`` is the full path to the daemon to be executed; ``ARGS`` are any +required arguments to the daemon. + +For example: + +.. code-block:: ini + + [os_daemons] + basic_responder = /usr/local/bin/responsder.js + +There is no interactivity between CouchDB and the running process, but +you can use the OS Daemons service to create new HTTP servers and +responders and then use the new proxy service to redirect requests and +output to the CouchDB managed service. For more information on proxying, +see :ref:`proxying`. For further background on the OS Daemon service, see +`CouchDB Externals API`_. + +.. _update-notifications: + +Update Notifications +==================== + +.. todo:: Update Notifications + +Socket Options Configuration Setting +==================================== + +The socket options for the listening socket in CouchDB can now be set +within the CouchDB configuration file. The setting should be added to +the ``[httpd]`` section of the file using the option name +``socket_options``. The specification is as a list of tuples. For +example: + +.. code-block:: ini + + [httpd] + socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}] + +The options supported are a subset of full options supported by the +TCP/IP stack. A list of the supported options are provided in the +`Erlang inet`_ documentation. + +``vhosts`` definitions +====================== + +Similar to the rewrites section of a ``_design`` document, the +``vhosts`` system uses variables in the form of ``:varname`` or wildcards in +the form of asterisks. The variable results can be output into the +resulting path as they are in the rewriter. + +Configuring SSL Network Sockets +=============================== + +SSL configuration in CouchDB was designed to be as easy as possible. All +you need is two files; a certificate and a private key. If you bought an +official SSL certificate from a certificate authority, both should be in +your possession already. + +If you just want to try this out and don't want to pay anything upfront, +you can create a self-signed certificate. Everything will work the same, +but clients will get a warning about an insecure certificate. + +You will need the OpenSSL command line tool installed. It probably +already is. + +.. code-block:: bash + + shell> mkdir cert && cd cert + shell> openssl genrsa > privkey.pem + shell> openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095 + shell> ls + mycert.pem privkey.pem + +Now, you need to edit CouchDB's configuration, either by editing your +``local.ini`` file or using the ``/_config`` API calls or the +configuration screen in Futon. Here is what you need to do in +``local.ini``, you can infer what needs doing in the other places. + +Be sure to make these edits. Under ``[daemons]`` you should see: + +.. code-block:: ini + + ; enable SSL support by uncommenting the following line and supply the PEM's below. + ; the default ssl port CouchDB listens on is 6984 + ;httpsd = {couch_httpd, start_link, [https]} + +Here uncomment the last line: + +.. code-block:: ini + + httpsd = {couch_httpd, start_link, [https]} + +Next, under ``[ssl]`` you will see: + +.. code-block:: ini + + ;cert_file = /full/path/to/server_cert.pem + ;key_file = /full/path/to/server_key.pem + +Uncomment and adjust the paths so it matches your system's paths: + +.. code-block:: ini + + cert_file = /home/jan/cert/mycert.pem + key_file = /home/jan/cert/privkey.pem + +For more information please read +`http://www.openssl.org/docs/HOWTO/certificates.txt`_. + +Now start (or restart) CouchDB. You should be able to connect to it +using HTTPS on port 6984: + +.. code-block:: bash + + shell> curl https://127.0.0.1:6984/ + curl: (60) SSL certificate problem, verify that the CA cert is OK. Details: + error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed + More details here: http://curl.haxx.se/docs/sslcerts.html + + curl performs SSL certificate verification by default, using a "bundle" + of Certificate Authority (CA) public keys (CA certs). If the default + bundle file isn't adequate, you can specify an alternate file + using the --cacert option. + If this HTTPS server uses a certificate signed by a CA represented in + the bundle, the certificate verification probably failed due to a + problem with the certificate (it might be expired, or the name might + not match the domain name in the URL). + If you'd like to turn off curl's verification of the certificate, use + the -k (or --insecure) option. + +Oh no what happened?! — Remember, clients will notify their users that +your certificate is self signed. ``curl`` is the client in this case and +it notifies you. Luckily you trust yourself (don't you?) and you can +specify the ``-k`` option as the message reads: + +.. code-block:: bash + + shell> curl -k https://127.0.0.1:6984/ + {"couchdb":"Welcome","version":"1.1.0"} + +.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html +.. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2 +.. _`http://www.openssl.org/docs/HOWTO/certificates.txt`: http://www.openssl.org/docs/HOWTO/certificates.txt + + +Configuration options reference +=============================== + + +Configuration Groups +-------------------- + ++----------------------------------+-------------------------------------------+ +| Section | Description | ++==================================+===========================================+ +| attachments | Attachment options | ++----------------------------------+-------------------------------------------+ +| couchdb | CouchDB specific options | ++----------------------------------+-------------------------------------------+ +| couch_httpd_auth | HTTPD Authentication options | ++----------------------------------+-------------------------------------------+ +| daemons | Daemons and background processes | ++----------------------------------+-------------------------------------------+ +| httpd | HTTPD Server options | ++----------------------------------+-------------------------------------------+ +| httpd_db_handlers | Database Operation handlers | ++----------------------------------+-------------------------------------------+ +| httpd_design_handlers | Handlers for design document operations | ++----------------------------------+-------------------------------------------+ +| httpd_global_handlers | Handlers for global operations | ++----------------------------------+-------------------------------------------+ +| log | Logging options | ++----------------------------------+-------------------------------------------+ +| query_servers | Query Server options | ++----------------------------------+-------------------------------------------+ +| query_server_config | Query server options | ++----------------------------------+-------------------------------------------+ +| replicator | Replicator Options | ++----------------------------------+-------------------------------------------+ +| ssl | SSL (Secure Sockets Layer) Options | ++----------------------------------+-------------------------------------------+ +| stats | Statistics options | ++----------------------------------+-------------------------------------------+ +| uuids | UUID generation options | ++----------------------------------+-------------------------------------------+ + +attachments Configuration Options +--------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| compressible_types | compressible_types | ++--------------------------------------+---------------------------------------+ +| compression_level | compression_level | ++--------------------------------------+---------------------------------------+ + +couchdb Configuration Options +----------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| database_dir | database_dir | ++--------------------------------------+---------------------------------------+ +| delayed_commits | delayed_commits | ++--------------------------------------+---------------------------------------+ +| max_attachment_chunk_size | max_attachment_chunk_size | ++--------------------------------------+---------------------------------------+ +| max_dbs_open | max_dbs_open | ++--------------------------------------+---------------------------------------+ +| max_document_size | max_document_size | ++--------------------------------------+---------------------------------------+ +| os_process_timeout | os_process_timeout | ++--------------------------------------+---------------------------------------+ +| uri_file | uri_file | ++--------------------------------------+---------------------------------------+ +| util_driver_dir | util_driver_dir | ++--------------------------------------+---------------------------------------+ +| view_index_dir | view_index_dir | ++--------------------------------------+---------------------------------------+ + +daemons Configuration Options +----------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| auth_cache | auth_cache | ++--------------------------------------+---------------------------------------+ +| db_update_notifier | db_update_notifier | ++--------------------------------------+---------------------------------------+ +| external_manager | external_manager | ++--------------------------------------+---------------------------------------+ +| httpd | httpd | ++--------------------------------------+---------------------------------------+ +| httpsd | Enabled HTTPS service | ++--------------------------------------+---------------------------------------+ +| query_servers | query_servers | ++--------------------------------------+---------------------------------------+ +| stats_aggregator | stats_aggregator | ++--------------------------------------+---------------------------------------+ +| stats_collector | stats_collector | ++--------------------------------------+---------------------------------------+ +| uuids | uuids | ++--------------------------------------+---------------------------------------+ +| view_manager | view_manager | ++--------------------------------------+---------------------------------------+ + +httpd_db_handlers Configuration Options +--------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| _changes | _changes | ++--------------------------------------+---------------------------------------+ +| _compact | _compact | ++--------------------------------------+---------------------------------------+ +| _design | _design | ++--------------------------------------+---------------------------------------+ +| _temp_view | _temp_view | ++--------------------------------------+---------------------------------------+ +| _view_cleanup | _view_cleanup | ++--------------------------------------+---------------------------------------+ + +couch_httpd_auth Configuration Options +-------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| auth_cache_size | auth_cache_size | ++--------------------------------------+---------------------------------------+ +| authentication_db | authentication_db | ++--------------------------------------+---------------------------------------+ +| authentication_redirect | authentication_redirect | ++--------------------------------------+---------------------------------------+ +| require_valid_user | require_valid_user | ++--------------------------------------+---------------------------------------+ +| timeout | timeout | ++--------------------------------------+---------------------------------------+ + +httpd Configuration Options +--------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| allow_jsonp | allow_jsonp | ++--------------------------------------+---------------------------------------+ +| authentication_handlers | authentication_handlers | ++--------------------------------------+---------------------------------------+ +| bind_address | bind_address | ++--------------------------------------+---------------------------------------+ +| default_handler | default_handler | ++--------------------------------------+---------------------------------------+ +| max_connections | max_connections | ++--------------------------------------+---------------------------------------+ +| nodelay | Enable TCP_NODELAY | ++--------------------------------------+---------------------------------------+ +| port | port | ++--------------------------------------+---------------------------------------+ +| secure_rewrites | secure_rewrites | ++--------------------------------------+---------------------------------------+ +| vhost_global_handlers | vhost_global_handlers | ++--------------------------------------+---------------------------------------+ + +httpd_design_handlers Configuration Options +------------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| _info | _info | ++--------------------------------------+---------------------------------------+ +| _list | _list | ++--------------------------------------+---------------------------------------+ +| _rewrite | _rewrite | ++--------------------------------------+---------------------------------------+ +| _show | _show | ++--------------------------------------+---------------------------------------+ +| _update | _update | ++--------------------------------------+---------------------------------------+ +| _view | _view | ++--------------------------------------+---------------------------------------+ + +httpd_global_handlers Configuration Options +------------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| / | / | ++--------------------------------------+---------------------------------------+ +| _active_tasks | _active_tasks | ++--------------------------------------+---------------------------------------+ +| _all_dbs | _all_dbs | ++--------------------------------------+---------------------------------------+ +| _config | _config | ++--------------------------------------+---------------------------------------+ +| _log | _log | ++--------------------------------------+---------------------------------------+ +| _oauth | _oauth | ++--------------------------------------+---------------------------------------+ +| _replicate | _replicate | ++--------------------------------------+---------------------------------------+ +| _restart | _restart | ++--------------------------------------+---------------------------------------+ +| _session | _session | ++--------------------------------------+---------------------------------------+ +| _stats | _stats | ++--------------------------------------+---------------------------------------+ +| _utils | _utils | ++--------------------------------------+---------------------------------------+ +| _uuids | _uuids | ++--------------------------------------+---------------------------------------+ +| favicon.ico | favicon.ico | ++--------------------------------------+---------------------------------------+ + +log Configuration Options +------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| file | file | ++--------------------------------------+---------------------------------------+ +| include_sasl | include_sasl | ++--------------------------------------+---------------------------------------+ +| level | level | ++--------------------------------------+---------------------------------------+ + +query_servers Configuration Options +----------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| javascript | javascript | ++--------------------------------------+---------------------------------------+ + +query_server_config Configuration Options +----------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| reduce_limit | reduce_limit | ++--------------------------------------+---------------------------------------+ + +replicator Configuration Options +-------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| max_http_pipeline_size | max_http_pipeline_size | ++--------------------------------------+---------------------------------------+ +| max_http_sessions | max_http_sessions | ++--------------------------------------+---------------------------------------+ + +stats Configuration Options +--------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| rate | rate | ++--------------------------------------+---------------------------------------+ +| samples | samples | ++--------------------------------------+---------------------------------------+ + +uuids Configuration Options +--------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| algorithm | algorithm | ++--------------------------------------+---------------------------------------+ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/features.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/features.rst b/share/sphinx-docs/features.rst new file mode 100644 index 0000000..3c4a344 --- /dev/null +++ b/share/sphinx-docs/features.rst @@ -0,0 +1,191 @@ +========================== +Features and Functionality +========================== + +  + +HTTP Range Requests +=================== + +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. + +.. code-block:: bash + + shell> cat file.txt + My hovercraft is full of eels! + +Uploading this as an attachment to a ``text`` database using ``curl``: + +.. code-block:: bash + + shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \ + -H "Content-Type: application/octet-stream" -d@file.txt + {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"} + +Requesting the whole file works as normal: + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt + My hovercraft is full of eels! + +But to retrieve only the first 13 bytes using ``curl``: + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \ + -H "Range: bytes=0-12" + My hovercraft + +HTTP supports many ways to specify single and even multiple byte +rangers. See `RFC 2616`_. + +.. note:: + 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. + +.. _proxying: + +HTTP Proxying +============= + +The HTTP proxy feature makes it easy to map and redirect different +content through your CouchDB URL. The proxy works by mapping a path name +and passing all content after that prefix through to the configured +proxy address. + +Configuration of the proxy redirect is handled through the +``[httpd_global_handlers]`` section of the CouchDB configuration file +(typically ``local.ini``). The format is: + +.. code-block:: ini + + [httpd_global_handlers] + PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>} + +Where: + +- ``PREFIX`` + + 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. + +- ``DESTINATION`` + + The fully-qualified URL to which the request should be sent. The + destination must include the ``http`` 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. + +The proxy process then translates requests of the form: + +.. code-block:: text + + http://couchdb:5984/PREFIX/path + +To: + +.. code-block:: text + + DESTINATION/path + +.. note:: + Everything after ``PREFIX`` including the required forward slash + will be appended to the ``DESTINATION``. + +The response is then communicated back to the original client. + +For example, the following configuration: + +.. code-block:: ini + + _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>} + +Would forward all requests for ``http://couchdb:5984/_google`` to the +Google website. + +The service can also be used to forward to related CouchDB services, +such as Lucene: + +.. code-block:: ini + + [httpd_global_handlers] + _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>} + +.. note:: + The proxy service is basic. If the request is not identified by the + ``DESTINATION``, or the remainder of the ``PATH`` specification is + incomplete, the original request URL is interpreted as if the + ``PREFIX`` component of that URL does not exist. + + For example, requesting ``http://couchdb:5984/_intranet/media`` when + ``/media`` on the proxy destination does not exist, will cause the + request URL to be interpreted as ``http://couchdb:5984/media``. Care + should be taken to ensure that both requested URLs and destination + URLs are able to cope. + +CommonJS support for map functions +================================== + +CommonJS support allows you to use CommonJS notation inside map and +reduce functions, but only of libraries that are stored inside the views +part of the design doc. + +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 ``design_doc.views.lib``. + +There's no worry here about namespace collisions, as Couch just plucks +``views.*.map`` and ``views.*.reduce`` out of the design doc. So you +could have a view called ``lib`` if you wanted, and still have CommonJS +stored in ``views.lib.sha1`` and ``views.lib.stemmer`` if you wanted. + +The implementation is simplified by enforcing that CommonJS modules to +be used in map functions be stored in views.lib. + +A sample design doc (taken from the test suite in Futon) is below: + +.. code-block:: javascript + + { + "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" + } + +The ``require()`` statement is relative to the design document, but +anything loaded form outside of ``views/lib`` will fail. + +Granular ETag support +===================== + +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. + +In CouchDB 1.1 each ``_view`` 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). + +.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27 http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/images/futon-createdb.png ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/images/futon-createdb.png b/share/sphinx-docs/images/futon-createdb.png new file mode 100644 index 0000000..c8c1b9d Binary files /dev/null and b/share/sphinx-docs/images/futon-createdb.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/images/futon-editdoc.png ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/images/futon-editdoc.png b/share/sphinx-docs/images/futon-editdoc.png new file mode 100644 index 0000000..6802c2c Binary files /dev/null and b/share/sphinx-docs/images/futon-editdoc.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/images/futon-editeddoc.png ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/images/futon-editeddoc.png b/share/sphinx-docs/images/futon-editeddoc.png new file mode 100644 index 0000000..5c8b549 Binary files /dev/null and b/share/sphinx-docs/images/futon-editeddoc.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/images/futon-overview.png ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/images/futon-overview.png b/share/sphinx-docs/images/futon-overview.png new file mode 100644 index 0000000..d1eac6e Binary files /dev/null and b/share/sphinx-docs/images/futon-overview.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/images/futon-replform.png ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/images/futon-replform.png b/share/sphinx-docs/images/futon-replform.png new file mode 100644 index 0000000..d904f0d Binary files /dev/null and b/share/sphinx-docs/images/futon-replform.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/index.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/index.rst b/share/sphinx-docs/index.rst new file mode 100644 index 0000000..dbc84df --- /dev/null +++ b/share/sphinx-docs/index.rst @@ -0,0 +1,31 @@ +.. CouchDB documentation master file, created by + sphinx-quickstart on Tue Jul 31 20:52:16 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to CouchDB's documentation! +=================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + features + api-basics + configuring + replication + views + changes + 1.1/index + api/reference + json-structure + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/intro.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/intro.rst b/share/sphinx-docs/intro.rst new file mode 100644 index 0000000..930ab2c --- /dev/null +++ b/share/sphinx-docs/intro.rst @@ -0,0 +1,300 @@ +============ +Introduction +============ + +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 :ref:`using-futon`. + +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. + +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 ``curl``. See +:ref:`using-curl`. + +.. _using-futon: + +Using Futon +=========== + +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. + +The default view is the Overview 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: + +.. figure:: images/futon-overview.png + :align: center + :alt: Futon Overview + + Futon Overview + +The main sections are: + +- Overview + + 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 :ref:`futon-management`. + +- Configuration + + 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 :ref:`configuring`. + +- Replicator + + An interface to the replication system, enabling you to initiate + replication between local and remote databases. See + :ref:`futon-replication`. + +- Status + + Displays a list of the running background tasks on the server. + Background tasks include view index building, compaction and + replication. The Status page is an interface to the + :ref:`Active Tasks ` API call. + +- Verify Installation + + The Verify Installation allows you to check whether all of the + components of your CouchDB installation are correctly installed. + +- Test Suite + + The Test Suite 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 Run All + button. This will execute all the tests, which may take some time. + +.. _futon-management: + +Managing Databases and Documents +-------------------------------- + +You can manage databases and documents within Futon using the main +Overview section of the Futon interface. + +To create a new database, click the Create Database ELLIPSIS button. You +will be prompted for the database name, as shown in the figure below. + +.. figure:: images/futon-createdb.png + :align: center + :alt: Creating a Database + + Creating a Database + +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. + +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. + +For example, the figure below shows the editor for a single document, a +newly created document with a single ID, the document ``_id`` field. + +.. figure:: images/futon-editdoc.png + :align: center + :alt: Editing a Document + + Editing a Document + +To add a field to the document: + +1. Click Add Field. + +2. In the fieldname box, enter the name of the field you want to create. + For example, “company”. + +3. Click the green tick next to the field name to confirm the field name + change. + +4. Double-click the corresponding Value cell. + +5. Enter a company name, for example “Example”. + +6. Click the green tick next to the field value to confirm the field + value. + +7. The document is still not saved as this point. You must explicitly + save the document by clicking the Save Document button at the top of + the page. This will save the document, and then display the new + document with the saved revision information (the ``_rev`` field). + + .. figure:: images/futon-editeddoc.png + :align: center + :alt: Edited Document + + Edited Document + +The same basic interface is used for all editing operations within Futon. +You *must* remember to save the individual element (fieldname, value) +using the green tick button, before then saving the document. + +.. _futon-replication: + +Configuring Replication +----------------------- + +When you click the Replicator option within the Tools 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. + +.. figure:: images/futon-replform.png + :align: center + :alt: Replication Form + + Replication Form + +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. + +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 +``http://username:pass@remotehost:5984/demo``. + +To enable continuous replication, click the Continuous checkbox. + +To start the replication process, click the Replicate 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 Status option under the Tools menu. + +Once replication has been completed, the page will show the information +returned when the replication process completes by the API. + +The Replicator tool is an interface to the underlying replication API. +For more information, see :ref:`replicate`. For more information on +replication, see :ref:`replication`. + +.. _using-curl: + +Using ``curl`` +============== + +The ``curl`` utility is a command line tool available on Unix, Linux, +Mac OS X and Windows and many other platforms. ``curl`` 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. + +For simple ``GET`` requests you can supply the URL of the request. For +example, to get the database information: + +.. code-block:: bash + + shell> curl http://127.0.0.1:5984 + +This returns the database information (formatted in the output below for +clarity): + +.. code-block:: javascript + + { + "modules" : { + "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f" + }, + "couchdb" : "Welcome", + "version" : "1.1.0", + } + +.. note:: 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: + + .. code-block:: bash + + shell> curl 'http://couchdb:5984/_uuids?count=5' + +You can explicitly set the HTTP command using the ``-X`` 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: + +.. code-block:: bash + + shell> curl -X PUT http://127.0.0.1:5984/demo + {"ok":true} + +But to obtain the database information you use a ``GET`` request (with +the return information formatted for clarity): + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/demo + { + "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 + } + +For certain operations, you must specify the content type of request, +which you do by specifying the ``Content-Type`` header using the ``-H`` +command-line option: + +.. code-block:: bash + + shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids + +You can also submit 'payload' data, that is, data in the body of the +HTTP request using the ``-d`` 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 ``demo`` +database: + +.. code-block:: bash + + shell> curl -H 'Content-Type: application/json' \ + -X POST http://127.0.0.1:5984/demo \ + -d '{"company": "Example, Inc."}' + {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8", + "rev":"1-33b9fbce46930280dab37d672bbc8bb9"} + +In the above example, the argument after the ``-d`` option is the JSON +of the document we want to submit. + +The document can be accessed by using the automatically generated +document ID that was returned: + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8 + {"_id":"8843faaf0b831d364278331bc3001bd8", + "_rev":"1-33b9fbce46930280dab37d672bbc8bb9", + "company":"Example, Inc."} + +The API samples in the :ref:`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 ``curl`` with the +command-line examples shown above.