http://git-wip-us.apache.org/repos/asf/couchdb/blob/838cf30b/share/sphinx-docs/json-structure.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/json-structure.rst b/share/sphinx-docs/json-structure.rst deleted file mode 100644 index 32db3d6..0000000 --- a/share/sphinx-docs/json-structure.rst +++ /dev/null @@ -1,401 +0,0 @@ -======================== -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/838cf30b/share/sphinx-docs/make.bat ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/make.bat b/share/sphinx-docs/make.bat deleted file mode 100644 index 4994199..0000000 --- a/share/sphinx-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 ^<target^>` where ^<target^> 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/838cf30b/share/sphinx-docs/replication.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/replication.rst b/share/sphinx-docs/replication.rst deleted file mode 100644 index 92beed9..0000000 --- a/share/sphinx-docs/replication.rst +++ /dev/null @@ -1,375 +0,0 @@ -.. _replication: - -=========== -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/838cf30b/share/sphinx-docs/views.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/views.rst b/share/sphinx-docs/views.rst deleted file mode 100644 index 52ef53f..0000000 --- a/share/sphinx-docs/views.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _views: - -Views -===== - -To be added: information on writing views.
