http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/json-structure.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/json-structure.rst b/share/doc/src/json-structure.rst new file mode 100644 index 0000000..b0a88b5 --- /dev/null +++ b/share/doc/src/json-structure.rst @@ -0,0 +1,413 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +======================== +JSON Structure Reference +======================== + +The following appendix provides a quick reference to all the JSON structures +that you can supply to CouchDB, or get in return to requests. + +All Database Documents +====================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| total_rows | Number of documents in the database/view | ++--------------------------------+---------------------------------------------+ +| offset | Offset where the document list started | ++--------------------------------+---------------------------------------------+ +| update_seq (optional) | Current update sequence for the database | ++--------------------------------+---------------------------------------------+ +| rows [array] | Array of document object | ++--------------------------------+---------------------------------------------+ + +Bulk Document Response +====================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| docs [array] | Bulk Docs Returned Documents | ++--------------------------------+---------------------------------------------+ +| id | Document ID | ++--------------------------------+---------------------------------------------+ +| error | Error type | ++--------------------------------+---------------------------------------------+ +| reason | Error string with extended reason | ++--------------------------------+---------------------------------------------+ + +Bulk Documents +============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| all_or_nothing (optional) | Sets the database commit mode to use | +| | all-or-nothing semantics | ++--------------------------------+---------------------------------------------+ +| docs [array] | Bulk Documents Document | ++--------------------------------+---------------------------------------------+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _deleted (optional) | Whether the document should be deleted | ++--------------------------------+---------------------------------------------+ + +Changes information for a database +================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| last_seq | Last change sequence number | ++--------------------------------+---------------------------------------------+ +| results [array] | Changes made to a database | ++--------------------------------+---------------------------------------------+ +| seq | Update sequence number | ++--------------------------------+---------------------------------------------+ +| id | Document ID | ++--------------------------------+---------------------------------------------+ +| changes [array] | List of changes, field-by-field, for this | +| | document | ++--------------------------------+---------------------------------------------+ + +CouchDB Document +================ + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ + +CouchDB Error Status +==================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| id | Document ID | ++--------------------------------+---------------------------------------------+ +| error | Error type | ++--------------------------------+---------------------------------------------+ +| reason | Error string with extended reason | ++--------------------------------+---------------------------------------------+ + +CouchDB database information object +=================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| db_name | The name of the database. | ++--------------------------------+---------------------------------------------+ +| committed_update_seq | The number of committed update. | ++--------------------------------+---------------------------------------------+ +| doc_count | A count of the documents in the specified | +| | database. | ++--------------------------------+---------------------------------------------+ +| doc_del_count | Number of deleted documents | ++--------------------------------+---------------------------------------------+ +| compact_running | Set to true if the database compaction | +| | routine is operating on this database. | ++--------------------------------+---------------------------------------------+ +| disk_format_version | The version of the physical format used for | +| | the data when it is stored on disk. | ++--------------------------------+---------------------------------------------+ +| disk_size | Size in bytes of the data as stored on the | +| | disk. Views indexes are not included in the | +| | calculation. | ++--------------------------------+---------------------------------------------+ +| instance_start_time | Timestamp of when the database was created, | +| | expressed in milliseconds since the epoch. | ++--------------------------------+---------------------------------------------+ +| purge_seq | The number of purge operations on the | +| | database. | ++--------------------------------+---------------------------------------------+ +| update_seq | The current number of updates to the | +| | database. | ++--------------------------------+---------------------------------------------+ + +Design Document +=============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id | Design Document ID | ++--------------------------------+---------------------------------------------+ +| _rev | Design Document Revision | ++--------------------------------+---------------------------------------------+ +| views | View | ++--------------------------------+---------------------------------------------+ +| viewname | View Definition | ++--------------------------------+---------------------------------------------+ +| map | Map Function for View | ++--------------------------------+---------------------------------------------+ +| reduce (optional) | Reduce Function for View | ++--------------------------------+---------------------------------------------+ + +Design Document Information +=========================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| name | Name/ID of Design Document | ++--------------------------------+---------------------------------------------+ +| view_index | View Index | ++--------------------------------+---------------------------------------------+ +| compact_running | Indicates whether a compaction routine is | +| | currently running on the view | ++--------------------------------+---------------------------------------------+ +| disk_size | Size in bytes of the view as stored on disk | ++--------------------------------+---------------------------------------------+ +| language | Language for the defined views | ++--------------------------------+---------------------------------------------+ +| purge_seq | The purge sequence that has been processed | ++--------------------------------+---------------------------------------------+ +| signature | MD5 signature of the views for the design | +| | document | ++--------------------------------+---------------------------------------------+ +| update_seq | The update sequence of the corresponding | +| | database that has been indexed | ++--------------------------------+---------------------------------------------+ +| updater_running | Indicates if the view is currently being | +| | updated | ++--------------------------------+---------------------------------------------+ +| waiting_clients | Number of clients waiting on views from this| +| | design document | ++--------------------------------+---------------------------------------------+ +| waiting_commit | Indicates if there are outstanding commits | +| | to the underlying database that need to | +| | processed | ++--------------------------------+---------------------------------------------+ + +Design Document spatial index Information +========================================= + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| name | Name/ID of Design Document | ++--------------------------------+---------------------------------------------+ +| spatial_index | View Index | ++--------------------------------+---------------------------------------------+ +| compact_running | Indicates whether a compaction routine is | +| | currently running on the view | ++--------------------------------+---------------------------------------------+ +| disk_size | Size in bytes of the view as stored on disk | ++--------------------------------+---------------------------------------------+ +| language | Language for the defined views | ++--------------------------------+---------------------------------------------+ +| purge_seq | The purge sequence that has been processed | ++--------------------------------+---------------------------------------------+ +| signature | MD5 signature of the views for the design | +| | document | ++--------------------------------+---------------------------------------------+ +| update_seq | The update sequence of the corresponding | +| | database that has been indexed | ++--------------------------------+---------------------------------------------+ +| updater_running | Indicates if the view is currently being | +| | updated | ++--------------------------------+---------------------------------------------+ +| waiting_clients | Number of clients waiting on views from this| +| | design document | ++--------------------------------+---------------------------------------------+ +| waiting_commit | Indicates if there are outstanding commits | +| | to the underlying database that need to | +| | processed | ++--------------------------------+---------------------------------------------+ + +Document with Attachments +========================= + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _attachments (optional) | Document Attachment | ++--------------------------------+---------------------------------------------+ +| filename | Attachment information | ++--------------------------------+---------------------------------------------+ +| content_type | MIME Content type string | ++--------------------------------+---------------------------------------------+ +| data | File attachment content, Base64 encoded | ++--------------------------------+---------------------------------------------+ + +List of Active Tasks +==================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| tasks [array] | Active Task | ++--------------------------------+---------------------------------------------+ +| pid | Process ID | ++--------------------------------+---------------------------------------------+ +| status | Task status message | ++--------------------------------+---------------------------------------------+ +| task | Task name | ++--------------------------------+---------------------------------------------+ +| type | Operation Type | ++--------------------------------+---------------------------------------------+ + +Replication Settings +==================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| source | Source database name or URL | ++--------------------------------+---------------------------------------------+ +| target | Target database name or URL | ++--------------------------------+---------------------------------------------+ +| create_target (optional) | Creates the target database | ++--------------------------------+---------------------------------------------+ +| continuous (optional) | Configure the replication to be continuous | ++--------------------------------+---------------------------------------------+ +| cancel (optional) | Cancels the replication | ++--------------------------------+---------------------------------------------+ +| doc_ids (optional) | Array of document IDs to be synchronized | ++--------------------------------+---------------------------------------------+ +| proxy (optional) | Address of a proxy server through which | +| | replication should occur | ++--------------------------------+---------------------------------------------+ + +Replication Status +================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| ok | Replication status | ++--------------------------------+---------------------------------------------+ +| session_id | Unique session ID | ++--------------------------------+---------------------------------------------+ +| source_last_seq | Last sequence number read from source | +| | database | ++--------------------------------+---------------------------------------------+ +| history [array] | Replication History | ++--------------------------------+---------------------------------------------+ +| session_id | Session ID for this replication operation | ++--------------------------------+---------------------------------------------+ +| recorded_seq | Last recorded sequence number | ++--------------------------------+---------------------------------------------+ +| docs_read | Number of documents read | ++--------------------------------+---------------------------------------------+ +| docs_written | Number of documents written to target | ++--------------------------------+---------------------------------------------+ +| doc_write_failures | Number of document write failures | ++--------------------------------+---------------------------------------------+ +| start_time | Date/Time replication operation started | ++--------------------------------+---------------------------------------------+ +| start_last_seq | First sequence number in changes stream | ++--------------------------------+---------------------------------------------+ +| end_time | Date/Time replication operation completed | ++--------------------------------+---------------------------------------------+ +| end_last_seq | Last sequence number in changes stream | ++--------------------------------+---------------------------------------------+ +| missing_checked | Number of missing documents checked | ++--------------------------------+---------------------------------------------+ +| missing_found | Number of missing documents found | ++--------------------------------+---------------------------------------------+ + +Returned CouchDB Document with Detailed Revision Info +===================================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _revs_info [array] | CouchDB Document Extended Revision Info | ++--------------------------------+---------------------------------------------+ +| rev | Full revision string | ++--------------------------------+---------------------------------------------+ +| status | Status of the revision | ++--------------------------------+---------------------------------------------+ + +Returned CouchDB Document with Revision Info +============================================ + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _revisions | CouchDB Document Revisions | ++--------------------------------+---------------------------------------------+ +| ids [array] | Array of valid revision IDs, in reverse | +| | order (latest first) | ++--------------------------------+---------------------------------------------+ +| start | Prefix number for the latest revision | ++--------------------------------+---------------------------------------------+ + +Returned Document with Attachments +================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _attachments (optional) | Document Attachment | ++--------------------------------+---------------------------------------------+ +| filename | Attachment | ++--------------------------------+---------------------------------------------+ +| stub | Indicates whether the attachment is a stub | ++--------------------------------+---------------------------------------------+ +| content_type | MIME Content type string | ++--------------------------------+---------------------------------------------+ +| length | Length (bytes) of the attachment data | ++--------------------------------+---------------------------------------------+ +| revpos | Revision where this attachment exists | ++--------------------------------+---------------------------------------------+ + +Security Object +=============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| admins | Roles/Users with admin privileges | ++--------------------------------+---------------------------------------------+ +| roles [array] | List of roles with parent privilege | ++--------------------------------+---------------------------------------------+ +| users [array] | List of users with parent privilege | ++--------------------------------+---------------------------------------------+ +| readers | Roles/Users with reader privileges | ++--------------------------------+---------------------------------------------+ +| roles [array] | List of roles with parent privilege | ++--------------------------------+---------------------------------------------+ +| users [array] | List of users with parent privilege | ++--------------------------------+---------------------------------------------+ http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/os-daemons.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/os-daemons.rst b/share/doc/src/os-daemons.rst new file mode 100644 index 0000000..5ff850c --- /dev/null +++ b/share/doc/src/os-daemons.rst @@ -0,0 +1,50 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +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/responder.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:`http-proxying`. For further background on the OS Daemon service, see +`CouchDB Externals API`_. + +.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/range.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/range.rst b/share/doc/src/range.rst new file mode 100644 index 0000000..a2f6ed1 --- /dev/null +++ b/share/doc/src/range.rst @@ -0,0 +1,72 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +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. This is available for all attachments inside CouchDB. + +This is just a real quick run through how this looks under the hood. +Usually, you will have larger binary files to serve from CouchDB, like +MP3s and videos, but to make things a little more obvious, I use a text +file here (Note that I use the ``application/octet-stream`` Content-Type +instead of ``text/plain``). + +.. code-block:: bash + + shell> cat file.txt + My hovercraft is full of eels! + +Now let's store this text file as an attachment in CouchDB. First, we +create a database: + +.. code-block:: bash + + shell> curl -X PUT http://127.0.0.1:5984/test + {"ok":true} + +Then we create a new document and the file attachment in one go: + +.. 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"} + +Now we can request the whole file easily: + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt + My hovercraft is full of eels! + +But say we only want the first 13 bytes: + +.. 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 +ranges. Read all about it in `RFC 2616`_. + +.. note:: + Databases that have been created with CouchDB 1.0.2 or earlier will + support range requests in |version|, 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 |version| to take advantage of a + better algorithm to find byte ranges. + +.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27 http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/release.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/release.rst b/share/doc/src/release.rst new file mode 100644 index 0000000..c61d8ad --- /dev/null +++ b/share/doc/src/release.rst @@ -0,0 +1,47 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +======================================= +CouchDB Release |version| Feature Guide +======================================= + +Upgrading to CouchDB |version| +============================== + +You can upgrade your existing CouchDB 1.0.x installation to CouchDB |version| +without any specific steps or migration. When you run CouchDB |version| the +existing data and index files will be opened and used as normal. + +The first time you run a compaction routine on your database within +CouchDB |version|, the data structure and indexes will be updated to the new +version of the CouchDB database format that can only be read by CouchDB +|version| and later. This step is not reversible. Once the data files have +been updated and migrated to the new version the data files will no +longer work with a CouchDB 1.0.x release. + +.. warning:: + If you want to retain support for opening the data files in + CouchDB 1.0.x you must back up your data files before performing the + upgrade and compaction process. + +New features in CouchDB |version| +================================= + +.. toctree:: +.. :maxdepth: 2 +.. +.. replicator +.. ssl +.. range +.. proxy +.. commonjs +.. other http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/replication.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/replication.rst b/share/doc/src/replication.rst new file mode 100644 index 0000000..9245a08 --- /dev/null +++ b/share/doc/src/replication.rst @@ -0,0 +1,383 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _replication: + +Replicator Database +=================== + +A database where you ``PUT``/``POST`` documents to trigger replications +and you ``DELETE`` to cancel ongoing replications. These documents have +exactly the same content as the JSON objects we used to ``POST`` to +``_replicate`` (fields ``source``, ``target``, ``create_target``, +``continuous``, ``doc_ids``, ``filter``, ``query_params``. + +Replication documents can have a user defined ``_id``. Design documents +(and ``_local`` documents) added to the replicator database are ignored. + +The default name of this database is ``_replicator``. The name can be +changed in the ``local.ini`` configuration, section ``[replicator]``, +parameter ``db``. + +Basics +------ + +Let's say you PUT the following document into ``_replicator``: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "create_target": true + } + +In the couch log you'll see 2 entries like these: + +.. code-block:: text + + [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`) + +As soon as the replication is triggered, the document will be updated by +CouchDB with 3 new fields: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "create_target": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 + } + +Special fields set by the replicator start with the prefix +``_replication_``. + +- ``_replication_id`` + + The ID internally assigned to the replication. This is also the ID + exposed by ``/_active_tasks``. + +- ``_replication_state`` + + The current state of the replication. + +- ``_replication_state_time`` + + A Unix timestamp (number of seconds since 1 Jan 1970) that tells us + when the current replication state (marked in ``_replication_state``) + was set. + +When the replication finishes, it will update the ``_replication_state`` +field (and ``_replication_state_time``) with the value ``completed``, so +the document will look like: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "create_target": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "completed", + "_replication_state_time": 1297974122 + } + +When an error happens during replication, the ``_replication_state`` +field is set to ``error`` (and ``_replication_state`` gets updated of +course). + +When you PUT/POST a document to the ``_replicator`` database, CouchDB +will attempt to start the replication up to 10 times (configurable under +``[replicator]``, parameter ``max_replication_retry_count``). 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: + +.. code-block:: text + + [error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">> + +.. note:: + The ``_replication_state`` field is only set to ``error`` when all + the attempts were unsuccessful. + +There are only 3 possible values for the ``_replication_state`` field: +``triggered``, ``completed`` and ``error``. Continuous replications +never get their state set to ``completed``. + +Documents describing the same replication +----------------------------------------- + +Lets suppose 2 documents are added to the ``_replicator`` database in +the following order: + +.. code-block:: javascript + + { + "_id": "doc_A", + "source": "http://myserver.com:5984/foo", + "target": "bar" + } + +and + +.. code-block:: javascript + + { + "_id": "doc_B", + "source": "http://myserver.com:5984/foo", + "target": "bar" + } + +Both describe exactly the same replication (only their ``_ids`` differ). +In this case document ``doc_A`` triggers the replication, getting +updated by CouchDB with the fields ``_replication_state``, +``_replication_state_time`` and ``_replication_id``, just like it was +described before. Document ``doc_B`` however, is only updated with one +field, the ``_replication_id`` so it will look like this: + +.. code-block:: javascript + + { + "_id": "doc_B", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "_replication_id": "c0ebe9256695ff083347cbf95f93e280" + } + +While document ``doc_A`` will look like this: + +.. code-block:: javascript + + { + "_id": "doc_A", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 + } + +Note that both document get exactly the same value for the +``_replication_id`` 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. + +Canceling replications +---------------------- + +To cancel a replication simply ``DELETE`` the document which triggered +the replication. The Couch log will show you an entry like the +following: + +.. code-block:: text + + [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 + +.. note:: + You need to ``DELETE`` the document that triggered the replication. + ``DELETE``-ing another document that describes the same replication + but did not trigger it, will not cancel the replication. + +Server restart +-------------- + +When CouchDB is restarted, it checks its ``_replicator`` database and +restarts any replication that is described by a document that either has +its ``_replication_state`` field set to ``triggered`` or it doesn't have +yet the ``_replication_state`` field set. + +.. note:: + Continuous replications always have a ``_replication_state`` field + with the value ``triggered``, therefore they're always restarted + when CouchDB is restarted. + +Changing the Replicator Database +-------------------------------- + +Imagine your replicator database (default name is ``_replicator``) has the +two following documents that represent pull replications from servers A +and B: + +.. code-block:: javascript + + { + "_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 + } + +.. code-block:: javascript + + { + "_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 + } + +Now without stopping and restarting CouchDB, you change the name of the +replicator database to ``another_replicator_db``: + +.. code-block:: bash + + $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"' + "_replicator" + +As soon as this is done, both pull replications defined before, are +stopped. This is explicitly mentioned in CouchDB's log: + +.. code-block:: text + + [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 + +Imagine now you add a replication document to the new replicator +database named ``another_replicator_db``: + +.. code-block:: javascript + + { + "_id": "rep_from_X", + "source": "http://xserver.com:5984/foo", + "target": "foo_x", + "continuous": true + } + +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 ``_replicator``: + +:: + + $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"' + "another_replicator_db" + +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. + +Changing again the replicator database to ``another_replicator_db`` will +stop the pull replications pulling from servers A and B, and resume the +pull replication pulling from server X. + +Replicating the replicator database +----------------------------------- + +Imagine you have in server C a replicator database with the two +following pull replication documents in it: + +.. code-block:: javascript + + { + "_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 + } + +.. code-block:: javascript + + { + "_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 + } + +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: + +- Explicitly add two documents to server's D replicator database + +- Replicate server's C replicator database into server's D replicator + database + +Both alternatives accomplish exactly the same goal. + +Delegations +----------- + +Replication documents can have a custom ``user_ctx`` property. This +property defines the user context under which a replication runs. For +the old way of triggering replications (POSTing to ``/_replicate/``), +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 ``?include_docs=true``) 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 ``user_ctx`` 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 ``user_ctx`` property that doesn't match his/her own name (same +principle applies for the roles). + +For admins, the ``user_ctx`` 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 ``_admin`` must be set explicitly. + +Also, for admins the ``user_ctx`` 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. + +.. note:: + The ``user_ctx`` property only has effect for local endpoints. + +Example delegated replication document: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://bserver.com:5984/foo", + "target": "bar", + "continuous": true, + "user_ctx": { + "name": "joe", + "roles": ["erlanger", "researcher"] + } + } + +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 +``user_ctx`` is missing, it defaults to the empty list ``[ ]``. http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/ssl.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/ssl.rst b/share/doc/src/ssl.rst new file mode 100644 index 0000000..3a546d8 --- /dev/null +++ b/share/doc/src/ssl.rst @@ -0,0 +1,109 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +Native SSL Support +================== + +CouchDB |version| supports SSL natively. All your secure connection needs can +now be served without needing to setup and maintain a separate proxy server +that handles SSL. + +SSL setup can be tricky, but the 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. + +:: + + 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: + +:: + + ; 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: + +:: + + httpsd = {couch_httpd, start_link, [https]} + +Next, under ``[ssl]`` you will see: + +:: + + ;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: + +:: + + 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: + +:: + + 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: + +:: + + shell> curl -k https://127.0.0.1:6984/ + {"couchdb":"Welcome","version":"|version|"} + +All done. + +.. _`http://www.openssl.org/docs/HOWTO/certificates.txt`: http://www.openssl.org/docs/HOWTO/certificates.txt http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/Makefile.am ---------------------------------------------------------------------- diff --git a/share/docs/Makefile.am b/share/docs/Makefile.am deleted file mode 100644 index 0a039f5..0000000 --- a/share/docs/Makefile.am +++ /dev/null @@ -1,53 +0,0 @@ -## Licensed under the Apache License, Version 2.0 (the "License"); you may not -## use this file except in compliance with the License. You may obtain a copy of -## the License at -## -## http://www.apache.org/licenses/LICENSE-2.0 -## -## Unless required by applicable law or agreed to in writing, software -## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -## License for the specific language governing permissions and limitations under -## the License. - -# @@ can we remove _static? - -# @@ what is the license for conf.py? - -EXTRA_DIST = \ - demo.mk \ - images/epub-icon.png \ - images/futon-createdb.png \ - images/futon-editdoc.png \ - images/futon-editeddoc.png \ - images/futon-overview.png \ - images/futon-replform.png \ - make.bat \ - Makefile.am \ - src/_static \ - src/api/authn.rst \ - src/api/configuration.rst \ - src/api/database.rst \ - src/api/dbmaint.rst \ - src/api/design.rst \ - src/api/documents.rst \ - src/api/local.rst \ - src/api/misc.rst \ - src/api/reference.rst \ - src/api-basics.rst \ - src/changes.rst \ - src/commonjs.rst \ - src/conf.py \ - src/config_reference.rst \ - src/configuring.rst \ - src/ddocs.rst \ - src/errors.rst \ - src/http-proxying.rst \ - src/index.rst \ - src/intro.rst \ - src/json-structure.rst \ - src/os-daemons.rst \ - src/range.rst \ - src/release.rst \ - src/replication.rst \ - src/ssl.rst \ No newline at end of file http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/demo.mk ---------------------------------------------------------------------- diff --git a/share/docs/demo.mk b/share/docs/demo.mk deleted file mode 100644 index 28a1541..0000000 --- a/share/docs/demo.mk +++ /dev/null @@ -1,173 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) src -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -# include -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -# exclude, doesn't work locally -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -# maybe include, but not as default option, too big -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -# exclude, no use for this -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -# exclude, no use for this -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -# exclude, but mention availability on wiki -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." -# exclude -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/CouchDB.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/CouchDB.qhc" - -# exclude -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/CouchDB" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/CouchDB" - @echo "# devhelp" - -# exclude -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -# include -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -# include, replace automake -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -# exclude -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -# exclude -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -# include -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -# include, replace automake -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -# exclude, but mention that this is an option on wiki (for translators) -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -# hook this into producing the changelog, ooh!! ooh!! -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -# figure out what cloudstack are doing for copyright stuff - -# run this and check for errors, aborting the build -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -# exclude, but mention on the wiki -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/images/epub-icon.png ---------------------------------------------------------------------- diff --git a/share/docs/images/epub-icon.png b/share/docs/images/epub-icon.png deleted file mode 100644 index 3fda935..0000000 Binary files a/share/docs/images/epub-icon.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/images/futon-createdb.png ---------------------------------------------------------------------- diff --git a/share/docs/images/futon-createdb.png b/share/docs/images/futon-createdb.png deleted file mode 100644 index c8c1b9d..0000000 Binary files a/share/docs/images/futon-createdb.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/images/futon-editdoc.png ---------------------------------------------------------------------- diff --git a/share/docs/images/futon-editdoc.png b/share/docs/images/futon-editdoc.png deleted file mode 100644 index 6802c2c..0000000 Binary files a/share/docs/images/futon-editdoc.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/images/futon-editeddoc.png ---------------------------------------------------------------------- diff --git a/share/docs/images/futon-editeddoc.png b/share/docs/images/futon-editeddoc.png deleted file mode 100644 index 5c8b549..0000000 Binary files a/share/docs/images/futon-editeddoc.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/images/futon-overview.png ---------------------------------------------------------------------- diff --git a/share/docs/images/futon-overview.png b/share/docs/images/futon-overview.png deleted file mode 100644 index d1eac6e..0000000 Binary files a/share/docs/images/futon-overview.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/images/futon-replform.png ---------------------------------------------------------------------- diff --git a/share/docs/images/futon-replform.png b/share/docs/images/futon-replform.png deleted file mode 100644 index d904f0d..0000000 Binary files a/share/docs/images/futon-replform.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/make.bat ---------------------------------------------------------------------- diff --git a/share/docs/make.bat b/share/docs/make.bat deleted file mode 100644 index 4994199..0000000 --- a/share/docs/make.bat +++ /dev/null @@ -1,190 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\CouchDB.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\CouchDB.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/src/_static/.gitignore ---------------------------------------------------------------------- diff --git a/share/docs/src/_static/.gitignore b/share/docs/src/_static/.gitignore deleted file mode 100644 index e69de29..0000000 http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/docs/src/api-basics.rst ---------------------------------------------------------------------- diff --git a/share/docs/src/api-basics.rst b/share/docs/src/api-basics.rst deleted file mode 100644 index 97ea70c..0000000 --- a/share/docs/src/api-basics.rst +++ /dev/null @@ -1,459 +0,0 @@ -.. Licensed under the Apache License, Version 2.0 (the "License"); you may not -.. use this file except in compliance with the License. You may obtain a copy of -.. the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -.. License for the specific language governing permissions and limitations under -.. the License. - -.. _api-basics: - -=========== -CouchDB API -=========== - -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. - -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 -``GET`` operation, while updates are handled by either a ``POST`` or -``PUT`` 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 :ref:`api-format`. - -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 -:ref:`json`. - -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 :ref:`errors`. - -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 -:ref:`api-overview`. - -.. _api-format: - -Request Format and Responses -============================ - -CouchDB supports the following HTTP request methods: - -- ``GET`` - - 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. - -- ``HEAD`` - - The ``HEAD`` method is used to get the HTTP header of a ``GET`` - request without the body of the response. - -- ``POST`` - - Upload data. Within CouchDB ``POST`` is used to set values, including - uploading documents, setting document values, and starting certain - administration commands. - -- ``PUT`` - - Used to put a specified resource. In CouchDB ``PUT`` is used to - create new objects, including databases, documents, views and design - documents. - -- ``DELETE`` - - Deletes the specified resource, including documents, views, and - design documents. - -- ``COPY`` - - A special method that can be used to copy documents and objects. - -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: - -.. code-block:: javascript - - { - "error":"method_not_allowed", - "reason":"Only GET,HEAD allowed" - } - - -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 ``headers`` block of the return object. - -HTTP Headers -============ - -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. - -Request Headers ---------------- - -- ``Content-type`` - - 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 (``application/json``). 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 (``application/octet-stream``). - - The use of the ``Content-type`` on a request is highly recommended. - -- ``Accept`` - - 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. - - For the majority of requests the definition should be for JSON data - (``application/json``). For attachments you can either specify the - MIME type explicitly, or use ``*/*`` to specify that all file types - are supported. If the ``Accept`` header is not supplied, then the - ``*/*`` MIME type is assumed (i.e. client accepts all formats). - - The use of ``Accept`` 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. - - If you specify a data type using the ``Accept`` header, CouchDB will - honor the specified type in the ``Content-type`` header field - returned. For example, if you explicitly request ``application/json`` - in the ``Accept`` of a request, the returned HTTP headers will use - the value in the returned ``Content-type`` field. - - For example, when sending a request without an explicit ``Accept`` - header, or when specifying ``*/*``: - - .. code-block:: http - - GET /recipes HTTP/1.1 - Host: couchdb:5984 - Accept: */* - - The returned headers are: - - .. code-block:: http - - 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 - - Note that the returned content type is ``text/plain`` even though the - information returned by the request is in JSON format. - - Explicitly specifying the ``Accept`` header: - - .. code-block:: http - - GET /recipes HTTP/1.1 - Host: couchdb:5984 - Accept: application/json - - The headers returned include the ``application/json`` content type: - - .. code-block:: http - - Server: CouchDB/|version| (Erlang OTP/R13B) - Date: Thu, 13 Jan 2011 13:40:11 GMT - Content-Type: application/json - Content-Length: 227 - Cache-Control: must-revalidate - -Response Headers ----------------- - -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. - -- ``Content-type`` - - Specifies the MIME type of the returned data. For most request, the - returned MIME type is ``text/plain``. All text is encoded in Unicode - (UTF-8), and this is explicitly stated in the returned - ``Content-type``, as ``text/plain;charset=utf-8``. - -- ``Cache-control`` - - The cache control HTTP response header provides a suggestion for - client caching mechanisms on how to treat the returned information. - CouchDB typically returns the ``must-revalidate``, 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. - -- ``Content-length`` - - The length (in bytes) of the returned content. - -- ``Etag`` - - The ``Etag`` HTTP header field is used to show the revision for a - document, or a view. - - 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. - - Each ``_view`` URL has its 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). - -.. _json: - -JSON Basics -=========== - -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. - -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. - -JSON supports the same basic types as supported by JavaScript, these -are: - -- Number (either integer or floating-point). - -- String; this should be enclosed by double-quotes and supports Unicode - characters and backslash escaping. For example: - - .. code-block:: javascript - - "A String" - -- Boolean - a ``true`` or ``false`` value. You can use these strings - directly. For example: - - .. code-block:: javascript - - { "value": true} - -- Array - a list of values enclosed in square brackets. For example: - - .. code-block:: javascript - - ["one", "two", "three"] - -- 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: - - .. code-block:: javascript - - { - "servings" : 4, - "subtitle" : "Easy to make in advance, and then cook when ready", - "cooktime" : 60, - "title" : "Chicken Coriander" - } - - - In CouchDB, the JSON object is used to represent a variety of - structures, including the main CouchDB document. - -Parsing JSON into a JavaScript object is supported through the -``JSON.parse()`` 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. - -.. warning:: - 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). - -.. _errors: - -HTTP Status Codes -================= - -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. - -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. - -- ``200 - OK`` - - Request completed successfully. - -- ``201 - Created`` - - Document created successfully. - -- ``202 - Accepted`` - - Request has been accepted, but the corresponding operation may not - have completed. This is used for background operations, such as - database compaction. - -- ``304 - Not Modified`` - - The additional content requested has not been modified. This is used - with the ETag system to identify the version of information returned. - -- ``400 - Bad Request`` - - 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. - -- ``401 - Unauthorized`` - - The item requested was not available using the supplied - authorization, or authorization was not supplied. - -- ``403 - Forbidden`` - - The requested item or operation is forbidden. - -- ``404 - Not Found`` - - 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, ``error`` and ``reason``. For example: - - .. code-block:: javascript - - {"error":"not_found","reason":"no_db_file"} - -- ``405 - Resource Not Allowed`` - - A request was made using an invalid HTTP request type for the URL - requested. For example, you have requested a ``PUT`` when a ``POST`` - is required. Errors of this type can also triggered by invalid URL - strings. - -- ``406 - Not Acceptable`` - - The requested content type is not supported by the server. - -- ``409 - Conflict`` - - Request resulted in an update conflict. - -- ``412 - Precondition Failed`` - - The request headers from the client and the capabilities of the - server do not match. - -- ``415 - Bad Content Type`` - - The content types supported, and the content type of the information - being requested or submitted indicate that the content type is not - supported. - -- ``416 - Requested Range Not Satisfiable`` - - The range specified in the request header cannot be satisfied by the - server. - -- ``417 - Expectation Failed`` - - When sending documents in bulk, the bulk load operation failed. - -- ``500 - Internal Server Error`` - - The request was invalid, either because the supplied JSON was - invalid, or invalid information was supplied as part of the request. - -.. _api-overview: - -CouchDB API Overview -==================== - -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. - -As with all URLs, the individual components are separated by a forward -slash. - -As a general rule, URL components and JSON fields starting with the -``_`` (underscore) character represent a special component or entity -within the server or returned object. For example, the URL fragment -``/_all_dbs`` gets a list of all of the databases in a CouchDB instance. - -The remainder of the URL API structure can be divided up according to -the URL structure. The different sections are divided as follows: - -- ``/db`` - - Database methods, related to adding, updating or deleting databases, - and setting database parameters and operations. For more detailed - information, see :ref:`api-db`. - -- ``/db/doc`` - - Document methods, those that create, store, update or delete CouchDB - documents and their attachments. For more information, see :ref:`api-doc`. - -- ``/db/_local/local-doc`` - - 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 - :ref:`api-local`. - -- ``/db/_design/design-doc`` - - 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 :ref:`api-design`. - -- ``/_special`` - - 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 :ref:`api-misc`. - -- ``/_config`` - - Methods for getting, and settings, CouchDB configuration parameters. - For more information, see :ref:`api-config`.