This is an automated email from the ASF dual-hosted git repository. wohali pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
The following commit(s) were added to refs/heads/master by this push: new 3aa2737 Last wiki migrations; rework of TOC & headers (#372) 3aa2737 is described below commit 3aa2737f084a728fced4384740920b5069323d24 Author: Joan Touzet <woh...@users.noreply.github.com> AuthorDate: Fri Dec 21 14:59:21 2018 -0500 Last wiki migrations; rework of TOC & headers (#372) --- .travis.yml | 8 +++++++ ext/configdomain.py | 4 ++-- ext/httpdomain.py | 2 +- src/api/local.rst | 5 ++--- src/cluster/index.rst | 6 +++--- src/conf.py | 6 ++++-- src/config/index.rst | 6 +++--- src/cve/index.rst | 6 +++--- src/ddocs/views/intro.rst | 14 ++++++++++++ src/ddocs/views/joins.rst | 29 ++++++++++++++----------- src/index.rst | 48 +++++++++++++++++++++++++---------------- src/install/troubleshooting.rst | 18 ++++++++++++++++ src/intro/api.rst | 3 ++- src/intro/overview.rst | 14 +++--------- src/maintenance/index.rst | 6 +++--- src/replication/conflicts.rst | 42 ++++++++++++++++++++++++++++++++++++ src/replication/index.rst | 2 +- src/setup/cluster.rst | 8 +++---- src/whatsnew/index.rst | 7 +++--- templates/layout.html | 6 +++--- templates/pages/index.html | 4 ++-- 21 files changed, 167 insertions(+), 77 deletions(-) diff --git a/.travis.yml b/.travis.yml index 5a3da42..7bfff38 100644 --- a/.travis.yml +++ b/.travis.yml @@ -2,6 +2,14 @@ language: python python: - 3.6 +# start a push build on master and release branches + PRs build on every branch +# Avoid double build on PRs (See https://github.com/travis-ci/travis-ci/issues/1147) +branches: + only: + - master + - /^\d+\.x\.x$/ + - /^\d+\.\d+\.x$/ + install: - pip install -r requirements.txt diff --git a/ext/configdomain.py b/ext/configdomain.py index fae52a9..66ed532 100644 --- a/ext/configdomain.py +++ b/ext/configdomain.py @@ -57,8 +57,8 @@ class ConfigObject(ObjectDescription): class ConfigIndex(Index): name = "ref" - localname = "Configuration Reference" - shortname = "Config Reference" + localname = "Configuration Quick Reference" + shortname = "Config Quick Reference" def generate(self, docnames=None): content = dict( diff --git a/ext/httpdomain.py b/ext/httpdomain.py index 6354b24..5e8803d 100644 --- a/ext/httpdomain.py +++ b/ext/httpdomain.py @@ -495,7 +495,7 @@ class HTTPXRefRole(XRefRole): class HTTPIndex(Index): name = "api" - localname = "HTTP API Reference" + localname = "API Quick Reference" shortname = "API Reference" def generate(self, docnames=None): diff --git a/src/api/local.rst b/src/api/local.rst index c261721..0698ae2 100644 --- a/src/api/local.rst +++ b/src/api/local.rst @@ -54,9 +54,8 @@ A list of the available methods and URL paths are provided below: .. _api/local/doc: -======================== ``/db/_local_docs`` -======================== +=================== .. http:get:: /{db}/_local_docs :synopsis: Returns a built-in view of all local (non-replicating) documents @@ -227,7 +226,7 @@ A list of the available methods and URL paths are provided below: } ``/db/_local/id`` -======================== +================= .. http:get:: /{db}/_local/{docid} :synopsis: Returns the latest revision of the local document diff --git a/src/cluster/index.rst b/src/cluster/index.rst index 93973d0..46e569a 100644 --- a/src/cluster/index.rst +++ b/src/cluster/index.rst @@ -12,9 +12,9 @@ .. _cluster: -================= -Cluster Reference -================= +================== +Cluster Management +================== As of CouchDB 2.0.0, CouchDB can be run in two different modes of operation: * Standalone diff --git a/src/conf.py b/src/conf.py index 8ada770..a0cb15e 100644 --- a/src/conf.py +++ b/src/conf.py @@ -36,9 +36,11 @@ nitpicky = True version = "2.3" release = "2.3.0" -project = "Apache CouchDB" +project = u"Apache CouchDB\u00ae" -copyright = "%d, %s" % (datetime.datetime.now().year, "Apache Software Foundation") +copyright = u"%d, %s" % (datetime.datetime.now().year, \ + u"Apache Software Foundation. CouchDB\u00ae is a registered trademark of the " + \ + u"Apache Software Foundation") primary_domain = "http" diff --git a/src/config/index.rst b/src/config/index.rst index 64b03bf..492f23d 100644 --- a/src/config/index.rst +++ b/src/config/index.rst @@ -12,9 +12,9 @@ .. _config: -=================== -Configuring CouchDB -=================== +============= +Configuration +============= .. toctree:: :maxdepth: 2 diff --git a/src/cve/index.rst b/src/cve/index.rst index d55fec8..8807d04 100644 --- a/src/cve/index.rst +++ b/src/cve/index.rst @@ -12,9 +12,9 @@ .. _cve: -=========================== -Security Issues Information -=========================== +====================== +Security Issues / CVEs +====================== .. toctree:: :maxdepth: 1 diff --git a/src/ddocs/views/intro.rst b/src/ddocs/views/intro.rst index 1596145..8ac6c82 100644 --- a/src/ddocs/views/intro.rst +++ b/src/ddocs/views/intro.rst @@ -178,6 +178,20 @@ confusion. CouchDB automatically includes the document ID of the document that created the entry in the view result. We’ll use this as well when constructing links to the blog post pages. +.. warning:: + + Do not emit the entire document as the value of your ``emit(key, value)`` + statement unless you're sure you know you want it. This stores an entire + additional copy of your document in the view's secondary index. Views with + ``emit(key, doc)`` take longer to update, longer to write to disk, and + consume significantly more disk space. The only advantage is that they + are faster to query than using the ``?include_docs=true`` parameter when + querying a view. + + Consider the trade-offs before emitting the entire document. Often it is + sufficient to emit only a portion of the document, or just a single key / + value pair, in your views. + Efficient Lookups ================= diff --git a/src/ddocs/views/joins.rst b/src/ddocs/views/joins.rst index d991fc5..df30078 100644 --- a/src/ddocs/views/joins.rst +++ b/src/ddocs/views/joins.rst @@ -334,9 +334,9 @@ some use of that: function(doc) { if (doc.type == "post") { - emit([doc._id, 0], doc); + emit([doc._id, 0], null); } else if (doc.type == "comment") { - emit([doc.post, 1], doc); + emit([doc.post, 1], null); } } @@ -349,7 +349,8 @@ and/or sort the results you get back from your views. When you “invoke” a vi you can say that you're only interested in a subset of the view rows by specifying a ``?key=foo`` query string parameter. Or you can specify ``?startkey=foo`` and/or ``?endkey=bar`` query string parameters to fetch rows -over a range of keys. +over a range of keys. Finally, by adding ``?include_docs=true`` to the query, +the result will include the full body of each emitted document. It's also important to note that keys are always used for collating (i.e. sorting) the rows. CouchDB has well defined (but as of yet undocumented) rules @@ -380,23 +381,23 @@ the following: "total_rows": 5, "offset": 0, "rows": [{ "id": "myslug", "key": ["myslug", 0], - "value": {...} + "value": null }, { "id": "ABCDEF", "key": ["myslug", 1], - "value": {...} + "value": null }, { "id": "DEFABC", "key": ["myslug", 1], - "value": {...} + "value": null }, { "id": "other_slug", "key": ["other_slug", 0], - "value": {...} + "value": null }, { "id": "CDEFAB", "key": ["other_slug", 1], - "value": {...} + "value": null }, ] } @@ -408,11 +409,12 @@ the following: Now, to get a specific blog post and all associated comments, we'd invoke that view with the query string:: - ?startkey=["myslug"]&endkey;=["myslug", 2] + ?startkey=["myslug"]&endkey=["myslug", 2]&include_docs=true We'd get back the first three rows, those that belong to the ``myslug`` post, -but not the others. Et voila, we now have the data we need to display a post -with all associated comments, retrieved via a single ``GET`` request. +but not the others, along with the full bodies of each document. Et voila, we +now have the data we need to display a post with all associated comments, +retrieved via a single ``GET`` request. You may be asking what the 0 and 1 parts of the keys are for. They're simply to ensure that the post document is always sorted before the the associated @@ -424,5 +426,6 @@ One remaining problem with this model is that comments are not ordered, but that's simply because we don't have date/time information associated with them. If we had, we'd add the timestamp as third element of the key array, probably as ISO date/time strings. Now we would continue using the query string -``?startkey=["myslug"]&endkey=["myslug", 2]`` to fetch the blog post and all -associated comments, only now they'd be in chronological order. +``?startkey=["myslug"]&endkey=["myslug", 2]&include_docs=true`` to fetch the +blog post and all associated comments, only now they'd be in chronological +order. diff --git a/src/index.rst b/src/index.rst index 03b1032..a592539 100644 --- a/src/index.rst +++ b/src/index.rst @@ -12,37 +12,47 @@ .. This file exists solely to hold the top-level Table of Contents. -============================================= -|Apache CouchDB(TM)|_ |release| Documentation -============================================= +============== +Apache CouchDB +============== -Welcome! This is the documentation for Apache CouchDB |release|. - -Table of Contents -================= .. toctree:: + :caption: User Guides :maxdepth: 3 :numbered: intro/index + replication/index + ddocs/index + best-practices/index + +.. toctree:: + :caption: Administration Guides + :maxdepth: 3 + :numbered: + install/index setup/index config/index - replication/index + cluster/index maintenance/index - ddocs/index - query-server/index fauxton/index - best-practices/index + experimental + +.. toctree:: + :caption: Reference Guides + :maxdepth: 3 + :numbered: + api/index - cluster/index json-structure - experimental - contributing + query-server/index + +.. toctree:: + :caption: Other + :numbered: + whatsnew/index cve/index - about - -.. This is how you get a TM sign into a link. Haha. Seriously. -.. |Apache CouchDB(TM)| unicode:: Apache U+0020 CouchDB U+2122 -.. _Apache CouchDB(TM): http://couchdb.apache.org/ + License <about> + contributing diff --git a/src/install/troubleshooting.rst b/src/install/troubleshooting.rst index acb5f8b..a2e9496 100644 --- a/src/install/troubleshooting.rst +++ b/src/install/troubleshooting.rst @@ -304,6 +304,24 @@ Because CouchDB does not make use of MD5 hashes for cryptographic purposes, this workaround does not defeat the purpose of "FIPS mode," provided that the system owner is aware of and consents to its use. +Debugging startup +----------------- +If you've compiled from scratch and are having problems getting CouchDB to even +start up, you may want to see more detail. Start by enabling logging at the debug +level: + +.. code-block:: ini + + [log] + level = debug + +You can then pass the ``-init_debug +W i +v +V -emu_args`` flags in the ``ERL_FLAGS`` +environment variable to turn on additional debugging information that CouchDB +developers can use to help you. + +Then, reach out to the CouchDB development team using the links provided on the +`CouchDB home page <https://couchdb.apache.org/>`_ for assistance. + macOS Known Issues ==================== undefined error, exit_status 134 diff --git a/src/intro/api.rst b/src/intro/api.rst index 99731a5..82e067b 100644 --- a/src/intro/api.rst +++ b/src/intro/api.rst @@ -466,7 +466,8 @@ mechanisms, but we'll explore these later in the documents. start learning one of the popular systems). Using new versions for document changes works a lot like version control, but there's an important difference: **CouchDB does not guarantee that older versions are kept - around**. + around. Don't use the ``_rev`` token in CouchDB as a revision control system + for your documents.** Documents in Detail ------------------- diff --git a/src/intro/overview.rst b/src/intro/overview.rst index d9bd343..b58ce0e 100644 --- a/src/intro/overview.rst +++ b/src/intro/overview.rst @@ -37,7 +37,7 @@ editing the same document saves their changes first, the client gets an edit conflict error on save. To resolve the update conflict, the latest document version can be opened, the edits reapplied and the update tried again. -Document updates (add, edit, delete) are all or nothing, either succeeding +Single document updates (add, edit, delete) are all or nothing, either succeeding entirely or failing completely. The database never contains partially saved or edited documents. @@ -59,7 +59,8 @@ reading documents without being locked out or interrupted by concurrent updates, even on the same document. CouchDB read operations use a `Multi-Version Concurrency Control` (`MVCC`_) model where each client sees a consistent snapshot of the database from the beginning to the end of the read -operation. +operation. This means that CouchDB can guarantee transactional semantics on +a per-document basis. Documents are indexed in `B-trees`_ by their name (DocID) and a Sequence ID. Each update to a database instance generates a new sequential number. @@ -318,15 +319,6 @@ histories. Updates to documents can be implemented to exploit incremental field and blob replication, where replicated updates are nearly as efficient and incremental as the actual edit differences ("diffs"). -The CouchDB replication model can be modified for other distributed update -models. If the storage engine is enhanced to allow multi-document update -transactions, it is possible to perform Subversion-like "all or nothing" -atomic commits when replicating with an upstream server, such that any single -document conflict or validation failure will cause the entire update to fail. -Like Subversion, conflicts would be resolved by doing a "pull" replication to -force the conflicts locally, then merging and re-replicating to the upstream -server. - Implementation ============== diff --git a/src/maintenance/index.rst b/src/maintenance/index.rst index ffb2f0d..449deff 100644 --- a/src/maintenance/index.rst +++ b/src/maintenance/index.rst @@ -10,9 +10,9 @@ .. License for the specific language governing permissions and limitations under .. the License. -=================== -CouchDB Maintenance -=================== +=========== +Maintenance +=========== .. toctree:: diff --git a/src/replication/conflicts.rst b/src/replication/conflicts.rst index 7b59cfa..2341fb9 100644 --- a/src/replication/conflicts.rst +++ b/src/replication/conflicts.rst @@ -258,6 +258,48 @@ delete. Multiple document API ===================== +Finding conflicted documents with Mango +--------------------------------------- + +.. versionadded:: 2.2.0 + +CouchDB's :ref:`Mango system <api/db/_find>` allows easy querying of +documents with conflicts, returning the full body of each document as well. + +Here's how to use it to find all conflicts in a database: + +.. code-block:: bash + + $ curl -X POST http://127.0.0.1/dbname/_find \ + -d '{"selector": {"_conflicts": { "$exists": true}}, "conflicts": true}' \ + -Hcontent-type:application/json + +.. code-block:: javascript + + {"docs": [ + {"_id":"doc","_rev":"1-3975759ccff3842adf690a5c10caee42","a":2,"_conflicts":["1-23202479633c2b380f79507a776743d5"]} + ], + "bookmark": "g1AAAABheJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYozA1kgKQ6YVA5QkBFMgKSVDHWNjI0MjEzMLc2MjZONkowtDNLMLU0NzBPNzc3MTYxTTLOysgCY2ReV"} + +The ``bookmark`` value can be used to navigate through additional pages of +results if necessary. Mango by default only returns 25 results per request. + +If you expect to run this query often, be sure to create a Mango secondary +index to speed the query: + +.. code-block:: bash + + $ curl -X POST http://127.0.0.1/dbname/_index \ + -d '{"index":{"fields": ["_conflicts"]}}' \ + -Hcontent-type:application/json + +Of course, the selector can be enhanced to filter documents on additional +keys in the document. Be sure to add those keys to your secondary index as +well, or a full database scan will be triggered. + +Finding conflicted documents using the ``_all_docs`` index +---------------------------------------------------------- + You can fetch multiple documents at once using ``include_docs=true`` on a view. However, a ``conflicts=true`` request is ignored; the "doc" part of the value never includes a ``_conflicts`` member. Hence you would need to do another query diff --git a/src/replication/index.rst b/src/replication/index.rst index 4818ac8..6f79958 100644 --- a/src/replication/index.rst +++ b/src/replication/index.rst @@ -32,6 +32,6 @@ destination database. :maxdepth: 2 intro - protocol replicator conflicts + protocol diff --git a/src/setup/cluster.rst b/src/setup/cluster.rst index c40cbdf..ce80bc6 100644 --- a/src/setup/cluster.rst +++ b/src/setup/cluster.rst @@ -278,10 +278,10 @@ Now your cluster is ready and available! You can send requests to any one of the nodes, and all three will respond as if you are working with a single CouchDB cluster. -For a proper production setup, you'd now set up an HTTP proxy in front of the -node that does load balancing and SSL termination, if desired. We recommend -`HAProxy`_. See our `example configuration for HAProxy`_. All you need is to -adjust the IP addresses or hostnames and ports. +For a proper production setup, you'd now set up an HTTP reverse proxy in front +of the cluster, for load balancing and SSL termination. We recommend +`HAProxy`_, but others can be used. Sample configurations are available in the +:ref:`best-practices` section. .. _cluster/setup/api: diff --git a/src/whatsnew/index.rst b/src/whatsnew/index.rst index 3620588..4272b22 100644 --- a/src/whatsnew/index.rst +++ b/src/whatsnew/index.rst @@ -12,12 +12,13 @@ .. _releases: -=============== -Release History -=============== +============= +Release Notes +============= .. toctree:: :glob: + :maxdepth: 2 2.3 2.2 diff --git a/templates/layout.html b/templates/layout.html index 344950f..706e50f 100644 --- a/templates/layout.html +++ b/templates/layout.html @@ -15,10 +15,10 @@ specific language governing permissions and limitations under the License. {% block menu %} <h2>Table of Contents</h2> {{ super() }} -<h2>Quick Reference</h2> +<h2>Quick Reference Guides</h2> <ul> -<li><a href="{{ pathto('http-api') }}">HTTP API Reference</a></li> -<li><a href="{{ pathto('config-ref') }}">Configuration Reference</a></li> +<li><a href="{{ pathto('http-api') }}">API Quick Reference</a></li> +<li><a href="{{ pathto('config-ref') }}">Configuration Quick Reference</a></li> </ul> {% if local %} diff --git a/templates/pages/index.html b/templates/pages/index.html index 3d032a0..4c26bfc 100644 --- a/templates/pages/index.html +++ b/templates/pages/index.html @@ -16,10 +16,10 @@ specific language governing permissions and limitations under the License. {% extends "layout.html" %} {% set title = _('Overview') %} {% block body %} - <h1>{{ docstitle|e }}</h1> + <h1>Apache CouchDB<sup>®</sup> {{ release|e }} Documentation</h1> <p> {{ _('Welcome! This is') }} - {% block description %}{{ _('the documentation for') }} {{ project|e }} + {% block description %}{{ _('the documentation for') }} Apache CouchDB<sup>®</sup> {{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}{% endblock %}. </p> {% block tables %}