You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by de...@apache.org on 2013/10/01 15:46:11 UTC
[01/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Updated Branches:
refs/heads/replicator-redesign 494e45719 -> 066d69b2b (forced update)
Update intro response.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/71ec7568
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/71ec7568
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/71ec7568
Branch: refs/heads/replicator-redesign
Commit: 71ec7568627cae62b93e6785c8083a2e4f4cb4d7
Parents: b35bf75
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 17:29:07 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/intro.rst | 14 ++++++++++----
1 file changed, 10 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71ec7568/share/doc/src/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst
index 6f3603b..57eb235 100644
--- a/share/doc/src/intro.rst
+++ b/share/doc/src/intro.rst
@@ -227,10 +227,16 @@ clarity):
.. code-block:: json
- {
- "couchdb" : "Welcome",
- "version" : "|version|",
- }
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "vendor": {
+ "name": "The Apache Software Foundation",
+ "version": "1.4.0"
+ },
+ "version": "1.4.0"
+ }
+
.. note:: For some URLs, especially those that include special characters such
as ampersand, exclamation mark, or question mark, you should quote
[11/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Update images to 1.4.0
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/c5e0cc59
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/c5e0cc59
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/c5e0cc59
Branch: refs/heads/replicator-redesign
Commit: c5e0cc5937c0a4e23b8ad841cc58e995f823f226
Parents: 7ef3ef6
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 4 19:37:24 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/images/futon-editdoc.png | Bin 64369 -> 52733 bytes
share/doc/images/futon-editeddoc.png | Bin 69595 -> 56005 bytes
share/doc/images/futon-overview.png | Bin 63039 -> 50815 bytes
share/doc/images/futon-replform.png | Bin 68068 -> 52223 bytes
share/doc/images/intro-tour-01.png | Bin 56231 -> 50815 bytes
share/doc/images/intro-tour-02.png | Bin 125209 -> 83380 bytes
share/doc/images/intro-tour-03.png | Bin 62323 -> 53795 bytes
share/doc/images/intro-tour-04.png | Bin 72533 -> 56470 bytes
share/doc/images/intro-tour-05.png | Bin 73625 -> 53778 bytes
share/doc/images/intro-tour-06.png | Bin 78923 -> 61296 bytes
share/doc/images/intro-tour-07.png | Bin 121770 -> 47487 bytes
share/doc/images/intro-tour-08.png | Bin 130063 -> 83494 bytes
share/doc/images/intro-tour-09.png | Bin 131956 -> 84701 bytes
share/doc/images/intro-tour-10.png | Bin 88116 -> 61631 bytes
14 files changed, 0 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-editdoc.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-editdoc.png b/share/doc/images/futon-editdoc.png
index 6802c2c..f31dbbe 100644
Binary files a/share/doc/images/futon-editdoc.png and b/share/doc/images/futon-editdoc.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-editeddoc.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-editeddoc.png b/share/doc/images/futon-editeddoc.png
index 5c8b549..a5913bc 100644
Binary files a/share/doc/images/futon-editeddoc.png and b/share/doc/images/futon-editeddoc.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-overview.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-overview.png b/share/doc/images/futon-overview.png
index d1eac6e..e1daf5c 100644
Binary files a/share/doc/images/futon-overview.png and b/share/doc/images/futon-overview.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-replform.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-replform.png b/share/doc/images/futon-replform.png
index d904f0d..72b9ff5 100644
Binary files a/share/doc/images/futon-replform.png and b/share/doc/images/futon-replform.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-01.png b/share/doc/images/intro-tour-01.png
index 41b6420..e6fe9df 100644
Binary files a/share/doc/images/intro-tour-01.png and b/share/doc/images/intro-tour-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-02.png b/share/doc/images/intro-tour-02.png
index f263664..2c6f0cc 100644
Binary files a/share/doc/images/intro-tour-02.png and b/share/doc/images/intro-tour-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-03.png b/share/doc/images/intro-tour-03.png
index 47f013b..7137583 100644
Binary files a/share/doc/images/intro-tour-03.png and b/share/doc/images/intro-tour-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-04.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-04.png b/share/doc/images/intro-tour-04.png
index 33ceccc..7bc5678 100644
Binary files a/share/doc/images/intro-tour-04.png and b/share/doc/images/intro-tour-04.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-05.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-05.png b/share/doc/images/intro-tour-05.png
index 08042d7..972cb65 100644
Binary files a/share/doc/images/intro-tour-05.png and b/share/doc/images/intro-tour-05.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-06.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-06.png b/share/doc/images/intro-tour-06.png
index bb9c7c8..9f27df1 100644
Binary files a/share/doc/images/intro-tour-06.png and b/share/doc/images/intro-tour-06.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-07.png b/share/doc/images/intro-tour-07.png
index dc009a8..e75987d 100644
Binary files a/share/doc/images/intro-tour-07.png and b/share/doc/images/intro-tour-07.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-08.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-08.png b/share/doc/images/intro-tour-08.png
index 6976f57..4aa549b 100644
Binary files a/share/doc/images/intro-tour-08.png and b/share/doc/images/intro-tour-08.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-09.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-09.png b/share/doc/images/intro-tour-09.png
index f41b306..b850ade 100644
Binary files a/share/doc/images/intro-tour-09.png and b/share/doc/images/intro-tour-09.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-10.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-10.png b/share/doc/images/intro-tour-10.png
index e95bc66..68038bf 100644
Binary files a/share/doc/images/intro-tour-10.png and b/share/doc/images/intro-tour-10.png differ
[27/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
docs: basics.rst extend floating point explanation
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/2a8af951
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/2a8af951
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/2a8af951
Branch: refs/heads/replicator-redesign
Commit: 2a8af951019dcf9cf9032696a67f3a9732553a3a
Parents: 2375d00
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Fri Sep 27 20:46:21 2013 +0200
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Fri Sep 27 21:29:11 2013 +0200
----------------------------------------------------------------------
share/doc/src/api/basics.rst | 22 ++++++++++++++++------
1 file changed, 16 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2a8af951/share/doc/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/basics.rst b/share/doc/src/api/basics.rst
index d05ddb6..6a86f3c 100644
--- a/share/doc/src/api/basics.rst
+++ b/share/doc/src/api/basics.rst
@@ -223,7 +223,7 @@ below.
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
+ for those views would generate a new ETag for all view URLs in a
single design doc, even if that specific view's results had not
changed.
@@ -307,11 +307,15 @@ languages, including Perl, Python, Ruby, Erlang and others.
Number Handling
---------------
+Developers and users new to computer handling of numbers often encounter
+suprises when expecting that a number stored in JSON format does not
+necessarily return as the same number as compared character by character.
+
Any numbers defined in JSON that contain a decimal point or exponent
will be passed through the Erlang VM's idea of the "double" data type.
-Any numbers that are used in views will pass through the views idea of
-a number (the common JavaScript case means even integers pass through
-a double due to JavaScript's definition of a number).
+Any numbers that are used in views will pass through the view server's
+idea of a number (the common JavaScript case means even integers pass
+through a double due to JavaScript's definition of a number).
Consider this document that we write to CouchDB:
@@ -357,7 +361,7 @@ major parsers that we know about.
While we've only been discussing cases where the textual
representation changes, another important case is when an input value
-is contains more precision than can actually represented in a double.
+contains more precision than can actually represented in a double.
(You could argue that this case is actually "losing" data if you don't
accept that numbers are stored in doubles).
@@ -446,7 +450,7 @@ the 1.1 input as described above.
The important point to realize here is that a double can only hold a
finite number of values. What we're doing here is generating a string
that when passed through the "standard" floating point parsing
-algorithms (ie, strtod) will result in the same bit pattern in memory
+algorithms (ie, ``strtod``) will result in the same bit pattern in memory
as we started with. Or, slightly different, the bytes in a JSON
serialized number are chosen such that they refer to a single specific
value that a double can represent.
@@ -482,6 +486,12 @@ string or by using integer types (although integer types can still
bite you if you use a platform that has a different integer
representation than normal, ie, JavaScript).
+Further information can be found easily, including the
+`Floating Point Guide`_, and `David Goldberg's Reference`_.
+
+.. _Floating Point Guide: http://floating-point-gui.de/
+.. _David Goldberg's Reference: http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html
+
Also, if anyone is really interested in changing this behavior, we're
all ears for contributions to `jiffy`_ (which is theoretically going to
replace ejson when we get around to updating the build system). The
[14/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Import introduction to the API from Guide to CouchDB.
http://guide.couchdb.org/draft/api.html
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/360381ac
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/360381ac
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/360381ac
Branch: refs/heads/replicator-redesign
Commit: 360381ac07ede47ae26e80be17dcf3f75ce23ef5
Parents: 5562be1
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 7 20:44:09 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +
share/doc/src/intro/api.rst | 784 +++++++++++++++++++++++++++++++++++++
share/doc/src/intro/index.rst | 5 +
3 files changed, 792 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/360381ac/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 16ed5d6..bc4af7b 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -109,6 +109,7 @@ html_files = \
html/_sources/install/mac.txt \
html/_sources/install/unix.txt \
html/_sources/install/windows.txt \
+ html/_sources/intro/api.txt \
html/_sources/intro/consistency.txt \
html/_sources/intro/curl.txt \
html/_sources/intro/futon.txt \
@@ -222,6 +223,7 @@ html_files = \
html/install/mac.html \
html/install/unix.html \
html/install/windows.html \
+ html/intro/api.html \
html/intro/consistency.html \
html/intro/curl.html \
html/intro/futon.html \
@@ -357,6 +359,7 @@ src_files = \
../src/install/mac.rst \
../src/install/unix.rst \
../src/install/windows.rst \
+ ../src/intro/api.rst \
../src/intro/consistency.rst \
../src/intro/curl.rst \
../src/intro/futon.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/360381ac/share/doc/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/api.rst b/share/doc/src/intro/api.rst
new file mode 100644
index 0000000..f617df0
--- /dev/null
+++ b/share/doc/src/intro/api.rst
@@ -0,0 +1,784 @@
+.. 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.
+
+.. default-domain:: http
+
+.. _intro/api:
+
+============
+The Core API
+============
+
+This chapter explores the CouchDB in minute detail. It shows all the
+nitty-gritty and clever bits. We show you best practices and guide you around
+common pitfalls.
+
+We start out by revisiting the basic operations we ran in the last chapter,
+looking behind the scenes. We also show what Futon needs to do behind its
+user interface to give us the nice features we saw earlier.
+
+This chapter is both an introduction to the core CouchDB API as well as a
+reference. If you can't remember how to run a particular request or why some
+parameters are needed, you can always come back here and look things up (we
+are probably the heaviest users of this chapter).
+
+While explaining the API bits and pieces, we sometimes need to take a larger
+detour to explain the reasoning for a particular request. This is a good
+opportunity for us to tell you why CouchDB works the way it does.
+
+The API can be subdivided into the following sections. We'll explore them
+individually:
+
+.. contents::
+ :depth: 1
+ :local:
+
+
+Server
+======
+
+This one is basic and simple. It can serve as a sanity check to see if
+CouchDB is running at all. It can also act as a safety guard for libraries
+that require a certain version of CouchDB. We're using the `curl`_ utility
+again::
+
+ curl http://127.0.0.1:5984/
+
+CouchDB replies, all excited to get going:
+
+.. code-block:: javascript
+
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "vendor": {
+ "name": "The Apache Software Foundation",
+ "version": "1.4.0"
+ },
+ "version": "1.4.0"
+ }
+
+You get back a JSON string, that, if parsed into a native object or data
+structure of your programming language, gives you access to the welcome
+string and version information.
+
+This is not terribly useful, but it illustrates nicely the way CouchDB
+behaves. You send an HTTP request and you receive a JSON string in the HTTP
+response as a result.
+
+.. _curl: http://curl.haxx.se/
+
+
+Databases
+=========
+
+Now let's do something a little more useful: *create databases*.
+For the strict, CouchDB is a *database management system* (DMS). That means it
+can hold multiple databases. A database is a bucket that holds "related data".
+We'll explore later what that means exactly. In practice, the terminology is
+overlapping -- often people refer to a DMS as "a database" and also a database
+within the DMS as "a database." We might follow that slight oddity, so don't
+get confused by it. In general, it should be clear from the context if we are
+talking about the whole of CouchDB or a single database within CouchDB.
+
+Now let's make one! We want to store our favorite music albums,
+and we creatively give our database the name albums. Note that we're now
+using the ``-X`` option again to tell curl to send a :method:`PUT` request
+instead of the default :method:`GET` request::
+
+ curl -X PUT http://127.0.0.1:5984/albums
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+That's it. You created a database and CouchDB told you that all went well.
+What happens if you try to create a database that already exists? Let's try
+to create that database again::
+
+ curl -X PUT http://127.0.0.1:5984/albums
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"error":"file_exists","reason":"The database could not be created, the file already exists."}
+
+We get back an error. This is pretty convenient. We also learn a little bit
+about how CouchDB works. CouchDB stores each database in a single file.
+Very simple.
+
+Let's create another database, this time with curl's ``-v`` (for "verbose")
+option. The verbose option tells curl to show us not only the essentials --
+the HTTP response body -- but all the underlying request and response details::
+
+ curl -vX PUT http://127.0.0.1:5984/albums-backup
+
+curl elaborates::
+
+ * About to connect() to 127.0.0.1 port 5984 (#0)
+ * Trying 127.0.0.1... connected
+ * Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
+ > PUT /albums-backup HTTP/1.1
+ > User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
+ > Host: 127.0.0.1:5984
+ > Accept: */*
+ >
+ < HTTP/1.1 201 Created
+ < Server: CouchDB/0.9.0 (Erlang OTP/R12B)
+ < Date: Sun, 05 Jul 2009 22:48:28 GMT
+ < Content-Type: text/plain;charset=utf-8
+ < Content-Length: 12
+ < Cache-Control: must-revalidate
+ <
+ {"ok":true}
+ * Connection #0 to host 127.0.0.1 left intact
+ * Closing connection #0
+
+What a mouthful. Let's step through this line by line to understand what's
+going on and find out what's important. Once you've seen this output a few
+times, you'll be able to spot the important bits more easily.
+
+::
+
+ * About to connect() to 127.0.0.1 port 5984 (#0)
+
+This is curl telling us that it is going to establish a TCP connection to the
+CouchDB server we specified in our request URI. Not at all important,
+except when debugging networking issues.
+
+::
+
+ * Trying 127.0.0.1... connected
+ * Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
+
+curl tells us it successfully connected to CouchDB. Again,
+not important if you aren't trying to find problems with your network.
+
+The following lines are prefixed with ``>`` and ``<`` characters.
+The ``>`` means the line was sent to CouchDB verbatim (without the actual
+``>``). The ``<`` means the line was sent back to curl by CouchDB.
+
+::
+
+ > PUT /albums-backup HTTP/1.1
+
+This initiates an HTTP request. Its *method* is :method:`PUT`, the *URI* is
+``/albums-backup``, and the HTTP version is ``HTTP/1.1``. There is also
+``HTTP/1.0``, which is simpler in some cases, but for all practical reasons
+you should be using ``HTTP/1.1``.
+
+Next, we see a number of *request headers*. These are used to provide
+additional details about the request to CouchDB.
+
+::
+
+ > User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
+
+The User-Agent header tells CouchDB which piece of client software is doing
+the HTTP request. We don't learn anything new: it's curl. This header is
+often useful in web development when there are known errors in client
+implementations that a server might want to prepare the response for.
+It also helps to determine which platform a user is on. This information
+can be used for technical and statistical reasons. For CouchDB, the
+:header:`User-Agent` header is irrelevant.
+
+::
+
+ > Host: 127.0.0.1:5984
+
+The :header:`Host` header is required by ``HTTP 1.1``. It tells the server
+the hostname that came with the request.
+
+::
+
+ > Accept: */*
+
+The :header:`Accept` header tells CouchDB that curl accepts any media type.
+We'll look into why this is useful a little later.
+
+::
+
+ >
+
+An empty line denotes that the request headers are now finished and the rest
+of the request contains data we're sending to the server. In this case,
+we're not sending any data, so the rest of the curl output is dedicated to
+the HTTP response.
+
+::
+
+ < HTTP/1.1 201 Created
+
+The first line of CouchDB's HTTP response includes the HTTP version
+information (again, to acknowledge that the requested version could be
+processed), an HTTP *status code*, and a *status code message*.
+Different requests trigger different response codes. There's a whole range of
+them telling the client (curl in our case) what effect the request had on the
+server. Or, if an error occurred, what kind of error. :rfc:`2616` (the HTTP 1.1
+specification) defines clear behavior for response codes. CouchDB fully
+follows the RFC.
+
+The :statuscode:`201` status code tells the client that the resource
+the request was made against was successfully created. No surprise here,
+but if you remember that we got an error message when we tried to create this
+database twice, you now know that this response could include a different
+response code. Acting upon responses based on response codes is a common
+practice. For example, all response codes of :statuscode:`400` or larger
+tell you that some error occurred. If you want to shortcut your logic and
+immediately deal with the error, you could just check a >= ``400`` response
+code.
+
+::
+
+ < Server: CouchDB/0.10.1 (Erlang OTP/R13B)
+
+The :header:`Server` header is good for diagnostics. It tells us which
+CouchDB version and which underlying Erlang version we are talking to.
+In general, you can ignore this header, but it is good to know it's there if
+you need it.
+
+::
+
+ < Date: Sun, 05 Jul 2009 22:48:28 GMT
+
+The :header:`Date` header tells you the time of the server. Since client
+and server time are not necessarily synchronized, this header is purely
+informational. You shouldn't build any critical application logic on top
+of this!
+
+::
+
+ < Content-Type: text/plain;charset=utf-8
+
+The :header:`Content-Type` header tells you which MIME type
+the HTTP response body is and its encoding. We already know CouchDB returns
+JSON strings. The appropriate :header:`Content-Type` header is
+:mimetype:`application/json`. Why do we see :mimetype:`text/plain`?
+This is where pragmatism wins over purity. Sending an
+:mimetype:`application/json` :header:`Content-Type` header will make
+a browser offer you the returned JSON for download instead of
+just displaying it. Since it is extremely useful to be able to test CouchDB
+from a browser, CouchDB sends a :mimetype:`text/plain` content type, so all
+browsers will display the JSON as text.
+
+.. note::
+
+ There are some extensions that make your browser JSON-aware,
+ but they are not installed by default. For more information, look at
+ the popular `JSONView`_ extension, available for both Firefox and Chrome.
+
+ .. _JSONView: http://jsonview.com/
+
+Do you remember the :header:`Accept` request header and how it is set to
+``\*/\* -> */*`` to express interest in any MIME type? If you send ``Accept:
+application/json`` in your request, CouchDB knows that you can deal with a pure
+JSON response with the proper :header:`Content-Type` header and will
+use it instead of :mimetype:`text/plain`.
+
+::
+
+ < Content-Length: 12
+
+The :header:`Content-Length` header simply tells us how many bytes
+the response body has.
+
+::
+
+ < Cache-Control: must-revalidate
+
+This :header:`Cache-Control` header tells you, or any proxy server between
+CouchDB and you, not to cache this response.
+
+::
+
+ <
+
+This empty line tells us we're done with the response headers and what
+follows now is the response body.
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+We've seen this before.
+
+::
+
+ * Connection #0 to host 127.0.0.1 left intact
+ * Closing connection #0
+
+The last two lines are curl telling us that it kept the TCP connection it
+opened in the beginning open for a moment, but then closed it after it
+received the entire response.
+
+Throughout the book, we'll show more requests with the ``-v`` option,
+but we'll omit some of the headers we've seen here and include only those
+that are important for the particular request.
+
+Creating databases is all fine, but how do we get rid of one? Easy -- just
+change the HTTP method::
+
+ > curl -vX DELETE http://127.0.0.1:5984/albums-backup
+
+This deletes a CouchDB database. The request will remove the file that the
+database contents are stored in. There is no *"Are you sure?"* safety net or
+any *"Empty the trash"* magic you've got to do to delete a database. Use this
+command with care. Your data will be deleted without a chance to bring it
+back easily if you don't have a backup copy.
+
+This section went knee-deep into HTTP and set the stage for discussing the
+rest of the core CouchDB API. Next stop: documents.
+
+
+Documents
+=========
+
+.. _GUID: http://en.wikipedia.org/wiki/Globally_unique_identifier
+.. _UUID: http://en.wikipedia.org/wiki/Universally_unique_identifier
+
+Documents are CouchDB's central data structure. The idea behind a document
+is, unsurprisingly, that of a real-world document -- a sheet of paper such as
+an invoice, a recipe, or a business card. We already learned that CouchDB uses
+the JSON format to store documents. Let's see how this storing works at the
+lowest level.
+
+Each document in CouchDB has an *ID*. This ID is unique per database. You are
+free to choose any string to be the ID, but for best results we recommend a
+`UUID`_ (or `GUID`_), i.e., a Universally (or Globally) Unique IDentifier.
+UUIDs are random numbers that have such a low collision probability that
+everybody can make thousands of UUIDs a minute for millions of years without
+ever creating a duplicate. This is a great way to ensure two independent people
+cannot create two different documents with the same ID. Why should you care
+what somebody else is doing? For one, that somebody else could be you at a
+later time or on a different computer; secondly, CouchDB replication lets you
+share documents with others and using UUIDs ensures that it all works.
+But more on that later; let's make some documents::
+
+ curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"1-2902191555"}
+
+The curl command appears complex, but let's break it down.
+First, ``-X PUT`` tells curl to make a :method:`PUT` request.
+It is followed by the URL that specifies your CouchDB IP address and port.
+The resource part of the URL ``/albums/6e1295ed6c29495e54cc05947f18c8af``
+specifies the location of a document inside our albums database.
+The wild collection of numbers and characters is a UUID. This UUID is your
+document's ID. Finally, the ``-d`` flag tells curl to use the following
+string as the body for the :method:`PUT` request. The string is a simple JSON
+structure including ``title`` and ``artist`` attributes with their respective
+values.
+
+.. note::
+
+ If you don't have a UUID handy, you can ask CouchDB to give you one (in fact,
+ that is what we did just now without showing you). Simply send a
+ :get:`/_uuids` request::
+
+ curl -X GET http://127.0.0.1:5984/_uuids
+
+ CouchDB replies:
+
+ .. code-block:: javascript
+
+ {"uuids":["6e1295ed6c29495e54cc05947f18c8af"]}
+
+ Voilà, a UUID. If you need more than one, you can pass in the ``?count=10`` HTTP
+ parameter to request 10 UUIDs, or really, any number you need.
+
+To double-check that CouchDB isn't lying about having saved your document (it
+usually doesn't), try to retrieve it by sending a GET request::
+
+ curl -X GET http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
+
+We hope you see a pattern here. Everything in CouchDB has an address, a URI,
+and you use the different HTTP methods to operate on these URIs.
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"_id":"6e1295ed6c29495e54cc05947f18c8af","_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters"}
+
+This looks a lot like the document you asked CouchDB to save, which is good.
+But you should notice that CouchDB added two fields to your JSON structure.
+The first is ``_id``, which holds the UUID we asked CouchDB to save our document
+under. We always know the ID of a document if it is included, which is very
+convenient.
+
+The second field is ``_rev``. It stands for *revision*.
+
+Revisions
+---------
+
+If you want to change a document in CouchDB, you don't tell it to go and find
+a field in a specific document and insert a new value. Instead, you load
+the full document out of CouchDB, make your changes in the JSON structure
+(or object, when you are doing actual programming), and save the entire new
+revision (or version) of that document back into CouchDB. Each revision is
+identified by a new ``_rev`` value.
+
+If you want to update or delete a document, CouchDB expects you to include
+the ``_rev`` field of the revision you wish to change. When CouchDB accepts
+the change, it will generate a new revision number. This mechanism ensures that,
+in case somebody else made a change without you knowing before you got to
+request the document update, CouchDB will not accept your update because you
+are likely to overwrite data you didn't know existed. Or simplified: whoever
+saves a change to a document first, wins. Let's see what happens if we don't
+provide a ``_rev`` field (which is equivalent to providing a outdated value)::
+
+ curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
+ -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"error":"conflict","reason":"Document update conflict."}
+
+If you see this, add the latest revision number of your document to the JSON
+structure::
+
+ curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
+ -d '{"_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
+
+Now you see why it was handy that CouchDB returned that ``_rev`` when we made
+the initial request. CouchDB replies:
+
+.. code-block:: javascript
+
+ {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"2-8aff9ee9d06671fa89c99d20a4b3ae"}
+
+CouchDB accepted your write and also generated a new revision number.
+The revision number is the *MD5 hash* of the transport representation of a
+document with an ``N-`` prefix denoting the number of times a document got
+updated. This is useful for replication. See :ref:`replication/conflicts` for
+more information.
+
+There are multiple reasons why CouchDB uses this revision system,
+which is also called Multi-Version Concurrency Control (`MVCC`_). They all work
+hand-in-hand, and this is a good opportunity to explain some of them.
+
+.. _MVCC: http://en.wikipedia.org/wiki/Multiversion_concurrency_control
+
+One of the aspects of the HTTP protocol that CouchDB uses is that it is
+stateless. What does that mean? When talking to CouchDB you need to make
+requests. Making a request includes opening a network connection to CouchDB,
+exchanging bytes, and closing the connection. This is done every time you
+make a request. Other protocols allow you to open a connection, exchange bytes,
+keep the connection open, exchange more bytes later -- maybe depending on the
+bytes you exchanged at the beginning -- and eventually close the connection.
+Holding a connection open for later use requires the server to do extra work.
+One common pattern is that for the lifetime of a connection, the client has
+a consistent and static view of the data on the server. Managing huge amounts
+of parallel connections is a significant amount of work. HTTP connections are
+usually short-lived, and making the same guarantees is a lot easier.
+As a result, CouchDB can handle many more concurrent connections.
+
+Another reason CouchDB uses MVCC is that this model is simpler conceptually
+and, as a consequence, easier to program. CouchDB uses less code to make this
+work, and less code is always good because the ratio of defects per lines of
+code is static.
+
+The revision system also has positive effects on replication and storage
+mechanisms, but we'll explore these later in the book.
+
+.. warning::
+
+ The terms *version* and *revision* might sound familiar (if you are
+ programming without version control, drop this book right now and 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**.
+
+
+Documents in Detail
+-------------------
+
+Now let's have a closer look at our document creation requests with the curl
+``-v`` flag that was helpful when we explored the database API earlier.
+This is also a good opportunity to create more documents that we can use in
+later examples.
+
+We'll add some more of our favorite music albums. Get a fresh UUID from the
+``/_uuids`` resource. If you don't remember how that works, you can look it up
+a few pages back.
+
+::
+
+ curl -vX PUT http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 \
+ -d '{"title":"Blackened Sky","artist":"Biffy Clyro","year":2002}'
+
+.. note::
+
+ By the way, if you happen to know more information about your favorite
+ albums, don't hesitate to add more properties. And don't worry about not
+ knowing all the information for all the albums. CouchDB's schema-less
+ documents can contain whatever you know. After all, you should relax and not
+ worry about data.
+
+Now with the ``-v`` option, CouchDB's reply (with only the important bits shown)
+looks like this::
+
+ > PUT /albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 HTTP/1.1
+ >
+ < HTTP/1.1 201 Created
+ < Location: http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0
+ < ETag: "1-e89c99d29d06671fa0a4b3ae8aff9e"
+ <
+ {"ok":true,"id":"70b50bfa0a4b3aed1f8aff9e92dc16a0","rev":"1-e89c99d29d06671fa0a4b3ae8aff9e"}
+
+We're getting back the :statuscode:`201` HTTP status code in the response
+headers, as we saw earlier when we created a database. The :header:`Location`
+header gives us a full URL to our newly created document. And there's a new
+header. An :header:`ETag` in HTTP-speak identifies a specific version of a
+resource. In this case, it identifies a specific version (the first one) of our
+new document. Sound familiar? Yes, conceptually, an :header:`ETag` is the same
+as a CouchDB document revision number, and it shouldn't come as a surprise that
+CouchDB uses revision numbers for ETags. ETags are useful for caching
+infrastructures.
+
+
+Attachments
+-----------
+
+CouchDB documents can have attachments just like an email message can have
+attachments. An attachment is identified by a name and includes its MIME type
+(or :header:`Content-Type`) and the number of bytes the attachment
+contains. Attachments can be any data. It is easiest to think about attachments
+as files attached to a document. These files can be text, images, Word
+documents, music, or movie files. Let's make one.
+
+Attachments get their own URL where you can upload data. Say we want to add
+the album artwork to the ``6e1295ed6c29495e54cc05947f18c8af`` document
+(*"There is Nothing Left to Lose"*), and let's also say the artwork is in a file
+artwork `.jpg` in the current directory::
+
+ curl -vX PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg?rev=2-2739352689 \
+ --data-binary @artwork.jpg -H "Content-Type:image/jpg"
+
+.. note::
+
+ The ``--data-binary`` ``@`` option tells curl to read a file's contents into
+ the HTTP request body. We're using the ``-H`` option to tell CouchDB that
+ we're uploading a JPEG file. CouchDB will keep this information around and
+ will send the appropriate header when requesting this attachment; in case of
+ an image like this, a browser will render the image instead of offering you
+ the data for download. This will come in handy later. Note that you need
+ to provide the current revision number of the document you're attaching
+ the artwork to, just as if you would update the document. Because, after all,
+ attaching some data is changing the document.
+
+You should now see your artwork image if you point your browser to
+http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg
+
+If you request the document again, you'll see a new member::
+
+ curl http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {
+ "_id": "6e1295ed6c29495e54cc05947f18c8af",
+ "_rev": "3-131533518",
+ "title": "There is Nothing Left to Lose",
+ "artist": "Foo Fighters",
+ "year": "1997",
+ "_attachments": {
+ "artwork.jpg": {
+ "stub": true,
+ "content_type": "image/jpg",
+ "length": 52450
+ }
+ }
+ }
+
+``_attachments`` is a list of keys and values where the values are JSON objects
+containing the attachment metadata. ``stub=true`` tells us that this entry is
+just the metadata. If we use the ``?attachments=true`` HTTP option when
+requesting this document, we'd get a `Base64`_ encoded string containing the
+attachment data.
+
+.. _Base64: http://en.wikipedia.org/wiki/Base64
+
+We'll have a look at more document request options later as we explore more
+features of CouchDB, such as replication, which is the next topic.
+
+
+Replication
+===========
+
+CouchDB replication is a mechanism to synchronize databases. Much like `rsync`_
+synchronizes two directories locally or over a network, replication synchronizes
+two databases locally or remotely.
+
+.. _rsync: http://en.wikipedia.org/wiki/Rsync
+
+In a simple :method:`POST` request, you tell CouchDB the *source* and the
+*target* of a replication and CouchDB will figure out which documents and new
+document revisions are on *source* that are not yet on *target*, and will
+proceed to move the missing documents and revisions over.
+
+We'll take an in-depth look at replication later in the book; in this
+chapter, we'll just show you how to use it.
+
+First, we'll create a target database. Note that CouchDB won't automatically
+create a target database for you, and will return a replication failure if
+the target doesn't exist (likewise for the source, but that mistake isn't as
+easy to make)::
+
+ curl -X PUT http://127.0.0.1:5984/albums-replica
+
+Now we can use the database `albums-replica` as a replication target::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"albums","target":"albums-replica"}' \
+ -H "Content-Type: application/json"
+
+.. note::
+
+ CouchDB supports the option ``"create_target":true`` placed in the JSON POSTed
+ to the :ref:`_replicate <api/server/replicate>` URL. It implicitly creates
+ the target database if it doesn't exist.
+
+CouchDB replies (this time we formatted the output so you can read it more
+easily):
+
+.. code-block:: javascript
+
+ {
+ "history": [
+ {
+ "start_last_seq": 0,
+ "missing_found": 2,
+ "docs_read": 2,
+ "end_last_seq": 5,
+ "missing_checked": 2,
+ "docs_written": 2,
+ "doc_write_failures": 0,
+ "end_time": "Sat, 11 Jul 2009 17:36:21 GMT",
+ "start_time": "Sat, 11 Jul 2009 17:36:20 GMT"
+ }
+ ],
+ "source_last_seq": 5,
+ "session_id": "924e75e914392343de89c99d29d06671",
+ "ok": true
+ }
+
+CouchDB maintains a *session history* of replications. The response for a
+replication request contains the history entry for this *replication session*.
+It is also worth noting that the request for replication will stay open until
+replication closes. If you have a lot of documents, it'll take a while until
+they are all replicated and you won't get back the replication response
+until all documents are replicated. It is important to note that
+replication replicates the database only as it was at the point in time
+when replication was started. So, any additions, modifications,
+or deletions subsequent to the start of replication will not be replicated.
+
+We'll punt on the details again -- the ``"ok": true`` at the end tells us all
+went well. If you now have a look at the albums-replica database,
+you should see all the documents that you created in the albums database.
+Neat, eh?
+
+What you just did is called local replication in CouchDB terms. You created a
+local copy of a database. This is useful for backups or to keep snapshots of
+a specific state of your data around for later. You might want to do this
+if you are developing your applications but want to be able to roll back to
+a stable version of your code and data.
+
+There are more types of replication useful in other situations. The source
+and target members of our replication request are actually links (like in
+HTML) and so far we've seen links relative to the server we're working on
+(hence local). You can also specify a remote database as the target::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"albums","target":"http://example.org:5984/albums-replica"}' \
+ -H "Content-Type:application/json"
+
+Using a *local source* and a *remote target* database is called *push
+replication*. We're pushing changes to a remote server.
+
+.. note::
+
+ Since we don't have a second CouchDB server around just yet, we'll just use
+ the absolute address of our single server, but you should be able to infer
+ from this that you can put any remote server in there.
+
+This is great for sharing local changes with remote servers or buddies next
+door.
+
+You can also use a *remote source* and a *local target* to do a *pull
+replication*. This is great for getting the latest changes from a server that
+is used by others::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"http://example.org:5984/albums-replica","target":"albums"}' \
+ -H "Content-Type:application/json"
+
+Finally, you can run remote replication, which is mostly useful for management
+operations::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"http://example.org:5984/albums","target":"http://example.org:5984/albums-replica"}' \
+ -H"Content-Type: application/json"
+
+.. note::
+
+ **CouchDB and REST**
+
+ CouchDB prides itself on having a `RESTful`_ API, but these replication
+ requests don't look very RESTy to the trained eye. What's up with that?
+ While CouchDB's core database, document, and attachment API are RESTful,
+ not all of CouchDB's API is. The replication API is one example. There are
+ more, as we'll see later in the book.
+
+ Why are there RESTful and non-RESTful APIs mixed up here? Have the developers
+ been too lazy to go REST all the way? Remember, REST is an architectural
+ style that lends itself to certain architectures (such as the CouchDB
+ document API). But it is not a one-size-fits-all. Triggering an event like
+ replication does not make a whole lot of sense in the REST world. It is more
+ like a traditional remote procedure call. And there is nothing wrong with
+ this.
+
+ We very much believe in the "use the right tool for the job" philosophy,
+ and REST does not fit every job. For support, we refer to Leonard Richardson
+ and Sam Ruby who wrote `RESTful Web Services`_ (O'Reilly), as they share our
+ view.
+
+ .. _RESTful: http://en.wikipedia.org/wiki/Representational_state_transfer
+ .. _RESTful Web Services: http://oreilly.com/catalog/9780596529260
+
+
+Wrapping Up
+===========
+
+This is still not the full CouchDB API, but we discussed the essentials in
+great detail. We're going to fill in the blanks as we go. For now, we believe
+you're ready to start building CouchDB applications.
+
+.. seealso::
+
+ :ref:`Complete HTTP API Reference <api>`:
+
+ - :ref:`Server API Reference <api/server>`
+ - :ref:`Database API Reference <api/database>`
+ - :ref:`Document API Reference <api/document>`
+ - :ref:`Replication API <api/server/replicate>`
http://git-wip-us.apache.org/repos/asf/couchdb/blob/360381ac/share/doc/src/intro/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/index.rst b/share/doc/src/intro/index.rst
index 900dca2..a934fae 100644
--- a/share/doc/src/intro/index.rst
+++ b/share/doc/src/intro/index.rst
@@ -37,6 +37,10 @@ consistent <intro/consistency>`. And we care *a lot* about your data.
CouchDB has a fault-tolerant storage engine that puts the safety of your data
first.
+In this section you'll learn about every basic bit of CouchDB, see upon what
+conceptions and technologies it built and walk through short tutorial that
+teach how to use CouchDB.
+
.. _distributed scaling: http://en.wikipedia.org/wiki/CAP_theorem
.. toctree::
@@ -46,5 +50,6 @@ first.
why
consistency
tour
+ api
futon
curl
[33/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Update Fauxton docs links.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a00c6a48
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a00c6a48
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a00c6a48
Branch: refs/heads/replicator-redesign
Commit: a00c6a48b059f8c48adf56cf7836f639fa7446ec
Parents: a169ab6
Author: Alexander Shorin <kx...@apache.org>
Authored: Fri Sep 27 22:37:48 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 08:52:31 2013 +0400
----------------------------------------------------------------------
src/fauxton/app/helpers.js | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a00c6a48/src/fauxton/app/helpers.js
----------------------------------------------------------------------
diff --git a/src/fauxton/app/helpers.js b/src/fauxton/app/helpers.js
index d6ea966..a8e0698 100644
--- a/src/fauxton/app/helpers.js
+++ b/src/fauxton/app/helpers.js
@@ -36,13 +36,13 @@ function() {
// update the URLs in documentation_urls.js
Helpers.docs = {
"docs": "http://docs.couchdb.org/en/latest/index.html",
- "replication_doc": "http://docs.couchdb.org/en/latest/replicator.html#basics",
- "design_doc": "http://docs.couchdb.org/en/latest/ddocs.html#design-docs",
- "view_functions": "http://docs.couchdb.org/en/latest/ddocs.html#view-functions",
- "map_functions": "http://docs.couchdb.org/en/latest/ddocs.html#map-functions",
- "reduce_functions": "http://docs.couchdb.org/en/latest/ddocs.html#reduce-and-rereduce-functions",
- "api_reference": "http://docs.couchdb.org/en/latest/api-basics.html?highlight=api",
- "database_permission": "http://docs.couchdb.org/en/latest/api/database.html#get-db-security"
+ "replication_doc": "http://docs.couchdb.org/en/latest/replication/replicator.html#basics",
+ "design_doc": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#design-docs",
+ "view_functions": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#view-functions",
+ "map_functions": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#map-functions",
+ "reduce_functions": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#reduce-and-rereduce-functions",
+ "api_reference": "http://docs.couchdb.org/en/latest/http-api.html",
+ "database_permission": "http://docs.couchdb.org/en/latest/api/database/security.html#db-security"
};
Helpers.getDocUrl = function(doc){
[25/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Describe some performance tips.
Source: http://wiki.apache.org/couchdb/Performance
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/71abc8f1
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/71abc8f1
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/71abc8f1
Branch: refs/heads/replicator-redesign
Commit: 71abc8f1672cdabc5fa66f5ad706f7b8eee9e51f
Parents: 47ff863
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Sep 8 22:20:30 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +
share/doc/src/maintenance/index.rst | 1 +
share/doc/src/maintenance/performance.rst | 295 +++++++++++++++++++++++++
3 files changed, 299 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71abc8f1/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index f59e557..c13f8a2 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -119,6 +119,7 @@ html_files = \
html/_sources/intro/why.txt \
html/_sources/maintenance/compaction.txt \
html/_sources/maintenance/index.txt \
+ html/_sources/maintenance/performance.txt \
html/_sources/query-server/index.txt \
html/_sources/query-server/erlang.txt \
html/_sources/query-server/javascript.txt \
@@ -235,6 +236,7 @@ html_files = \
html/intro/why.html \
html/maintenance/compaction.html \
html/maintenance/index.html \
+ html/maintenance/performance.html \
html/query-server/index.html \
html/query-server/erlang.html \
html/query-server/javascript.html \
@@ -373,6 +375,7 @@ src_files = \
../src/intro/why.rst \
../src/maintenance/compaction.rst \
../src/maintenance/index.rst \
+ ../src/maintenance/performance.rst \
../src/query-server/index.rst \
../src/query-server/erlang.rst \
../src/query-server/javascript.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71abc8f1/share/doc/src/maintenance/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/index.rst b/share/doc/src/maintenance/index.rst
index 86cc761..b0072fe 100644
--- a/share/doc/src/maintenance/index.rst
+++ b/share/doc/src/maintenance/index.rst
@@ -18,3 +18,4 @@ CouchDB Maintenance
.. toctree::
compaction
+ performance
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71abc8f1/share/doc/src/maintenance/performance.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/performance.rst b/share/doc/src/maintenance/performance.rst
new file mode 100644
index 0000000..918b1cf
--- /dev/null
+++ b/share/doc/src/maintenance/performance.rst
@@ -0,0 +1,295 @@
+.. 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.
+
+.. default-domain:: http
+
+
+.. _performance:
+
+===========
+Performance
+===========
+
+With up to tens of thousands of documents you will generally find CouchDB to
+perform well no matter how you write your code. Once you start getting into
+the millions of documents you need to be a lot more careful.
+
+
+Disk I/O
+========
+
+File Size
+---------
+
+The smaller your file size, the less `I/O` operations there will be,
+the more of the file can be cached by CouchDB and the operating system,
+the quicker it is to replicate, backup etc. Consequently you should carefully
+examine the data you are storing. For example it would be silly to use keys
+that are hundreds of characters long, but your program would be hard to
+maintain if you only used single character keys. Carefully consider data
+that is duplicated by putting it in views.
+
+
+Disk and File System Performance
+--------------------------------
+
+Using faster disks, striped RAID arrays and modern file systems can all speed
+up your CouchDB deployment. However, there is one option that can increase
+the responsiveness of your CouchDB server when disk performance is a
+bottleneck. From the Erlang documentation for the file module:
+
+ On operating systems with thread support, it is possible to let file
+ operations be performed in threads of their own, allowing other Erlang
+ processes to continue executing in parallel with the file operations.
+ See the `command line flag +A in erl(1)`_.
+
+Setting this argument to a number greater than zero can keep your CouchDB
+installation responsive even during periods of heavy disk utilization. The
+easiest way to set this option is through the ``ERL_FLAGS`` environment
+variable. For example, to give Erlang four threads with which to perform I/O
+operations add the following to ``(prefix)/etc/defaults/couchdb``
+(or equivalent)::
+
+ export ERL_FLAGS="+A 4"
+
+
+.. _command line flag +A in erl(1): http://erlang.org/doc/man/erl.html
+
+
+System Resource Limits
+======================
+
+One of the problems that administrators run into as their deployments become
+large are resource limits imposed by the system and by the application
+configuration. Raising these limits can allow your deployment to grow beyond
+what the default configuration will support.
+
+
+CouchDB Configuration Options
+-----------------------------
+
+delayed_commits
+^^^^^^^^^^^^^^^
+
+The :ref:`delayed commits <config/couchdb/delayed_commits>` allows it to
+achieve better write performance for some workloads while sacrificing a small
+amount of durability. The setting causes CouchDB to wait up to a full second
+before committing new data after an update. If the server crashes before
+the header is written then any writes since the last commit are lost. Keep this
+option enabled on your own risk.
+
+max_dbs_open
+^^^^^^^^^^^^
+
+In your :ref:`configuration <config>` (local.ini or similar) familiarize
+yourself with the :ref:`max_dbs_open <config/couchdb/max_dbs_open>`:
+
+.. code-block:: ini
+
+ [couchdb]
+ max_dbs_open = 100
+
+This option places an upper bound on the number of databases that can be
+open at one time. CouchDB reference counts database accesses internally and
+will close idle databases when it must. Sometimes it is necessary to keep
+more than the default open at once, such as in deployments where many databases
+will be continuously replicating.
+
+
+Erlang
+------
+
+Even if you've increased the maximum connections CouchDB will allow,
+the Erlang runtime system will not allow more than 1024 connections by
+default. Adding the following directive to ``(prefix)/etc/default/couchdb`` (or
+equivalent) will increase this limit (in this case to 4096)::
+
+ export ERL_MAX_PORTS=4096
+
+CouchDB versions up to 1.1.x also create Erlang Term Storage (`ETS`_) tables for
+each replication. If you are using a version of CouchDB older than 1.2 and
+must support many replications, also set the ``ERL_MAX_ETS_TABLES`` variable.
+The default is approximately 1400 tables.
+
+Note that on Mac OS X, Erlang will not actually increase the file descriptor
+limit past 1024 (i.e. the system header–defined value of ``FD_SETSIZE``). See
+`this tip for a possible workaround`_ and `this thread for a deeper
+explanation`_.
+
+.. _ETS: http://www.erlang.org/doc/man/ets.html
+.. _this tip for a possible workaround: http://erlang.org/pipermail/erlang-questions/2011-December/063119.html
+.. _this thread for a deeper explanation: http://erlang.org/pipermail/erlang-questions/2011-October/061971.html
+
+
+PAM and ulimit
+--------------
+
+Finally, most \*nix operating systems impose various resource limits on every
+process. If your system is set up to use the Pluggable Authentication Modules
+(`PAM`_) system, increasing this limit is straightforward. For example,
+creating a file named ``/etc/security/limits.d/100-couchdb.conf`` with the
+following contents will ensure that CouchDB can open enough file descriptors
+to service your increased maximum open databases and Erlang ports::
+
+ #<domain> <type> <item> <value>
+ couchdb hard nofile 4096
+ couchdb soft nofile 4096
+
+If your system does not use PAM, a `ulimit` command is usually available for
+use in a custom script to launch CouchDB with increased resource limits.
+If necessary, feel free to increase this limits as long as your hardware can
+handle the load.
+
+.. _PAM: http://www.linux-pam.org/
+
+
+Network
+=======
+
+There is latency overhead making and receiving each request/response.
+In general you should do your requests in batches. Most APIs have some
+mechanism to do batches, usually by supplying lists of documents or keys in
+the request body. Be careful what size you pick for the batches. The larger
+batch requires more time your client has to spend encoding the items into JSON
+and more time is spent decoding that number of responses. Do some benchmarking
+with your own configuration and typical data to find the sweet spot.
+It is likely to be between one and ten thousand documents.
+
+If you have a fast I/O system then you can also use concurrency - have
+multiple requests/responses at the same time. This mitigates the latency
+involved in assembling JSON, doing the networking and decoding JSON.
+
+As of CouchDB 1.1.0, users often report lower write performance of documents
+compared to older releases. The main reason is that this release ships with
+the more recent version of the HTTP server library Mochiweb, which by default
+sets the TCP socket option `SO_NODELAY`_ to false. This means that small data
+sent to the TCP socket, like the reply to a document write request (or reading
+a very small document), will not be sent immediately to the network - TCP will
+buffer it for a while hoping that it will be asked to send more data through
+the same socket and then send all the data at once for increased performance.
+This TCP buffering behaviour can be disabled via :ref:`socket_options
+<config/httpd/socket_options>`:
+
+.. code-block:: ini
+
+ [httpd]
+ socket_options = [{nodelay, true}]
+
+.. _SO_NODELAY: http://en.wikipedia.org/wiki/Nagle%27s_algorithm
+
+.. seealso::
+
+ Bulk :ref:`load <api/db/all_docs>` and :ref:`store <api/db/bulk_docs>` API.
+
+
+CouchDB
+=======
+
+DELETE operation
+----------------
+
+When you :method:`DELETE` a document the database will create a new
+revision which contains the ``_id`` and ``_rev`` fields as well as
+the `_deleted` flag. This revision will remain even after a `database
+compaction` so that the deletion can be replicated. Deleted documents, like
+non-deleted documents, can affect view build times, :method:`PUT` and
+:method:`DELETE` requests time and size of database on disk, since they
+increase the size of the B+Tree's. You can see the number of deleted documents
+in :get:`database information </{db}>`. If your use case creates lots of
+deleted documents (for example, if you are storing short-term data like logfile
+entries, message queues, etc), you might want to periodically switch to a new
+database and delete the old one (once the entries in it have all expired).
+
+
+Document's ID
+-------------
+
+The db file size is derived from your document and view sizes but also on a
+multiple of your ``_id`` sizes. Not only is the ``_id`` present in the document,
+but it and parts of it are duplicated in the binary tree structure CouchDB uses
+to navigate the file to find the document in the first place. As a real world
+example for one user switching from 16 byte ids to 4 byte ids made a database
+go from 21GB to 4GB with 10 million documents (the raw JSON text when from
+2.5GB to 2GB).
+
+Inserting with sequential (and at least sorted) ids is faster than random ids.
+Consequently you should consider generating ids yourself, allocating them
+sequentially and using an encoding scheme that consumes fewer bytes.
+For example, something that takes 16 hex digits to represent can be done in
+4 base 62 digits (10 numerals, 26 lower case, 26 upper case).
+
+
+Views
+=====
+
+Views Generation
+----------------
+
+Views with the Javascript query server are extremely slow to generate when
+there are a non-trivial number of documents to process. The generation process
+won't even saturate a single CPU let alone your I/O. The cause is the latency
+involved in the CouchDB server and separate `couchjs` query server, dramatically
+indicating how important it is to take latency out of your implementation.
+
+You can let view access be "stale" but it isn't practical to determine when
+that will occur giving you a quick response and when views will be updated
+which will take a long time. (A 10 million document database took about 10
+minutes to load into CouchDB but about 4 hours to do view generation).
+
+View information isn't replicated - it is rebuilt on each database so you
+can't do the view generation on a separate sever.
+
+
+Builtin Reduce Functions
+------------------------
+
+If you’re using a very simple view function that only performs a sum or count
+reduction, you can call native Erlang implementations of them by simply
+writing ``_sum`` or ``_count`` in place of your function declaration.
+This will speed up things dramatically, as it cuts down on IO between CouchDB
+and the :ref:`JavaScript query server <query-server/js>`. For example, as
+`mentioned on the mailing list`_, the time for outputting an (already indexed
+and cached) view with about 78,000 items went down from 60 seconds to 4 seconds.
+
+Before:
+
+.. code-block:: javascript
+
+ {
+ "_id": "_design/foo",
+ "views": {
+ "bar": {
+ "map": "function (doc) { emit(doc.author, 1); }",
+ "reduce": "function (keys, values, rereduce) { return sum(values); }"
+ }
+ }
+ }
+
+After:
+
+.. code-block:: javascript
+
+ {
+ "_id": "_design/foo",
+ "views": {
+ "bar": {
+ "map": "function (doc) { emit(doc.author, 1); }",
+ "reduce": "_sum"
+ }
+ }
+ }
+
+.. _mentioned on the mailing list: http://mail-archives.apache.org/mod_mbox/couchdb-user/201003.mbox/%3c5E07E00E-3D69-4A8C-ADA3-1B20CF0BA4C8@julianstahnke.com%3e
+
+.. seealso::
+
+ :ref:`reducefun/builtin`
[35/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Stabilize order of HTTP API reference entries.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/8baf5eb0
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/8baf5eb0
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/8baf5eb0
Branch: refs/heads/replicator-redesign
Commit: 8baf5eb03d57ed1cd15678a779b129d7ad696446
Parents: d282c82
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:04:47 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:04:47 2013 +0400
----------------------------------------------------------------------
share/doc/ext/httpdomain.py | 16 +++++++++++++++-
1 file changed, 15 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/8baf5eb0/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index a36493f..a2de686 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -201,6 +201,16 @@ http_sig_param_re = re.compile(r'\((?:(?P<type>[^:)]+):)?(?P<name>[\w_]+)\)',
re.VERBOSE)
+def sort_by_method(entries):
+ def cmp(item):
+ order = ['HEAD', 'GET', 'POST', 'PUT', 'DELETE', 'COPY', 'OPTIONS']
+ method = item[0].split(' ', 1)[0]
+ if method in order:
+ return order.index(method)
+ return 100
+ return sorted(entries, key=cmp)
+
+
def http_resource_anchor(method, path):
path = re.sub(r'[<>:/]', '-', path)
return method.lower() + '-' + path
@@ -455,7 +465,11 @@ class HTTPIndex(Index):
method.upper() + ' ' + path, 0, info[0],
http_resource_anchor(method, path), '', '', info[1]
])
- return (sorted(content.items()), True)
+ items = sorted(
+ (path, sort_by_method(entries))
+ for path, entries in content.items()
+ )
+ return (items, True)
class HTTPDomain(Domain):
[16/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Improve grammar, text flow in new configuration docs.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/cf4a09bc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/cf4a09bc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/cf4a09bc
Branch: refs/heads/replicator-redesign
Commit: cf4a09bce2848f3cb0fe98bfe4e32d4a930da674
Parents: 738095b
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Fri Sep 20 14:37:59 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/server/common.rst | 8 +--
share/doc/src/config/auth.rst | 110 +++++++++++++++++++------------
share/doc/src/config/couchdb.rst | 88 +++++++++++++++----------
share/doc/src/config/http.rst | 6 +-
share/doc/src/config/misc.rst | 55 ++++++++--------
5 files changed, 160 insertions(+), 107 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 690c55d..22e312d 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -959,9 +959,9 @@ structure is as follows:
The UUID type is determined by the :ref:`UUID algorithm <config/uuids/algorithm>`
setting in the CouchDB configuration.
-The UUID type could be changed in anytime through
-:ref:`Config API <api/config/section/key>`. For example, changing the UUID
-type to ``random`` use next HTTP request:
+The UUID type may be changed at any time through the
+:ref:`Configuration API <api/config/section/key>`. For example, the UUID type
+could be changed to ``random`` by sending this HTTP request:
.. code-block:: http
@@ -971,7 +971,7 @@ type to ``random`` use next HTTP request:
"random"
-When obtaining a list of UUIDs you'll see the changes:
+You can verify the change by obtaining a list of UUIDs:
.. code-block:: javascript
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 410ae46..279e124 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -108,7 +108,9 @@ work factor for ``PBKDF2``, and the algorithm itself at
``allow_persistent_cookies`` :: Persistent cookies
--------------------------------------------------
-Makes cookies persistent if ``true``::
+Makes cookies persistent if ``true``.
+
+::
[couch_httpd_auth]
allow_persistent_cookies = false
@@ -119,7 +121,9 @@ Makes cookies persistent if ``true``::
``auth_cache_size`` :: Authentication cache
-------------------------------------------
-Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
+Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
+
+::
[couch_httpd_auth]
auth_cache_size = 50
@@ -130,14 +134,15 @@ Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
``authentication_db`` :: Users database
---------------------------------------
-Specifies the name of the system database for storing CouchDB users::
+Specifies the name of the system database for storing CouchDB users.
+
+::
[couch_httpd_auth]
authentication_db = _users
-.. warning:: If there was any reasons to change this name for you, don't forget
- to remove/cleanup old database since it wouldn't be protected by CouchDB
- anymore.
+.. warning:: If you change the database name, do not forget to remove or clean
+ up the old database, since it will no longer be protected by CouchDB.
.. _config/couch_httpd_auth/authentication_redirect:
@@ -146,7 +151,9 @@ Specifies the name of the system database for storing CouchDB users::
---------------------------------------------------------------------------
Specifies the location for redirection on successful authentication if a
-``text/html`` response is accepted by the client (via ``Accept`` header)::
+``text/html`` response is accepted by the client (via an ``Accept`` header).
+
+::
[couch_httpd_auth]
authentication_redirect = /_utils/session.html
@@ -159,8 +166,11 @@ Specifies the location for redirection on successful authentication if a
.. versionadded:: 1.3
-The umbenr of iterations for password hashing by the PBKDF2 algorithm. A higher
-number provides better hash durability, but with cost of performance on each request that requires authentication::
+The number of iterations for password hashing by the PBKDF2 algorithm. A higher
+number provides better hash durability, but comes at a cost in performance for
+each request that requires authentication.
+
+::
[couch_httpd_auth]
iterations = 10000
@@ -171,8 +181,11 @@ number provides better hash durability, but with cost of performance on each req
``proxy_use_secret`` :: Force proxy auth use secret token
---------------------------------------------------------
-When this option is ``true`` the :ref:`secret <config/couch_httpd_auth/secret>`
-is required for :ref:`api/auth/proxy`::
+When this option is set to ``true``, the
+:ref:`secret <config/couch_httpd_auth/secret>` option is required for
+:ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
proxy_use_secret = false
@@ -185,9 +198,10 @@ is required for :ref:`api/auth/proxy`::
.. versionadded:: 1.4
-Comma-separated list of field names that will be available to view for any user
-document in :ref:`authentication_db <config/couch_httpd_auth/authentication_db>`
-If unset or not specified, authenticated users may retrieve only their own docs.
+A comma-separated list of field names in user documents (in
+:ref:`authentication_db <config/couch_httpd_auth/authentication_db>`) that can
+be read by any user. If unset or not specified, authenticated users can only
+retrieve their own document.
::
@@ -204,11 +218,13 @@ If unset or not specified, authenticated users may retrieve only their own docs.
.. _config/couch_httpd_auth/require_valid_user:
-``require_valid_user`` :: Force users authentication
-----------------------------------------------------
+``require_valid_user`` :: Force user authentication
+---------------------------------------------------
+
+When this option is set to ``true``, no requests are allowed from anonymous
+users. Everyone must be authenticated.
-When this option ``true`` no requests allowed from anonymous users. Everyone
-must be authenticated::
+::
[couch_httpd_auth]
require_valid_user = false
@@ -219,7 +235,9 @@ must be authenticated::
``secret`` :: Proxy Auth secret token
-------------------------------------
-The secret token used for :ref:`api/auth/proxy` method::
+The secret token used for :ref:`api/auth/proxy` method.
+
+::
[couch_httpd_auth]
secret = 92de07df7e7a3fe14808cef90a7cc0d91
@@ -230,7 +248,9 @@ The secret token used for :ref:`api/auth/proxy` method::
``timeout`` :: Session timeout
------------------------------
-Number of seconds since the last request before session will be expired::
+Number of seconds since the last request before sessions will be expired.
+
+::
[couch_httpd_auth]
timeout = 600
@@ -239,13 +259,15 @@ Number of seconds since the last request before session will be expired::
.. _config/couch_httpd_auth/users_db_public:
-``users_db_public`` :: Publish users info
------------------------------------------
+``users_db_public`` :: Publish user documents
+---------------------------------------------
.. versionadded:: 1.4
Allow all users to view user documents. By default, only admins may browse
-all users documents while users may browse only their own document::
+all users documents, while users may browse only their own document.
+
+::
[couch_httpd_auth]
users_db_public = false
@@ -256,8 +278,10 @@ all users documents while users may browse only their own document::
``x_auth_roles`` :: Proxy Auth roles header
-------------------------------------------
-HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the list of
-user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
+The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the
+list of a user's roles, separated by a comma. Used for :ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Roles
@@ -268,13 +292,16 @@ user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
``x_auth_token`` :: Proxy Auth token header
-------------------------------------------
-HTTP header name (``X-Auth-CouchDB-Token`` by default) with token to
-authenticate the authorization. This token is an `HMAC-SHA1` created from
-:ref:`secret key <config/couch_httpd_auth/secret>` and
+The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing the
+token used to authenticate the authorization. This token is an `HMAC-SHA1`
+created from :ref:`secret key <config/couch_httpd_auth/secret>` and
:ref:`username <config/couch_httpd_auth/x_auth_username>`. The secret key
-should be the same in the client and CouchDB node. This token is optional
-if value of :ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
-option isn't ``true``. Used for :ref:`api/auth/proxy`::
+should be the same on the client and the CouchDB node. This token is optional
+if the value of the
+:ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
+option is not ``true``. Used for :ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Token
@@ -285,8 +312,10 @@ option isn't ``true``. Used for :ref:`api/auth/proxy`::
``x_auth_username`` :: Proxy Auth username header
-------------------------------------------------
-HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
-username. Used for :ref:`api/auth/proxy`::
+The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
+username. Used for :ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
x_auth_username = X-Auth-CouchDB-UserName
@@ -305,11 +334,10 @@ username. Used for :ref:`api/auth/proxy`::
Store credentials within config
-------------------------------
-To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`) method
-there is need to setup three special sections in :ref:`configuration <config>`
-file:
+To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
+special sections must be set up in the :ref:`configuration <config>` file:
-1. Consumer secret:
+1. The Consumer secret:
::
@@ -323,7 +351,7 @@ file:
[oauth_token_secrets]
token1 = tokensekr1t
-3. Tokens to users mapping:
+3. A mapping from tokens to users:
::
@@ -339,8 +367,8 @@ Store OAuth credentials within auth database
.. versionadded:: 1.2
-CouchDB is able to store OAuth credentials within users documents instead of
-config file by using next option::
+CouchDB is able to store OAuth credentials within user documents instead of
+config file by using this option::
[couch_httpd_oauth]
use_users_db = true
@@ -348,7 +376,7 @@ config file by using next option::
If set to ``true``, OAuth token and consumer secrets will be looked up in the
:ref:`authentication database <config/couch_httpd_auth/authentication_db>`.
These secrets are stored in a top level field named ``"oauth"`` in user
-documents. Example:
+documents, as below.
.. code-block:: javascript
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index 053f7e9..c1bd182 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -26,9 +26,12 @@ Base Configuration
``attachment_stream_buffer_size`` :: Attachment streaming buffer
----------------------------------------------------------------
-Higher values may give better read performance due to less read operations
-and/or more OS page cache hits, but they can also increase overall response
-time for writes when there are many attachment write requests in parallel::
+Higher values may result in better read performance due to fewer read
+operations and/or more OS page cache hits. However, they can also increase
+overall response time for writes when there are many attachment write
+requests in parallel.
+
+::
[couchdb]
attachment_stream_buffer_size = 4096
@@ -39,9 +42,11 @@ time for writes when there are many attachment write requests in parallel::
``database_dir`` :: Databases location directory
------------------------------------------------
-Specifies location of CouchDB databases files (``*.couch`` named). This location
-should be writable and readable for user that runs CouchDB service (``couchdb``
-by default)::
+Specifies location of CouchDB database files (``*.couch`` named). This location
+should be writable and readable for the user the CouchDB service runs as
+(``couchdb`` by default).
+
+::
[couchdb]
database_dir = /var/lib/couchdb
@@ -74,15 +79,15 @@ losing durability - it's strongly not recommended to do such in production::
``file_compression`` :: Compression method for documents
-----------------------------------------------------------
-.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm
+.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
Method used to compress everything that is appended to database and view index
files, except for attachments (see the :ref:`[attachments] <config/attachments>`
section). Available methods are:
* ``none``: no compression
-* ``snappy``: use Google Snappy, a very fast compressor/decompressor.
-* ``deflate_N``: use zlib's deflate, ``N`` is the compression level which ranges
+* ``snappy``: use Google Snappy, a very fast compressor/decompressor
+* ``deflate_N``: use zlib's deflate; ``N`` is the compression level which ranges
from 1 (fastest, lowest compression ratio) to 9 (slowest, highest compression
ratio)
@@ -99,9 +104,11 @@ section). Available methods are:
``fsync_options`` :: Fsync options
----------------------------------
-Specifies when to make `fsync` calls. `fsync` makes sure that any file system
-buffers kept by the operating system are written to disk. Normally, you have no
-need to edit this parameter::
+Specifies when to make `fsync` calls. `fsync` makes sure that the contents of
+any file system buffers kept by the operating system are flushed to disk.
+There is generally no need to modify this parameter.
+
+::
[couchdb]
fsync_options = [before_header, after_header, on_file_open]
@@ -112,11 +119,13 @@ need to edit this parameter::
``max_dbs_open`` :: Limit of simultaneously opened databases
------------------------------------------------------------
-This option places an upper bound on the number of databases that can be open at
-one time. CouchDB reference counts database accesses internally and will close
-idle databases when it must. Sometimes it is necessary to keep more than the
+This option places an upper bound on the number of databases that can be open
+at once. CouchDB reference counts database accesses internally and will close
+idle databases as needed. Sometimes it is necessary to keep more than the
default open at once, such as in deployments where many databases will be
-continuously replicating::
+replicating continuously.
+
+::
[couchdb]
max_dbs_open = 100
@@ -129,11 +138,13 @@ continuously replicating::
.. versionchanged:: 1.3 This option now actually works.
-Defines limit of size in bytes that document may has in JSON form. Doesn't
-applies for attachments since they are been transferred as stream of chunks.
-Do not set this value too small since you want be able to modify config options,
-database security and other options until you restore this value by edit config
-file::
+Defines a maximum size for JSON documents, in bytes. This limit does not
+apply to attachments, since they are transferred as a stream of chunks. If you
+set this to a small value, you might be unable to modify configuration options,
+database security and other larger documents until a larger value is restored
+by editing the configuration file.
+
+::
[couchdb]
max_document_size = 4294967296 ; 4 GB
@@ -144,10 +155,12 @@ file::
``os_process_timeout`` :: External processes time limit
-------------------------------------------------------
-Number of microseconds that external processes such as `query server` and
-`externals` may process CouchDB commands before return any result. Keeping
-this value smaller you'll be ensured that your services works fast, but you may
-tweak it depending on your needs::
+If an external process, such as a query server or external process, runs for
+this amount of microseconds without returning any results, it will be
+terminated. Keeping this value smaller ensures you get expedient errors, but
+you may want to tweak it for your specific needs.
+
+::
[couchdb]
os_process_timeout = 5000 ; 5 sec
@@ -158,10 +171,13 @@ tweak it depending on your needs::
``uri_file`` :: Discovery CouchDB help file
-------------------------------------------
-This file contains full `URI`_ that runs CouchDB. It's used to help discover
-CouchDB served port if it was set to ``0`` (e.g. automatically assigned any
-free one). This file should be writable and readable for user that runs CouchDB
-service (``couchdb`` by default)::
+This file contains the full `URI`_ that can be used to access this instance of
+CouchDB. It is used to help discover the port CouchDB is running on (if it was
+set to ``0`` (e.g. automatically assigned any free one). This file should be
+writable and readable for the user that runs the CouchDB service (``couchdb``
+by default).
+
+::
[couchdb]
uri_file = /var/run/couchdb/couchdb.uri
@@ -174,8 +190,10 @@ service (``couchdb`` by default)::
``util_driver_dir`` :: CouchDB binary utility drivers
-----------------------------------------------------
-Specified location of binary drivers (`icu`, `ejson`, etc.). This location and
-his content should be readable for user that runs CouchDB service::
+Specifies location of binary drivers (`icu`, `ejson`, etc.). This location and
+its contents should be readable for the user that runs the CouchDB service.
+
+::
[couchdb]
util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.3.0/priv/lib
@@ -188,7 +206,9 @@ his content should be readable for user that runs CouchDB service::
.. versionadded:: 1.3
-Unique identifier of CouchDB server instance::
+Unique identifier for this CouchDB server instance.
+
+::
[couchdb]
uuid = 0a959b9b8227188afc2ac26ccdf345a6
@@ -200,7 +220,9 @@ Unique identifier of CouchDB server instance::
-----------------------------------------------------
Specifies location of CouchDB view index files. This location should be writable
-and readable for user that runs CouchDB service (``couchdb`` by default)::
+and readable for the user that runs the CouchDB service (``couchdb`` by default).
+
+::
[couchdb]
view_index_dir = /var/lib/couchdb
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/http.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index 3c86585..f225092 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -653,9 +653,9 @@ behind a proxy, then you don't need to specify a port number in the `vhost` key.
The first line will rewrite the request to display the content of the `example`
database. This rule works only if the ``Host`` header is ``couchdb.local`` and
-won't work for `CNAMEs`. The second rule on the other hand matches all
-`CNAMEs` to `example` db. So `www.couchdb.local` or `db.couchdb.local` will
-work.
+won't work for `CNAMEs`. The second rule, on the other hand, matches all
+`CNAMEs` to `example` db, so that both `www.couchdb.local` and `db.couchdb.local`
+will work.
.. _config/vhosts/rewriting:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index ffd9041..235142d 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -27,7 +27,7 @@ Miscellaneous Parameters
---------------------
Defines zlib compression level for the attachments from ``1`` (lowest, fastest)
-to ``9`` (highest, slowest). ``0`` value disables compression::
+to ``9`` (highest, slowest). A value of ``0`` disables compression::
[attachments]
compression_level = 8
@@ -38,8 +38,8 @@ to ``9`` (highest, slowest). ``0`` value disables compression::
``compressible_types``
----------------------
-While not all attached files could be compressed well, it is possible to let
-CouchDB compress only specific attachments identified by their MIME type::
+Since compression is ineffective for some types of files, it is possible to let
+CouchDB compress only some types of attachments, specified by their MIME type::
[attachments]
compressible_types = text/*, application/javascript, application/json, application/xml
@@ -81,8 +81,8 @@ intervals (in seconds)::
.. versionchanged:: 1.3 ``utc_id`` algorithm.
-CouchDB provides various algorithms to generate UUID value that will be used
-for document `_id` by default::
+CouchDB provides various algorithms to generate the UUID values that are used
+for document `_id`'s by default::
[uuids]
algorithm = sequential
@@ -109,9 +109,9 @@ Available algorithms:
}
- ``sequential``: Monotonically increasing ids with random increments.
- First 26 hex characters are random. Last 6 increment in random amounts until
- an overflow occurs. On overflow, the random prefix is regenerated and the
- process starts over:
+ The first 26 hex characters are random, the last 6 increment in random
+ amounts until an overflow occurs. On overflow, the random prefix is
+ regenerated and the process starts over.
.. code-block:: javascript
@@ -130,8 +130,8 @@ Available algorithms:
]
}
-- ``utc_random``: Time since Jan 1, 1970 UTC with microseconds. First 14
- characters are the time in hex. Last 18 are random:
+- ``utc_random``: The time since Jan 1, 1970 UTC, in microseconds. The first
+ 14 characters are the time in hex. The last 18 are random.
.. code-block:: javascript
@@ -150,9 +150,9 @@ Available algorithms:
]
}
-- ``utc_id``: Time since Jan 1, 1970 UTC with microseconds,
- plus ``utc_id_suffix`` string. First 14 characters are the time in hex.
- :ref:`config/uuids/utc_id_suffix` string value is appended to these:
+- ``utc_id``: The time since Jan 1, 1970 UTC, in microseconds, plus
+ the ``utc_id_suffix`` string. The first 14 characters are the time in hex.
+ The :ref:`config/uuids/utc_id_suffix` string value is appended to these.
.. code-block:: javascript
@@ -171,14 +171,15 @@ Available algorithms:
]
}
-.. note:: **Impact of UUID choices:**
- The choice of UUID has a significant impact on the layout of the B-tree,
- prior to compaction.
+.. note::
- For example, a sequential UUID algorithm during uploading thousands of
- documents, will avoid the need to rewrite many intermediate B-tree nodes.
+ **Impact of UUID choices:** the choice of UUID has a significant impact on
+ the layout of the B-tree, prior to compaction.
+
+ For example, using a sequential UUID algorithm while uploading a large batch
+ of documents will avoid the need to rewrite many intermediate B-tree nodes.
A random UUID algorithm may require rewriting intermediate nodes on a regular
- basis, with a corresponding decrease of throughput, and significant wasted
+ basis, resulting in significantly decreased throughput and wasted disk space
space due to the append-only B-tree design.
It is generally recommended to set your own UUIDs, or use the sequential
@@ -193,9 +194,11 @@ UTC ID Suffix
.. versionadded:: 1.3
-The utc_id_suffix value will be appended to UUIDs generated by the ``utc_id``
-algorithm. Replicating instances should have unique utc_id_suffix values to
-ensure uniqueness of ``utc_id`` ids::
+The ``utc_id_suffix`` value will be appended to UUIDs generated by the
+``utc_id`` algorithm. Replicating instances should have unique
+``utc_id_suffix`` values to ensure uniqueness of ``utc_id`` ids.
+
+::
[uuid]
utc_id_suffix = my-awesome-suffix
@@ -208,11 +211,11 @@ ensure uniqueness of ``utc_id`` ids::
.. versionadded:: 1.3
-For CouchDB distributors there is an option to customise CouchDB's welcome
-message which is returned when requesting ``GET /``.
+CouchDB distributors have the option of customizing CouchDB's welcome
+message. This is returned when requesting ``GET /``.
+
+::
[vendor]
name = The Apache Software Foundation
version = 1.3.0
-
-
[17/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
fix problem when LOCAL_VERSION_RELEASE isn't set
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/fe961f83
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/fe961f83
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/fe961f83
Branch: refs/heads/replicator-redesign
Commit: fe961f83816d3da5d8e03c98ef07b0fc06536454
Parents: 9454b50
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Fri Sep 20 11:52:59 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe961f83/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index bfdcd99..f60e545 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -51,7 +51,7 @@ release = '.'.join([
_info['LOCAL_VERSION_REVISION']
]) + (
_info['LOCAL_VERSION_STAGE'] + '' + _info['LOCAL_VERSION_RELEASE']
- if _info['LOCAL_VERSION_RELEASE'] == '%revision%'
+ if _info.get('LOCAL_VERSION_RELEASE') == '%revision%'
else '-dev'
)
[34/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Normalize API path's params names.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/d282c828
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/d282c828
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/d282c828
Branch: refs/heads/replicator-redesign
Commit: d282c828ab61b8822c0dfc27b370b32977ce0ccd
Parents: a00c6a4
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 09:22:21 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 09:22:21 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/common.rst | 24 ++++++++++++------------
share/doc/src/api/ddoc/rewrites.rst | 4 ++--
share/doc/src/api/ddoc/views.rst | 12 ++++++------
share/doc/src/api/local.rst | 8 ++++----
4 files changed, 24 insertions(+), 24 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index 1e5b183..79c7357 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -16,7 +16,7 @@
``/db/_design/design-doc``
==========================
-.. http:head:: /{db}/_design/{ddocname}
+.. http:head:: /{db}/_design/{ddoc}
Returns the HTTP Headers containing a minimal amount of information
about the specified design document.
@@ -26,7 +26,7 @@
:http:head:`/{db}/{docid}`
-.. http:get:: /{db}/_design/{ddocname}
+.. http:get:: /{db}/_design/{ddoc}
Returns design document with the specified design document` from the specified
database. Unless you request a specific revision, the latest revision of the
@@ -37,7 +37,7 @@
:http:get:`/{db}/{docid}`
-.. http:put:: /{db}/_design/{ddocname}
+.. http:put:: /{db}/_design/{ddoc}
The :http:method:`PUT` method creates a new named design document, or creates
a new revision of the existing design document.
@@ -67,7 +67,7 @@
:http:put:`/{db}/{docid}`
-.. http:delete:: /{db}/_design/{ddocname}
+.. http:delete:: /{db}/_design/{ddoc}
Deletes the specified document from the database. You must supply the
current (latest) revision, either by using the ``rev`` parameter to
@@ -77,7 +77,7 @@
:http:delete:`/{db}/{docid}`
-.. http:copy:: /{db}/_design/{ddocname}
+.. http:copy:: /{db}/_design/{ddoc}
The :http:method:`COPY` (which is non-standard HTTP) copies an existing
design document to a new or existing one.
@@ -97,7 +97,7 @@
``/db/_design/design-doc/attachment``
=====================================
-.. http:head:: /{db}/_design/{ddocname}/{attname}
+.. http:head:: /{db}/_design/{ddoc}/{attname}
Returns the HTTP headers containing a minimal amount of information
about the specified attachment.
@@ -106,7 +106,7 @@
:http:head:`/{db}/{docid}/{attname}`
-.. http:get:: /{db}/_design/{ddocname}/{attname}
+.. http:get:: /{db}/_design/{ddoc}/{attname}
Returns the file attachment associated with the design document.
The raw data of the associated attachment is returned (just as if you were
@@ -116,7 +116,7 @@
:http:get:`/{db}/{docid}/{attname}`
-.. http:put:: /{db}/_design/{ddocname}/{attname}
+.. http:put:: /{db}/_design/{ddoc}/{attname}
Uploads the supplied content as an attachment to the specified design
document. The attachment name provided must be a URL encoded string.
@@ -125,7 +125,7 @@
:http:put:`/{db}/{docid}/{attname}`
-.. http:delete:: /{db}/_design/{ddocname}/{attname}
+.. http:delete:: /{db}/_design/{ddoc}/{attname}
Deletes the attachment of the specified design document.
@@ -139,14 +139,14 @@
``/db/_design/design-doc/_info``
================================
-.. http:get:: /{db}/_design/{ddocname}/_info
+.. http:get:: /{db}/_design/{ddoc}/_info
Obtains information about the specified design document, including the index,
index size and current status of the design document and associated
index information.
:param db: Database name
- :param ddocname: Design document name
+ :param ddoc: Design document name
:<header Accept: - :mimetype:`application/json`
- :mimetype:`text/plain`
:>header Content-Type: - :mimetype:`application/json`
@@ -196,7 +196,7 @@
View Index Information
----------------------
-The response from :http:get:`/{db}/_design/{ddocname}/_info` contains
+The response from :http:get:`/{db}/_design/{ddoc}/_info` contains
``view_index`` (*object*) field with the next structure:
* **compact_running** (*boolean*): Indicates whether a compaction routine
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/share/doc/src/api/ddoc/rewrites.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/rewrites.rst b/share/doc/src/api/ddoc/rewrites.rst
index 3bcf6b4..61eebed 100644
--- a/share/doc/src/api/ddoc/rewrites.rst
+++ b/share/doc/src/api/ddoc/rewrites.rst
@@ -16,7 +16,7 @@
``/db/_design/design-doc/_rewrite/path``
========================================
-.. http:any:: /{db}/_design/{ddocname}/_rewrite/{path}
+.. http:any:: /{db}/_design/{ddoc}/_rewrite/{path}
Rewrites the specified path by rules defined in the specified design document.
@@ -85,5 +85,5 @@
are depended on endpoint to which url will be rewrited.
:param db: Database name
- :param ddocname: Design document name
+ :param ddoc: Design document name
:param path: URL path to rewrite
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index ade789c..7834539 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -16,13 +16,13 @@
``/db/_design/design-doc/_view/view-name``
==========================================
-.. http:get:: /{db}/_design/{ddocname}/_view/{viewname}
+.. http:get:: /{db}/_design/{ddoc}/_view/{view}
Executes the specified view function from the specified design document.
:param db: Database name
- :param ddocname: Design document name
- :param viewname: View function name
+ :param ddoc: Design document name
+ :param view: View function name
:<header Accept: - :mimetype:`application/json`
- :mimetype:`text/plain`
@@ -123,14 +123,14 @@
}
-.. http:post:: /{db}/_design/{ddocname}/_view/{viewname}
+.. http:post:: /{db}/_design/{ddoc}/_view/{view}
Executes the specified view function from the specified design document.
- Unlike the :http:get:`/{db}/_design/{ddocname}/_view/{viewname}` method
+ Unlike the :http:get:`/{db}/_design/{ddoc}/_view/{view}` method
for accessing views, the :http:method:`POST` method supports the specification
of explicit keys to be retrieved from the view results. The remainder of the
:http:method:`POST` view functionality is identical to the
- :http:get:`/{db}/_design/{ddocname}/_view/{viewname}` API.
+ :http:get:`/{db}/_design/{ddoc}/_view/{view}` API.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index 83a64cf..0fb6d6c 100644
--- a/share/doc/src/api/local.rst
+++ b/share/doc/src/api/local.rst
@@ -55,25 +55,25 @@ A list of the available methods and URL paths are provided below:
``/db/_local/id``
========================
-.. http:get:: /{db}/_local/{id}
+.. http:get:: /{db}/_local/{docid}
Gets the specified local document. The semantics are identical to
accessing a standard document in the specified database, except that the
document is not replicated. See :http:get:`/{db}/{docid}`.
-.. http:put:: /{db}/_local/{id}
+.. http:put:: /{db}/_local/{docid}
Stores the specified local document. The semantics are identical to
storing a standard document in the specified database, except that the
document is not replicated. See :http:put:`/{db}/{docid}`.
-.. http:delete:: /{db}/_local/{id}
+.. http:delete:: /{db}/_local/{docid}
Deletes the specified local document. The semantics are identical to
deleting a standard document in the specified database, except that the
document is not replicated. See :http:delete:`/{db}/{docid}`.
-.. http:copy:: /{db}/_local/{id}
+.. http:copy:: /{db}/_local/{docid}
Copies the specified local document. The semantics are identical to
copying a standard document in the specified database, except that the
[12/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Fix markup for PUT /{db}
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/7ef3ef62
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/7ef3ef62
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/7ef3ef62
Branch: refs/heads/replicator-redesign
Commit: 7ef3ef62eb12f2dda51298461d354f480007d068
Parents: a16de04
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Sep 3 14:09:12 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/common.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7ef3ef62/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 4880e61..2fb525f 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -103,7 +103,7 @@
}
-.. http::put /{db}
+.. http:put:: /{db}
Creates a new database. The database name ``{db}`` must be composed by
following next rules:
[26/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Make builtin reduce functions definition referenceable.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/47ff8636
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/47ff8636
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/47ff8636
Branch: refs/heads/replicator-redesign
Commit: 47ff8636fd57cfd85b2ebe9f2f902cc99db0c4c7
Parents: 6f007f8
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Sep 8 22:17:58 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/couchapp/ddocs.rst | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/47ff8636/share/doc/src/couchapp/ddocs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/ddocs.rst b/share/doc/src/couchapp/ddocs.rst
index 01d3d69..1920a42 100644
--- a/share/doc/src/couchapp/ddocs.rst
+++ b/share/doc/src/couchapp/ddocs.rst
@@ -112,8 +112,14 @@ that main task of reduce functions is to *reduce* mapped result, not to make it
even bigger. Generally, your reduce function should converge rapidly to a single
value - which could be an array or similar object.
-Also CouchDB has three built-in reduce functions. These are implemented in
-Erlang and run right inside CouchDB, so they are much faster than the equivalent
+
+.. _reducefun/builtin:
+
+Builtin reduce functions
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Additionally, CouchDB has three built-in reduce functions. These are implemented
+in Erlang and runs inside CouchDB, so they are much faster than the equivalent
JavaScript functions: ``_sum``, ``_count`` and ``_stats``. Their equivalents in
JavaScript below:
[13/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Add download page.
Fixes COUCHDB-906
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a16de046
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a16de046
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a16de046
Branch: refs/heads/replicator-redesign
Commit: a16de04618620e293f74992061ba29569ac3da2c
Parents: 1449a37
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Sep 2 03:25:15 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 1 +
share/doc/src/conf.py | 8 ++++-
share/doc/templates/help.html | 1 +
share/doc/templates/pages/download.html | 48 ++++++++++++++++++++++++++++
4 files changed, 57 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index dcc1150..16ed5d6 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -391,6 +391,7 @@ src_files = \
src_files_html = \
../static/rtd.css \
+ ../templates/pages/download.html \
../templates/help.html \
../templates/searchbox.html \
../templates/utilities.html
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 04b7079..7c49bbf 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -90,6 +90,12 @@ html_favicon = "../images/favicon.ico"
html_use_index = False
+html_additional_pages = {
+ 'download': 'pages/download.html'
+}
+
+html_context = {}
+
html_sidebars = {
"**": [
"searchbox.html",
@@ -133,7 +139,7 @@ extlinks = {
github_project = 'apache/couchdb'
-github_branch = 'master'
+html_context['git_branch'] = github_branch = 'master'
github_docs_path = 'share/doc/src'
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/templates/help.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/help.html b/share/doc/templates/help.html
index fcc75c5..be0cb91 100644
--- a/share/doc/templates/help.html
+++ b/share/doc/templates/help.html
@@ -21,6 +21,7 @@ specific language governing permissions and limitations under the License.
<li><a href="https://couchdb.apache.org/#mailing-list">Mailing Lists</a></li>
<li><a href="http://webchat.freenode.net/?channels=couchdb">IRC</a></li>
<li><a href="https://issues.apache.org/jira/browse/CouchDB">Issues</a></li>
+<li><a href="{{ pathto('download') }}">Download</a></li>
{%- if github_show_url %}
<li><a href="{{ github_show_url }}"
rel="nofollow">{{ _('Show on GitHub') }}</a></li>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/templates/pages/download.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/pages/download.html b/share/doc/templates/pages/download.html
new file mode 100644
index 0000000..76fe93d
--- /dev/null
+++ b/share/doc/templates/pages/download.html
@@ -0,0 +1,48 @@
+<!--
+
+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.
+
+-->
+
+{% extends "layout.html" %}
+{% set title = 'Download' %}
+{% set url = 'https://media.readthedocs.org/%s/couchdb/%s/couchdb.%s' %}
+{% if git_branch == 'master' %}
+ {% set rtd_ver = 'latest' %}
+{% else %}
+ {% set rtd_ver = git_branch %}
+{% endif %}
+
+{% block body %}
+<h1>Download Apache CouchDB™ {{ release }} Documentation</h1>
+
+<p>To download an archive containing all the documents for this version of
+CouchDB in one of various formats, follow one of links in this table</p>
+
+<table class="docutils">
+ <tr>
+ <td>PDF (A4 paper size)</td>
+ <td><a href="{{ url|format('pdf', rtd_ver, 'pdf') }}">Download</a> (~1 MB)</td>
+ </tr>
+ <tr>
+ <td>HTML</td>
+ <td><a href="{{ url|format('htmlzip', rtd_ver, 'zip') }}">Download</a> (~5 MB)</td>
+ </tr>
+ <tr>
+ <td>EPUB</td>
+ <td><a href="{{ url|format('epub', rtd_ver, 'epub') }}">Download</a> (~1 MB)</td>
+ </tr>
+</table>
+
+<p>These archives contain all the content of the documentation.</p>
+
+{% endblock %}
[03/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Use own template to override the defaults.
Make HTTP API Index page looks nicer without top flat index.
May be one day we'll redesign docs to fit main site/fauxton style.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/fe79a4dc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/fe79a4dc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/fe79a4dc
Branch: refs/heads/replicator-redesign
Commit: fe79a4dcab08052ebaba3630e118b3fb5879143d
Parents: 1e23d25
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 15:29:54 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
NOTICE | 3 ++
share/doc/src/conf.py | 4 +-
share/doc/templates/couchdb/domainindex.html | 49 +++++++++++++++++++++++
share/doc/templates/couchdb/theme.conf | 13 ++++++
4 files changed, 68 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index da1b6d4..6a41c6c 100644
--- a/NOTICE
+++ b/NOTICE
@@ -186,3 +186,6 @@ This product also includes the following third-party components:
Copyright 2007, Christopher Lenz <cm...@gmail.com>
+ * share/doc/src/templates/couchdb/domainindex.html
+
+ Copyright 2007-2011 by the Sphinx team
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 9606213..3e6d5a3 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -64,7 +64,9 @@ highlight_language = "json"
pygments_style = "sphinx"
-html_theme = "default"
+html_theme = "couchdb"
+
+html_theme_path = ['../templates']
templates_path = ["../templates"]
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/share/doc/templates/couchdb/domainindex.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/couchdb/domainindex.html b/share/doc/templates/couchdb/domainindex.html
new file mode 100644
index 0000000..38ff144
--- /dev/null
+++ b/share/doc/templates/couchdb/domainindex.html
@@ -0,0 +1,49 @@
+{#
+ basic/domainindex.html
+ ~~~~~~~~~~~~~~~~~~~~~~
+
+ Template for domain indices (module index, ...).
+
+ :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ :license: BSD, see LICENSE for details.
+#}
+{% extends "layout.html" %}
+{% set title = indextitle %}
+{% block extrahead %}
+{{ super() }}
+{% if not embedded and collapse_index %}
+ <script type="text/javascript">
+ DOCUMENTATION_OPTIONS.COLLAPSE_INDEX = true;
+ </script>
+{% endif %}
+{% endblock %}
+{% block body %}
+
+ {%- set groupid = idgen() %}
+
+ <h1>{{ indextitle }}</h1>
+
+ <table class="indextable modindextable" cellspacing="0" cellpadding="2">
+ {%- for letter, entries in content %}
+ <tr class="pcap"><td></td><td> </td><td></td></tr>
+ <tr class="cap" id="cap-{{ letter }}"><td></td><td>
+ <strong>{{ letter }}</strong></td><td></td></tr>
+ {%- for (name, grouptype, page, anchor, extra, qualifier, description)
+ in entries %}
+ <tr{% if grouptype == 2 %} class="cg-{{ groupid.current() }}"{% endif %}>
+ <td>{% if grouptype == 1 -%}
+ <img src="{{ pathto('_static/minus.png', 1) }}" class="toggler"
+ id="toggle-{{ groupid.next() }}" style="display: none" alt="-" />
+ {%- endif %}</td>
+ <td>{% if grouptype == 2 %} {% endif %}
+ {% if page %}<a href="{{ pathto(page) }}#{{ anchor }}">{% endif -%}
+ <tt class="xref">{{ name|e }}</tt>
+ {%- if page %}</a>{% endif %}
+ {%- if extra %} <em>({{ extra|e }})</em>{% endif -%}
+ </td><td>{% if qualifier %}<strong>{{ qualifier|e }}:</strong>{% endif %}
+ <em>{{ description|e }}</em></td></tr>
+ {%- endfor %}
+ {%- endfor %}
+ </table>
+
+{% endblock %}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/share/doc/templates/couchdb/theme.conf
----------------------------------------------------------------------
diff --git a/share/doc/templates/couchdb/theme.conf b/share/doc/templates/couchdb/theme.conf
new file mode 100644
index 0000000..546fca0
--- /dev/null
+++ b/share/doc/templates/couchdb/theme.conf
@@ -0,0 +1,13 @@
+; 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.
+
+[theme]
+inherit = default
[40/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Add notes about multipart/related API requests.
COUCHDB-1168
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/598ccd4d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/598ccd4d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/598ccd4d
Branch: refs/heads/replicator-redesign
Commit: 598ccd4d87be97d3cbed8ab1773d5b79f0a9d5f7
Parents: 9a18fd2
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 13:18:50 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 13:18:50 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/document/common.rst | 150 +++++++++++++++++++++++++++++
1 file changed, 150 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/598ccd4d/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index 03b1de1..4ad854e 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -570,6 +570,59 @@ query parameter:
}
+Efficient Multiple Attachments Retrieving
+`````````````````````````````````````````
+
+As you had noted above, retrieving document with ``attachements=true`` returns
+large JSON object where all attachments are included. While you document and
+files are smaller it's ok, but if you have attached something bigger like media
+files (audio/video), parsing such response might be very expensive.
+
+To solve this problem, CouchDB allows to get documents in
+:mimetype:`multipart/related` format:
+
+**Request**:
+
+.. code-block:: http
+
+ GET /recipes/secret?attachments=true HTTP/1.1
+ Accept: multipart/related
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Length: 538
+ Content-Type: multipart/related; boundary="e89b3e29388aef23453450d10e5aaed0"
+ Date: Sat, 28 Sep 2013 08:08:22 GMT
+ ETag: "2-c1c6c44c4bc3c9344b037c8690468605"
+ Server: CouchDB (Erlang OTP)
+
+ --e89b3e29388aef23453450d10e5aaed0
+ Content-Type: application/json
+
+ {"_id":"secret","_rev":"2-c1c6c44c4bc3c9344b037c8690468605","_attachments":{"recipe.txt":{"content_type":"text/plain","revpos":2,"digest":"md5-HV9aXJdEnu0xnMQYTKgOFA==","length":86,"follows":true}}}
+ --e89b3e29388aef23453450d10e5aaed0
+ Content-Disposition: attachment; filename="recipe.txt"
+ Content-Type: text/plain
+ Content-Length: 86
+
+ 1. Take R
+ 2. Take E
+ 3. Mix with L
+ 4. Add some A
+ 5. Serve with X
+
+ --e89b3e29388aef23453450d10e5aaed0--
+
+In this response the document contains only attachments stub information and
+quite short while all attachments goes as separate entities which reduces
+memory footprint and processing overhead (you'd noticed, that attachment content
+goes as raw data, not in base64 encoding, right?).
+
+
Retrieving Attachments Encoding Info
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -636,6 +689,103 @@ about compressed attachments size and used codec.
}
+Creating Multiple Attachments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To create a document with multiple attachments with single request you need
+just inline base64 encoded attachments data into the document body:
+
+.. code-block:: javascript
+
+ {
+ "_id":"multiple_attachments",
+ "_attachments":
+ {
+ "foo.txt":
+ {
+ "content_type":"text\/plain",
+ "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+ },
+
+ "bar.txt":
+ {
+ "content_type":"text\/plain",
+ "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+ }
+ }
+ }
+
+Alternatively, you can upload a document with attachments more efficiently in
+:mimetype:`multipart/related` format. This avoids having to Base64-encode
+the attachments, saving CPU and bandwidth. To do this, set the
+:http:header:`Content-Type` header of the :http:put:`/{db}/{docid}` request to
+:mimetype:`multipart/related`.
+
+The first MIME body is the document itself, which should have its own
+:http:header:`Content-Type` of :mimetype:`application/json"`. It also should
+include an ``_attachments`` metadata object in which each attachment object
+has a key ``follows`` with value ``true``.
+
+The subsequent MIME bodies are the attachments.
+
+**Request**:
+
+.. code-block:: http
+
+ PUT /temp/somedoc HTTP/1.1
+ Accept: application/json
+ Content-Length: 372
+ Content-Type: multipart/related;boundary="abc123"
+ Host: localhost:5984
+ User-Agent: HTTPie/0.6.0
+
+ --abc123
+ Content-Type: application/json
+
+ {
+ "body": "This is a body.",
+ "_attachments": {
+ "foo.txt": {
+ "follows": true,
+ "content_type": "text/plain",
+ "length": 21
+ },
+ "bar.txt": {
+ "follows": true,
+ "content_type": "text/plain",
+ "length": 20
+ }
+ }
+ }
+
+ --abc123
+
+ this is 21 chars long
+ --abc123
+
+ this is 20 chars lon
+ --abc123--
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 72
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 09:13:24 GMT
+ ETag: "1-5575e26acdeb1df561bb5b70b26ba151"
+ Location: http://localhost:5984/temp/somedoc
+ Server: CouchDB (Erlang OTP)
+
+ {
+ "id": "somedoc",
+ "ok": true,
+ "rev": "1-5575e26acdeb1df561bb5b70b26ba151"
+ }
+
+
Getting a List of Revisions
---------------------------
[19/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Remove duplicate MacPorts instructions.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/738095bb
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/738095bb
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/738095bb
Branch: refs/heads/replicator-redesign
Commit: 738095bbf9675eb8650732d9693ef286b83d31b3
Parents: fe961f8
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Fri Sep 20 11:57:04 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/install/mac.rst | 30 ------------------------------
1 file changed, 30 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/738095bb/share/doc/src/install/mac.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/install/mac.rst b/share/doc/src/install/mac.rst
index 2f7a12d..81afa6b 100644
--- a/share/doc/src/install/mac.rst
+++ b/share/doc/src/install/mac.rst
@@ -42,36 +42,6 @@ That's all, now CouchDB is installed on your Mac:
.. _Open up Futon: http://localhost:5984/_utils
-
-.. _install/mac/macports:
-
-Installation from MacPorts
-==========================
-
-To install CouchDB using MacPorts you have 2 package choices:
-
-- ``couchdb`` - the latest release version
-- ``couchdb-devel`` - updated every few weeks from the master branch
-
-::
-
- $ sudo port install couchdb
-
-or, if you want the last development version:
-
- $ sudo port install couchdb-devel
-
-MacPorts takes care of installing all necessary dependencies.
-It should now be up and accessible via Futon at http://127.0.0.1:5984/_utils.
-
-If you want to run CouchDB as a service, load the launchd configuration which
-comes with the project, with this command::
-
- $ sudo port load couchdb
-
-Now CouchDB should be started automatically after every reboot.
-
-
.. _install/mac/homebrew:
Installation with HomeBrew
[42/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Import Security chapter from Guide to CouchDB. Describe _users db.
TODO: Authorization and Database Security parts.
COUCHDB-1822
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/d513c576
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/d513c576
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/d513c576
Branch: refs/heads/replicator-redesign
Commit: d513c57619251d4b7b0023a7f2b86b69b4a11300
Parents: 5522488
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 15:45:14 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 15:45:14 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +
share/doc/src/intro/index.rst | 1 +
share/doc/src/intro/security.rst | 525 ++++++++++++++++++++++++++++++++++
3 files changed, 529 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d513c576/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 870976a..ef98bde 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -115,6 +115,7 @@ html_files = \
html/_sources/intro/futon.txt \
html/_sources/intro/index.txt \
html/_sources/intro/overview.txt \
+ html/_sources/intro/security.txt \
html/_sources/intro/tour.txt \
html/_sources/intro/why.txt \
html/_sources/maintenance/compaction.txt \
@@ -234,6 +235,7 @@ html_files = \
html/intro/futon.html \
html/intro/index.html \
html/intro/overview.html \
+ html/intro/security.html \
html/intro/tour.html \
html/intro/why.html \
html/maintenance/compaction.html \
@@ -375,6 +377,7 @@ src_files = \
../src/intro/futon.rst \
../src/intro/index.rst \
../src/intro/overview.rst \
+ ../src/intro/security.rst \
../src/intro/tour.rst \
../src/intro/why.rst \
../src/maintenance/compaction.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d513c576/share/doc/src/intro/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/index.rst b/share/doc/src/intro/index.rst
index a934fae..1c1088b 100644
--- a/share/doc/src/intro/index.rst
+++ b/share/doc/src/intro/index.rst
@@ -51,5 +51,6 @@ teach how to use CouchDB.
consistency
tour
api
+ security
futon
curl
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d513c576/share/doc/src/intro/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/security.rst b/share/doc/src/intro/security.rst
new file mode 100644
index 0000000..1c25159
--- /dev/null
+++ b/share/doc/src/intro/security.rst
@@ -0,0 +1,525 @@
+.. 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.
+
+
+.. _intro/security:
+
+********
+Security
+********
+
+In this chapter, we'll look at the basic security mechanisms in CouchDB: the
+`Admin Party`, `Basic Authentication`, `Cookie Authentication`; how CouchDB
+handles users and protects their credentials.
+
+==============
+Authentication
+==============
+
+.. _intro/security/admin_party:
+
+The Admin Party
+===============
+
+When you start out fresh, CouchDB allows any request to be made by anyone.
+Create a database? No problem, here you go. Delete some documents? Same deal.
+CouchDB calls this the `Admin Party`. Everybody has privileges to do anything.
+Neat.
+
+While it is incredibly easy to get started with CouchDB that way,
+it should be obvious that putting a default installation into the wild is
+adventurous. Any rogue client could come along and delete a database.
+
+A note of relief: by default, CouchDB will listen only on your loopback
+network interface (``127.0.0.1`` or ``localhost``) and thus only you will be
+able to make requests to CouchDB, nobody else. But when you start to open up
+your CouchDB to the public (that is, by telling it to bind to your machine's
+public IP address), you will want to think about restricting access so that
+the next bad guy doesn't ruin your admin party.
+
+In our previous discussions, we dropped some keywords about how things
+without the `Admin Party` work. First, there's *admin* itself, which implies
+some sort of super user. Then there are *privileges*. Let's explore these terms
+a little more.
+
+CouchDB has the idea of an *admin user* (e.g. an administrator, a super user,
+or root) that is allowed to do anything to a CouchDB installation. By default,
+everybody is an admin. If you don't like that, you can create specific admin
+users with a username and password as their credentials.
+
+CouchDB also defines a set of requests that only admin users are allowed to
+do. If you have defined one or more specific admin users, CouchDB will ask for
+identification for certain requests:
+
+- Creating a database (:put:`PUT /database </{db}>`)
+- Deleting a database (:put:`DELETE /database </{db}>`)
+- Setup a database security (:put:`PUT /database/_security
+ </{db}/_security>`)
+- Creating a design document (:put:`PUT /database/_design/app
+ </{db}/_design/{ddocname}>`)
+- Updating a design document (:put:`PUT /database/_design/app?rev=1-4E2
+ </{db}/_design/{ddocname}>`)
+- Deleting a design document (:delete:`DELETE /database/_design/app?rev=2-6A7
+ </{db}/_design/{ddocname}>`)
+- Execute a temporary view (:post:`POST /database/_temp_view
+ </{db}/_temp_view>`)
+- Triggering compaction (:post:`POST /database/_compact </{db}/_compact>`)
+- Reading the task status list (:get:`GET /_active_tasks </_active_tasks>`)
+- Restarting the server (:post:`:POST /_restart </_restart>`)
+- Reading the active configuration (:get:`GET /_config </_config>`)
+- Updating the active configuration (:put:`PUT /_config/section/key
+ </_config/{section}/{key}>`)
+
+
+Creating New Admin User
+-----------------------
+
+Let's do another walk through the API using `curl` to see how CouchDB behaves
+when you add admin users.
+
+::
+
+ > HOST="http://127.0.0.1:5984"
+ > curl -X PUT $HOST/database
+ {"ok":true}
+
+When starting out fresh, we can add a database. Nothing unexpected. Now let's
+create an admin user. We'll call her ``anna``, and her password is ``secret``.
+Note the double quotes in the following code; they are needed to denote a string
+value for the :ref:`configuration API <api/config>`::
+
+ > curl -X PUT $HOST/_config/admins/anna -d '"secret"'
+ ""
+
+As per the :ref:`_config <api/config>` API's behavior, we're getting
+the previous value for the config item we just wrote. Since our admin user
+didn't exist, we get an empty string.
+
+
+Hashing Passwords
+-----------------
+
+Seeing the plain-text password is scary, isn't it? No worries, CouchDB doesn't
+show up the plain-text password anywhere. It gets hashed right away. The hash
+is that big, ugly, long string that starts out with ``-hashed-``.
+How does that work?
+
+#. Creates a new 128-bit UUID. This is our *salt*.
+#. Creates a sha1 hash of the concatenation of the bytes of the plain-text
+ password and the salt ``(sha1(password + salt))``.
+#. Prefixes the result with ``-hashed-`` and appends ``,salt``.
+
+To compare a plain-text password during authentication with the stored hash,
+the same procedure is run and the resulting hash is compared to the stored
+hash. The probability of two identical hashes for different passwords is too
+insignificant to mention (c.f. `Bruce Schneier`_). Should the stored hash fall
+into the hands of an attacker, it is, by current standards, way too inconvenient
+(i.e., it'd take a lot of money and time) to find the plain-text password from
+the hash.
+
+.. _Bruce Schneier: http://en.wikipedia.org/wiki/Bruce_Schneier
+
+But what's with the ``-hashed-`` prefix? When CouchDB starts up, it reads a set
+of `.ini` files with config settings. It loads these settings into an internal
+data store (not a database). The config API lets you read the current
+configuration as well as change it and create new entries. CouchDB is writing
+any changes back to the `.ini` files.
+
+The `.ini` files can also be edited by hand when CouchDB is not running.
+Instead of creating the admin user as we showed previously, you could have
+stopped CouchDB, opened your `local.ini`, added ``anna = secret`` to the
+:ref:`[admins] section <config/admins>`, and restarted CouchDB. Upon reading
+the new line from local.ini, CouchDB would run the hashing algorithm and write
+back the hash to `local.ini`, replacing the plain-text password. To make sure
+CouchDB only hashes plain-text passwords and not an existing hash a second time,
+it prefixes the hash with ``-hashed-``, to distinguish between plain-text
+passwords and hashed passwords. This means your plain-text password can't start
+with the characters ``-hashed-``, but that's pretty unlikely to begin with.
+
+.. note::
+
+ Since :ref:`1.3.0 release <release/1.3.0>` CouchDB uses ``-pbkdf2-`` prefix
+ by default to sign about using `PBKDF2`_ hashing algorithm instead of `SHA1`.
+
+ .. _PBKDF2: http://en.wikipedia.org/wiki/PBKDF2
+
+
+.. _intro/security/basicauth:
+
+Basic Authentication
+====================
+
+Now that we have defined an admin, CouchDB will not allow us to create new
+databases unless we give the correct admin user credentials. Let's verify::
+
+ > curl -X PUT $HOST/somedatabase
+ {"error":"unauthorized","reason":"You are not a server admin."}
+
+That looks about right. Now we try again with the correct credentials::
+
+ > HOST="http://anna:secret@127.0.0.1:5984"
+ > curl -X PUT $HOST/somedatabase
+ {"ok":true}
+
+If you have ever accessed a website or FTP server that was password-protected,
+the ``username:password@`` URL variant should look familiar.
+
+If you are security conscious, the missing ``s`` in ``http://`` will make you
+nervous. We're sending our password to CouchDB in plain text. This is a bad
+thing, right? Yes, but consider our scenario: CouchDB listens on ``127.0.0.1``
+on a development box that we're the sole user of. Who could possibly sniff our
+password?
+
+If you are in a production environment, however, you need to reconsider. Will
+your CouchDB instance communicate over a public network? Even a LAN shared
+with other collocation customers is public. There are multiple ways to secure
+communication between you or your application and CouchDB that exceed the
+scope of this documentation. CouchDB as of version :ref:`1.1.0 <release/1.1.0>`
+comes with :ref:`SSL built in <config/ssl>`.
+
+.. seealso::
+
+ :ref:`Basic Authentication API Reference <api/auth/basic>`
+
+
+.. _intro/security/cookie:
+
+Cookie Authentication
+=====================
+
+Basic authentication that uses plain-text passwords is nice and convenient,
+but not very secure if no extra measures are taken. It is also a very poor
+user experience. If you use basic authentication to identify admins,
+your application's users need to deal with an ugly, unstylable browser modal
+dialog that says non-professional at work more than anything else.
+
+To remedy some of these concerns, CouchDB supports cookie authentication.
+With cookie authentication your application doesn't have to include the ugly
+login dialog that the users' browsers come with. You can use a regular HTML
+form to submit logins to CouchDB. Upon receipt, CouchDB will generate a
+one-time token that the client can use in its next request to CouchDB. When
+CouchDB sees the token in a subsequent request, it will authenticate the user
+based on the token without the need to see the password again. By default,
+a token is valid for 10 minutes.
+
+To obtain the first token and thus authenticate a user for the first time,
+the username and password must be sent to the :ref:`_session <api/auth/session>`
+API. The API is smart enough to decode HTML form submissions, so you don't have
+to resort to any smarts in your application.
+
+If you are not using HTML forms to log in, you need to send an HTTP request
+that looks as if an HTML form generated it. Luckily, this is super simple::
+
+ > HOST="http://127.0.0.1:5984"
+ > curl -vX POST $HOST/_session \
+ -H 'Content-Type:application/x-www-form-urlencoded' \
+ -d 'name=anna&password=secret'
+
+CouchDB replies, and we'll give you some more detail::
+
+ < HTTP/1.1 200 OK
+ < Set-Cookie: AuthSession=YW5uYTo0QUIzOTdFQjrC4ipN-D-53hw1sJepVzcVxnriEw;
+ < Version=1; Path=/; HttpOnly
+ > ...
+ <
+ {"ok":true}
+
+A :statuscode:`200` response code tells us all is well, a :header:`Set-Cookie`
+header includes the token we can use for the next request, and the standard JSON
+response tells us again that the request was successful.
+
+Now we can use this token to make another request as the same user without
+sending the username and password again::
+
+ > curl -vX PUT $HOST/mydatabase \
+ --cookie AuthSession=YW5uYTo0QUIzOTdFQjrC4ipN-D-53hw1sJepVzcVxnriEw \
+ -H "X-CouchDB-WWW-Authenticate: Cookie" \
+ -H "Content-Type:application/x-www-form-urlencoded"
+ {"ok":true}
+
+You can keep using this token for 10 minutes by default. After 10 minutes you
+need to authenticate your user again. The token lifetime can be configured
+with the timeout (in seconds) setting in the :ref:`couch_httpd_auth
+<config/couch_httpd_auth>` configuration section.
+
+.. seealso::
+
+ :ref:`Cookie Authentication API Reference <api/auth/cookie>`
+
+
+=======================
+Authentication Database
+=======================
+
+You may already note, that CouchDB administrators are defined within config file
+and you now wondering does regular users are also stored there. No, they don't.
+CouchDB has special `authentication database` -- ``_users`` by default -- that
+stores all registered users as JSON documents.
+
+CouchDB uses special database (called ``_users`` by default) to store
+information about registered users. This is a `system database` -- this means
+that while it shares common :ref:`database API <api/database>`, there are some
+special security-related constraints applied and used agreements on documents
+structure. So how `authentication database` is different from others?
+
+- Only administrators may browse list of all documents
+ (:get:`GET /_users/_all_docs </{db}/_all_docs>`)
+- Only administrators may listen :ref:`changes feed
+ <changes>` (:get:`GET /_users/_changes </{db}/_changes>`)
+- Only administrators may execute design functions like :ref:`views <viewfun>`,
+ :ref:`shows <showfun>` and :ref:`others <ddocs>`
+- Only administrators may :method:`GET`, :method:`PUT` or :method:`DELETE`
+ any document (to be honest, that they always can do)
+- There is special design document ``_auth`` that cannot be modified
+- Every document (of course, except `design documents`) represents registered
+ CouchDB users and belong to him
+- Users may only access (:get:`GET /_users/org.couchdb.user:Jan
+ </{db}/{docid}>`) or modify (:put:`PUT /_users/org.couchdb.user:Jan
+ </{db}/{docid}>`) documents that they owns
+
+These draconian rules are reasonable: CouchDB cares about user's personal
+information and doesn't discloses it for everyone. Often, users documents are
+contains not only system information like `login`, `password hash` and `roles`,
+but also sensitive personal information like: real name, email, phone, special
+internal identifications and more - this is not right information that you
+want to share with the World.
+
+
+Users Documents
+===============
+
+Each CouchDB user is stored in document format. These documents are contains
+several *mandatory* fields, that CouchDB handles for correct authentication
+process:
+
+- **_id** (*string*): Document ID. Contains user's login with special prefix
+ :ref:`org.couchdb.user`
+- **derived_key** (*string*): `PBKDF2`_ key
+- **name** (*string*): User's name aka login. **Immutable** e.g. you cannot
+ rename existed user - you have to create new one
+- **roles** (*array* of *string*): List of user roles. CouchDB doesn't provides
+ any builtin roles, so you're free to define your own depending on your needs.
+ However, you cannot set system roles like ``_admin`` there. Also, only
+ administrators may assign roles to users - by default all users have no roles
+- **password_sha** (*string*): Hashed password with salt. Used for ``simple``
+ `password_scheme`
+- **password_scheme** (*string*): Password hashing scheme. May be ``simple`` or
+ ``pbkdf2``
+- **salt** (*string*): Hash salt. Used for ``simple`` `password_scheme`
+- **type** (*string*): Document type. Constantly have value ``user``
+
+Additionally, you may specify any custom fields that are relates to the target
+user. This is good place to store user's private information because only he and
+CouchDB administrators may browse it.
+
+.. _org.couchdb.user:
+
+Why ``org.couchdb.user:`` prefix?
+---------------------------------
+
+The reason to have special prefix before user's login name is to have
+namespaces which users are belongs to. This prefix is designed to prevent
+replication conflicts when you'll try to merge two `_user` databases or more.
+
+For current CouchDB releases, all users are belongs to the same
+``org.couchdb.user`` namespace and this cannot be changed, but we'd made
+such design decision for future releases.
+
+
+Creating New User
+=================
+
+Creating new user is a very trivial operation. You need just to send single
+:method:`PUT` request with user's data to CouchDB. Let's create user with login
+`jan` and password `apple`::
+
+ curl -X PUT http://localhost:5984/_users/org.couchdb.user:jan \
+ -H "Accept: application/json" \
+ -H "Content-Type: application/json" \
+ -d '{"name": "jan", "password": "apple", "roles": [], "type": "user"}'
+
+This `curl` command will produce next HTTP request:
+
+.. code-block:: http
+
+ PUT /_users/org.couchdb.user:jan HTTP/1.1
+ Accept: application/json
+ Content-Length: 62
+ Content-Type: application/json
+ Host: localhost:5984
+ User-Agent: curl/7.31.0
+
+And CouchDB responds with:
+
+.. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 83
+ Content-Type: application/json
+ Date: Fri, 27 Sep 2013 07:33:28 GMT
+ ETag: "1-e0ebfb84005b920488fc7a8cc5470cc0"
+ Location: http://localhost:5984/_users/org.couchdb.user:jan
+ Server: CouchDB (Erlang OTP)
+
+ {"ok":true,"id":"org.couchdb.user:jan","rev":"1-e0ebfb84005b920488fc7a8cc5470cc0"}
+
+Document successfully created what also means that user `jan` have created too!
+Let's check is this true::
+
+ curl -X POST http://localhost:5984/_session -d 'name=jan&password=apple'
+
+CouchDB should respond with:
+
+.. code-block:: javascript
+
+ {"ok":true,"name":"jan","roles":[]}
+
+Which means that username was recognized and password's hash matches with stored
+one. If we specify wrong login and/or password, CouchDB will notify us with
+the next error message:
+
+.. code-block:: javascript
+
+ {"error":"unauthorized","reason":"Name or password is incorrect."}
+
+
+Password Changing
+=================
+
+This is quite common situation: user had forgot his password, it was leaked
+somehow (via copy-paste, screenshot, or by typing in wrong chat window) or
+something else. Let's change password for our user `jan`.
+
+First of all, let's define what is the password changing from the point of
+CouchDB and the authentication database. Since "users" are "documents", this
+operation is nothing, but updating the document with special field ``password``
+which contains the *plain text password*. Scared? No need to: the authentication
+database has special internal hook on document update which looks for this
+field and replaces it with the *secured hash*, depending on chosen
+``password_scheme``.
+
+Summarizing above, we need to get document content, add ``password`` field
+with new plain text password value and store JSON result to the authentication
+database.
+
+::
+
+ curl -X GET http://localhost:5984/_users/org.couchdb.user:jan
+
+.. code-block:: javascript
+
+ {
+ "_id": "org.couchdb.user:jan",
+ "_rev": "1-e0ebfb84005b920488fc7a8cc5470cc0",
+ "derived_key": "e579375db0e0c6a6fc79cd9e36a36859f71575c3",
+ "iterations": 10,
+ "name": "jan",
+ "password_scheme": "pbkdf2",
+ "roles": [],
+ "salt": "1112283cf988a34f124200a050d308a1",
+ "type": "user"
+ }
+
+Here is our user's document. We may strip hashes from stored document to reduce
+amount of posted data::
+
+ curl -X PUT http://localhost:5984/_users/org.couchdb.user:jan \
+ -H "Accept: application/json" \
+ -H "Content-Type: application/json" \
+ -H "If-Match: 1-e0ebfb84005b920488fc7a8cc5470cc0" \
+ -d '{"name":"jan", "roles":[], "type":"user", "password":"orange"}'
+
+.. code-block:: javascript
+
+ {"ok":true,"id":"org.couchdb.user:jan","rev":"2-ed293d3a0ae09f0c624f10538ef33c6f"}
+
+Updated! Now let's check that password was really changed::
+
+ curl -X POST http://localhost:5984/_session -d 'name=jan&password=apple'
+
+CouchDB should respond with:
+
+.. code-block:: javascript
+
+ {"error":"unauthorized","reason":"Name or password is incorrect."}
+
+Looks like the password ``apple`` is wrong, what about ``orange``?
+
+::
+
+ curl -X POST http://localhost:5984/_session -d 'name=jan&password=orange'
+
+CouchDB should respond with:
+
+.. code-block:: javascript
+
+ {"ok":true,"name":"jan","roles":[]}
+
+Hooray! You may wonder why so complex: need to retrieve user's document, add
+special field to him, post it back - where is one big button that changes the
+password without worry about document's content? Actually, :ref:`Futon
+<intro/futon>` has such at the right bottom corner if you have logged in -
+all implementation details are hidden from your sight.
+
+.. note::
+
+ There is no password confirmation for API request: you should implement it
+ on your application layer like Futon does.
+
+
+Users Public Information
+========================
+
+.. versionadded:: 1.4
+
+Sometimes users *wants* to share some information with the World. For instance,
+their contact email to let other users get in touch with him. To solve this
+problem, but still keep sensitive and private information secured there is
+special :ref:`configuration <config>` option :ref:`public_fields
+<config/couch_httpd_auth/public_fields>`. In this options you may define comma
+separated list of users document fields that will be publicity available.
+
+Normally, if you request any user's document and you're not administrator or
+this document owner, CouchDB will respond with :statuscode:`404`::
+
+ curl http://localhost:5984/_users/org.couchdb.user:robert
+
+.. code-block:: javascript
+
+ {"error":"not_found","reason":"missing"}
+
+This response is constant for both cases when user exists or not exists - by
+security reasons.
+
+Now let's share field ``name``. First, setup the ``public_fields`` configuration
+option. Remember, that this action requires administrator's privileges and
+the next command will ask for password for user `admin`, assuming that he is
+the server administrator::
+
+ curl -X PUT http://localhost:5984/_config/couch_http_auth/public_fields \
+ -H "Content-Type: application/json" \
+ -d '"name"' \
+ -u admin
+
+What have changed? Let's check Robert's document once again::
+
+ curl http://localhost:5984/_users/org.couchdb.user:robert
+
+.. code-block:: javascript
+
+ {"_id":"org.couchdb.user:robert","_rev":"6-869e2d3cbd8b081f9419f190438ecbe7","name":"robert"}
+
+Good news! Now we may read field ``name`` from *every user's document without
+need to be an administrator*. That's important note: don't publish sensitive
+information, especially without user's acknowledge - they may not like such
+actions from your side.
[06/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Add missed Replication-Git comparison authorship.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/627806e2
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/627806e2
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/627806e2
Branch: refs/heads/replicator-redesign
Commit: 627806e25628861481f760acddfd6eb2ded0b13e
Parents: a103e74
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Aug 26 20:27:53 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/replication/conflicts.rst | 6 ++++++
1 file changed, 6 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/627806e2/share/doc/src/replication/conflicts.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/conflicts.rst b/share/doc/src/replication/conflicts.rst
index d0149b0..354c286 100644
--- a/share/doc/src/replication/conflicts.rst
+++ b/share/doc/src/replication/conflicts.rst
@@ -702,9 +702,15 @@ to use "history rewriting" to make git forget commits earlier than a particular
one.
+.. _replication/conflicts/git:
+
What is the CouchDB replication protocol? Is it like Git?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:Author: Jason Smith
+:Date: 2011-01-29
+:Source: http://stackoverflow.com/questions/4766391/what-is-the-couchdb-replication-protocol-is-it-like-git
+
**Key points**
**If you know Git, then you know how Couch replication works.** Replicating is
[48/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
New Replication UI and switching to _replicator
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/62e6dacc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/62e6dacc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/62e6dacc
Branch: refs/heads/replicator-redesign
Commit: 62e6dacca9629c591316b5790aa8f8c5921870e2
Parents: b144050
Author: suelockwood <de...@gmail.com>
Authored: Thu Sep 26 10:38:10 2013 -0400
Committer: suelockwood <de...@gmail.com>
Committed: Mon Sep 30 16:25:46 2013 -0400
----------------------------------------------------------------------
.../replication/assets/less/replication.less | 50 +++
src/fauxton/app/addons/replication/resources.js | 7 +-
src/fauxton/app/addons/replication/route.js | 4 +-
.../replication/templates/authfields.html | 16 +
.../app/addons/replication/templates/form.html | 87 ++---
.../replication/templates/localremotetabs.html | 35 ++
.../replication/templates/newdatabase.html | 34 ++
.../addons/replication/templates/options.html | 36 ++
src/fauxton/app/addons/replication/views.js | 325 +++++++++++++++----
.../app/templates/layouts/one_pane_notabs.html | 27 ++
src/fauxton/assets/js/plugins/happy.js | 150 +++++++++
11 files changed, 654 insertions(+), 117 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/assets/less/replication.less
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/assets/less/replication.less b/src/fauxton/app/addons/replication/assets/less/replication.less
index a301966..ea446ec 100644
--- a/src/fauxton/app/addons/replication/assets/less/replication.less
+++ b/src/fauxton/app/addons/replication/assets/less/replication.less
@@ -25,6 +25,54 @@ form#replication {
max-width: none;
width: auto;
+ #create_target{
+ input[type=radio]{display: none;}
+ label.btn {
+ margin-right: 0;
+ }
+ }
+
+ .actions{
+ padding: 15px 0;
+ }
+ #from_name {
+ margin-right: 20px;
+ }
+ .autharea {
+ display: inline-block;
+ vertical-align: top;
+ padding-top: 10px;
+ }
+ button.fonticon-replicate{
+ padding: 15px 20px;
+ }
+ .span12{
+ margin-left: 0;
+ padding-bottom: 20px;
+ }
+ .nav-tabs{
+ margin-bottom: 0;
+ border: 0;
+ }
+ .dropdown-menu {
+ width: 85%;
+ }
+ .tab-content.small-tabs{
+ margin-top: 0;
+ border: 1px solid #e3e3e3;
+ margin-bottom: 10px;
+ .tab-pane {
+ padding: 30px 20px;
+ }
+ > .active {
+ display: block;
+ background-color: #fff;
+ }
+ }
+ h3 {
+ margin-top: 0;
+ line-height: 27px
+ }
.form_set{
width: 350px;
display: inline-block;
@@ -157,6 +205,7 @@ form#replication {
}
#replicationStatus{
+
&.showHeader{
li.header{
display: block;
@@ -194,3 +243,4 @@ form#replication {
}
}
}
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/resources.js
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/resources.js b/src/fauxton/app/addons/replication/resources.js
index 38ae139..8c916c4 100644
--- a/src/fauxton/app/addons/replication/resources.js
+++ b/src/fauxton/app/addons/replication/resources.js
@@ -21,6 +21,9 @@ function (app, FauxtonAPI, ActiveTasks) {
//these are probably dupes from the database modules. I'm going to keep them seperate for now.
Replication.DBModel = Backbone.Model.extend({
+ url: function(){
+ return app.host + "/" + this.id;
+ },
label: function () {
//for autocomplete
return this.get("name");
@@ -60,9 +63,11 @@ function (app, FauxtonAPI, ActiveTasks) {
Replication.Replicate = Backbone.Model.extend({
url: function(){
- return app.host + "/_replicate";
+ return app.host + "/_replicator";
}
});
+
+
return Replication;
});
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/route.js
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/route.js b/src/fauxton/app/addons/replication/route.js
index 7ea318c..0dd25a5 100644
--- a/src/fauxton/app/addons/replication/route.js
+++ b/src/fauxton/app/addons/replication/route.js
@@ -18,7 +18,7 @@ define([
],
function(app, FauxtonAPI, Replication, Views) {
var RepRouteObject = FauxtonAPI.RouteObject.extend({
- layout: "one_pane",
+ layout: "one_pane_notabs",
roles: ["_admin"],
routes: {
"replication": "defaultView",
@@ -29,7 +29,7 @@ function(app, FauxtonAPI, Replication, Views) {
return app.host+"/_replication";
},
crumbs: [
- {"name": "Replicate changes from: ", "link": "replication"}
+ {"name": "", "link": "replication"}
],
defaultView: function(dbname){
this.databases = new Replication.DBList({});
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/templates/authfields.html
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/templates/authfields.html b/src/fauxton/app/addons/replication/templates/authfields.html
new file mode 100644
index 0000000..9806dcf
--- /dev/null
+++ b/src/fauxton/app/addons/replication/templates/authfields.html
@@ -0,0 +1,16 @@
+<!--
+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.
+-->
+<p>Authorize the use of this database for replication.</p>
+<input class="input-medium" type="text" name="user_<%=type%>" size="30" placeholder="Username">
+<input class="input-medium next" type="password" name="password_<%=type%>" size="30" placeholder="Password" data-next-step="step<%=step%>">
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/templates/form.html
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/templates/form.html b/src/fauxton/app/addons/replication/templates/form.html
index 32a87dc..e75453e 100644
--- a/src/fauxton/app/addons/replication/templates/form.html
+++ b/src/fauxton/app/addons/replication/templates/form.html
@@ -11,64 +11,67 @@ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.
-->
-
<form id="replication" class="form-horizontal">
- <div class="from form_set local">
- <div class="btn-group">
- <button class="btn local-btn" type="button" value="local">Local</button>
- <button class="btn remote-btn" type="button" value="remote">Remote</button>
- </div>
-
- <div class="from_local local_option">
- <select id="from_name" name="source">
- <% _.each( databases, function( db, i ){ %>
- <option value="<%=db.name%>" <% if(selectedDB == db.name){%>selected<%}%> ><%=db.name%></option>
- <% }); %>
- </select>
- </div>
- <div class="from_to_remote remote_option">
- <input type="text" id="from_url" name="source" size="30" value="http://">
- </div>
+ <!-- SOURCE -->
+ <div class="control-group" id="step1">
+ <label class="control-label">FROM: </label>
+ <div class="source controls">
+ <p>Select a database to replicate.</p>
+ <div id="source_form"></div>
</div>
- <div class="form_set middle">
- <span class="circle "></span>
- <a href="#" title="Switch Target and Source" class="swap">
- <span class="fonticon-swap-arrows"></span>
- </a>
- </span>
- </div>
+ </div>
- <div class="to form_set local">
- <div class="btn-group">
- <button class="btn local-btn" type="button" value="local">Local</button>
- <button class="btn remote-btn" type="button" value="remote">Remote</button>
- </div>
- <div class="to_local local_option">
- <input type="text" id="to_name" name="target" size="30" placeholder="database name">
- </div>
+ <div class="control-group hide" id="step2">
+ <label class="control-label">TO:</label>
+ <div class="target controls">
+ <p>Where do you want to replicate your data?</p>
+ <div class="btn-group" id="create_target">
+
+ <label for="existing-target" class="btn">
+ Existing Database
+ </label>
+
+ <label for="new-target" class="btn">
+ New Database
+ </label>
- <div class="to_remote remote_option">
- <input type="text" id="to_url" name="target" size="30" value="http://">
+ <input type="radio" id="existing-target" name="create_target" class="next" data-next-step="step3" value="false">
+ <input type="radio" id="new-target" name="create_target" class="next" data-next-step="step3" value="true">
+
</div>
</div>
+ </div>
+ <!--TARGET-->
+ <div class="control-group hide" id="step3">
+ <div class="target controls">
+ <p>Select a target database for your data.</p>
+ <div id="target_form"></div>
- <div class="actions">
- <div class="control-group">
<label for="continuous">
<input type="checkbox" name="continuous" value="true" id="continuous">
- Continuous
+ Make this replication continuous.
</label>
- <label for="createTarget">
- <input type="checkbox" name="create_target" value="true" id="createTarget">
- Create Target <a href="<%=getDocUrl('replication_doc')%>" target="_blank"><i class="icon-question-sign" rel="tooltip" title="Create the target database"></i></a>
- </label>
</div>
- <button class="btn btn-success btn-large save" type="submit">Replicate</button>
</div>
+ <div class="control-group hide" id="step4">
+ <label class="control-label">NAME: </label>
+ <div class="source controls">
+ <p>Give this replication task an ID. (optional)</p>
+ <input type="text" id="repID" name="_id" size="30" value="" data-validation="optional" placeholder="e.g. my_rep">
+
+ <div class="actions">
+ <button class="button green save btn-large fonticon-replicate" type="submit" >Replicate</button>
+ </div>
+ </div>
+
+ </div>
+
+
+
</form>
<div id="replicationStatus"></div>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/templates/localremotetabs.html
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/templates/localremotetabs.html b/src/fauxton/app/addons/replication/templates/localremotetabs.html
new file mode 100644
index 0000000..61337e1
--- /dev/null
+++ b/src/fauxton/app/addons/replication/templates/localremotetabs.html
@@ -0,0 +1,35 @@
+<!--
+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.
+-->
+<ul class="nav nav-tabs" id="<%=type%>Tabs">
+ <li class="active">
+ <a href="#" class="btn local-btn" data-tab="<%=type%>_local">My Databases</a>
+ </li>
+ <li>
+ <a href="#" class="btn remote-btn" data-tab="<%=type%>_remote">Remote Database</a>
+ </li>
+</ul>
+
+<div class="tab-content small-tabs">
+ <div class="tab-pane active" id="<%=type%>_local">
+ <input type="text" id="to_name" name="<%=type%>" size="30" placeholder="Select a <%=type%> database" class="permission auto">
+ <div class="autharea authArea_<%=type%>"></div>
+ </div>
+
+ <div class="tab-pane" id="<%=type%>_remote">
+ <input type="text" id="to_url" name="<%=type%>" size="30" class="next" value="http://" data-next-step="step<%=step%>">
+ <small>e.g. http://username:password@user.cloudant.com/database</small>
+ </div>
+</div>
+
+<div id="options-here"></div>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/templates/newdatabase.html
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/templates/newdatabase.html b/src/fauxton/app/addons/replication/templates/newdatabase.html
new file mode 100644
index 0000000..1bcc3bc
--- /dev/null
+++ b/src/fauxton/app/addons/replication/templates/newdatabase.html
@@ -0,0 +1,34 @@
+<!--
+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.
+-->
+
+<ul class="nav nav-tabs" id="<%=type%>Tabs">
+ <li class="active">
+ <a href="#" class="btn local-btn" data-tab="<%=type%>_local">Create a new database locally</a>
+ </li>
+ <li>
+ <a href="#" class="btn remote-btn" data-tab="<%=type%>_remote">Create a new remote database</a>
+ </li>
+</ul>
+
+<div class="tab-content small-tabs">
+ <div class="tab-pane active" id="<%=type%>_local">
+ <input type="text" id="to_name" name="<%=type%>" size="30" placeholder="Name your database" class="permission next" data-next-step="step<%=step%>">
+ <div class="autharea authArea_<%=type%>"></div>
+ </div>
+
+ <div class="tab-pane" id="<%=type%>_remote">
+ <input type="text" id="to_url" name="<%=type%>" size="30" class="next" value="http://" data-next-step="step<%=step%>">
+ <small>e.g. http://username:password@user.cloudant.com/database</small>
+ </div>
+</div>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/templates/options.html
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/templates/options.html b/src/fauxton/app/addons/replication/templates/options.html
new file mode 100644
index 0000000..5c6465e
--- /dev/null
+++ b/src/fauxton/app/addons/replication/templates/options.html
@@ -0,0 +1,36 @@
+<!--
+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.
+-->
+
+
+<span class="options off">Advanced Options</span>
+<div class="advancedOptions hide">
+ <h4>Apply filters</h4>
+ <p>Sometimes you don't want to transfer all documents from source to target. You can include one or more filter functions in a design document on the source and then tell the replicator to use them.</p>
+ <label for="filter">Enter the design doc and filter name</label>
+ <input type="text" placeholder="myddoc/myfilter" name="filter" id="filter"/>
+ <label for="query">Add query parameters (optional)</label>
+ <input type="text" placeholder='{"key":"value"}' name="query_params" id="query"/>
+
+ <hr>
+ <h4>Named Document Replication</h4>
+ <p>Sometimes you only want to replicate some documents. For this simple case you do not need to write a filter function. Simply add the list of keys, separated by commas.</p>
+ <input type="text" placeholder="foo, bar, baz" name="doc_ids" id="doc_ids"/>
+
+ <hr>
+ <h4>Replicate through a proxy</h4>
+ <p>Pass a "proxy" argument in the replication data to have replication go through an HTTP proxy</p>
+ <input type="text" placeholder="http://localhost:8888" name="proxy" id="proxy"/>
+
+</div>
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/addons/replication/views.js
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/views.js b/src/fauxton/app/addons/replication/views.js
index f4b96fd..3366937 100644
--- a/src/fauxton/app/addons/replication/views.js
+++ b/src/fauxton/app/addons/replication/views.js
@@ -24,13 +24,13 @@ function(app, FauxtonAPI, Components, replication) {
intervalId: null
};
+ app.temphost ="http://deathbear.cloudant.com";
_.extend(Events, Backbone.Events);
// NOTES: http://wiki.apache.org/couchdb/Replication
// Replication form view is huge
// -----------------------------------
- // afterRender: autocomplete on the target input field
// beforeRender: add the status table
// disableFields: disable non active fields on submit
// enableFields: enable field when radio btns are clicked
@@ -46,76 +46,45 @@ function(app, FauxtonAPI, Components, replication) {
template: "addons/replication/templates/form",
events: {
"submit #replication": "validate",
- "click .btn-group .btn": "showFields",
- "click .swap": "swapFields",
- "click .options": "toggleAdvancedOptions"
+ "change .next": "nextStep",
+ "change #create_target input[type='radio']": "showTargetForm",
+ "click #create_target label": "createTargetActiveState"
},
initialize: function(options){
this.status = options.status;
this.selectedDB = options.selectedDB;
this.newRepModel = new replication.Replicate({});
},
- afterRender: function(){
- this.dbSearchTypeahead = new Components.DbSearchTypeahead({
- dbLimit: 30,
- el: "input#to_name"
- });
-
- this.dbSearchTypeahead.render();
-
- },
-
beforeRender: function(){
this.insertView("#replicationStatus", new View.ReplicationList({
collection: this.status
}));
+
+ this.insertView("#source_form",new View.LocalRemoteTabs({
+ selectedDB: this.selectedDB ||"",
+ type: "source",
+ step: "2"
+ }));
},
cleanup: function(){
clearInterval(pollingInfo.intervalId);
},
+ createTargetActiveState: function(e){
+ var $currentTarget = this.$(e.currentTarget);
+ $currentTarget.parents("#create_target").find('.active').removeClass('active');
+ $currentTarget.addClass('active');
+ },
enableFields: function(){
this.$el.find('input','select').attr('disabled',false);
},
disableFields: function(){
- this.$el.find('input:hidden','select:hidden').attr('disabled',true);
- },
- showFields: function(e){
- var $currentTarget = this.$(e.currentTarget),
- targetVal = $currentTarget.val();
-
- if (targetVal === "local"){
- $currentTarget.parents('.form_set').addClass('local');
- }else{
- $currentTarget.parents('.form_set').removeClass('local');
- }
+ this.$el.find('input[type="text"]:hidden','select:hidden').not("[type='radio']").attr('disabled',true);
},
establish: function(){
return [ this.collection.fetch(), this.status.fetch()];
},
- validate: function(e){
- e.preventDefault();
- var notification;
- if (this.formValidation()){
- notification = FauxtonAPI.addNotification({
- msg: "Please enter every field.",
- type: "error",
- clear: true
- });
- }else if (this.$('input#to_name').is(':visible') && !this.$('input[name=create_target]').is(':checked')){
- var alreadyExists = this.collection.where({"name":this.$('input#to_name').val()});
- if (alreadyExists.length === 0){
- notification = FauxtonAPI.addNotification({
- msg: "This database doesn't exist. Check create target if you want to create it.",
- type: "error",
- clear: true
- });
- }
- }else{
- this.submit(e);
- }
- },
- formValidation: function(e){
- var $remote = this.$el.find('input:visible'),
+ validationCheck: function(e){
+ var $remote = this.$el.find('input:visible').not('[data-validation="optional"]'),
error = false;
for(var i=0; i<$remote.length; i++){
if ($remote[i].value =="http://" || $remote[i].value ===""){
@@ -124,12 +93,24 @@ function(app, FauxtonAPI, Components, replication) {
}
return error;
},
+ nextStep: function(e){
+ this.$("#"+this.$(e.currentTarget).attr('data-next-step')).removeClass('hide');
+ },
serialize: function(){
return {
- databases: this.collection.toJSON(),
- selectedDB: this.selectedDB
+ host: app.host+"/"
};
},
+ showTargetForm: function(e){
+ if (this.targetForm){ this.targetForm.remove();}
+ var targetView = this.$('[name="create_target"]:checked').val()==="true"? "CreateTarget": "LocalRemoteTabs";
+ this.targetForm = this.insertView("#target_form",new View[targetView]({
+ type: "target",
+ step: "4"
+ }));
+ this.targetForm.render();
+ this.nextStep(e);
+ },
startReplication: function(json){
var that = this;
this.newRepModel.save(json,{
@@ -153,7 +134,7 @@ function(app, FauxtonAPI, Components, replication) {
}
});
this.enableFields();
- },
+ },
updateButtonText: function(wait){
var $button = this.$('#replication button[type=submit]');
if(wait){
@@ -162,41 +143,241 @@ function(app, FauxtonAPI, Components, replication) {
$button.text('Replication').attr('disabled', false);
}
},
+ validate: function(e){
+ e.preventDefault();
+ var notification;
+
+ if (this.validationCheck()){
+ notification = FauxtonAPI.addNotification({
+ msg: "Please enter every field.",
+ type: "error",
+ clear: true
+ });
+ } else if (this.$('input#to_name').is(':visible') && !this.$('input[name=create_target]').is(':checked')){
+ var alreadyExists = this.collection.where({"name":this.$('input#to_name').val()});
+ if (alreadyExists.length === 0){
+ notification = FauxtonAPI.addNotification({
+ msg: "This database doesn't exist. Select New Database if you want to create it.",
+ type: "error",
+ clear: true
+ });
+ }else{
+ this.submit(e);
+ }
+ }else{
+ this.submit(e);
+ }
+ },
submit: function(e){
- this.disableFields();
- var formJSON = {};
+ this.disableFields();
+ var formData = this.scrubFormData(e),
+ that = this;
+ this.updateButtonText(true);
+ if (this.collection.where({"name":"_replicator"}).length !==0){
+ this.startReplication(formData);
+ } else {
+ var db = new this.collection.model();
+ db.save({
+ id: "_replicator",
+ name: "_replicator"
+ }).done(function(){
+ that.startReplication(formData);
+ });
+ }
+
+ },
+ setAuthHeaders: function(source,user,pass){
+ var basicHeader = new FauxtonAPI.session.createBasicAuthHeader(user,pass),
+ json = {};
+ json.url = app.temphost+"/"+source;
+ json.headers = {
+ "Authorization": basicHeader.basicAuthHeader
+ };
+ return json;
+ },
+ scrubFormData: function(e){
+ var data = {},
+ scrub = {};
_.map(this.$(e.currentTarget).serializeArray(), function(formData){
if(formData.value !== ''){
- formJSON[formData.name] = (formData.value ==="true"? true: formData.value.replace(/\s/g, '').toLowerCase());
+ //clean booleans & whitespaces
+ if (formData.name == "_id" || formData.name == "create_target" ){
+ data[formData.name] = (formData.value ==="true"? true: formData.value.replace(/\s/g, '').toLowerCase());
+ } else {
+ //Lotta stuff needs to be scrubbed before it's in proper json to submit
+ scrub[formData.name] = formData.value.replace(/\s/g, '').toLowerCase();
+ }
}
});
- this.updateButtonText(true);
- this.startReplication(formJSON);
- },
- swapFields: function(e){
+ //username & password for source
+ if ( scrub.user_source && scrub.password_source){
+ data.source = this.setAuthHeaders(scrub.source, scrub.user_source, scrub.password_source);
+ } else {
+ data.source = scrub.source;
+ }
+
+ //username & password for target
+ if ( scrub.user_target && scrub.password_target){
+ data.target = this.setAuthHeaders(scrub.target, scrub.user_target, scrub.password_target);
+ } else {
+ data.target = scrub.target;
+ }
+
+ return data;
+ }
+ });
+
+ View.AdvancedOptions = FauxtonAPI.View.extend({
+ className: "authenticate",
+ template: "addons/replication/templates/options",
+ events: {
+ "click .options": "toggleAdvancedOptions",
+ },
+ toggleAdvancedOptions: function(e){
+ this.$(e.currentTarget).toggleClass("off");
+ this.$('.advancedOptions').toggle("hidden").find('input').removeAttr('disabled');
+ }
+ });
+
+
+ View.LocalRemoteTabs = FauxtonAPI.View.extend({
+ template: "addons/replication/templates/localremotetabs",
+ events: {
+ "click .nav-tabs a": "tabs",
+ "change .permission": "showAuth"
+ },
+ afterRender: function(){
+ this.dbSearchTypeahead = new Components.DbSearchTypeahead({
+ dbLimit: 30,
+ el: "input.auto",
+ updater: function(item){
+ return app.host+"/"+item;
+ }
+ });
+ this.dbSearchTypeahead.render();
+
+ this.preselectedDatabase();
+ },
+ initialize: function(options){
+ this.type = options.type;
+ this.step = options.step;
+ this.selected = options.selectedDB || "";
+ },
+ preselectedDatabase: function(){
+ //if selected database is passed through from the _all_dbs page
+ if (this.selected){
+ this.$('input.auto').val(this.selected);
+ this.showAuthFields();
+ }
+ },
+ showAdvancedOptions: function(e){
+ if (this.advancedOptions){ this.advancedOptions.remove();}
+ this.advancedOptions = this.insertView("#options-here", new View.AdvancedOptions({}));
+ this.advancedOptions.render();
+ },
+ showAuthFields: function(e){
+ var dataAuthSelector = this.$('input.auto').attr('name'),
+ autharea = ".authArea_"+dataAuthSelector,
+ nextStep = this.step;
+
+ if (this[dataAuthSelector]){ this[dataAuthSelector].remove();}
+
+ this[dataAuthSelector] = this.insertView(autharea, new View.AuthFields({
+ type: dataAuthSelector,
+ step: nextStep }));
+ this[dataAuthSelector].render();
+ },
+ showAuth: function(e){
+ if (this.$(e.currentTarget).attr('name') === "source"){
+ this.showAdvancedOptions(e);
+ }
+ this.showAuthFields(e);
+ },
+ tabs: function(e){
e.preventDefault();
- //WALL O' VARIABLES
- var $fromSelect = this.$('#from_name'),
- $toSelect = this.$('#to_name'),
- $toInput = this.$('#to_url'),
- $fromInput = this.$('#from_url'),
- fromSelectVal = $fromSelect.val(),
- fromInputVal = $fromInput.val(),
- toSelectVal = $toSelect.val(),
- toInputVal = $toInput.val();
+ var $currentTarget = this.$(e.currentTarget),
+ getTabID = "#"+$currentTarget.attr('data-tab');
- $fromSelect.val(toSelectVal);
- $toSelect.val(fromSelectVal);
+ $currentTarget.parents('ul').find('.active').removeClass('active');
+ $currentTarget.parents('li').addClass('active');
- $fromInput.val(toInputVal);
- $toInput.val(fromInputVal);
+ $(getTabID).parents('.tab-content').find('.active').removeClass('active');
+ $(getTabID).addClass('active');
+ },
+ serialize: function(){
+ return {
+ step: this.step,
+ type: this.type
+ };
}
});
+ View.CreateTarget = FauxtonAPI.View.extend({
+ template: "addons/replication/templates/newdatabase",
+ events: {
+ "click .nav-tabs a": "tabs",
+ "change .permission": "showAuth"
+ },
+ initialize: function(options){
+ this.type = options.type;
+ this.step = options.step;
+ },
+ showAuthFields: function(e){
+ var dataAuthSelector = this.$(e.currentTarget).attr('name'),
+ autharea = ".authArea_"+dataAuthSelector;
+
+ if (this[dataAuthSelector]){ this[dataAuthSelector].remove();}
+
+ this[dataAuthSelector] = this.insertView(autharea, new View.AuthFields({
+ type:dataAuthSelector,
+ step:"4"
+ }));
+ this[dataAuthSelector].render();
+ },
+ showAuth: function(e){
+ if (this.$(e.currentTarget).attr('name') === "source"){
+ this.showAdvancedOptions(e);
+ }
+ this.showAuthFields(e);
+ },
+ tabs: function(e){
+ e.preventDefault();
+ var $currentTarget = this.$(e.currentTarget),
+ getTabID = "#"+$currentTarget.attr('data-tab');
+
+ $currentTarget.parents('ul').find('.active').removeClass('active');
+ $currentTarget.parents('li').addClass('active');
+
+ $(getTabID).parents('.tab-content').find('.active').removeClass('active');
+ $(getTabID).addClass('active');
+ },
+ serialize: function(){
+ return {
+ step: this.step,
+ type: this.type
+ };
+ }
+ });
+
+
+ View.AuthFields = FauxtonAPI.View.extend({
+ template: "addons/replication/templates/authfields",
+ initialize: function(options){
+ this.type = options.type;
+ this.step = options.step;
+ },
+ serialize: function(){
+ return {
+ step: this.step,
+ type: this.type
+ };
+ }
+ });
View.ReplicationList = FauxtonAPI.View.extend({
tagName: "ul",
+ className: "testing",
initialize: function(){
Events.bind('update:tasks', this.establish, this);
this.listenTo(this.collection, "reset", this.render);
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/app/templates/layouts/one_pane_notabs.html
----------------------------------------------------------------------
diff --git a/src/fauxton/app/templates/layouts/one_pane_notabs.html b/src/fauxton/app/templates/layouts/one_pane_notabs.html
new file mode 100644
index 0000000..f58661f
--- /dev/null
+++ b/src/fauxton/app/templates/layouts/one_pane_notabs.html
@@ -0,0 +1,27 @@
+<!--
+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.
+-->
+
+<div id="primary-navbar"></div>
+<div id="dashboard" class="container-fluid one-pane">
+ <div class="fixed-header">
+ <div id="breadcrumbs"></div>
+ <div id="api-navbar"></div>
+ </div>
+
+
+ <div class="row-fluid content-area">
+ <div id="dashboard-content" class="window-resizeable"></div>
+ </div>
+</div>
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62e6dacc/src/fauxton/assets/js/plugins/happy.js
----------------------------------------------------------------------
diff --git a/src/fauxton/assets/js/plugins/happy.js b/src/fauxton/assets/js/plugins/happy.js
new file mode 100644
index 0000000..5c4dc7c
--- /dev/null
+++ b/src/fauxton/assets/js/plugins/happy.js
@@ -0,0 +1,150 @@
+// HAPPY JS.
+// WARNING: this has been editted to support custom error message handling.
+// $('#awesomeForm').isHappy({
+// fields: {
+// // reference the field you're talking about, probably by `id`
+// // but you could certainly do $('[name=name]') as well.
+// '#yourName': {
+// required: true,
+// message: 'Might we inquire your name'
+// },
+// '#email': {
+// required: true,
+// message: 'How are we to reach you sans email??',
+// test: happy.email // this can be *any* function that returns true or false
+// }
+// },
+// errorHandling: function(error){console.log(error.message);}
+// });
+//
+// if you don't pass in a function for errorHandling, it behaves as designed. - Sue
+
+(function($){
+ function trim(el) {
+ return (''.trim) ? el.val().trim() : $.trim(el.val());
+ }
+ $.fn.isHappy = function (config) {
+ var fields = [],
+ item;
+
+ function errorMessaging(error,selector){
+ if(config.errorHandling){
+ config.errorHandling(error);
+ }else{
+ if ($("#"+error.id).length <= 0){
+ var errorEl = $('<span id="'+error.id+'" class="unhappyMessage">'+error.message+'</span>');
+ $(selector).after(errorEl);
+ }
+ }
+ }
+ function handleSubmit(e) {
+ var errors = false, i, l;
+ for (i = 0, l = fields.length; i < l; i += 1) {
+ if (!fields[i].testValid(true)) {
+ errors = true;
+ }
+ }
+ if (errors) {
+ if (isFunction(config.unHappy)) config.unHappy();
+ return false;
+ } else if (config.testMode) {
+ if (window.console) console.warn('would have submitted');
+ return false;
+ }
+ }
+ function isFunction (obj) {
+ return !!(obj && obj.constructor && obj.call && obj.apply);
+ }
+ function processField(opts, selector) {
+ var field = $(selector),
+ errorM = {
+ message: opts.message,
+ id: field.attr('name') + '_unhappy'
+ };
+ // },
+ // errorEl = $(error.id).length > 0 ? $(error.id) : getError(error);
+
+ fields.push(field);
+ field.testValid = function (submit) {
+ var val,
+ el = $(this),
+ gotFunc,
+ error = false,
+ temp,
+ required = !!el.get(0).attributes.getNamedItem('required') || opts.required,
+ password = (field.attr('type') === 'password'),
+ arg = isFunction(opts.arg) ? opts.arg() : opts.arg;
+
+ // clean it or trim it
+ if (isFunction(opts.clean)) {
+ val = opts.clean(el.val());
+ } else if (!opts.trim && !password) {
+ val = trim(el);
+ } else {
+ val = el.val();
+ }
+
+ // write it back to the field
+ el.val(val);
+
+ // get the value
+ gotFunc = ((val.length > 0 || required === 'sometimes') && isFunction(opts.test));
+
+ // check if we've got an error on our hands
+ if (submit === true && required === true && val.length === 0) {
+ error = true;
+ } else if (gotFunc) {
+ error = !opts.test(val, arg);
+ }
+
+ if (error) {
+ el.addClass('unhappy');
+ errorMessaging(errorM, el);
+ return false;
+ } else {
+ el.removeClass('unhappy');
+ $("#"+field.attr('name') + '_unhappy').remove();
+ return true;
+ }
+ };
+ field.bind(config.when || 'blur', field.testValid);
+ }
+
+ for (item in config.fields) {
+ processField(config.fields[item], item);
+ }
+
+ if (config.submitButton) {
+ $(config.submitButton).click(handleSubmit);
+ } else {
+ this.bind('submit', handleSubmit);
+ }
+ return this;
+ };
+})(this.jQuery || this.Zepto);
+var happy = {
+ USPhone: function (val) {
+ return (/^\(?(\d{3})\)?[\- ]?\d{3}[\- ]?\d{4}$/).test(val);
+ },
+
+ // matches mm/dd/yyyy (requires leading 0's (which may be a bit silly, what do you think?)
+ date: function (val) {
+ return (/^(?:0[1-9]|1[0-2])\/(?:0[1-9]|[12][0-9]|3[01])\/(?:\d{4})/).test(val);
+ },
+
+ email: function (val) {
+ return (/^(?:\w+\.?)*\w+@(?:\w+\.)+\w+$/).test(val);
+ },
+
+ minLength: function (val, length) {
+ return val.length >= length;
+ },
+
+ maxLength: function (val, length) {
+ return val.length <= length;
+ },
+
+ equal: function (val1, val2) {
+ return (val1 == val2);
+ }
+};
[08/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Open CouchDB maintenance section about keeping CouchDB live and well.
Import Compaction article. Source: http://wiki.apache.org/couchdb/Compaction
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6f007f86
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6f007f86
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6f007f86
Branch: refs/heads/replicator-redesign
Commit: 6f007f867feb7f9cd88e63a8bef1ee883c2bfce3
Parents: 28e1b1f
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Sep 8 22:16:11 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 6 +
share/doc/src/index.rst | 1 +
share/doc/src/maintenance/compaction.rst | 193 ++++++++++++++++++++++++++
share/doc/src/maintenance/index.rst | 20 +++
4 files changed, 220 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index bc4af7b..f59e557 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -117,6 +117,8 @@ html_files = \
html/_sources/intro/overview.txt \
html/_sources/intro/tour.txt \
html/_sources/intro/why.txt \
+ html/_sources/maintenance/compaction.txt \
+ html/_sources/maintenance/index.txt \
html/_sources/query-server/index.txt \
html/_sources/query-server/erlang.txt \
html/_sources/query-server/javascript.txt \
@@ -231,6 +233,8 @@ html_files = \
html/intro/overview.html \
html/intro/tour.html \
html/intro/why.html \
+ html/maintenance/compaction.html \
+ html/maintenance/index.html \
html/query-server/index.html \
html/query-server/erlang.html \
html/query-server/javascript.html \
@@ -367,6 +371,8 @@ src_files = \
../src/intro/overview.rst \
../src/intro/tour.rst \
../src/intro/why.rst \
+ ../src/maintenance/compaction.rst \
+ ../src/maintenance/index.rst \
../src/query-server/index.rst \
../src/query-server/erlang.rst \
../src/query-server/javascript.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index c41cc9f..bb491de 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -21,6 +21,7 @@
intro/index
install/index
config/index
+ maintenance/index
replication/index
couchapp/index
externals
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/src/maintenance/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/compaction.rst b/share/doc/src/maintenance/compaction.rst
new file mode 100644
index 0000000..c2859bf
--- /dev/null
+++ b/share/doc/src/maintenance/compaction.rst
@@ -0,0 +1,193 @@
+.. 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.
+
+.. _compact:
+
+Compaction
+==========
+
+The `compaction` operation is the way to reduce disk space usage by removing
+unused and old data from database or view index files. This operation is a very
+similar to the `vacuum` (`SQLite`_ ex.) available for other database management
+systems.
+
+.. _SQLite: http://www.sqlite.org/lang_vacuum.html
+
+During compaction of the `target` CouchDB creates new file with the ``.compact``
+extension and transfers only actual data into. Because of this, CouchDB checks
+first for the available disk space - it should be *twice greater* than the
+compacted file's data.
+
+When all actual data successful transferred to the `compacted` file CouchDB
+*removes* the `target` replacing him with it.
+
+
+.. _compact/db:
+
+Database Compaction
+-------------------
+
+Database compaction compresses the database file by removing unused file
+sections created during updates. Old documents revisions are replaced with
+small amount of metadata called `tombstone` which are used for conflicts
+resolution during replication. The number of stored revisions
+(and their `tombstones`) can be configured by using the :http:get:`_revs_limit
+</{db}/_revs_limit>` URL endpoint.
+
+Compaction is manually triggered operation per database and runs as a background
+task. To start it for specific database there is need to send HTTP
+:http:post:`/{db}/_compact` sub-resource of the target database::
+
+ curl -H "Content-Type: application/json" -X POST http://localhost:5984/my_db/_compact
+
+On success, HTTP status :http:statuscode:`202` is returned immediately:
+
+.. code-block:: http
+
+ HTTP/1.1 202 Accepted
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: text/plain; charset=utf-8
+ Date: Wed, 19 Jun 2013 09:43:52 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+Although the request body is not used you must still specify
+:http:header:`Content-Type` header with :mimetype:`application/json` value
+for the request. If you don't, you will be aware about with HTTP status
+:http:statuscode:`415` response:
+
+.. code-block:: http
+
+ HTTP/1.1 415 Unsupported Media Type
+ Cache-Control: must-revalidate
+ Content-Length: 78
+ Content-Type: application/json
+ Date: Wed, 19 Jun 2013 09:43:44 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+ {"error":"bad_content_type","reason":"Content-Type must be application/json"}
+
+When the compaction is successful started and running it is possible to get
+information about it via :ref:`database information resource <api/db>`::
+
+ curl http://localhost:5984/my_db
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 246
+ Content-Type: application/json
+ Date: Wed, 19 Jun 2013 16:51:20 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+ {
+ "committed_update_seq": 76215,
+ "compact_running": true,
+ "data_size": 3787996,
+ "db_name": "my_db",
+ "disk_format_version": 6,
+ "disk_size": 17703025,
+ "doc_count": 5091,
+ "doc_del_count": 0,
+ "instance_start_time": "1371660751878859",
+ "purge_seq": 0,
+ "update_seq": 76215
+ }
+
+
+Note that ``compaction_running`` field is ``true`` indicating that compaction
+is actually running. To track the compaction progress you may query the
+:http:get:`_active_tasks </_active_tasks>` resource::
+
+ curl http://localhost:5984/my_db
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 175
+ Content-Type: application/json
+ Date: Wed, 19 Jun 2013 16:27:23 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+ [
+ {
+ "changes_done": 44461,
+ "database": "my_db",
+ "pid": "<0.218.0>",
+ "progress": 58,
+ "started_on": 1371659228,
+ "total_changes": 76215,
+ "type": "database_compaction",
+ "updated_on": 1371659241
+ }
+ ]
+
+
+.. _compact/views:
+
+Views Compaction
+----------------
+
+`Views` are also need compaction like databases, unlike databases views
+are compacted by groups per `design document`. To start their compaction there
+is need to send HTTP :http:post:`/{db}/_compact/{ddoc}` request::
+
+ curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_compact/designname
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+This compacts the view index from the current version of the specified design
+document. The HTTP response code is :http:statuscode:`202`
+(like :ref:`compaction for databases <compact/db>`) and a compaction background
+task will be created.
+
+
+.. _compact/views/cleanup:
+
+Views cleanup
+^^^^^^^^^^^^^
+
+View indexes on disk are named after their `MD5` hash of the view definition.
+When you change a view, old indexes remain on disk. To clean up all outdated
+view indexes (files named after the MD5 representation of views, that does not
+exist anymore) you can trigger a :ref:`view cleanup <api/db/view_cleanup>`::
+
+ curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_view_cleanup
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+
+.. _compact/auto:
+
+Automatic Compaction
+--------------------
+
+While both :ref:`database <compact/db>` and :ref:`views <compact/views>`
+compactions are required be manually triggered, it is also possible to configure
+automatic compaction, so that compaction of databases and views is automatically
+triggered based on various criteria. Automatic compaction is configured in
+CouchDB's :ref:`configuration files <config/intro>`.
+
+The :ref:`compaction daemon <config/daemons/compaction_daemon>` is responsible
+for triggering the compaction. It is automatically started, but disabled by
+default. The criteria for triggering the compactions is configured in the
+:ref:`compactions <config/compactions>` section.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/src/maintenance/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/index.rst b/share/doc/src/maintenance/index.rst
new file mode 100644
index 0000000..86cc761
--- /dev/null
+++ b/share/doc/src/maintenance/index.rst
@@ -0,0 +1,20 @@
+.. 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 Maintenance
+===================
+
+.. toctree::
+
+ compaction
[46/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Merge branch '1781-reorganize-and-improve-docs'
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/17e0b7c6
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/17e0b7c6
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/17e0b7c6
Branch: refs/heads/replicator-redesign
Commit: 17e0b7c6e103b81d9abca39cedfd5378a467bdfc
Parents: 221ada7 30f0599
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 16:40:49 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 16:40:49 2013 +0400
----------------------------------------------------------------------
.gitignore | 2 +
LICENSE | 31 +
NOTICE | 25 +-
license.skip | 7 +
share/doc/build/Makefile.am | 382 +++++-
share/doc/ext/github.py | 44 +
share/doc/ext/http-api-descr.json | 79 ++
share/doc/ext/httpdomain.py | 650 +++++++++
share/doc/images/futon-editdoc.png | Bin 64369 -> 52733 bytes
share/doc/images/futon-editeddoc.png | Bin 69595 -> 56005 bytes
share/doc/images/futon-overview.png | Bin 63039 -> 50815 bytes
share/doc/images/futon-replform.png | Bin 68068 -> 52223 bytes
share/doc/images/intro-consistency-01.png | Bin 0 -> 35605 bytes
share/doc/images/intro-consistency-02.png | Bin 0 -> 48145 bytes
share/doc/images/intro-consistency-03.png | Bin 0 -> 17333 bytes
share/doc/images/intro-consistency-04.png | Bin 0 -> 13744 bytes
share/doc/images/intro-consistency-05.png | Bin 0 -> 25592 bytes
share/doc/images/intro-consistency-06.png | Bin 0 -> 56651 bytes
share/doc/images/intro-consistency-07.png | Bin 0 -> 53634 bytes
share/doc/images/intro-tour-01.png | Bin 0 -> 50815 bytes
share/doc/images/intro-tour-02.png | Bin 0 -> 83380 bytes
share/doc/images/intro-tour-03.png | Bin 0 -> 53795 bytes
share/doc/images/intro-tour-04.png | Bin 0 -> 56470 bytes
share/doc/images/intro-tour-05.png | Bin 0 -> 53778 bytes
share/doc/images/intro-tour-06.png | Bin 0 -> 61296 bytes
share/doc/images/intro-tour-07.png | Bin 0 -> 67121 bytes
share/doc/images/intro-tour-08.png | Bin 0 -> 83494 bytes
share/doc/images/intro-tour-09.png | Bin 0 -> 84701 bytes
share/doc/images/intro-tour-10.png | Bin 0 -> 61631 bytes
share/doc/images/intro-why-01.png | Bin 0 -> 25755 bytes
share/doc/images/intro-why-02.png | Bin 0 -> 5937 bytes
share/doc/images/intro-why-03.png | Bin 0 -> 5134 bytes
share/doc/images/views-intro-01.png | Bin 0 -> 1026767 bytes
share/doc/images/views-intro-02.png | Bin 0 -> 9758 bytes
share/doc/images/views-intro-03.png | Bin 0 -> 12650 bytes
share/doc/images/views-intro-04.png | Bin 0 -> 14537 bytes
share/doc/src/about.rst | 25 +
share/doc/src/api-basics.rst | 463 -------
share/doc/src/api/authn.rst | 41 -
share/doc/src/api/basics.rst | 601 +++++++++
share/doc/src/api/configuration.rst | 297 ----
share/doc/src/api/database.rst | 1471 --------------------
share/doc/src/api/database/bulk-api.rst | 599 +++++++++
share/doc/src/api/database/changes.rst | 556 ++++++++
share/doc/src/api/database/common.rst | 423 ++++++
share/doc/src/api/database/compact.rst | 239 ++++
share/doc/src/api/database/index.rst | 47 +
share/doc/src/api/database/misc.rst | 339 +++++
share/doc/src/api/database/security.rst | 180 +++
share/doc/src/api/database/temp-views.rst | 78 ++
share/doc/src/api/ddoc/common.rst | 216 +++
share/doc/src/api/ddoc/index.rst | 37 +
share/doc/src/api/ddoc/render.rst | 380 ++++++
share/doc/src/api/ddoc/rewrites.rst | 89 ++
share/doc/src/api/ddoc/views.rst | 779 +++++++++++
share/doc/src/api/design.rst | 1264 -----------------
share/doc/src/api/document/attachments.rst | 314 +++++
share/doc/src/api/document/common.rst | 1178 ++++++++++++++++
share/doc/src/api/document/index.rst | 26 +
share/doc/src/api/documents.rst | 973 --------------
share/doc/src/api/index.rst | 42 +
share/doc/src/api/local.rst | 139 +-
share/doc/src/api/misc.rst | 867 ------------
share/doc/src/api/reference.rst | 42 -
share/doc/src/api/server/authn.rst | 451 +++++++
share/doc/src/api/server/common.rst | 1000 ++++++++++++++
share/doc/src/api/server/configuration.rst | 332 +++++
share/doc/src/api/server/index.rst | 28 +
share/doc/src/changelog.rst | 1489 ---------------------
share/doc/src/changes.rst | 227 ----
share/doc/src/conf.py | 91 +-
share/doc/src/config/auth.rst | 401 ++++++
share/doc/src/config/compaction.rst | 181 +++
share/doc/src/config/couchdb.rst | 229 ++++
share/doc/src/config/externals.rst | 179 +++
share/doc/src/config/http-handlers.rst | 341 +++++
share/doc/src/config/http.rst | 680 ++++++++++
share/doc/src/config/index.rst | 34 +
share/doc/src/config/intro.rst | 168 +++
share/doc/src/config/logging.rst | 94 ++
share/doc/src/config/misc.rst | 221 +++
share/doc/src/config/proxying.rst | 98 ++
share/doc/src/config/query-servers.rst | 164 +++
share/doc/src/config/replicator.rst | 193 +++
share/doc/src/config/services.rst | 175 +++
share/doc/src/config_reference.rst | 330 -----
share/doc/src/configuring.rst | 629 ---------
share/doc/src/contents.rst | 39 +
share/doc/src/couchapp/ddocs.rst | 759 +++++++++++
share/doc/src/couchapp/index.rst | 31 +
share/doc/src/couchapp/views/collation.rst | 256 ++++
share/doc/src/couchapp/views/index.rst | 30 +
share/doc/src/couchapp/views/intro.rst | 675 ++++++++++
share/doc/src/couchapp/views/joins.rst | 430 ++++++
share/doc/src/couchapp/views/nosql.rst | 530 ++++++++
share/doc/src/couchapp/views/pagination.rst | 287 ++++
share/doc/src/cve/2010-0009.rst | 54 +
share/doc/src/cve/2010-2234.rst | 64 +
share/doc/src/cve/2010-3854.rst | 57 +
share/doc/src/cve/2012-5641.rst | 77 ++
share/doc/src/cve/2012-5649.rst | 50 +
share/doc/src/cve/2012-5650.rst | 69 +
share/doc/src/cve/index.rst | 73 +
share/doc/src/ddocs.rst | 751 -----------
share/doc/src/externals.rst | 259 ++++
share/doc/src/fauxton/addons.rst | 199 +++
share/doc/src/fauxton/index.rst | 23 +
share/doc/src/fauxton/install.rst | 109 ++
share/doc/src/index.rst | 46 -
share/doc/src/install/freebsd.rst | 80 ++
share/doc/src/install/gentoo.rst | 29 +
share/doc/src/install/index.rst | 27 +
share/doc/src/install/mac.rst | 194 +++
share/doc/src/install/unix.rst | 269 ++++
share/doc/src/install/windows.rst | 275 ++++
share/doc/src/intro.rst | 309 -----
share/doc/src/intro/api.rst | 783 +++++++++++
share/doc/src/intro/consistency.rst | 465 +++++++
share/doc/src/intro/curl.rst | 122 ++
share/doc/src/intro/futon.rst | 186 +++
share/doc/src/intro/index.rst | 56 +
share/doc/src/intro/overview.rst | 387 ++++++
share/doc/src/intro/security.rst | 525 ++++++++
share/doc/src/intro/tour.rst | 542 ++++++++
share/doc/src/intro/why.rst | 315 +++++
share/doc/src/json-structure.rst | 189 ---
share/doc/src/maintenance/compaction.rst | 193 +++
share/doc/src/maintenance/index.rst | 21 +
share/doc/src/maintenance/performance.rst | 293 ++++
share/doc/src/query-server/erlang.rst | 139 ++
share/doc/src/query-server/index.rst | 40 +
share/doc/src/query-server/javascript.rst | 288 ++++
share/doc/src/query-server/protocol.rst | 967 +++++++++++++
share/doc/src/query-servers.rst | 436 ------
share/doc/src/replication.rst | 95 --
share/doc/src/replication/conflicts.rst | 793 +++++++++++
share/doc/src/replication/index.rst | 37 +
share/doc/src/replication/intro.rst | 95 ++
share/doc/src/replication/protocol.rst | 202 +++
share/doc/src/replication/replicator.rst | 383 ++++++
share/doc/src/replicator.rst | 383 ------
share/doc/src/whatsnew/0.10.rst | 150 +++
share/doc/src/whatsnew/0.11.rst | 357 +++++
share/doc/src/whatsnew/0.8.rst | 178 +++
share/doc/src/whatsnew/0.9.rst | 262 ++++
share/doc/src/whatsnew/1.0.rst | 277 ++++
share/doc/src/whatsnew/1.1.rst | 175 +++
share/doc/src/whatsnew/1.2.rst | 242 ++++
share/doc/src/whatsnew/1.3.rst | 256 ++++
share/doc/src/whatsnew/1.4.rst | 61 +
share/doc/src/whatsnew/1.5.rst | 31 +
share/doc/src/whatsnew/index.rst | 32 +
share/doc/templates/couchdb/domainindex.html | 49 +
share/doc/templates/couchdb/theme.conf | 13 +
share/doc/templates/help.html | 9 +
share/doc/templates/layout.html | 27 +
share/doc/templates/pages/download.html | 48 +
share/doc/templates/pages/index.html | 156 +++
src/fauxton/app/helpers.js | 14 +-
159 files changed, 26485 insertions(+), 10498 deletions(-)
----------------------------------------------------------------------
[15/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Wrong image for temporary views.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5562be1a
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5562be1a
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5562be1a
Branch: refs/heads/replicator-redesign
Commit: 5562be1ad33f525a0b7f91481ca720f6c35e0dd3
Parents: d1e3b5d
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 4 19:43:45 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/images/intro-tour-07.png | Bin 47487 -> 67121 bytes
1 file changed, 0 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5562be1a/share/doc/images/intro-tour-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-07.png b/share/doc/images/intro-tour-07.png
index e75987d..229ce63 100644
Binary files a/share/doc/images/intro-tour-07.png and b/share/doc/images/intro-tour-07.png differ
[22/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Fix main TOC tree reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/2375d005
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/2375d005
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/2375d005
Branch: refs/heads/replicator-redesign
Commit: 2375d0056a9fb866a06ec59a632ccc8b5cf4cbf9
Parents: ebaac5c
Author: Alexander Shorin <kx...@apache.org>
Authored: Fri Sep 27 21:15:26 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 6 +++---
share/doc/src/conf.py | 4 ++--
2 files changed, 5 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2375d005/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 729313a..d03eb30 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -139,9 +139,9 @@ html_files = \
html/_sources/whatsnew/1.3.txt \
html/_sources/whatsnew/1.4.txt \
html/_sources/whatsnew/index.txt \
+ html/_sources/contents.txt \
html/_sources/contributing.txt \
html/_sources/externals.txt \
- html/_sources/index.txt \
html/_sources/json-structure.txt \
html/_static/ajax-loader.gif \
html/_static/basic.css \
@@ -256,8 +256,8 @@ html_files = \
html/whatsnew/1.3.html \
html/whatsnew/1.4.html \
html/whatsnew/index.html \
+ html/contents.html \
html/externals.html \
- html/index.html \
html/json-structure.html \
html/objects.inv \
html/http-api.html \
@@ -395,9 +395,9 @@ src_files = \
../src/whatsnew/1.3.rst \
../src/whatsnew/1.4.rst \
../src/whatsnew/index.rst \
+ ../src/contents.rst \
../src/contributing.rst \
../src/externals.rst \
- ../src/index.rst \
../src/json-structure.rst \
../src/conf.py
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2375d005/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index f60e545..6cdb9ef 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -108,7 +108,7 @@ html_sidebars = {
text_newlines = "native"
latex_documents = [(
- "index",
+ "contents",
"CouchDB.tex",
project,
"",
@@ -121,7 +121,7 @@ latex_elements = {
}
texinfo_documents = [(
- "index",
+ "contents",
"CouchDB",
project,
"",
[09/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Preserve valid JSON output.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/28e1b1fc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/28e1b1fc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/28e1b1fc
Branch: refs/heads/replicator-redesign
Commit: 28e1b1fcf63264782bddfa9b8d8208ac0fcd6c83
Parents: 360381a
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 7 21:29:33 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/views.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/28e1b1fc/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index 00aa077..bb45095 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -397,7 +397,7 @@ content. The basic order of output is as follows:
},
{
"id": "dummy-doc",
- "key": "привет",
+ "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
"value": null
},
{
@@ -516,7 +516,7 @@ You can reverse the order of the returned view information by using the
},
{
"id": "dummy-doc",
- "key": "привет",
+ "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
"value": null
},
{
[37/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Add about page with CouchDB license.
While sources are ships with all license bits, documentation artifacts lack of such.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6b50511d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6b50511d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6b50511d
Branch: refs/heads/replicator-redesign
Commit: 6b50511d88d29d50e0b9b927d239e337087f4e4b
Parents: 088ea1e
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:43:00 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:43:00 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +++
share/doc/src/about.rst | 25 +++++++++++++++++++++++++
share/doc/src/contents.rst | 1 +
3 files changed, 29 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6b50511d/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 5a9441f..c83e392 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -139,6 +139,7 @@ html_files = \
html/_sources/whatsnew/1.3.txt \
html/_sources/whatsnew/1.4.txt \
html/_sources/whatsnew/index.txt \
+ html/_sources/about.txt \
html/_sources/contents.txt \
html/_sources/contributing.txt \
html/_sources/externals.txt \
@@ -256,6 +257,7 @@ html_files = \
html/whatsnew/1.3.html \
html/whatsnew/1.4.html \
html/whatsnew/index.html \
+ html/about.html \
html/contents.html \
html/externals.html \
html/json-structure.html \
@@ -395,6 +397,7 @@ src_files = \
../src/whatsnew/1.3.rst \
../src/whatsnew/1.4.rst \
../src/whatsnew/index.rst \
+ ../src/about.rst \
../src/contents.rst \
../src/contributing.rst \
../src/externals.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6b50511d/share/doc/src/about.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/about.rst b/share/doc/src/about.rst
new file mode 100644
index 0000000..fe24c61
--- /dev/null
+++ b/share/doc/src/about.rst
@@ -0,0 +1,25 @@
+.. 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.
+
+
+.. _about:
+
+===========================
+About CouchDB Documentation
+===========================
+
+License
+=======
+
+.. literalinclude:: ../../../LICENSE
+ :lines: 1-202
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6b50511d/share/doc/src/contents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/contents.rst b/share/doc/src/contents.rst
index 700e90a..0b38b73 100644
--- a/share/doc/src/contents.rst
+++ b/share/doc/src/contents.rst
@@ -32,6 +32,7 @@
contributing
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
[07/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Remove duplicate content.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a103e74f
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a103e74f
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a103e74f
Branch: refs/heads/replicator-redesign
Commit: a103e74fb7fcccaa8c84837699fb411dbd160e82
Parents: 71ec756
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 17:30:35 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/basics.rst | 65 ++-------------------------------------
1 file changed, 2 insertions(+), 63 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a103e74f/share/doc/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/basics.rst b/share/doc/src/api/basics.rst
index dd64257..74465b6 100644
--- a/share/doc/src/api/basics.rst
+++ b/share/doc/src/api/basics.rst
@@ -181,8 +181,8 @@ Request Headers
.. code-block:: http
- Server: CouchDB/|version| (Erlang OTP/R13B)
- Date: Thu, 13 Jan 2011 13:40:11 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Date: Thu, 13 Jan 2013 13:40:11 GMT
Content-Type: application/json
Content-Length: 227
Cache-Control: must-revalidate
@@ -589,64 +589,3 @@ corresponding API call reference.
The request was invalid, either because the supplied JSON was
invalid, or invalid information was supplied as part of the request.
-
-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
[29/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
docs: update changes
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/e6f1e841
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/e6f1e841
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/e6f1e841
Branch: refs/heads/replicator-redesign
Commit: e6f1e8411eeb0737d2126f4367dff07238c48de1
Parents: 1f10129
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Fri Sep 27 23:47:42 2013 +0200
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Fri Sep 27 23:47:42 2013 +0200
----------------------------------------------------------------------
share/doc/src/api/database/changes.rst | 53 ++++++++++++++++-------------
1 file changed, 30 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/e6f1e841/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index 344a3bb..739f7d8 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -21,9 +21,10 @@
.. http:head:: /{db}/_changes
.. http:post:: /{db}/_changes
- A list of changes made to documents in the database, in the order they were
- made, can be obtained from the database's ``_changes`` resource.
- This can be used to monitor for update and modifications to the database for
+ A sorted list of changes made to documents in the database, in the order
+ they were made, can be obtained from the database's ``_changes`` resource.
+
+ This can be used to listen for update and modifications to the database for
post processing or synchronization.
:param db: Database name
@@ -162,7 +163,7 @@ Changes Feeds
Polling
-------
-By default all changes are immediately returned as a JSON object::
+By default all changes are immediately returned within the JSON body::
GET /somedatabase/_changes HTTP/1.1
@@ -194,7 +195,7 @@ including the given sequence number::
The return structure for ``normal`` and ``longpoll`` modes is a JSON
array of changes objects, and the last update sequence number.
-The return format for ``continuous`` mode the server sends a ``CRLF``
+In the return format for ``continuous`` mode, the server sends a ``CRLF``
(carriage-return, linefeed) delimited line for each change. Each line
contains the `JSON object` described above.
@@ -203,35 +204,43 @@ of just the change notification) by using the ``include_docs`` parameter.
.. code-block:: javascript
- {"results":[
- {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
- ],
- "last_seq":5}
-
+ {
+ "last_seq": 5
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "2-eec205a9d413992850a6e32678485900"
+ }
+ ],
+ "deleted": true,
+ "id": "deleted",
+ "seq": 5,
+ }
+ ]
+ }
.. _changes/longpoll:
Long Polling
------------
-With long polling the request to the server will remain open until a
-change is made on the database, when the changes will be reported,
-and then the connection will close. The long poll is useful when you
-want to monitor for changes for a specific purpose without wanting to
-monitoring continuously for changes.
-
-The `longpoll` feed (probably most useful used from a browser) is a more
+The `longpoll` feed, probably most applicable for a browser, is a more
efficient form of polling that waits for a change to occur before the response
is sent. `longpoll` avoids the need to frequently poll CouchDB to discover
nothing has changed!
+The request to the server will remain open until a change is made on the
+database and is subsequently transferred, and then the connection will close.
+This is low load for both server and client.
+
The response is basically the same JSON as is sent for the `normal` feed.
Because the wait for a change can be significant you can set a
timeout before the connection is automatically closed (the
``timeout`` argument). You can also set a heartbeat interval (using
the ``heartbeat`` query argument), which sends a newline to keep the
-connection open.
+connection active.
.. _changes/continuous:
@@ -239,7 +248,7 @@ connection open.
Continuous
----------
-Polling the CouchDB server is not a good thing to do. Setting up new HTTP
+Continually polling the CouchDB server is not ideal - setting up new HTTP
connections just to tell the client that nothing happened puts unnecessary
strain on CouchDB.
@@ -271,8 +280,7 @@ results.
Obviously, `... tum tee tum ...` does not appear in the actual response, but
represents a long pause before the change with seq 6 occurred.
-.. _section in the book: http://books.couchdb.org/relax/reference/change-notifications
-
+.. _section in the book: http://guide.couchdb.org/draft/notifications.html
.. _changes/eventsource:
@@ -282,7 +290,6 @@ Event Source
The `eventsource` feed provides push notifications that can be consumed in
the form of DOM events in the browser. Refer to the `W3C eventsource
specification`_ for further details. CouchDB also honors the ``Last-Event-ID``
-header, and if it's present it will take precedence over the ``since`` query
parameter.
.. code-block:: text
@@ -316,7 +323,7 @@ parameter.
.. note::
EventSource connections are subject to cross-origin resource sharing
- restrictions. You might need to use the experimental :ref:`CORS support
+ restrictions. You might need to configure :ref:`CORS support
<cors>` to get the EventSource to work in your application.
.. _W3C eventsource specification: http://www.w3.org/TR/eventsource/
[28/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
docs: update bulk-api
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1f10129e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1f10129e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1f10129e
Branch: refs/heads/replicator-redesign
Commit: 1f10129e99ffe09d2b159aedbb37ea9bbefa6ad9
Parents: 2a8af95
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Fri Sep 27 21:52:02 2013 +0200
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Fri Sep 27 21:52:02 2013 +0200
----------------------------------------------------------------------
share/doc/src/api/database/bulk-api.rst | 34 ++++++++++++++++++++--------
1 file changed, 25 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1f10129e/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index 9017227..eb49a28 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -20,9 +20,9 @@
Returns a JSON structure of all of the documents in a given database.
The information is returned as a JSON structure containing meta
- information about the return structure, and the list documents and basic
- contents, consisting the ID, revision and key. The key is generated from
- the document ID.
+ information about the return structure, including a list of all documents
+ and basic contents, consisting the ID, revision and key. The key is the
+ from the document's ``_id``.
:param db: Database name
:<header Accept: - :mimetype:`application/json`
@@ -47,7 +47,8 @@
specified number. *Optional*.
:query number skip: Skip this number of records before starting to return
the results. Default is ``0``.
- :query string stale: Allow the results from a stale view to be used.
+ :query string stale: Allow the results from a stale view to be used, without
+ triggering a rebuild of all views within the encompassing design doc.
Supported values: ``ok`` and ``update_after``. *Optional*.
:query string startkey: Return records starting with the specified key.
*Optional*.
@@ -56,7 +57,7 @@
document ID. *Optional*.
:query string start_key_doc_id: Alias for `startkey_docid` param.
:query boolean update_seq: Response includes an ``update_seq`` value
- indicating which sequence id of the database the view reflects.
+ indicating which sequence id of the underlying database the view reflects.
Default is ``false``.
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
@@ -64,7 +65,8 @@
:>json number offset: Offset where the document list started
:>json array rows: Array of view row objects. By default the information
returned contains only the document ID and revision.
- :>json number total_rows: Number of documents in the database/view
+ :>json number total_rows: Number of documents in the database/view. Note that
+ this is not the number of rows returned in the actual query.
:>json number update_seq: Current update sequence for the database
:code 200: Request completed successfully
@@ -156,7 +158,7 @@
]
}
- The return JSON is the all documents structure, but with only the
+ The returned JSON is the all documents structure, but with only the
selected keys in the output:
.. code-block:: javascript
@@ -223,7 +225,10 @@
:>jsonarr string error: Error type. *Optional*.
:>jsonarr string reason: Error reason. *Optional*.
:code 201: Document(s) have been created or updated
- :code 400: Invalid request`s JSON data
+ :code 400: The request provided invalid JSON data. Check that your data
+ is both ``utf-8`` and complies to the `JSON specification`_. Tools such as
+ `yajl`_ are available on all platforms that CouchDB runs on to assist with
+ validation and pretty printing.
:code 500: Malformed data provided
**Request**:
@@ -273,16 +278,27 @@
}
]
+.. _JSON specification: http://json.org/
+.. _yajl: http://lloyd.github.io/yajl/
+
Inserting Documents in Bulk
---------------------------
+Each time a document is stored or updated in CouchDB, the internal B-tree
+is updated. Bulk insertion provides efficiency gains in both storage space,
+and time, by consolidating many of the updates to intermediate B-tree nodes.
+
+It is not intended as a way to perform ``ACID``-like transactions in CouchDB,
+the only transaction boundary within CouchDB is a single update to a single
+database. The constraints are detailed in :ref:`api/db/bulk_docs/semantics`.
+
To insert documents in bulk into a database you need to supply a JSON
structure with the array of documents that you want to add to the
database. Using this method you can either include a document ID, or
allow the document ID to be automatically generated.
-For example, the following inserts three new documents, two with the
+For example, the following update inserts three new documents, two with the
supplied document IDs, and one which will have a document ID generated:
.. code-block:: javascript
[02/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Externals API article cleanup.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/b35bf757
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/b35bf757
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/b35bf757
Branch: refs/heads/replicator-redesign
Commit: b35bf757e2376dac20b5a295e08bf208e5aa3ba0
Parents: fe79a4d
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 16:52:13 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/externals.rst | 77 ++++++++++++++++++----------------------
1 file changed, 35 insertions(+), 42 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b35bf757/share/doc/src/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/externals.rst b/share/doc/src/externals.rst
index 10ed34a..9b4530f 100644
--- a/share/doc/src/externals.rst
+++ b/share/doc/src/externals.rst
@@ -19,9 +19,10 @@ CouchDB Externals API
:Author: Paul Joseph Davis
:Date: 2010-09-26
+:Source: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
-For a bit of background, CouchDB has had an API for managing external OS
-processes [1] that are capable of handling HTTP requests for a given
+For a bit of background, CouchDB has had an API for managing `external OS
+processes`_ that are capable of handling HTTP requests for a given
URL prefix. These OS processes communicate with CouchDB using JSON over
stdio. They're dead simple to write and provide CouchDB users an easy way to
extend CouchDB functionality.
@@ -50,7 +51,7 @@ fringe benefits as well. I'm always a fan of extra awesomeness.
After hitting on the idea of adding a reverse proxy, people quickly pointed
out that it would require users to start manually managing their external
-processes using something like Runit [2] or Supervisord [3]. After some
+processes using something like `Runit`_ or `Supervisord`_. After some
more discussions I ran into people that wanted something like _externals that
didn't handle HTTP requests. After that it was easy to see that adding a second
feature that managed OS processes was the way to go.
@@ -60,26 +61,23 @@ of working but requiring more testing. In the case of the HTTP proxy I have no
tests because I can't decide how to test the thing. If you have ideas, I'd
sure like to hear them.
-[Update]: I woke up the other morning realizing that I was being an idiot and
-that Erlang is awesome. There's no reason that I can't have an HTTP client,
+**[Update]**: I woke up the other morning realizing that I was being an idiot
+and that Erlang is awesome. There's no reason that I can't have an HTTP client,
proxy, and server all hosted in the same process. So that's what I did. It
turns out to be a fairly nice way of configuring matching assertions between
the client and the server to test the proxy transmissions.
-The code for both features is in this branch:
-
- http://github.com/davisp/couchdb/tree/new_externals
-
How does it work? - HTTP Proxying
---------------------------------
-To configure a proxy handler, edit your local.ini and add a section like such:
+To configure a :ref:`proxy handler <config/proxy>`, edit your `local.ini` and
+add a section like such::
[httpd_global_handlers]
_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
-This would be approximately what you'd need to do to get CouchDB-Lucene handled
-through this interface. The URL you use to access a query would be:
+This would be approximately what you'd need to do to get `CouchDB-Lucene`_
+handled through this interface. The URL you use to access a query would be:
http://127.0.0.1:5984/_fti/db_name/_design/foo/by_content?q=hello
@@ -105,7 +103,7 @@ one instance of it is alive. If you have something where you want multiple
processes, you need to either tell CouchDB about each one, or have a main
process that forks off the required sub-processes.
-To configure an OS daemon, add this to your local.ini::
+To configure an :ref:`OS daemon <config/os_daemons>`, add this to your local.ini::
[os_daemons]
my_daemon = /path/to/command -with args
@@ -116,8 +114,8 @@ Configuration API
As an added benefit, because stdio is now free, I implemented a simple API
that OS daemons can use to read the configuration of their CouchDB host. This
way you can have them store their configuration inside CouchDB's config system
-if you desire. Or they can peek at things like the bind_address and port that
-CouchDB is using.
+if you desire. Or they can peek at things like the :ref:`bind_address
+<config/httpd/bind_address>` and port that CouchDB is using.
A request for a config section looks like this::
@@ -135,7 +133,7 @@ And the response::
"/path/to/command -with args"\n
-All requests and responses are terminated with a newline (indicated by \n).
+All requests and responses are terminated with a newline (indicated by ``\n``).
Logging API
+++++++++++
@@ -144,24 +142,26 @@ There's also an API for adding messages to CouchDB's logs. Its simply::
["log", $MESG]\n
-Where $MESG is any arbitrary JSON. There is no response from this command. As
-with the config API, the trailing "\n" represents a newline byte.
+Where ``$MESG`` is any arbitrary JSON. There is no response from this command. As
+with the config API, the trailing ``\n`` represents a newline byte.
Dynamic Daemons
+++++++++++++++
The OS daemons react in real time to changes to the configuration system. If
-you set or delete keys in the os_daemons section, the corresponding daemons
-will be started or killed as appropriate.
+you set or delete keys in the :ref:`os_daemons <config/os_daemons>` section,
+the corresponding daemons will be started or killed as appropriate.
Neat. But So What?
------------------
-It was suggested that a good first demo would be a Node.js [5] handler. So, I
+It was suggested that a good first demo would be a `Node.js`_ handler. So, I
present to you a "Hello, World" Node.js handler. Also, remember that this
-currently relies on code in my fork on GitHub [6].
+currently relies on code in my fork on `GitHub`_.
+
+File `node-hello-world.js`:
-File `node-hello-world.js`::
+.. code-block:: javascript
var http = require('http');
var sys = require('sys');
@@ -202,7 +202,9 @@ File `node-hello-world.js`::
console.log(JSON.stringify(["get", "node_hello", "port"]));
-File `local.ini` (Just add these to what you have)::
+File `local.ini` (Just add these to what you have):
+
+.. code-block:: ini
[log]
level = info
@@ -216,7 +218,9 @@ File `local.ini` (Just add these to what you have)::
[httpd_global_handlers]
_hello = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:8000">>}
-And then start CouchDB and try::
+And then start CouchDB and try:
+
+.. code-block:: bash
$ curl -v http://127.0.0.1:5984/_hello
* About to connect() to 127.0.0.1 port 5984 (#0)
@@ -247,20 +251,9 @@ The corresponding CouchDB logs look like::
[info] [<0.95.0>] Daemon "node-hello" :: GET /
-[1]: http://wiki.apache.org/couchdb/ExternalProcesses
-[2]: http://smarden.org/runit/
-[3]: http://supervisord.org/
-[4]: http://www.mikealrogers.com/
-[5]: http://nodejs.org/
-[6]: http://github.com/davisp/couchdb/tree/new_externals
-
-
-Copyright Notice
-----------------
-
-Copyright 2008-2010 Paul Joseph Davis
-
-License
--------
-
-http://creativecommons.org/licenses/by/3.0/
+.. _external OS processes: http://wiki.apache.org/couchdb/ExternalProcesses
+.. _Runit: http://smarden.org/runit/
+.. _Supervisord: http://supervisord.org/
+.. _Node.js: http://nodejs.org/
+.. _GitHub: http://github.com/davisp/couchdb/tree/new_externals
+.. _CouchDB-Lucene: https://github.com/rnewson/couchdb-lucene
[50/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Remove app.temphost
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/62f86842
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/62f86842
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/62f86842
Branch: refs/heads/replicator-redesign
Commit: 62f86842bcdbdee2126716827e8155243e86cb1a
Parents: 62e6dac
Author: suelockwood <de...@gmail.com>
Authored: Thu Sep 26 14:57:55 2013 -0400
Committer: suelockwood <de...@gmail.com>
Committed: Mon Sep 30 16:25:47 2013 -0400
----------------------------------------------------------------------
src/fauxton/app/addons/replication/views.js | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/62f86842/src/fauxton/app/addons/replication/views.js
----------------------------------------------------------------------
diff --git a/src/fauxton/app/addons/replication/views.js b/src/fauxton/app/addons/replication/views.js
index 3366937..6c504f1 100644
--- a/src/fauxton/app/addons/replication/views.js
+++ b/src/fauxton/app/addons/replication/views.js
@@ -24,7 +24,6 @@ function(app, FauxtonAPI, Components, replication) {
intervalId: null
};
- app.temphost ="http://deathbear.cloudant.com";
_.extend(Events, Backbone.Events);
// NOTES: http://wiki.apache.org/couchdb/Replication
@@ -189,7 +188,7 @@ function(app, FauxtonAPI, Components, replication) {
setAuthHeaders: function(source,user,pass){
var basicHeader = new FauxtonAPI.session.createBasicAuthHeader(user,pass),
json = {};
- json.url = app.temphost+"/"+source;
+ json.url = app.host+"/"+source;
json.headers = {
"Authorization": basicHeader.basicAuthHeader
};
[24/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Swap maintenance-replication sections.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/de48ff31
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/de48ff31
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/de48ff31
Branch: refs/heads/replicator-redesign
Commit: de48ff311b223563b302b5e93bd9feba66543c47
Parents: 71abc8f
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 11 20:16:09 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/de48ff31/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index bb491de..f00aed6 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -21,8 +21,8 @@
intro/index
install/index
config/index
- maintenance/index
replication/index
+ maintenance/index
couchapp/index
externals
query-server/index
[44/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Fix distcheck.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6c2123aa
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6c2123aa
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6c2123aa
Branch: refs/heads/replicator-redesign
Commit: 6c2123aacb1048a669440f9c90e8d2679801d6c3
Parents: 1d271f1
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 16:21:52 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 16:21:52 2013 +0400
----------------------------------------------------------------------
license.skip | 1 +
1 file changed, 1 insertion(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6c2123aa/license.skip
----------------------------------------------------------------------
diff --git a/license.skip b/license.skip
index d8389fd..9ade149 100644
--- a/license.skip
+++ b/license.skip
@@ -120,6 +120,7 @@
^src/fauxton/tasks/addon/rename.json
^src/fauxton/app/addons/activetasks/assets/less/activetasks.less
^src/fauxton/app/addons/auth/assets/less/auth.less
+^src/fauxton/app/addons/permissions/assets/less/permissions.less
^src/ibrowse/.*
^src/mochiweb/.*
^src/snappy/.*
[23/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Make main page a bit nicer and friendly.
Looks weird and empty, but we'll fix it later with more content and redesign.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/18735b67
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/18735b67
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/18735b67
Branch: refs/heads/replicator-redesign
Commit: 18735b6794fb2a63f37038bb3ebd5fdabe19d643
Parents: de48ff3
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Sep 12 04:58:16 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 4 +-
share/doc/src/conf.py | 7 +-
share/doc/src/contents.rst | 38 ++++++++
share/doc/src/index.rst | 38 --------
share/doc/templates/layout.html | 27 ++++++
share/doc/templates/pages/index.html | 156 ++++++++++++++++++++++++++++++
6 files changed, 227 insertions(+), 43 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index c13f8a2..1030dcd 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -260,7 +260,7 @@ html_files = \
html/index.html \
html/json-structure.html \
html/objects.inv \
- html/genindex.html \
+ html/http-api.html \
html/search.html \
html/searchindex.js
@@ -404,6 +404,8 @@ src_files = \
src_files_html = \
../static/rtd.css \
../templates/pages/download.html \
+ ../templates/pages/index.html \
+ ../templates/layout.html \
../templates/help.html \
../templates/searchbox.html \
../templates/utilities.html
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 7c49bbf..bfdcd99 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -38,8 +38,6 @@ looks like there is no such file there.''')
source_suffix = ".rst"
-master_doc = "index"
-
nitpicky = True
version = '.'.join([
@@ -79,7 +77,7 @@ html_static_path = ["../static"]
html_title = ' '.join([
project,
version,
- 'Manual'
+ 'Documentation'
])
html_style = "rtd.css"
@@ -91,7 +89,8 @@ html_favicon = "../images/favicon.ico"
html_use_index = False
html_additional_pages = {
- 'download': 'pages/download.html'
+ 'download': 'pages/download.html',
+ 'index': 'pages/index.html'
}
html_context = {}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/src/contents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/contents.rst b/share/doc/src/contents.rst
new file mode 100644
index 0000000..f00aed6
--- /dev/null
+++ b/share/doc/src/contents.rst
@@ -0,0 +1,38 @@
+.. 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.
+
+
+|Apache CouchDB(TM)|_ |release| Documentation
+=============================================
+
+.. toctree::
+ :maxdepth: 3
+ :numbered:
+
+ intro/index
+ install/index
+ config/index
+ replication/index
+ maintenance/index
+ couchapp/index
+ externals
+ query-server/index
+ fauxton/index
+ api/index
+ json-structure
+ contributing
+ whatsnew/index
+ cve/index
+
+.. 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/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
deleted file mode 100644
index f00aed6..0000000
--- a/share/doc/src/index.rst
+++ /dev/null
@@ -1,38 +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.
-
-
-|Apache CouchDB(TM)|_ |release| Documentation
-=============================================
-
-.. toctree::
- :maxdepth: 3
- :numbered:
-
- intro/index
- install/index
- config/index
- replication/index
- maintenance/index
- couchapp/index
- externals
- query-server/index
- fauxton/index
- api/index
- json-structure
- contributing
- whatsnew/index
- cve/index
-
-.. 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/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/templates/layout.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/layout.html b/share/doc/templates/layout.html
new file mode 100644
index 0000000..f5d1f2f
--- /dev/null
+++ b/share/doc/templates/layout.html
@@ -0,0 +1,27 @@
+<!--
+
+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.
+
+-->
+
+{% extends "!layout.html" %}
+{{ rellinks.append(('contents', 'Contents', '', 'Contents')) }}
+{%- block rootrellink %}
+ <li><a href="{{ pathto('index') }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
+{%- endblock %}
+{%- block sidebarlogo %}
+ {%- if logo %}
+ <p class="logo"><a href="{{ pathto('index') }}">
+ <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+ </a></p>
+ {%- endif %}
+{%- endblock %}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/templates/pages/index.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/pages/index.html b/share/doc/templates/pages/index.html
new file mode 100644
index 0000000..5d3b9b4
--- /dev/null
+++ b/share/doc/templates/pages/index.html
@@ -0,0 +1,156 @@
+<!--
+
+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.
+
+-->
+
+{% extends "defindex.html" %}
+{% block tables %}
+<h2>Meet CouchDB</h2>
+<table class="contentstable" align="center">
+ <tr>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("whatsnew/" + version) }}">
+ What's new in CouchDB {{ version }}?
+ </a>
+ <br />
+ <span class="linkdescr">
+ or browse <a href="{{ pathto("whatsnew/index") }}">all "What's new" documents</a>
+ </span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/why") }}">
+ Why CouchDB?
+ </a>
+ <br />
+ <span class="linkdescr">reasons to use CouchDB is there</span>
+ </p>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/overview") }}">
+ Technical Overview
+ </a>
+ <br />
+ <span class="linkdescr">quick overview about base technologies</span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/consistency") }}">
+ Eventual Consistency
+ </a>
+ <br />
+ <span class="linkdescr">the main conception of document databases</span>
+ </p>
+ </td>
+ </tr>
+</table>
+
+<h2>Getting started</h2>
+<table class="contentstable" align="center">
+ <tr>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("install/index") }}">
+ Installation guides
+ </a>
+ <br />
+ <span class="linkdescr">
+ install CouchDB on <a href="{{ pathto("install/windows") }}">Windows</a>,
+ <a href="{{ pathto("install/macos") }}">MacOS X</a> or
+ <a href="{{ pathto("install/unix") }}">Linux</a> in few minutes.
+ </span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/tour") }}">
+ Tutorial
+ </a>
+ <br />
+ <span class="linkdescr">start using CouchDB with
+ <a href="{{ pathto("intro/futon") }}">Futon</a> and
+ <a href="{{ pathto("intro/curl") }}">cURL</a></span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/api") }}">
+ HTTP API overview
+ </a>
+ <br />
+ <span class="linkdescr">short walk though API basics</span>
+ </p>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("couchapp/views/intro") }}">
+ Guide to Views
+ </a>
+ <br />
+ <span class="linkdescr">how query JSON data with no sql</span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("replication/intro") }}">
+ Data Replication
+ </a>
+ <br />
+ <span class="linkdescr">
+ painless master-master data synchronization
+ </span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("config/index") }}">
+ Configuration Reference
+ </a>
+ <br />
+ <span class="linkdescr">tweak CouchDB like you want</span>
+ </p>
+ </td>
+ </tr>
+</table>
+
+<h2>Developing with CouchDB</h2>
+<table class="contentstable" align="center"><tr>
+ <tr>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("api/index") }}">
+ Complete HTTP API Reference
+ </a>
+ <br />
+ <span class="linkdescr">
+ your favourite bookmark
+ </span>
+ </p>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("couchapp/ddocs") }}">
+ Design Documents
+ </a>
+ <br />
+ <span class="linkdescr">
+ transform, update and validate documents like a rock star
+ </span>
+ </p>
+ </td>
+ </tr>
+</table>
+
+
+<h2>Links</h2>
+<table class="contentstable" align="center"><tr>
+ <td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Documentation Contents</a></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("http-api") }}">HTTP API Index</a></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("contributing") }}">Contributing to this Documentation</a></p>
+ </td><td width="50%">
+ <p class="biglink"><a class="biglink" href="http://couchdb.org/">CouchDB Web site</a></p>
+ <p class="biglink"><a class="biglink" href="http://couchdb.org/#download">Download</a></p>
+ <p class="biglink"><a class="biglink" href="http://couchdb.org/#mailing-list">Mailing Lists</a></p>
+ </td></tr>
+</table>
+{% endblock %}
[39/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Describe POST /db/_changes and builtin filters.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/9a18fd22
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9a18fd22
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9a18fd22
Branch: refs/heads/replicator-redesign
Commit: 9a18fd22e4e6ad11d255a1930dd686e48a288895
Parents: 5fe5893
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 12:11:10 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 12:11:10 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/changes.rst | 230 ++++++++++++++++++++++++++--
1 file changed, 213 insertions(+), 17 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/9a18fd22/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index 52dc32d..f144f33 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -18,15 +18,13 @@
================
.. http:get:: /{db}/_changes
-.. http:head:: /{db}/_changes
-.. http:post:: /{db}/_changes
- A sorted list of changes made to documents in the database, in time order of
- application, can be obtained from the database's ``_changes`` resource. Only
- the most recent change for a given document is guaranteed to be provided,
- for example if a document has had fields added, and then deleted, an API
- client checking for changes will not necessarily receive the intermediate
- state of added documents.
+ Returns a sorted list of changes made to documents in the database, in time
+ order of application, can be obtained from the database's ``_changes``
+ resource. Only the most recent change for a given document is guaranteed to
+ be provided, for example if a document has had fields added, and then deleted,
+ an API client checking for changes will not necessarily receive the
+ intermediate state of added documents.
This can be used to listen for update and modifications to the database for
post processing or synchronization, and for practical purposes, a continuously
@@ -39,6 +37,10 @@
- :mimetype:`text/plain`
:<header Last-Event-ID: ID of the last events received by the server on a
previous connection. Overrides `since` query parameter.
+ :query array doc_ids: List of document IDs to filter the changes feed as
+ valid JSON array. Used with :ref:`_doc_ids <changes/filter/doc_ids>` filter.
+ Since `length of URL is limited`_, you better use :http:post:`/{db}/_changes`
+ method instead.
:query boolean conflicts: Includes `conflicts` information in response.
Ignored if `include_docs` isn't ``true``. Default is ``false``.
:query boolean descending: Return the change results in descending sequence
@@ -71,10 +73,9 @@
:ref:`changes_timeout <config/httpd/changes_timeout>` configuration option.
Note that ``60000`` value is also the default maximum timeout to prevent
undetected dead connections.
- :query string view: Allows to use view functions as filters. It requires to
- set ``filter`` special value ``_view`` to enable this feature.
- Documents counted as "passed" for view filter in case if map function emits
- at least one record for them.
+ :query string view: Allows to use view functions as filters. Documents
+ counted as "passed" for view filter in case if map function emits at least
+ one record for them. See :ref:`changes/filter/view` for more info.
:>header Cache-Control: ``no-cache`` if changes feed is
:ref:`eventsource <changes/eventsource>`
:>header Content-Type: - :mimetype:`application/json`
@@ -85,6 +86,7 @@
:>json number last_seq: Last change sequence number
:>json array results: Changes made to a database
:code 200: Request completed successfully
+ :code 400: Bad request
The ``result`` field of database changes
@@ -149,6 +151,7 @@
]
}
+.. _length of URL is limited: http://stackoverflow.com/a/417184/965635
.. versionchanged:: 0.11.0 added ``include_docs`` parameter
.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
@@ -159,6 +162,57 @@
.. versionchanged:: 1.4.0 Support ``Last-Event-ID`` header.
+.. http:post:: /{db}/_changes
+
+ Requests the database changes feed in the same way as
+ :http:get:`/{db}/_changes` does, but this method is widely used with
+ ``?filter=_doc_ids`` query parameter and allows to pass larger list of
+ document IDs to filter.
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /recipes/_changes?filter=_doc_ids HTTP/1.1
+ Accept: application/json
+ Content-Length: 40
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "doc_ids": [
+ "SpaghettiWithMeatballs"
+ ]
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:23:09 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
+ }
+ ],
+ "id": "SpaghettiWithMeatballs",
+ "seq": 38
+ }
+ ]
+ }
+
+
.. _changes:
Changes Feeds
@@ -335,6 +389,8 @@ parameter.
.. _W3C eventsource specification: http://www.w3.org/TR/eventsource/
+.. _changes/filter:
+
Filtering
=========
@@ -348,13 +404,153 @@ You can also filter the ``_changes`` feed by defining a filter function
within a design document. The specification for the filter is the same
as for replication filters. You specify the name of the filter function
to the ``filter`` parameter, specifying the design document name and
-filter name. For example:
+:ref:`filter name <filterfun>`. For example:
.. code-block:: http
GET /db/_changes?filter=design_doc/filtername
-The ``_changes`` feed can be used to watch changes to specific document
-ID's or the list of ``_design`` documents in a database. If the
-``filters`` parameter is set to ``_doc_ids`` a list of doc IDs can be
-passed in the ``doc_ids`` parameter as a JSON array.
+Additionally, there are couple of builtin filters are available and described
+below.
+
+
+.. _changes/filter/doc_ids:
+
+_doc_ids
+--------
+
+This filter accepts only changes for documents which ID in specified in
+``doc_ids`` query parameter or payload's object array. See
+:http:post:`/{db}/_changes` for an example.
+
+
+.. _changes/filter/design:
+
+_design
+-------
+
+The ``_design`` filter accepts only changes for any design document within the
+requested database.
+
+**Request**:
+
+.. code-block:: http
+
+ GET /recipes/_changes?filter=_design HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:28:28 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "10-304cae84fd862832ea9814f02920d4b2"
+ }
+ ],
+ "id": "_design/ingredients",
+ "seq": 29
+ },
+ {
+ "changes": [
+ {
+ "rev": "123-6f7c1b7c97a9e4f0d22bdf130e8fd817"
+ }
+ ],
+ "deleted": true,
+ "id": "_design/cookbook",
+ "seq": 35
+ },
+ {
+ "changes": [
+ {
+ "rev": "6-5b8a52c22580e922e792047cff3618f3"
+ }
+ ],
+ "deleted": true,
+ "id": "_design/meta",
+ "seq": 36
+ }
+ ]
+ }
+
+
+.. _changes/filter/view:
+
+_view
+-----
+
+.. versionadded:: 1.2
+
+The special filter ``_view`` allows to use existed :ref:`map function <mapfun>`
+as the :ref:`filter <filterfun>`. If the map function emits anything for the
+processed document he counts as accepted and the changes event emits to the
+feed. For most use-practice cases `filter` functions are very similar to `map`
+ones, so this feature helps to reduce amount of duplicated code.
+
+.. warning::
+
+ While :ref:`map functions <mapfun>` doesn't process the design documents,
+ using ``_view`` filter forces them to do this. You need to be sure, that
+ they are ready to handle documents with *alien* structure without panic
+ crush.
+
+.. note::
+
+ Using ``_view`` filter doesn't queries the view index files, so you cannot
+ use common :ref:`view query parameters <api/ddoc/view>` to additionally
+ filter the changes feed by index key. Also, CouchDB doesn't returns
+ the result instantly as he does for views - it really uses the specified
+ map function as filter.
+
+ Moreover, you cannot make such filters dynamic e.g. process the request
+ query parameters or handle the :ref:`userctx_object` - the map function is
+ only operates with the document.
+
+**Request**:
+
+.. code-block:: http
+
+ GET /recipes/_changes?filter=_view&view=ingredients/by_recipe HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:36:40 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
+ }
+ ],
+ "id": "SpaghettiWithMeatballs",
+ "seq": 38
+ }
+ ]
+ }
[04/50] [abbrv] Better introduction into CouchDB.
Posted by de...@apache.org.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/tour.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/tour.rst b/share/doc/src/intro/tour.rst
new file mode 100644
index 0000000..af91f5e
--- /dev/null
+++ b/share/doc/src/intro/tour.rst
@@ -0,0 +1,534 @@
+.. 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.
+
+
+.. _intro/tour:
+
+===============
+Getting Started
+===============
+
+In this chapter, we'll take a quick tour of CouchDB's features,
+familiarizing ourselves with Futon, the built-in administration interface.
+We'll create our first document and experiment with CouchDB views.
+
+
+All Systems Are Go!
+===================
+
+We'll have a very quick look at CouchDB's bare-bones Application Programming
+Interface (API) by using the command-line utility curl. Please note that this
+is not the only way of talking to CouchDB. We will show you plenty more
+throughout the rest of the book. What's interesting about curl is that it
+gives you control over raw HTTP requests, and you can see exactly what is
+going on "underneath the hood" of your database.
+
+Make sure CouchDB is still running, and then do::
+
+ curl http://127.0.0.1:5984/
+
+This issues a GET request to your newly installed CouchDB instance.
+
+The reply should look something like:
+
+.. code-block:: javascript
+
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "version": "1.4.0",
+ "vendor": {
+ "version": "1.4.0",
+ "name": "The Apache Software Foundation"
+ }
+ }
+
+Not all that spectacular. CouchDB is saying "hello" with the running version
+number.
+
+Next, we can get a list of databases::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+All we added to the previous request is the _all_dbs string.
+
+The response should look like::
+
+ ["_replicator","_users"]
+
+Oh, that's right, we didn't create any databases yet! All we see is an empty
+list.
+
+.. note::
+
+ The curl command issues GET requests by default. You can issue POST requests
+ using ``curl -X POST``. To make it easy to work with our terminal history,
+ we usually use the ``-X`` option even when issuing GET requests.
+ If we want to send a POST next time, all we have to change is the method.
+
+ HTTP does a bit more under the hood than you can see in the examples here.
+ If you're interested in every last detail that goes over the wire,
+ pass in the ``-v`` option (e.g., ``curl -vX GET``), which will show you
+ the server curl tries to connect to, the request headers it sends,
+ and response headers it receives back. Great for debugging!
+
+Let's create a database::
+
+ curl -X PUT http://127.0.0.1:5984/baseball
+
+CouchDB will reply with::
+
+ {"ok":true}
+
+Retrieving the list of databases again shows some useful results this time::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+::
+
+ ["baseball"]
+
+.. note::
+
+ We should mention JavaScript Object Notation (JSON) here,
+ the data format CouchDB speaks. JSON is a lightweight data interchange format
+ based on JavaScript syntax. Because JSON is natively compatible with
+ JavaScript, your web browser is an ideal client for CouchDB.
+
+ Brackets (``[]``) represent ordered lists, and curly braces (``{}``) represent
+ key/value dictionaries. Keys must be strings, delimited by quotes (``"``),
+ and values can be strings, numbers, booleans, lists,
+ or key/value dictionaries. For a more detailed description of JSON,
+ see Appendix E, JSON Primer.
+
+Let's create another database::
+
+ curl -X PUT http://127.0.0.1:5984/baseball
+
+CouchDB will reply with::
+
+ {"error":"file_exists","reason":"The database could not be created,
+ the file already exists."}
+
+We already have a database with that name, so CouchDB will respond with an
+error. Let's try again with a different database name::
+
+ curl -X PUT http://127.0.0.1:5984/plankton
+
+CouchDB will reply with::
+
+ {"ok":true}
+
+Retrieving the list of databases yet again shows some useful results::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+CouchDB will respond with::
+
+ ["baseball", "plankton"]
+
+To round things off, let's delete the second database::
+
+ curl -X DELETE http://127.0.0.1:5984/plankton
+
+CouchDB will reply with::
+
+ {"ok":true}
+
+The list of databases is now the same as it was before::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+CouchDB will respond with::
+
+ ["baseball"]
+
+For brevity, we'll skip working with documents, as the next section covers a
+different and potentially easier way of working with CouchDB that should
+provide experience with this. As we work through the example,
+keep in mind that "under the hood" everything is being done by the
+application exactly as you have been doing here manually.
+Everything is done using GET, PUT, POST, and DELETE with a URI.
+
+
+Welcome to Futon
+================
+
+After having seen CouchDB's raw API, let's get our feet wet by playing with
+Futon, the built-in administration interface. Futon provides full access to
+all of CouchDB's features and makes it easy to work with some of the more
+complex ideas involved. With Futon we can create and destroy databases; view
+and edit documents; compose and run MapReduce views; and trigger replication
+between databases.
+
+To load Futon in your browser, visit::
+
+ http://127.0.0.1:5984/_utils/
+
+If you're running version 0.9 or later, you should see something similar to
+:ref:`intro/tour-01`. In later chapters, we'll focus on using CouchDB from
+server-side languages such as Ruby and Python. As such, this chapter is a great
+opportunity to showcase an example of natively serving up a dynamic web
+application using nothing more than CouchDB's integrated web server, something
+you may wish to do with your own applications.
+
+The first thing we should do with a fresh installation of CouchDB is run the
+test suite to verify that everything is working properly. This assures us
+that any problems we may run into aren't due to bothersome issues with our
+setup. By the same token, failures in the Futon test suite are a red flag,
+telling us to double-check our installation before attempting to use a
+potentially broken database server, saving us the confusion when nothing
+seems to be working quite like we expect!
+
+
+.. _intro/tour-01:
+
+.. figure:: ../../images/intro-tour-01.png
+ :align: center
+ :alt: The Futon welcome screen
+
+ Figure 1. The Futon welcome screen
+
+
+Some common network configurations cause the replication test to fail when
+accessed via the localhost address. You can fix this by accessing CouchDB via
+127.0.0.1, e.g. http://127.0.0.1:5984/_utils/.
+
+Navigate to the test suite by clicking "Test Suite" on the Futon sidebar,
+then click "run all" at the top to kick things off. :ref:`intro/tour-02`
+shows the Futon test suite running some tests.
+
+
+.. _intro/tour-02:
+
+.. figure:: ../../images/intro-tour-02.png
+ :align: center
+ :alt: The Futon test suite running some tests
+
+ Figure 2. The Futon test suite running some tests
+
+
+Because the test suite is run from the browser, not only does it test that
+CouchDB is functioning properly, it also verifies that your browser's
+connection to the database is properly configured, which can be very handy
+for diagnosing misbehaving proxies or other HTTP middleware.
+
+If the test suite has an inordinate number of failures,
+you'll need to see the troubleshooting section in Appendix D,
+Installing from Source for the next steps to fix your installation.
+
+Now that the test suite is finished, you've verified that your CouchDB
+installation is successful and you're ready to see what else Futon has to offer.
+
+
+Your First Database and Document
+================================
+
+Creating a database in Futon is simple. From the overview page,
+click "Create Database." When asked for a name, enter hello-world and click
+the Create button.
+
+After your database has been created, Futon will display a list of all its
+documents. This list will start out empty (:ref:`intro/tour-03`), so let's
+create our first document. Click the "New Document" link and then the Create
+button in the pop up. Make sure to leave the document ID blank,
+and CouchDB will generate a UUID for you.
+
+For demoing purposes, having CouchDB assign a UUID is fine. When you write
+your first programs, we recommend assigning your own UUIDs. If your rely on
+the server to generate the UUID and you end up making two POST requests
+because the first POST request bombed out, you might generate two docs and
+never find out about the first one because only the second one will be
+reported back. Generating your own UUIDs makes sure that you'll never end up
+with duplicate documents.
+
+Futon will display the newly created document, with its _id and _rev as the
+only fields. To create a new field, click the "Add Field" button. We'll call
+the new field hello. Click the green check icon (or hit the Enter key) to
+finalize creating the hello field. Double-click the hello field's value
+(default null) to edit it.
+
+You can experiment with other JSON values; e.g., ``[1, 2, "c"]`` or
+``{"foo": "bar"}``. Once you've entered your values into the document,
+make a note of its ``_rev`` attribute and click "Save Document." The result
+should look like :ref:`intro/tour-04` document in Futon".
+
+
+.. _intro/tour-03:
+
+.. figure:: ../../images/intro-tour-03.png
+ :align: center
+ :alt: An empty database in Futon
+
+ Figure 3. An empty database in Futon
+
+
+.. _intro/tour-04:
+
+.. figure:: ../../images/intro-tour-04.png
+ :align: center
+ :alt: A "hello world" document in Futon
+
+ Figure 4. A "hello world" document in Futon
+
+
+You'll notice that the document's _rev has changed. We'll go into more detail
+about this in later chapters, but for now, the important thing to note is
+that _rev acts like a safety feature when saving a document. As long as you
+and CouchDB agree on the most recent _rev of a document, you can successfully
+save your changes.
+
+Futon also provides a way to display the underlying JSON data,
+which can be more compact and easier to read, depending on what sort of data
+you are dealing with. To see the JSON version of our "hello world" document,
+click the Source tab. The result should look like :ref:`intro/tour-05`.
+
+
+.. _intro/tour-05:
+
+.. figure:: ../../images/intro-tour-05.png
+ :align: center
+ :alt: The JSON source of a "hello world" document in Futon
+
+ Figure 5. The JSON source of a "hello world" document in Futon
+
+
+Running a Query Using MapReduce
+===============================
+
+Traditional relational databases allow you to run any queries you like as
+long as your data is structured correctly. In contrast,
+CouchDB uses predefined map and reduce functions in a style known as
+MapReduce. These functions provide great flexibility because they can adapt
+to variations in document structure, and indexes for each document can be
+computed independently and in parallel. The combination of a map and a reduce
+function is called a view in CouchDB terminology.
+
+For experienced relational database programmers, MapReduce can take some
+getting used to. Rather than declaring which rows from which tables to
+include in a result set and depending on the database to determine the most
+efficient way to run the query, reduce queries are based on simple range
+requests against the indexes generated by your map functions.
+
+Map functions are called once with each document as the argument.
+The function can choose to skip the document altogether or emit one or more
+view rows as key/value pairs. Map functions may not depend on any information
+outside of the document. This independence is what allows CouchDB views to be
+generated incrementally and in parallel.
+
+CouchDB views are stored as rows that are kept sorted by key. This makes
+retrieving data from a range of keys efficient even when there are thousands
+or millions of rows. When writing CouchDB map functions,
+your primary goal is to build an index that stores related data under nearby
+keys.
+
+Before we can run an example MapReduce view, we'll need some data to run it
+on. We'll create documents carrying the price of various supermarket items as
+found at different shops. Let's create documents for apples, oranges,
+and bananas. (Allow CouchDB to generate the _id and _rev fields.) Use Futon
+to create documents that have a final JSON structure that looks like this:
+
+.. code-block:: javascript
+
+ {
+ "_id": "00a271787f89c0ef2e10e88a0c0001f4",
+ "_rev": "1-2628a75ac8c3abfffc8f6e30c9949fd6",
+ "item": "apple",
+ "prices": {
+ "Fresh Mart": 1.59,
+ "Price Max": 5.99,
+ "Apples Express": 0.79
+ }
+ }
+
+This document should look like :ref:`intro/tour-06` when entered into Futon.
+
+
+.. _intro/tour-06:
+
+.. figure:: ../../images/intro-tour-06.png
+ :align: center
+ :alt: An example document with apple prices in Futon
+
+ Figure 6. An example document with apple prices in Futon
+
+
+OK, now that that's done, let's create the document for oranges:
+
+.. code-block:: javascript
+
+ {
+ "_id": "00a271787f89c0ef2e10e88a0c0003f0",
+ "_rev": "1-e9680c5d9a688b4ff8dd68549e8e072c",
+ "item": "orange",
+ "prices": {
+ "Fresh Mart": 1.99,
+ "Price Max": 3.19,
+ "Citrus Circus": 1.09
+ }
+ }
+
+And finally, the document for bananas:
+
+.. code-block:: javascript
+
+ {
+ "_id": "00a271787f89c0ef2e10e88a0c00048b",
+ "_rev": "1-60e25d93dc12884676d037400a6fa189",
+ "item": "banana",
+ "prices": {
+ "Fresh Mart": 1.99,
+ "Price Max": 0.79,
+ "Banana Montana": 4.22
+ }
+ }
+
+Imagine we're catering a big luncheon, but the client is very price-sensitive.
+To find the lowest prices, we're going to create our first view,
+which shows each fruit sorted by price. Click "hello-world" to return to the
+hello-world overview, and then from the "select view" menu choose "Temporary
+view…" to create a new view.
+
+Edit the map function, on the left, so that it looks like the following:
+
+.. code-block:: javascript
+
+ function(doc) {
+ var shop, price, value;
+ if (doc.item && doc.prices) {
+ for (shop in doc.prices) {
+ price = doc.prices[shop];
+ value = [doc.item, shop];
+ emit(price, value);
+ }
+ }
+ }
+
+This is a JavaScript function that CouchDB runs for each of our documents as
+it computes the view. We'll leave the reduce function blank for the time being.
+
+Click "Run" and you should see result rows like in :ref:`intro/tour-08`,
+with the various items sorted by price. This map function could be even more
+useful if it grouped the items by type so that all the prices for bananas were
+next to each other in the result set. CouchDB's key sorting system allows any
+valid JSON object as a key. In this case, we'll emit an array of [item, price]
+so that CouchDB groups by item type and price.
+
+
+.. _intro/tour-08:
+
+.. figure:: ../../images/intro-tour-08.png
+ :align: center
+ :alt: The results of running a view in Futon
+
+ Figure 8. The results of running a view in Futon
+
+
+Let's modify the view function so that it looks like this:
+
+.. code-block:: javascript
+
+ function(doc) {
+ var shop, price, key;
+ if (doc.item && doc.prices) {
+ for (shop in doc.prices) {
+ price = doc.prices[shop];
+ key = [doc.item, price];
+ emit(key, shop);
+ }
+ }
+ }
+
+Here, we first check that the document has the fields we want to use. CouchDB
+recovers gracefully from a few isolated map function failures,
+but when a map function fails regularly (due to a missing required field or
+other JavaScript exception), CouchDB shuts off its indexing to prevent any
+further resource usage. For this reason, it's important to check for the
+existence of any fields before you use them. In this case,
+our map function will skip the first "hello world" document we created
+without emitting any rows or encountering any errors. The result of this
+query should look like :ref:`intro/tour-09`.
+
+
+.. _intro/tour-09:
+
+.. figure:: ../../images/intro-tour-09.png
+ :align: center
+ :alt: The results of running a view after grouping by item type and price
+
+ Figure 9. The results of running a view after grouping by item type and price
+
+
+Once we know we've got a document with an item type and some prices,
+we iterate over the item's prices and emit key/values pairs. The key is an
+array of the item and the price, and forms the basis for CouchDB's sorted
+index. In this case, the value is the name of the shop where the item can be
+found for the listed price.
+
+View rows are sorted by their keys -- in this example, first by item,
+then by price. This method of complex sorting is at the heart of creating
+useful indexes with CouchDB.
+
+MapReduce can be challenging, especially if you've spent years working with
+relational databases. The important things to keep in mind are that map
+functions give you an opportunity to sort your data using any key you choose,
+and that CouchDB's design is focused on providing fast,
+efficient access to data within a range of keys.
+
+
+Triggering Replication
+======================
+
+Futon can trigger replication between two local databases,
+between a local and remote database, or even between two remote databases.
+We'll show you how to replicate data from one local database to another,
+which is a simple way of making backups of your databases as we're working
+through the examples.
+
+First we'll need to create an empty database to be the target of replication.
+Return to the overview and create a database called hello-replication.
+Now click "Replicator" in the sidebar and choose hello-world as the source
+and hello-replication as the target. Click "Replicate" to replicate your
+database. The result should look something like :ref:`intro/tour-10`.
+
+
+.. _intro/tour-10:
+
+.. figure:: ../../images/intro-tour-10.png
+ :align: center
+ :alt: Running database replication in Futon
+
+ Figure 10. Running database replication in Futon
+
+
+.. note::
+
+ For larger databases, replication can take much longer. It is important to
+ leave the browser window open while replication is taking place.
+ As an alternative, you can trigger replication via curl or some other HTTP
+ client that can handle long-running connections. If your client closes the
+ connection before replication finishes, you'll have to retrigger it.
+ Luckily, CouchDB's replication can take over from where it left off
+ instead of starting from scratch.
+
+
+Wrapping Up
+===========
+
+Now that you've seen most of Futon's features, you'll be prepared to dive in
+and inspect your data as we build our example application in the next few
+chapters. Futon's pure JavaScript approach to managing CouchDB shows how it's
+possible to build a fully featured web application using only CouchDB's HTTP
+API and integrated web server.
+
+But before we get there, we'll have another look at CouchDB's HTTP API -- now
+with a magnifying glass. Let's curl up on the couch and relax.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/why.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/why.rst b/share/doc/src/intro/why.rst
new file mode 100644
index 0000000..1b902d8
--- /dev/null
+++ b/share/doc/src/intro/why.rst
@@ -0,0 +1,315 @@
+.. 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.
+
+
+.. _intro/why:
+
+============
+Why CouchDB?
+============
+
+Apache CouchDB is one of a new breed of database management systems.
+This chapter explains why there's a need for new systems as well as the
+motivations behind building CouchDB.
+
+As CouchDB developers, we're naturally very excited to be using CouchDB.
+In this chapter we'll share with you the reasons for our enthusiasm.
+We'll show you how CouchDB's schema-free document model is a better fit
+for common applications, how the built-in query engine is a powerful way
+to use and process your data, and how CouchDB's design lends itself
+to modularization and scalability.
+
+
+Relax
+=====
+
+If there's one word to describe CouchDB, it is *relax*. It is in the title of
+this book, it is the byline to CouchDB's official logo,
+and when you start CouchDB, you see::
+
+ Apache CouchDB has started. Time to relax.
+
+Why is relaxation important? Developer productivity roughly doubled in the
+last five years. The chief reason for the boost is more powerful tools that
+are easier to use. Take Ruby on Rails as an example. It is an infinitely
+complex framework, but it's easy to get started with. Rails is a success
+story because of the core design focus on ease of use. This is one reason why
+CouchDB is relaxing: learning CouchDB and understanding its core concepts
+should feel natural to most everybody who has been doing any work on the Web.
+And it is still pretty easy to explain to non-technical people.
+
+Getting out of the way when creative people try to build specialized
+solutions is in itself a core feature and one thing that CouchDB aims to get
+right. We found existing tools too cumbersome to work with during development
+or in production, and decided to focus on making CouchDB easy, even a pleasure,
+to use.
+
+Another area of relaxation for CouchDB users is the production setting.
+If you have a live running application, CouchDB again goes out of its way
+to avoid troubling you. Its internal architecture is fault-tolerant,
+and failures occur in a controlled environment and are dealt with gracefully.
+Single problems do not cascade through an entire server system but stay
+isolated in single requests.
+
+CouchDB's core concepts are simple (yet powerful) and well understood.
+Operations teams (if you have a team; otherwise, that's you) do not have to
+fear random behavior and untraceable errors. If anything should go wrong,
+you can easily find out what the problem is, but these situations are rare.
+
+CouchDB is also designed to handle varying traffic gracefully. For instance,
+if a website is experiencing a sudden spike in traffic, CouchDB will generally
+absorb a lot of concurrent requests without falling over. It may take a little
+more time for each request, but they all get answered. When the spike is over,
+CouchDB will work with regular speed again.
+
+The third area of relaxation is growing and shrinking the underlying hardware
+of your application. This is commonly referred to as scaling. CouchDB enforces
+a set of limits on the programmer. On first look, CouchDB might seem
+inflexible, but some features are left out by design for the simple reason
+that if CouchDB supported them, it would allow a programmer to create
+applications that couldn't deal with scaling up or down.
+
+.. note::
+ CouchDB doesn't let you do things that would get you in trouble later on.
+ This sometimes means you'll have to unlearn best practices you might have
+ picked up in your current or past work.
+
+
+A Different Way to Model Your Data
+==================================
+
+We believe that CouchDB will drastically change the way you build
+document-based applications. CouchDB combines an intuitive document storage
+model with a powerful query engine in a way that's so simple you'll probably
+be tempted to ask, “Why has no one built something like this before?”
+
+ Django may be built for the Web, but CouchDB is built of the Web. I've
+ never seen software that so completely embraces the philosophies behind
+ HTTP. CouchDB makes Django look old-school in the same way that Django
+ makes ASP look outdated.
+
+ -- Jacob Kaplan-Moss, Django developer
+
+CouchDB's design borrows heavily from web architecture and the concepts of
+resources, methods, and representations. It augments this with powerful ways
+to query, map, combine, and filter your data. Add fault tolerance, extreme
+scalability, and incremental replication, and CouchDB defines a sweet spot
+for document databases.
+
+
+A Better Fit for Common Applications
+====================================
+
+We write software to improve our lives and the lives of others. Usually this
+involves taking some mundane information such as contacts, invoices,
+or receipts and manipulating it using a computer application. CouchDB is a
+great fit for common applications like this because it embraces the natural
+idea of evolving, self-contained documents as the very core of its data model.
+
+
+Self-Contained Data
+-------------------
+
+An invoice contains all the pertinent information about a single transaction
+the seller, the buyer, the date, and a list of the items or services sold.
+As shown in :ref:`intro/why-01`, there's no abstract reference on this
+piece of paper that points to some other piece of paper with the seller's
+name and address. Accountants appreciate the simplicity of having everything
+in one place. And given the choice, programmers appreciate that, too.
+
+
+.. _intro/why-01:
+
+.. figure:: ../../images/intro-why-01.png
+ :align: center
+ :alt: Self-contained documents
+
+ Figure 1. Self-contained documents
+
+
+Yet using references is exactly how we model our data in a relational
+database! Each invoice is stored in a table as a row that refers to other
+rows in other tables one row for seller information, one for the buyer,
+one row for each item billed, and more rows still to describe the item
+details, manufacturer details, and so on and so forth.
+
+This isn't meant as a detraction of the relational model, which is widely
+applicable and extremely useful for a number of reasons. Hopefully, though, it
+illustrates the point that sometimes your model may not “fit” your data
+in the way it occurs in the real world.
+
+Let's take a look at the humble contact database to illustrate a different
+way of modeling data, one that more closely “fits” its real-world counterpart
+-- a pile of business cards. Much like our invoice example, a business card
+contains all the important information, right there on the cardstock.
+We call this “self-contained” data, and it's an important concept
+in understanding document databases like CouchDB.
+
+
+Syntax and Semantics
+--------------------
+
+Most business cards contain roughly the same information -- someone's identity,
+an affiliation, and some contact information. While the exact form of this
+information can vary between business cards, the general information being
+conveyed remains the same, and we're easily able to recognize it as a
+business card. In this sense, we can describe a business card as a *real-world
+document*.
+
+Jan's business card might contain a phone number but no fax number,
+whereas J. Chris's business card contains both a phone and a fax number. Jan
+does not have to make his lack of a fax machine explicit by writing something
+as ridiculous as “Fax: None” on the business card. Instead, simply omitting
+a fax number implies that he doesn't have one.
+
+We can see that real-world documents of the same type, such as business cards,
+tend to be very similar in *semantics* -- the sort of information they carry,
+but can vary hugely in *syntax*, or how that information is structured. As human
+beings, we're naturally comfortable dealing with this kind of variation.
+
+While a traditional relational database requires you to model your data
+*up front*, CouchDB's schema-free design unburdens you with a powerful way to
+aggregate your data *after the fact*, just like we do with real-world
+documents. We'll look in depth at how to design applications with this
+underlying storage paradigm.
+
+
+Building Blocks for Larger Systems
+==================================
+
+CouchDB is a storage system useful on its own. You can build many applications
+with the tools CouchDB gives you. But CouchDB is designed with a bigger picture
+in mind. Its components can be used as building blocks that solve storage
+problems in slightly different ways for larger and more complex systems.
+
+Whether you need a system that's crazy fast but isn't too concerned with
+reliability (think logging), or one that guarantees storage in two or more
+physically separated locations for reliability, but you're willing to take a
+performance hit, CouchDB lets you build these systems.
+
+There are a multitude of knobs you could turn to make a system work better in
+one area, but you'll affect another area when doing so. One example would be
+the CAP theorem discussed in the next chapter. To give you an idea of other
+things that affect storage systems, see :ref:`Figure 2 <intro/why-figure-02>`
+and :ref:`Figure 3 <intro/why-figure-03>`.
+
+By reducing latency for a given system (and that is true not only for storage
+systems), you affect concurrency and throughput capabilities.
+
+
+.. _intro/why-figure-02:
+
+.. figure:: ../../images/intro-why-02.png
+ :align: center
+ :alt: Throughput, latency, or concurrency
+
+ Figure 2. Throughput, latency, or concurrency
+
+
+.. _intro/why-figure-03:
+
+.. figure:: ../../images/intro-why-03.png
+ :align: center
+ :alt: Scaling: read requests, write requests, or data
+
+ Figure 3. Scaling: read requests, write requests, or data
+
+
+When you want to scale out, there are three distinct issues to deal with:
+scaling read requests, write requests, and data. Orthogonal to all three and
+to the items shown in :ref:`Figure 2 <intro/why-figure-02>` and :ref:`Figure 3
+<intro/why-figure-03>` are many more attributes like reliability or simplicity.
+You can draw many of these graphs that show how different features or attributes
+pull into different directions and thus shape the system they describe.
+
+CouchDB is very flexible and gives you enough building blocks to create a
+system shaped to suit your exact problem. That's not saying that CouchDB can
+be bent to solve any problem -- CouchDB is no silver bullet -- but in the
+area of data storage, it can get you a long way.
+
+
+CouchDB Replication
+===================
+
+CouchDB replication is one of these building blocks. Its fundamental function
+is to synchronize two or more CouchDB databases. This may sound simple,
+but the simplicity is key to allowing replication to solve a number of
+problems: reliably synchronize databases between multiple machines for
+redundant data storage; distribute data to a cluster of CouchDB instances
+that share a subset of the total number of requests that hit the cluster
+(load balancing); and distribute data between physically distant locations,
+such as one office in New York and another in Tokyo.
+
+CouchDB replication uses the same REST API all clients use. HTTP is
+ubiquitous and well understood. Replication works incrementally; that is,
+if during replication anything goes wrong, like dropping your network
+connection, it will pick up where it left off the next time it runs. It also
+only transfers data that is needed to synchronize databases.
+
+A core assumption CouchDB makes is that things can go wrong,
+like network connection troubles, and it is designed for graceful error
+recovery instead of assuming all will be well. The replication system's
+incremental design shows that best. The ideas behind “things that can go
+wrong” are embodied in the `Fallacies of Distributed Computing`_:
+
+- The network is reliable.
+- Latency is zero.
+- Bandwidth is infinite.
+- The network is secure.
+- Topology doesn't change.
+- There is one administrator.
+- Transport cost is zero.
+- The network is homogeneous.
+
+Existing tools often try to hide the fact that there is a network and that
+any or all of the previous conditions don't exist for a particular system.
+This usually results in fatal error scenarios when something finally goes
+wrong. In contrast, CouchDB doesn't try to hide the network; it just handles
+errors gracefully and lets you know when actions on your end are required.
+
+.. _Fallacies of Distributed Computing: http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing
+
+
+Local Data Is King
+==================
+
+CouchDB takes quite a few lessons learned from the Web,
+but there is one thing that could be improved about the Web: latency.
+Whenever you have to wait for an application to respond or a website to
+render, you almost always wait for a network connection that isn't as fast as
+you want it at that point. Waiting a few seconds instead of milliseconds
+greatly affects user experience and thus user satisfaction.
+
+What do you do when you are offline? This happens all the time -- your DSL or
+cable provider has issues, or your iPhone, G1, or Blackberry has no bars,
+and no connectivity means no way to get to your data.
+
+CouchDB can solve this scenario as well, and this is where scaling is
+important again. This time it is scaling down. Imagine CouchDB installed on
+phones and other mobile devices that can synchronize data with centrally
+hosted CouchDBs when they are on a network. The synchronization is not bound
+by user interface constraints like subsecond response times. It is easier to
+tune for high bandwidth and higher latency than for low bandwidth and very
+low latency. Mobile applications can then use the local CouchDB to fetch
+data, and since no remote networking is required for that,
+latency is low by default.
+
+Can you really use CouchDB on a phone? Erlang, CouchDB's implementation
+language has been designed to run on embedded devices magnitudes smaller and
+less powerful than today's phones.
+
+
+Wrapping Up
+===========
+
+The next chapter further explores the distributed nature of CouchDB. We
+should have given you enough bites to whet your interest. Let's go!
[49/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Delete DB always goes back to /_all_dbs
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/066d69b2
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/066d69b2
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/066d69b2
Branch: refs/heads/replicator-redesign
Commit: 066d69b2b5520886a3bcfa27db1750fc932bdbe4
Parents: 62f8684
Author: suelockwood <de...@gmail.com>
Authored: Mon Sep 30 10:40:05 2013 -0400
Committer: suelockwood <de...@gmail.com>
Committed: Mon Sep 30 16:25:47 2013 -0400
----------------------------------------------------------------------
src/fauxton/app/modules/documents/views.js | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/066d69b2/src/fauxton/app/modules/documents/views.js
----------------------------------------------------------------------
diff --git a/src/fauxton/app/modules/documents/views.js b/src/fauxton/app/modules/documents/views.js
index 8036195..e948dc1 100644
--- a/src/fauxton/app/modules/documents/views.js
+++ b/src/fauxton/app/modules/documents/views.js
@@ -75,7 +75,7 @@ function(app, FauxtonAPI, Components, Documents, pouchdb, Codemirror, JSHint, re
if (!result) { return; }
return this.database.destroy().done(function () {
- app.router.navigate('/', {trigger: true});
+ app.router.navigate('#/_all_dbs', {trigger: true});
});
}
});
@@ -1417,7 +1417,7 @@ function(app, FauxtonAPI, Components, Documents, pouchdb, Codemirror, JSHint, re
var databaseName = this.database.id;
this.database.destroy().then(function () {
- FauxtonAPI.navigate('/');
+ FauxtonAPI.navigate('#/_all_dbs');
FauxtonAPI.addNotification({
msg: 'The database ' + databaseName + ' has been deleted.'
});
[43/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Update license skip.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1d271f1e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1d271f1e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1d271f1e
Branch: refs/heads/replicator-redesign
Commit: 1d271f1e8991f5c1edbc2bc90214868fc87348fc
Parents: d513c57
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 15:52:02 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 15:52:02 2013 +0400
----------------------------------------------------------------------
license.skip | 2 ++
1 file changed, 2 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1d271f1e/license.skip
----------------------------------------------------------------------
diff --git a/license.skip b/license.skip
index 3694057..d8389fd 100644
--- a/license.skip
+++ b/license.skip
@@ -60,8 +60,10 @@
^share/doc/Makefile.in
^share/doc/build/.*
^share/doc/ext/httpdomain.py
+^share/doc/ext/http-api-descr.json
^share/doc/images/.*
^share/doc/static/rtd.css
+^share/doc/templates/couchdb/domainindex.html
^share/server/json2.js
^share/server/mimeparse.js
^share/server/coffee-script.js
[31/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
docs: update api/database section
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/083bb15e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/083bb15e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/083bb15e
Branch: refs/heads/replicator-redesign
Commit: 083bb15e0c8899549ea591b4b7e7136d34b897a3
Parents: 655809f
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Sat Sep 28 01:58:42 2013 +0200
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Sat Sep 28 01:58:42 2013 +0200
----------------------------------------------------------------------
share/doc/src/api/database/common.rst | 26 ++++++++++++++------------
share/doc/src/api/database/compact.rst | 14 +++++++++++---
share/doc/src/api/database/misc.rst | 16 ++++++++++++----
share/doc/src/api/database/security.rst | 3 ++-
share/doc/src/api/database/temp-views.rst | 10 +++++++---
5 files changed, 46 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/083bb15e/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 853ff6b..a131e39 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -19,7 +19,7 @@
Returns the HTTP Headers containing a minimal amount of information
about the specified database. Since the response body is empty this method
- is a lightweight way to check is database exists or not.
+ is a lightweight way to check if the database exists already or not.
:param db: Database name
:code 200: Database exists
@@ -158,8 +158,8 @@
"ok": true
}
- If we repeat same request to CouchDB, it will response with :code:`412` since
- database is already exists:
+ If we repeat the same request to CouchDB, it will response with :code:`412`
+ since the database already exists:
**Request**:
@@ -185,7 +185,7 @@
"reason": "The database could not be created, the file already exists."
}
- In case of invalid database name CouchDB returns response with :code:`400`:
+ If an invalid database name is supplied, CouchDB returns response with :code:`400`:
**Request**:
@@ -225,8 +225,8 @@
:>json boolean ok: Operation status
:code 200: Database removed successfully
:code 400: Invalid database name
- :code 404: Database doesn't already exists
:code 401: CouchDB Server Administrator privileges required
+ :code 404: Database doesn't exist
**Request**:
@@ -260,7 +260,8 @@
If the JSON structure includes the ``_id`` field, then the document will be
created with the specified document ID.
- If the ``_id`` field is not specified, a new unique ID will be generated.
+ If the ``_id`` field is not specified, a new unique ID will be generated,
+ following whatever UUID algorithm is configured for that server.
:param db: Database name
:<header Accept: - :mimetype:`application/json`
@@ -282,8 +283,8 @@
:code 202: Document data accepted, but not yet stored on disk
:code 400: Invalid database name
:code 401: Write privileges required
- :code 404: Database doesn't already exists
- :code 409: Document with the specified document ID already exists
+ :code 404: Database doesn't exist
+ :code 409: A Conflicting Document with same ID already exists
**Request**:
@@ -380,10 +381,11 @@ respond with a HTTP :http:statuscode:`202` response code immediately.
.. note::
- Creating or updating documents with batch mode doesn't guarantees that
- document will be successfully stored on disk and CouchDB doesn't ensures you
- that it will to. Document may not be saved due to conflicts, rejection by
- :ref:`validation function <vdufun>` or by other reasons.
+ Creating or updating documents with batch mode doesn't guarantee that
+ document will be successfully stored on disk and CouchDB does not
+ guarantee that. For example, individual documents may not be saved due to
+ conflicts, rejection by :ref:`validation function <vdufun>` or by other
+ reasons, even if overall the batch transfer was sucessfully submitted.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/083bb15e/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 6982cb4..81935db 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -21,9 +21,9 @@
Request compaction of the specified database. Compaction compresses the
disk database file by performing the following operations:
- - Writes a new version of the database file, removing any unused
+ - Writes a new, optimised, version of the database file, removing any unused
sections from the new version during write. Because a new file is
- temporary created for this purpose, you will need twice the current
+ temporarily created for this purpose, you may require up to twice the current
storage space of the specified database in order for the compaction
routine to complete.
@@ -130,6 +130,11 @@
"ok": true
}
+ .. note::
+
+ View indexes are stored in a separate ``.couch`` file based on
+ a hash of the design document's relevant functions, in a sub directory
+ of where the main ``.couch`` database files are located.
.. _api/db/ensure_full_commit:
@@ -187,7 +192,10 @@
.. http:post:: /{db}/_view_cleanup
- Cleans up the cached view output on disk for a given view.
+ Removes view index files that are no longer required by CouchDB as a result
+ of changed views within design documents. As the view filename is based on
+ a hash of the view functions, over time old views will remain, consuming
+ storage. This call cleans up the cached view output on disk for a given view.
:param db: Database name
:<header Accept: - :mimetype:`application/json`
http://git-wip-us.apache.org/repos/asf/couchdb/blob/083bb15e/share/doc/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index d3507a5..ad46e15 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -19,12 +19,20 @@
.. http:post:: /{db}/_purge
A database purge permanently removes the references to deleted documents
- from the database. Deleting a document within CouchDB does not actually
+ from the database. Normal deletion of a document within CouchDB does not
remove the document from the database, instead, the document is marked as
- a deleted (and a new revision is created). This is to ensure that
- deleted documents are replicated to other databases as having been
+ ``_deleted=true`` (and a new revision is created). This is to ensure that
+ deleted documents can be replicated to other databases as having been
deleted. This also means that you can check the status of a document and
- identify that the document has been deleted.
+ identify that the document has been deleted by its absence.
+
+ .. warning::
+
+ Purging a document from a database should only be done as a last resort
+ when sensitive information has been introduced inadvertently into a
+ database. In clustered or replicated environments it is very difficult
+ to guarantee that a particular purged document has been removed from all
+ replicas. Do not rely on this API as a way of doing secure deletion.
The purge operation removes the references to the deleted documents from
the database. The purging of old documents is not replicated to other
http://git-wip-us.apache.org/repos/asf/couchdb/blob/083bb15e/share/doc/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index 8ad62e6..ee95ee4 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -31,7 +31,7 @@
write (and edit) design documents, add/remove database admins and members,
set the :ref:`database revisions limit <api/db/revs_limit>` and execute
:ref:`temporary views <api/db/temp_view>` against the database.
- They can not create a database and neither delete a database.
+ They can not create a database nor delete a database.
Both ``members`` and ``admins`` objects are contains two array-typed fields:
@@ -56,6 +56,7 @@
read documents from the database (or do a :http:get:`/{db}` call).
.. note::
+
If the security object for a database has never been set, then the
value returned will be empty.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/083bb15e/share/doc/src/api/database/temp-views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst
index 0b576b8..d9ac16d 100644
--- a/share/doc/src/api/database/temp-views.rst
+++ b/share/doc/src/api/database/temp-views.rst
@@ -23,9 +23,13 @@
The arguments also available to standard view requests also apply to
temporary views, but the execution of the view may take some time as it
- relies on being executed at the time of the request. In addition to the
- time taken, they are also computationally very expensive to produce. You
- should use a defined view if you want to achieve the best performance.
+ relies on being executed at the time of the request. This means that for
+ every temporary view you create, the entire database will be read
+ one doc at a time and passed through the view function.
+
+ This should not be used on production CouchDB instances, and is purely a
+ convenience function for quick development testing. You should use a
+ defined view if you want to achieve the best performance.
See :ref:`api/ddoc/view` for more info.
[41/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Make HTTP domain default one.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5522488e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5522488e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5522488e
Branch: refs/heads/replicator-redesign
Commit: 5522488e8c2e0772aa5f2844d0c557f3f17c5586
Parents: 598ccd4
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 13:33:53 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 13:33:53 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/bulk-api.rst | 2 +-
share/doc/src/api/database/changes.rst | 6 ++---
share/doc/src/api/database/common.rst | 4 ++--
share/doc/src/api/database/compact.rst | 10 ++++----
share/doc/src/api/database/misc.rst | 2 +-
share/doc/src/api/database/security.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 24 +++++++++----------
share/doc/src/api/ddoc/rewrites.rst | 2 +-
share/doc/src/api/ddoc/views.rst | 10 ++++----
share/doc/src/api/document/attachments.rst | 22 ++++++++---------
share/doc/src/api/document/common.rst | 32 ++++++++++++-------------
share/doc/src/api/local.rst | 8 +++----
share/doc/src/api/server/common.rst | 4 ++--
share/doc/src/conf.py | 2 ++
share/doc/src/config/compaction.rst | 2 +-
share/doc/src/intro/api.rst | 1 -
share/doc/src/maintenance/compaction.rst | 16 ++++++-------
share/doc/src/maintenance/performance.rst | 2 --
share/doc/src/query-server/erlang.rst | 1 +
share/doc/src/replication/conflicts.rst | 6 ++---
share/doc/src/replication/protocol.rst | 20 ++++++++--------
21 files changed, 89 insertions(+), 89 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index eb49a28..87233df 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -137,7 +137,7 @@
The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
selected from the database. This enables you to request multiple
- documents in a single request, in place of multiple :http:get:`/{db}/{docid}`
+ documents in a single request, in place of multiple :get:`/{db}/{docid}`
requests.
The request body should contain a list of the keys to be returned as an
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index f144f33..f2ad9b7 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -39,7 +39,7 @@
previous connection. Overrides `since` query parameter.
:query array doc_ids: List of document IDs to filter the changes feed as
valid JSON array. Used with :ref:`_doc_ids <changes/filter/doc_ids>` filter.
- Since `length of URL is limited`_, you better use :http:post:`/{db}/_changes`
+ Since `length of URL is limited`_, you better use :post:`/{db}/_changes`
method instead.
:query boolean conflicts: Includes `conflicts` information in response.
Ignored if `include_docs` isn't ``true``. Default is ``false``.
@@ -165,7 +165,7 @@
.. http:post:: /{db}/_changes
Requests the database changes feed in the same way as
- :http:get:`/{db}/_changes` does, but this method is widely used with
+ :get:`/{db}/_changes` does, but this method is widely used with
``?filter=_doc_ids`` query parameter and allows to pass larger list of
document IDs to filter.
@@ -421,7 +421,7 @@ _doc_ids
This filter accepts only changes for documents which ID in specified in
``doc_ids`` query parameter or payload's object array. See
-:http:post:`/{db}/_changes` for an example.
+:post:`/{db}/_changes` for an example.
.. _changes/filter/design:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 5265919..c374625 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -376,8 +376,8 @@ the risk of the documents not being stored in the event of a failure,
since the documents are not written to disk immediately.
To use the batched mode, append the ``batch=ok`` query argument to the
-URL of the ``PUT`` or :http:post:`/{db}` request. The CouchDB server will
-respond with a HTTP :http:statuscode:`202` response code immediately.
+URL of the ``PUT`` or :post:`/{db}` request. The CouchDB server will
+respond with a HTTP :statuscode:`202` response code immediately.
.. note::
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index f7289e5..d2b90d7 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -38,7 +38,7 @@
You can determine if the compaction process is operating on a database
by obtaining the database meta information, the ``compact_running``
value of the returned database structure will be set to true. See
- :http:get:`/{db}`.
+ :get:`/{db}`.
You can also obtain a list of running processes to determine whether
compaction is currently running. See :ref:`api/server/active_tasks`.
@@ -53,7 +53,7 @@
:code 202: Compaction request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
@@ -105,7 +105,7 @@
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
:code 404: Design document not found
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
@@ -162,7 +162,7 @@
:>json boolean ok: Operation status
:code 201: Commit completed successfully
:code 400: Invalid database name
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
@@ -212,7 +212,7 @@
:code 202: Compaction request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index ad46e15..e69ce8a 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -62,7 +62,7 @@
:>json object purged: Mapping of document ID to list of purged revisions
:code 200: Request completed successfully
:code 400: Invalid database name or JSON payload
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index ee95ee4..7bdf88e 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -53,7 +53,7 @@
If there are any member names or roles defined for a database, then only
authenticated users having a matching name or role are allowed to
- read documents from the database (or do a :http:get:`/{db}` call).
+ read documents from the database (or do a :get:`/{db}` call).
.. note::
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index 79c7357..16cfffc 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -23,7 +23,7 @@
.. seealso::
- :http:head:`/{db}/{docid}`
+ :head:`/{db}/{docid}`
.. http:get:: /{db}/_design/{ddoc}
@@ -34,12 +34,12 @@
.. seealso::
- :http:get:`/{db}/{docid}`
+ :get:`/{db}/{docid}`
.. http:put:: /{db}/_design/{ddoc}
- The :http:method:`PUT` method creates a new named design document, or creates
+ The :method:`PUT` method creates a new named design document, or creates
a new revision of the existing design document.
The design documents have some agreement upon their fields and structure.
@@ -64,7 +64,7 @@
.. seealso::
- :http:put:`/{db}/{docid}`
+ :put:`/{db}/{docid}`
.. http:delete:: /{db}/_design/{ddoc}
@@ -75,11 +75,11 @@
.. seealso::
- :http:delete:`/{db}/{docid}`
+ :delete:`/{db}/{docid}`
.. http:copy:: /{db}/_design/{ddoc}
- The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+ The :method:`COPY` (which is non-standard HTTP) copies an existing
design document to a new or existing one.
.. note::
@@ -89,7 +89,7 @@
.. seealso::
- :http:copy:`/{db}/{docid}`
+ :copy:`/{db}/{docid}`
.. _api/ddoc/attachment:
@@ -104,7 +104,7 @@
.. seealso::
- :http:head:`/{db}/{docid}/{attname}`
+ :head:`/{db}/{docid}/{attname}`
.. http:get:: /{db}/_design/{ddoc}/{attname}
@@ -114,7 +114,7 @@
.. seealso::
- :http:get:`/{db}/{docid}/{attname}`
+ :get:`/{db}/{docid}/{attname}`
.. http:put:: /{db}/_design/{ddoc}/{attname}
@@ -123,7 +123,7 @@
.. seealso::
- :http:put:`/{db}/{docid}/{attname}`
+ :put:`/{db}/{docid}/{attname}`
.. http:delete:: /{db}/_design/{ddoc}/{attname}
@@ -131,7 +131,7 @@
.. seealso::
- :http:delete:`/{db}/{docid}/{attname}`
+ :delete:`/{db}/{docid}/{attname}`
.. _api/ddoc/info:
@@ -196,7 +196,7 @@
View Index Information
----------------------
-The response from :http:get:`/{db}/_design/{ddoc}/_info` contains
+The response from :get:`/{db}/_design/{ddoc}/_info` contains
``view_index`` (*object*) field with the next structure:
* **compact_running** (*boolean*): Indicates whether a compaction routine
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/ddoc/rewrites.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/rewrites.rst b/share/doc/src/api/ddoc/rewrites.rst
index 61eebed..d6e83a9 100644
--- a/share/doc/src/api/ddoc/rewrites.rst
+++ b/share/doc/src/api/ddoc/rewrites.rst
@@ -52,7 +52,7 @@
The pattern matching is done by first matching the request method to a rule.
By default all methods match a rule. (method is equal to ``"*"`` by default).
Then It will try to match the path to one rule. If no rule match, then a
- :http:statuscode:`404` response returned.
+ :statuscode:`404` response returned.
Once a rule is found we rewrite the request url using the ``to`` and ``query``
fields. The identified token are matched to the rule and will replace var.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index 7834539..8683085 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -126,11 +126,11 @@
.. http:post:: /{db}/_design/{ddoc}/_view/{view}
Executes the specified view function from the specified design document.
- Unlike the :http:get:`/{db}/_design/{ddoc}/_view/{view}` method
- for accessing views, the :http:method:`POST` method supports the specification
+ Unlike the :get:`/{db}/_design/{ddoc}/_view/{view}` method
+ for accessing views, the :method:`POST` method supports the specification
of explicit keys to be retrieved from the view results. The remainder of the
- :http:method:`POST` view functionality is identical to the
- :http:get:`/{db}/_design/{ddoc}/_view/{view}` API.
+ :method:`POST` view functionality is identical to the
+ :get:`/{db}/_design/{ddoc}/_view/{view}` API.
**Request**:
@@ -295,7 +295,7 @@ In addition to using stale views, you can also make use of the
view information including the update sequence of the database from
which the view was generated. The returned value can be compared this to
the current update sequence exposed in the database information
-(returned by :http:get:`/{db}`).
+(returned by :get:`/{db}`).
.. _api/ddoc/view/sorting:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index 34526fc..c26b561 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -20,9 +20,9 @@
Returns the HTTP headers containing a minimal amount of information
about the specified attachment. The method supports the same query
- arguments as the :http:get:`/{db}/{docid}/{attname}` method, but only
+ arguments as the :get:`/{db}/{docid}/{attname}` method, but only
the header information (including attachment size, encoding and the MD5 hash
- as an :http:header:`ETag`), is returned.
+ as an :header:`ETag`), is returned.
:param db: Database name
:param docid: Document ID
@@ -41,8 +41,8 @@
:>header Content-MD5: Base64 encoded MD5 binary digest
:>header ETag: Double quoted base64 encoded MD5 binary digest
:code 200: Attachment exists
- :code 304: Attachment wasn't modified if :http:header:`ETag` equals specified
- :http:header:`If-None-Match` header
+ :code 304: Attachment wasn't modified if :header:`ETag` equals specified
+ :header:`If-None-Match` header
:code 401: Read privilege required
:code 404: Specified database, document or attachment was not found
@@ -73,7 +73,7 @@
Returns the file attachment associated with the document.
The raw data of the associated attachment is returned (just as if you were
- accessing a static file. The returned :http:header:`Content-Type`
+ accessing a static file. The returned :header:`Content-Type`
will be the same as the content type set when the document attachment
was submitted into the database.
@@ -95,8 +95,8 @@
:>header ETag: Double quoted base64 encoded MD5 binary digest
:response: Stored content
:code 200: Attachment exists
- :code 304: Attachment wasn't modified if :http:header:`ETag` equals specified
- :http:header:`If-None-Match` header
+ :code 304: Attachment wasn't modified if :header:`ETag` equals specified
+ :header:`If-None-Match` header
:code 401: Read privilege required
:code 404: Specified database, document or attachment was not found
@@ -105,7 +105,7 @@
Uploads the supplied content as an attachment to the specified document.
The attachment name provided must be a URL encoded string. You must also
- supply either the ``rev`` query argument or the :http:header:`If-Match`
+ supply either the ``rev`` query argument or the :header:`If-Match`
HTTP header for validation, and the HTTP headers (to set the attachment
content type).
@@ -184,7 +184,7 @@
.. http:delete:: /{db}/{docid}/{attname}
Deletes the attachment ``attachment`` of the specified ``doc``. You must
- supply the ``rev`` query parameter or :http:header:`If-Match` with the current
+ supply the ``rev`` query parameter or :header:`If-Match` with the current
revision to delete the attachment.
.. note::
@@ -224,7 +224,7 @@
Host: localhost:5984
Alternatively, instead of ``rev`` query parameter you may use
- :http:header:`If-Match` header:
+ :header:`If-Match` header:
.. code-block:: http
@@ -265,7 +265,7 @@ 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 :mimetype:`application/octet-stream`
-:http:header`Content-Type` instead of :mimetype:`text/plain`).
+:header`Content-Type` instead of :mimetype:`text/plain`).
.. code-block:: bash
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index 4ad854e..6687ebc 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -20,15 +20,15 @@
Returns the HTTP Headers containing a minimal amount of information
about the specified document. The method supports the same query
- arguments as the :http:get:`/{db}/{docid}` method, but only the header
+ arguments as the :get:`/{db}/{docid}` method, but only the header
information (including document size, and the revision as an ETag), is
returned.
- The :http:header:`ETag` header shows the current revision for the requested
- document, and the :http:header:`Content-Length` specifies the length of the
+ The :header:`ETag` header shows the current revision for the requested
+ document, and the :header:`Content-Length` specifies the length of the
data, if the document were requested in full.
- Adding any of the query arguments (see :http:get:`/{db}/{docid}`), then the
+ Adding any of the query arguments (see :get:`/{db}/{docid}`), then the
resulting HTTP Headers will correspond to what would be returned.
:param db: Database name
@@ -166,8 +166,8 @@
.. http:put:: /{db}/{docid}
- The :http:method:`PUT` method creates a new named document, or creates a new
- revision of the existing document. Unlike the :http:post:`/{db}` method, you
+ The :method:`PUT` method creates a new named document, or creates a new
+ revision of the existing document. Unlike the :post:`/{db}` method, you
must specify the document ID in the request URL.
:param db: Database name
@@ -280,7 +280,7 @@
Host: localhost:5984
Alternatively, instead of ``rev`` query parameter you may use
- :http:header:`If-Match` header:
+ :header:`If-Match` header:
.. code-block:: http
@@ -310,11 +310,11 @@
.. http:copy:: /{db}/{docid}
- The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+ The :method:`COPY` (which is non-standard HTTP) copies an existing
document to a new or existing document.
The source document is specified on the request line, with the
- :http:header:`Destination` header of the request specifying the target
+ :header:`Destination` header of the request specifying the target
document.
:param db: Database name
@@ -718,11 +718,11 @@ just inline base64 encoded attachments data into the document body:
Alternatively, you can upload a document with attachments more efficiently in
:mimetype:`multipart/related` format. This avoids having to Base64-encode
the attachments, saving CPU and bandwidth. To do this, set the
-:http:header:`Content-Type` header of the :http:put:`/{db}/{docid}` request to
+:header:`Content-Type` header of the :put:`/{db}/{docid}` request to
:mimetype:`multipart/related`.
The first MIME body is the document itself, which should have its own
-:http:header:`Content-Type` of :mimetype:`application/json"`. It also should
+:header:`Content-Type` of :mimetype:`application/json"`. It also should
include an ``_attachments`` metadata object in which each attachment object
has a key ``follows`` with value ``true``.
@@ -975,9 +975,9 @@ requested.
Retrieving Deleted Documents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-CouchDB doesn't actually deletes documents via :http:delete:`/{db}/{docid}`.
+CouchDB doesn't actually deletes documents via :delete:`/{db}/{docid}`.
Instead of this, it leaves tombstone with very basic information about document.
-If you just :http:get:`/{db}/{docid}` CouchDB returns :http:statuscode:`404`
+If you just :get:`/{db}/{docid}` CouchDB returns :statuscode:`404`
response:
**Request**:
@@ -1005,7 +1005,7 @@ response:
}
However, you may retrieve document's tombstone by using ``rev`` query parameter
-with :http:get:`/{db}/{docid}` request:
+with :get:`/{db}/{docid}` request:
**Request**:
@@ -1110,7 +1110,7 @@ Copying from a Specific Revision
--------------------------------
To copy *from* a specific version, use the ``rev`` argument to the query
-string or :http:header:`If-Match`:
+string or :header:`If-Match`:
**Request**:
@@ -1147,7 +1147,7 @@ Copying to an Existing Document
To copy to an existing document, you must specify the current revision
string for the target document by appending the ``rev`` parameter to the
-:http:header:`Destination` header string.
+:header:`Destination` header string.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index 0fb6d6c..970523e 100644
--- a/share/doc/src/api/local.rst
+++ b/share/doc/src/api/local.rst
@@ -59,22 +59,22 @@ A list of the available methods and URL paths are provided below:
Gets the specified local document. The semantics are identical to
accessing a standard document in the specified database, except that the
- document is not replicated. See :http:get:`/{db}/{docid}`.
+ document is not replicated. See :get:`/{db}/{docid}`.
.. http:put:: /{db}/_local/{docid}
Stores the specified local document. The semantics are identical to
storing a standard document in the specified database, except that the
- document is not replicated. See :http:put:`/{db}/{docid}`.
+ document is not replicated. See :put:`/{db}/{docid}`.
.. http:delete:: /{db}/_local/{docid}
Deletes the specified local document. The semantics are identical to
deleting a standard document in the specified database, except that the
- document is not replicated. See :http:delete:`/{db}/{docid}`.
+ document is not replicated. See :delete:`/{db}/{docid}`.
.. http:copy:: /{db}/_local/{docid}
Copies the specified local document. The semantics are identical to
copying a standard document in the specified database, except that the
- document is not replicated. See :http:copy:`/{db}/{docid}`.
+ document is not replicated. See :copy:`/{db}/{docid}`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 3c0686c..fda74f5 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -676,7 +676,7 @@ a 404 error.
:code 202: Server goes to restart (there is no guarantee that it will be
alive after)
:code 401: CouchDB Server Administrator privileges required
- :code 415: Bad request`s :http:header:`Content-Type`
+ :code 415: Bad request`s :header:`Content-Type`
**Request**:
@@ -892,7 +892,7 @@ structure is as follows:
Accesses the built-in Futon administration interface for CouchDB.
:>header Location: New URI location
- :code 301: Redirects to :http:get:`/_utils/`
+ :code 301: Redirects to :get:`/_utils/`
.. http:get:: /_utils/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 6cdb9ef..805f87d 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -64,6 +64,8 @@ copyright = '%d, %s' % (
highlight_language = "json"
+primary_domain = "http"
+
pygments_style = "sphinx"
html_theme = "couchdb"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/config/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/compaction.rst b/share/doc/src/config/compaction.rst
index 737c29d..0393d8c 100644
--- a/share/doc/src/config/compaction.rst
+++ b/share/doc/src/config/compaction.rst
@@ -76,7 +76,7 @@ Possible parameters:
(file_size - data_size) / file_size * 100
The data_size and file_size values can be obtained when
- querying :http:get:`/{db}`.
+ querying :get:`/{db}`.
- ``view_fragmentation``: If the ratio of legacy data, including metadata, to
current data in a view index file size is equal to or greater then this
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/api.rst b/share/doc/src/intro/api.rst
index 9779ea9..67c8f5b 100644
--- a/share/doc/src/intro/api.rst
+++ b/share/doc/src/intro/api.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. default-domain:: http
.. _intro/api:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/maintenance/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/compaction.rst b/share/doc/src/maintenance/compaction.rst
index a24e008..3e3ddfc 100644
--- a/share/doc/src/maintenance/compaction.rst
+++ b/share/doc/src/maintenance/compaction.rst
@@ -40,16 +40,16 @@ Database compaction compresses the database file by removing unused file
sections created during updates. Old documents revisions are replaced with
small amount of metadata called `tombstone` which are used for conflicts
resolution during replication. The number of stored revisions
-(and their `tombstones`) can be configured by using the :http:get:`_revs_limit
+(and their `tombstones`) can be configured by using the :get:`_revs_limit
</{db}/_revs_limit>` URL endpoint.
Compaction is manually triggered operation per database and runs as a background
task. To start it for specific database there is need to send HTTP
-:http:post:`/{db}/_compact` sub-resource of the target database::
+:post:`/{db}/_compact` sub-resource of the target database::
curl -H "Content-Type: application/json" -X POST http://localhost:5984/my_db/_compact
-On success, HTTP status :http:statuscode:`202` is returned immediately:
+On success, HTTP status :statuscode:`202` is returned immediately:
.. code-block:: http
@@ -65,9 +65,9 @@ On success, HTTP status :http:statuscode:`202` is returned immediately:
{"ok":true}
Although the request body is not used you must still specify
-:http:header:`Content-Type` header with :mimetype:`application/json` value
+:header:`Content-Type` header with :mimetype:`application/json` value
for the request. If you don't, you will be aware about with HTTP status
-:http:statuscode:`415` response:
+:statuscode:`415` response:
.. code-block:: http
@@ -111,7 +111,7 @@ information about it via :ref:`database information resource <api/db>`::
Note that ``compaction_running`` field is ``true`` indicating that compaction
is actually running. To track the compaction progress you may query the
-:http:get:`_active_tasks </_active_tasks>` resource::
+:get:`_active_tasks </_active_tasks>` resource::
curl http://localhost:5984/my_db
@@ -145,7 +145,7 @@ Views Compaction
`Views` are also need compaction like databases, unlike databases views
are compacted by groups per `design document`. To start their compaction there
-is need to send HTTP :http:post:`/{db}/_compact/{ddoc}` request::
+is need to send HTTP :post:`/{db}/_compact/{ddoc}` request::
curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_compact/designname
@@ -154,7 +154,7 @@ is need to send HTTP :http:post:`/{db}/_compact/{ddoc}` request::
{"ok":true}
This compacts the view index from the current version of the specified design
-document. The HTTP response code is :http:statuscode:`202`
+document. The HTTP response code is :statuscode:`202`
(like :ref:`compaction for databases <compact/db>`) and a compaction background
task will be created.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/maintenance/performance.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/performance.rst b/share/doc/src/maintenance/performance.rst
index 918b1cf..9495cb1 100644
--- a/share/doc/src/maintenance/performance.rst
+++ b/share/doc/src/maintenance/performance.rst
@@ -10,8 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. default-domain:: http
-
.. _performance:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/query-server/erlang.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/erlang.rst b/share/doc/src/query-server/erlang.rst
index 21f2399..165a341 100644
--- a/share/doc/src/query-server/erlang.rst
+++ b/share/doc/src/query-server/erlang.rst
@@ -10,6 +10,7 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: js
.. _query-server/erlang:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/replication/conflicts.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/conflicts.rst b/share/doc/src/replication/conflicts.rst
index 354c286..2d01a8c 100644
--- a/share/doc/src/replication/conflicts.rst
+++ b/share/doc/src/replication/conflicts.rst
@@ -109,10 +109,10 @@ Conflict avoidance
==================
When working on a single node, CouchDB will avoid creating conflicting revisions
-by returning a :http:statuscode:`409` error. This is because, when you
+by returning a :statuscode:`409` error. This is because, when you
PUT a new version of a document, you must give the ``_rev`` of the previous
version. If that ``_rev`` has already been superseded, the update is rejected
-with a :http:statuscode:`409` response.
+with a :statuscode:`409` response.
So imagine two users on the same node are fetching Bob's business card, updating
it concurrently, and writing it back:
@@ -238,7 +238,7 @@ arbitrarily large.
Working with conflicting documents
==================================
-The basic :http:get:`/{doc}/{docid}` operation will not show you any
+The basic :get:`/{doc}/{docid}` operation will not show you any
information about conflicts. You see only the deterministically-chosen winner,
and get no indication as to whether other conflicting revisions exist or not:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/replication/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/protocol.rst b/share/doc/src/replication/protocol.rst
index 3aae5c1..10ba243 100644
--- a/share/doc/src/replication/protocol.rst
+++ b/share/doc/src/replication/protocol.rst
@@ -151,26 +151,26 @@ Optimisations
API Reference
-------------
-- :http:head:`/{db}` -- Check Database existence
-- :http:post:`/{db}/_ensure_full_commit` -- Ensure that all changes are stored
+- :head:`/{db}` -- Check Database existence
+- :post:`/{db}/_ensure_full_commit` -- Ensure that all changes are stored
on disk
-- :http:get:`/{db}/_local/{id}` -- Read the last Checkpoint
-- :http:put:`/{db}/_local/{id}` -- Save a new Checkpoint
+- :get:`/{db}/_local/{id}` -- Read the last Checkpoint
+- :put:`/{db}/_local/{id}` -- Save a new Checkpoint
Push Only
~~~~~~~~~
-- :http:put:`/{db}` -- Create Target if it not exists and option was provided
-- :http:post:`/{db}/_revs_diff` -- Locate Revisions that are not known to the
+- :put:`/{db}` -- Create Target if it not exists and option was provided
+- :post:`/{db}/_revs_diff` -- Locate Revisions that are not known to the
Target
-- :http:post:`/{db}/_bulk_docs` -- Upload Revisions to the Target
-- :http:put:`/{db}/{docid}`?new_edits=false -- Upload a single Document with
+- :post:`/{db}/_bulk_docs` -- Upload Revisions to the Target
+- :put:`/{db}/{docid}`?new_edits=false -- Upload a single Document with
attachments to the Target
Pull Only
~~~~~~~~~
-- :http:get:`/{db}/_changes` -- Locate changes since on Source the last pull.
+- :get:`/{db}/_changes` -- Locate changes since on Source the last pull.
The request uses next query parameters:
- ``style=all_docs``
@@ -179,7 +179,7 @@ Pull Only
- ``limit=limit``
- ``heartbeat=heartbeat``
-- :http:get:`/{db}/{docid}` -- Retrieve a single Document from Source with attachments.
+- :get:`/{db}/{docid}` -- Retrieve a single Document from Source with attachments.
The request uses next query parameters:
- ``open_revs=revid`` - where ``revid`` is the actual Document Revision at the
[18/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Add missed theme's files.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/9454b50a
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9454b50a
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9454b50a
Branch: refs/heads/replicator-redesign
Commit: 9454b50af5671cc10f28e6885c6aadce7f606637
Parents: 18735b6
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Sep 12 04:59:25 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 2 ++
1 file changed, 2 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/9454b50a/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 1030dcd..729313a 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -403,6 +403,8 @@ src_files = \
src_files_html = \
../static/rtd.css \
+ ../templates/couchdb/domainindex.html \
+ ../templates/couchdb/theme.conf \
../templates/pages/download.html \
../templates/pages/index.html \
../templates/layout.html \
[45/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Don't run license check for Python bytecode files.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/30f05997
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/30f05997
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/30f05997
Branch: refs/heads/replicator-redesign
Commit: 30f05997864aa3f066e99d377982e8dfb8bd655e
Parents: 6c2123a
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 16:22:28 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 16:22:28 2013 +0400
----------------------------------------------------------------------
license.skip | 3 +++
1 file changed, 3 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/30f05997/license.skip
----------------------------------------------------------------------
diff --git a/license.skip b/license.skip
index 9ade149..08c4864 100644
--- a/license.skip
+++ b/license.skip
@@ -59,9 +59,12 @@
^share/doc/Makefile
^share/doc/Makefile.in
^share/doc/build/.*
+^share/doc/ext/__pycache__/.*
+^share/doc/ext/*.pyc
^share/doc/ext/httpdomain.py
^share/doc/ext/http-api-descr.json
^share/doc/images/.*
+^share/doc/src/conf.pyc
^share/doc/static/rtd.css
^share/doc/templates/couchdb/domainindex.html
^share/server/json2.js
[38/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Prepare for 1.5.0 release.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5fe58936
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5fe58936
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5fe58936
Branch: refs/heads/replicator-redesign
Commit: 5fe58936ae6bf4e72e43380d517c057f7cabd1c8
Parents: 6b50511
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:45:05 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:45:05 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +++
share/doc/src/whatsnew/1.5.rst | 31 +++++++++++++++++++++++++++++++
share/doc/src/whatsnew/index.rst | 2 +-
3 files changed, 35 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5fe58936/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index c83e392..870976a 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -138,6 +138,7 @@ html_files = \
html/_sources/whatsnew/1.2.txt \
html/_sources/whatsnew/1.3.txt \
html/_sources/whatsnew/1.4.txt \
+ html/_sources/whatsnew/1.5.txt \
html/_sources/whatsnew/index.txt \
html/_sources/about.txt \
html/_sources/contents.txt \
@@ -256,6 +257,7 @@ html_files = \
html/whatsnew/1.2.html \
html/whatsnew/1.3.html \
html/whatsnew/1.4.html \
+ html/whatsnew/1.5.html \
html/whatsnew/index.html \
html/about.html \
html/contents.html \
@@ -396,6 +398,7 @@ src_files = \
../src/whatsnew/1.2.rst \
../src/whatsnew/1.3.rst \
../src/whatsnew/1.4.rst \
+ ../src/whatsnew/1.5.rst \
../src/whatsnew/index.rst \
../src/about.rst \
../src/contents.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5fe58936/share/doc/src/whatsnew/1.5.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/whatsnew/1.5.rst b/share/doc/src/whatsnew/1.5.rst
new file mode 100644
index 0000000..f2ce86a
--- /dev/null
+++ b/share/doc/src/whatsnew/1.5.rst
@@ -0,0 +1,31 @@
+.. 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.
+
+
+.. _release/1.5.x:
+
+============
+1.5.x Branch
+============
+
+.. contents::
+ :depth: 1
+ :local:
+
+.. _release/1.5.0:
+
+Version 1.5.0
+=============
+
+.. warning::
+
+ This version is not released yet.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5fe58936/share/doc/src/whatsnew/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/whatsnew/index.rst b/share/doc/src/whatsnew/index.rst
index a69a75e..50cc9ec 100644
--- a/share/doc/src/whatsnew/index.rst
+++ b/share/doc/src/whatsnew/index.rst
@@ -19,7 +19,7 @@ Release History
.. toctree::
:glob:
- ../cve/index
+ 1.5
1.4
1.3
1.2
[10/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Add missed figure 7.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/d1e3b5d6
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/d1e3b5d6
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/d1e3b5d6
Branch: refs/heads/replicator-redesign
Commit: d1e3b5d6c69ac6cf9779a1fe2d77571e7fb48dd5
Parents: c5e0cc5
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 4 19:37:40 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/src/intro/tour.rst | 8 ++++++++
1 file changed, 8 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d1e3b5d6/share/doc/src/intro/tour.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/tour.rst b/share/doc/src/intro/tour.rst
index af91f5e..b8f9975 100644
--- a/share/doc/src/intro/tour.rst
+++ b/share/doc/src/intro/tour.rst
@@ -398,6 +398,14 @@ which shows each fruit sorted by price. Click "hello-world" to return to the
hello-world overview, and then from the "select view" menu choose "Temporary
view…" to create a new view.
+
+.. figure:: ../../images/intro-tour-07.png
+ :align: center
+ :alt: A temporary view in Futon
+
+ Figure 7. A temporary view in Futon
+
+
Edit the map function, on the left, so that it looks like the following:
.. code-block:: javascript
[30/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
docs: ensure scope of server administrator is clear
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/655809fc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/655809fc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/655809fc
Branch: refs/heads/replicator-redesign
Commit: 655809fca32292b1b3ba41bf2177c18e0b6b24a1
Parents: e6f1e84
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Sat Sep 28 00:32:59 2013 +0200
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Sat Sep 28 00:32:59 2013 +0200
----------------------------------------------------------------------
share/doc/src/api/database/common.rst | 4 ++--
share/doc/src/api/database/compact.rst | 6 +++---
share/doc/src/api/database/security.rst | 2 +-
share/doc/src/api/server/common.rst | 14 +++++++-------
share/doc/src/api/server/configuration.rst | 10 +++++-----
5 files changed, 18 insertions(+), 18 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/655809fc/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index ecf31fe..853ff6b 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -131,7 +131,7 @@
:>json string reason: Error description. Available if response code is ``4xx``
:code 201: Database created successfully
:code 400: Invalid database name
- :code 401: Administrator`s privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 412: Database already exists
**Request**:
@@ -225,8 +225,8 @@
:>json boolean ok: Operation status
:code 200: Database removed successfully
:code 400: Invalid database name
- :code 401: Administrator`s privileges required
:code 404: Database doesn't already exists
+ :code 401: CouchDB Server Administrator privileges required
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/655809fc/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 42d99eb..6982cb4 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -52,7 +52,7 @@
:>json boolean ok: Operation status
:code 202: Compaction request has been accepted
:code 400: Invalid database name
- :code 401: Administrator`s privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 415: Bad :http:header:`Content-Type` value
**Request**:
@@ -102,7 +102,7 @@
:>json boolean ok: Operation status
:code 202: Compaction request has been accepted
:code 400: Invalid database name
- :code 401: Administrator`s privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 404: Design document not found
:code 415: Bad :http:header:`Content-Type` value
@@ -198,7 +198,7 @@
:>json boolean ok: Operation status
:code 202: Compaction request has been accepted
:code 400: Invalid database name
- :code 401: Administrator`s privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 415: Bad :http:header:`Content-Type` value
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/655809fc/share/doc/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index 551e5a8..8ad62e6 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -131,7 +131,7 @@
- :mimetype:`text/plain; charset=utf-8`
:>json boolean ok: Operation status
:code 200: Request completed successfully
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/655809fc/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index f58403f..3c0686c 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -86,7 +86,7 @@
:>json string type: Operation Type
:>json number updated_on: Unix timestamp of last operation update
:code 200: Request completed successfully
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
**Request**:
@@ -234,8 +234,8 @@
:>json boolean ok: Event operation status
:>json string type: A database event is one of ``created``, ``updated``,
``deleted``
- :code 200: Request completed successfully.
- :code 401: Administrator's privileges required.
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
**Request**:
@@ -279,8 +279,8 @@
Default is ``0``.
:>header Content-Type: :mimetype:`text/plain; charset=utf-8`
:>header Transfer-Encoding: ``chunked``
- :code 200: Request completed successfully.
- :code 401: Administrator's privileges required.
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
**Request**:
@@ -366,7 +366,7 @@ jumping to ``offset`` bytes towards the beginning of the file first:
:code 200: Replication request successfully completed
:code 202: Continuous replication request has been accepted
:code 400: Invalid JSON data
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 404: Either the source or target DB is not found or attempt to
cancel unknown replication task
:code 500: JSON specification was invalid
@@ -675,7 +675,7 @@ a 404 error.
- :mimetype:`text/plain; charset=utf-8`
:code 202: Server goes to restart (there is no guarantee that it will be
alive after)
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 415: Bad request`s :http:header:`Content-Type`
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/655809fc/share/doc/src/api/server/configuration.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/configuration.rst b/share/doc/src/api/server/configuration.rst
index e974328..46a4e78 100644
--- a/share/doc/src/api/server/configuration.rst
+++ b/share/doc/src/api/server/configuration.rst
@@ -34,7 +34,7 @@ CouchDB instance.
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
**Request**
@@ -169,7 +169,7 @@ CouchDB instance.
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
**Request**:
@@ -220,7 +220,7 @@ CouchDB instance.
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
**Request**:
@@ -266,7 +266,7 @@ CouchDB instance.
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
:code 400: Invalid JSON request body
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 500: Error setting configuration
**Request**:
@@ -307,7 +307,7 @@ CouchDB instance.
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
- :code 401: Administrator's privileges required
+ :code 401: CouchDB Server Administrator privileges required
:code 404: Specified configuration option not found
**Request**:
[20/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Limit sections enumeration.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ebaac5cc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ebaac5cc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ebaac5cc
Branch: refs/heads/replicator-redesign
Commit: ebaac5cc519210d81ed9857d12c850b672a0cd30
Parents: 508b565
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 18 10:51:09 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/contents.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ebaac5cc/share/doc/src/contents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/contents.rst b/share/doc/src/contents.rst
index f00aed6..700e90a 100644
--- a/share/doc/src/contents.rst
+++ b/share/doc/src/contents.rst
@@ -16,7 +16,7 @@
.. toctree::
:maxdepth: 3
- :numbered:
+ :numbered: 3
intro/index
install/index
[32/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
docs: update the updates
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a169ab67
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a169ab67
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a169ab67
Branch: refs/heads/replicator-redesign
Commit: a169ab6746527a027d016c5ed8a22bc47d03a397
Parents: 083bb15
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Sat Sep 28 02:16:44 2013 +0200
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Sat Sep 28 02:16:44 2013 +0200
----------------------------------------------------------------------
share/doc/src/api/database/changes.rst | 14 ++++++++++----
share/doc/src/api/database/common.rst | 10 +++++-----
share/doc/src/api/database/compact.rst | 13 +++++++++----
3 files changed, 24 insertions(+), 13 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a169ab67/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index 739f7d8..52dc32d 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -21,11 +21,17 @@
.. http:head:: /{db}/_changes
.. http:post:: /{db}/_changes
- A sorted list of changes made to documents in the database, in the order
- they were made, can be obtained from the database's ``_changes`` resource.
+ A sorted list of changes made to documents in the database, in time order of
+ application, can be obtained from the database's ``_changes`` resource. Only
+ the most recent change for a given document is guaranteed to be provided,
+ for example if a document has had fields added, and then deleted, an API
+ client checking for changes will not necessarily receive the intermediate
+ state of added documents.
This can be used to listen for update and modifications to the database for
- post processing or synchronization.
+ post processing or synchronization, and for practical purposes, a continuously
+ connected ``_changes`` feed is a reasonable approach for generating a
+ real-time log for most applications.
:param db: Database name
:<header Accept: - :mimetype:`application/json`
@@ -289,7 +295,7 @@ Event Source
The `eventsource` feed provides push notifications that can be consumed in
the form of DOM events in the browser. Refer to the `W3C eventsource
-specification`_ for further details. CouchDB also honors the ``Last-Event-ID``
+specification`_ for further details. CouchDB also honours the ``Last-Event-ID``
parameter.
.. code-block:: text
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a169ab67/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index a131e39..5265919 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -381,11 +381,11 @@ respond with a HTTP :http:statuscode:`202` response code immediately.
.. note::
- Creating or updating documents with batch mode doesn't guarantee that
- document will be successfully stored on disk and CouchDB does not
- guarantee that. For example, individual documents may not be saved due to
- conflicts, rejection by :ref:`validation function <vdufun>` or by other
- reasons, even if overall the batch transfer was sucessfully submitted.
+ Creating or updating documents with batch mode doesn't guarantee that all
+ documents will be successfully stored on disk. For example, individual
+ documents may not be saved due to conflicts, rejection by
+ :ref:`validation function <vdufun>` or by other reasons, even if overall
+ the batch was sucessfully submitted.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a169ab67/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 81935db..f7289e5 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -88,9 +88,10 @@
.. http:post:: /{db}/_compact/{ddoc}
Compacts the view indexes associated with the specified design document.
- You can use this in place of the full database compaction if you know a
- specific set of view indexes have been affected by a recent database
- change.
+ If may be that compacting a large view can return more storage than
+ compacting the atual db. Thus, you can use this in place of the full
+ database compaction if you know a specific set of view indexes have been
+ affected by a recent database change.
:param db: Database name
:param ddoc: Design document name
@@ -144,7 +145,11 @@
.. http:post:: /{db}/_ensure_full_commit
Commits any recent changes to the specified database to disk. You should
- call this if you want to ensure that recent changes have been written.
+ call this if you want to ensure that recent changes have been flushed.
+ This function is likely not required, assuming you have the recommended
+ configuration setting of ``delayed_commits=false``, which requires CouchDB
+ to ensure changes are written to disk before a 200 or similar result is
+ returned.
:param db: Database name
:<header Accept: - :mimetype:`application/json`
[36/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Provides short description for the HTTP API reference entries.
The description is defined within special JSON file instead of markup attributes.
There should be way to hack sphinx for this, but currently I don't know how to
do this. Hope this will be fixed in nearest future.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/088ea1ed
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/088ea1ed
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/088ea1ed
Branch: refs/heads/replicator-redesign
Commit: 088ea1ed8c135647087fe99657cff07d714b9eb4
Parents: 8baf5eb
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:14:37 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:14:37 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +-
share/doc/ext/http-api-descr.json | 79 ++++++++++++++++++++++++++++++++++
share/doc/ext/httpdomain.py | 10 ++++-
3 files changed, 89 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/088ea1ed/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index d03eb30..5a9441f 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -414,7 +414,8 @@ src_files_html = \
sphinx_extensions = \
../ext/github.py \
- ../ext/httpdomain.py
+ ../ext/httpdomain.py \
+ ../ext/http-api-descr.json
EXTRA_DIST = \
$(image_files) \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/088ea1ed/share/doc/ext/http-api-descr.json
----------------------------------------------------------------------
diff --git a/share/doc/ext/http-api-descr.json b/share/doc/ext/http-api-descr.json
new file mode 100644
index 0000000..e7672e4
--- /dev/null
+++ b/share/doc/ext/http-api-descr.json
@@ -0,0 +1,79 @@
+{
+ "GET /": "Returns the welcome message and version information",
+ "GET /_active_tasks": "Obtains a list of the tasks running in the server",
+ "GET /_all_dbs": "Returns a list of all the databases",
+ "GET /_config": "Obtains a list of the entire server configuration",
+ "GET /_config/{section}": "Returns all the configuration values for the specified section",
+ "DELETE /_config/{section}/{key}": "Removes the current setting",
+ "GET /_config/{section}/{key}": "Returns a specific section/configuration value",
+ "PUT /_config/{section}/{key}": "Sets the specified configuration value",
+ "GET /_db_updates": "Return the server changes of databases",
+ "GET /_log": "Returns the server log file",
+ "POST /_replicate": "Starts or cancels the replication",
+ "POST /_restart": "Restarts the server",
+ "DELETE /_session": "Logout Cookie-based user",
+ "GET /_session": "Returns Cookie-based login user information",
+ "POST /_session": "Authenticates user by Cookie-based user login",
+ "GET /_stats": "Returns server statistics",
+ "GET /_utils/": "CouchDB administration interface (Futon)",
+ "GET /_uuids": "Generates a list of UUIDs from the server",
+ "GET /favicon.ico": "Returns the site icon",
+ "DELETE /{db}": "Deletes an existing database",
+ "GET /{db}": "Returns the database information",
+ "HEAD /{db}": "Checks the database existence",
+ "POST /{db}": "Creates a new document with generic ID if he had not specified",
+ "PUT /{db}": "Creates a new database",
+ "GET /{db}/_all_docs": "Returns a built-in view of all documents in this database",
+ "POST /{db}/_all_docs": "Returns certain rows from the built-in view of all documents",
+ "POST /{db}/_bulk_docs": "Inserts or updates multiple documents in to the database in a single request",
+ "GET /{db}/_changes": "Returns changes for the given database",
+ "POST /{db}/_changes": "Returns changes for the given database for certain document IDs",
+ "POST /{db}/_compact": "Starts a compaction for the database",
+ "POST /{db}/_compact/{ddoc}": "Starts a compaction for all the views in the selected design document",
+ "COPY /{db}/_design/{ddoc}": "Copies the design document",
+ "DELETE /{db}/_design/{ddoc}": "Deletes the design document",
+ "GET /{db}/_design/{ddoc}": "Returns the design document",
+ "HEAD /{db}/_design/{ddoc}": "Returns bare information in the HTTP Headers for the design document",
+ "PUT /{db}/_design/{ddoc}": "Creates a new design document, or new version of an existing one",
+ "GET /{db}/_design/{ddoc}/_info": "Returns view index information for the specified design document",
+ "GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}": "Executes a list function against the view from other design document",
+ "POST /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}": "",
+ "GET /{db}/_design/{ddoc}/_list/{func}/{view}": "Executes a list function against the view from the same design document",
+ "POST /{db}/_design/{ddoc}/_list/{func}/{view}": "",
+ "ANY /{db}/_design/{ddoc}/_rewrite/{path}": "Rewrites HTTP request for the specified path by using stored routing rules",
+ "GET /{db}/_design/{ddoc}/_show/{func}": "Executes a show function against null document",
+ "POST /{db}/_design/{ddoc}/_show/{func}": "",
+ "GET /{db}/_design/{ddoc}/_show/{func}/{docid}": "Executes a show function against the specified document",
+ "POST /{db}/_design/{ddoc}/_show/{func}/{docid}": "",
+ "POST /{db}/_design/{ddoc}/_update/{func}": "Executes an update function",
+ "PUT /{db}/_design/{ddoc}/_update/{func}/{docid}": "Executes an update function against the specified document",
+ "GET /{db}/_design/{ddoc}/_view/{view}": "Returns results for the specified stored view",
+ "POST /{db}/_design/{ddoc}/_view/{view}": "Returns certain rows for the specified stored view",
+ "DELETE /{db}/_design/{ddoc}/{attname}": "Deletes an attachment of a design document",
+ "GET /{db}/_design/{ddoc}/{attname}": "Gets the attachment of a design document",
+ "HEAD /{db}/_design/{ddoc}/{attname}": "Returns bare information in the HTTP Headers for the attachment",
+ "PUT /{db}/_design/{ddoc}/{attname}": "Adds an attachment of a design document",
+ "POST /{db}/_ensure_full_commit": "Makes sure all uncommitted changes are written and synchronized to the disk",
+ "COPY /{db}/_local/{docid}": "Copies the non-replicated document",
+ "DELETE /{db}/_local/{docid}": "Deletes the non-replicated document",
+ "GET /{db}/_local/{docid}": "Returns the latest revision of the non-replicated document",
+ "PUT /{db}/_local/{docid}": "Inserts a new version of the non-replicated document",
+ "POST /{db}/_missing_revs": "By given list of document revisions, returns the document revisions that do not exist in the database",
+ "POST /{db}/_purge": "Purges some historical documents entirely from database history",
+ "POST /{db}/_revs_diff": "By given list of document revisions, returns differences between the given revisions and ones that are in the database",
+ "GET /{db}/_revs_limit": "Returns the limit of historical revisions to store for a single document in the database",
+ "PUT /{db}/_revs_limit": "Sets the limit of historical revisions to store for a single document in the database",
+ "GET /{db}/_security": "Returns the special security object for the database",
+ "PUT /{db}/_security": "Sets the special security object for the database",
+ "POST /{db}/_temp_view": "Executes a given view function for all documents and returns the result",
+ "POST /{db}/_view_cleanup": "Removes view files that are not used by any design document",
+ "COPY /{db}/{docid}": "Copies the document",
+ "DELETE /{db}/{docid}": "Deletes the document",
+ "GET /{db}/{docid}": "Returns the document",
+ "HEAD /{db}/{docid}": "Returns bare information in the HTTP Headers for the document",
+ "PUT /{db}/{docid}": "Creates a new document, or new version of an existing document",
+ "DELETE /{db}/{docid}/{attname}": "Deletes an attachment of a document",
+ "GET /{db}/{docid}/{attname}": "Gets the attachment of a document",
+ "HEAD /{db}/{docid}/{attname}": "Returns bare information in the HTTP Headers for the attachment",
+ "PUT /{db}/{docid}/{attname}": "Adds an attachment of a document"
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/couchdb/blob/088ea1ed/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index a2de686..afc81b5 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -9,6 +9,8 @@
"""
+import os
+import json
import re
from docutils import nodes
@@ -452,6 +454,8 @@ class HTTPIndex(Index):
name = 'api'
localname = 'HTTP API Reference'
shortname = 'API Reference'
+ api_descr = json.load(open(os.path.join(os.path.dirname(__file__),
+ 'http-api-descr.json')))
def generate(self, docnames=None):
content = {}
@@ -461,9 +465,11 @@ class HTTPIndex(Index):
items = sorted(items, key=lambda item: item[1])
for method, path, info in items:
entries = content.setdefault(path, [])
+ entry_name = method.upper() + ' ' + path
entries.append([
- method.upper() + ' ' + path, 0, info[0],
- http_resource_anchor(method, path), '', '', info[1]
+ entry_name, 0, info[0],
+ http_resource_anchor(method, path),
+ '', '', self.api_descr.get(entry_name, '')
])
items = sorted(
(path, sort_by_method(entries))
[21/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
docs: use sphinx automatic version numbers for protocol responses
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/508b565d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/508b565d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/508b565d
Branch: refs/heads/replicator-redesign
Commit: 508b565d2d425bd31fb155538e2be20647ae0846
Parents: cf4a09b
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Fri Sep 27 14:17:07 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/basics.rst | 4 +--
share/doc/src/api/database/bulk-api.rst | 4 +--
share/doc/src/api/database/changes.rst | 2 +-
share/doc/src/api/database/common.rst | 18 ++++++-------
share/doc/src/api/database/compact.rst | 8 +++---
share/doc/src/api/database/misc.rst | 10 ++++----
share/doc/src/api/database/security.rst | 4 +--
share/doc/src/api/database/temp-views.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 2 +-
share/doc/src/api/ddoc/render.rst | 12 ++++-----
share/doc/src/api/ddoc/views.rst | 12 ++++-----
share/doc/src/api/document/attachments.rst | 6 ++---
share/doc/src/api/document/common.rst | 34 ++++++++++++-------------
share/doc/src/api/server/authn.rst | 14 +++++-----
share/doc/src/api/server/common.rst | 16 ++++++------
share/doc/src/api/server/configuration.rst | 12 ++++-----
share/doc/src/config/auth.rst | 4 +--
share/doc/src/config/couchdb.rst | 2 +-
share/doc/src/config/http.rst | 2 +-
share/doc/src/config/misc.rst | 2 +-
share/doc/src/externals.rst | 4 +--
share/doc/src/intro/api.rst | 8 +++---
share/doc/src/maintenance/compaction.rst | 8 +++---
23 files changed, 95 insertions(+), 95 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/basics.rst b/share/doc/src/api/basics.rst
index 74465b6..d05ddb6 100644
--- a/share/doc/src/api/basics.rst
+++ b/share/doc/src/api/basics.rst
@@ -160,7 +160,7 @@ Request Headers
.. code-block:: http
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+ Server: CouchDB (Erlang/OTP)
Date: Thu, 13 Jan 2011 13:39:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 227
@@ -181,7 +181,7 @@ Request Headers
.. code-block:: http
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Date: Thu, 13 Jan 2013 13:40:11 GMT
Content-Type: application/json
Content-Length: 227
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index 148da3d..9017227 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -85,7 +85,7 @@
Content-Type: application/json
Date: Sat, 10 Aug 2013 16:22:56 GMT
ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -258,7 +258,7 @@
Content-Length: 144
Content-Type: application/json
Date: Mon, 12 Aug 2013 00:15:05 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
[
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index 52a38a7..344a3bb 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -102,7 +102,7 @@
Content-Type: application/json
Date: Mon, 12 Aug 2013 00:54:58 GMT
ETag: "6ASLEKEMSRABT0O5XY9UPO9Z"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 2fb525f..ecf31fe 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -40,7 +40,7 @@
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:27:41 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}
@@ -86,7 +86,7 @@
Content-Length: 258
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:38:57 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"committed_update_seq": 292786,
@@ -152,7 +152,7 @@
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:45 GMT
Location: http://localhost:5984/db
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -178,7 +178,7 @@
Content-Length: 95
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:16 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "file_exists",
@@ -204,7 +204,7 @@
Content-Length: 194
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:02:10 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "illegal_database_name",
@@ -245,7 +245,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:54:00 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -311,7 +311,7 @@
Date: Tue, 13 Aug 2013 15:19:25 GMT
ETag: "1-9c65296036141e575d32ba9c034dd3ee"
Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "ab39fe0993049b84cfa81acd6ebad09d",
@@ -354,7 +354,7 @@ document with the ID ``FishStew``.
Date: Tue, 13 Aug 2013 15:19:25 GMT
ETag: "1-9c65296036141e575d32ba9c034dd3ee"
Location: http://localhost:5984/db/FishStew
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
@@ -411,7 +411,7 @@ respond with a HTTP :http:statuscode:`202` response code immediately.
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
Location: http://localhost:5984/db/FishStew
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 51e9c3f..42d99eb 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -73,7 +73,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 09:27:43 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -124,7 +124,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 09:36:44 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -172,7 +172,7 @@
Content-Length: 53
Content-Type: application/json
Date: Mon, 12 Aug 2013 10:22:19 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"instance_start_time": "1376269047459338",
@@ -219,7 +219,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 09:27:43 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index b0c3706..d3507a5 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -82,7 +82,7 @@
Content-Length: 103
Content-Type: application/json
Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"purge_seq":3,
@@ -162,7 +162,7 @@ database must be examined.
Content-Length: 64
Content-Type: application/json
Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"missed_revs":{
@@ -237,7 +237,7 @@ database must be examined.
Content-Length: 88
Content-Type: application/json
Date: Mon, 12 Aug 2013 16:56:02 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"190f721ca3411be7aa9477db5f948bbb": {
@@ -281,7 +281,7 @@ database must be examined.
Content-Length: 5
Content-Type: application/json
Date: Mon, 12 Aug 2013 17:27:30 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
1000
@@ -324,7 +324,7 @@ database must be examined.
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 17:47:52 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index 1856579..551e5a8 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -92,7 +92,7 @@
Content-Length: 109
Content-Type: application/json
Date: Mon, 12 Aug 2013 19:05:29 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"admins": {
@@ -172,7 +172,7 @@
Content-Length: 12
Content-Type: application/json
Date: Tue, 13 Aug 2013 11:26:28 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/temp-views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst
index 9bcecb5..0b576b8 100644
--- a/share/doc/src/api/database/temp-views.rst
+++ b/share/doc/src/api/database/temp-views.rst
@@ -53,7 +53,7 @@
Content-Type: application/json
Date: Tue, 13 Aug 2013 12:28:12 GMT
ETag: "AU33B3N7S9K4SAZSFA048HVB4"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index 0d6ec17..1e5b183 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -172,7 +172,7 @@
Content-Length: 263
Content-Type: application/json
Date: Sat, 17 Aug 2013 12:54:17 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"name": "recipe",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/ddoc/render.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/render.rst b/share/doc/src/api/ddoc/render.rst
index c87824c..9c6b1c4 100644
--- a/share/doc/src/api/ddoc/render.rst
+++ b/share/doc/src/api/ddoc/render.rst
@@ -62,7 +62,7 @@
Content-Type: text/html; charset=utf-8
Date: Wed, 21 Aug 2013 12:34:07 GMT
Etag: "7Z2TO7FPEMZ0F4GH0RJCRIOAU"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Vary: Accept
no doc
@@ -120,7 +120,7 @@
Content-Type: text/html; charset=utf-8
Date: Wed, 21 Aug 2013 12:38:08 GMT
Etag: "8IEBO8103EI98HDZL5Z4I1T0C"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Vary: Accept
An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.
@@ -181,7 +181,7 @@
Content-Type: text/plain; charset=utf-8
Date: Wed, 21 Aug 2013 12:49:15 GMT
Etag: "D52L2M1TKQYDD1Y8MEYJR8C84"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
Vary: Accept
@@ -244,7 +244,7 @@
Content-Type: text/plain; charset=utf-8
Date: Wed, 21 Aug 2013 12:49:15 GMT
Etag: "5L0975X493R0FB5Z3043POZHD"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
Vary: Accept
@@ -306,7 +306,7 @@
Content-Length: 52
Content-Type: application/json
Date: Wed, 21 Aug 2013 14:00:58 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "missed",
@@ -371,7 +371,7 @@
Content-Length: 16
Content-Type: application/json
Date: Wed, 21 Aug 2013 14:11:34 GMT
- Server: CouchDB/1.4.0+build.c843cef (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
X-Couch-Id: SpaghettiWithMeatballs
X-Couch-Update-NewRev: 12-a5e099df5720988dae90c8b664496baf
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index bb45095..ade789c 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -97,7 +97,7 @@
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:12:06 GMT
ETag: "2FOLSBSW4O6WB798XU4AQYA9B"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -157,7 +157,7 @@
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "6R5NM8E872JIJF796VF7WI3FZ"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -339,7 +339,7 @@ content. The basic order of output is as follows:
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "8LA1LZPQ37B6R9U8BK9BGQH27"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -467,7 +467,7 @@ You can reverse the order of the returned view information by using the
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "Z4N468R15JBT98OM0AMNSR8U"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -669,7 +669,7 @@ in view:
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "9Q6Q2GZKPH8D5F8L7PB6DBSS9"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -738,7 +738,7 @@ To omit some records you may use ``skip`` query parameter:
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "H3G7YZSNIVRRHO5FXPE16NJHN"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index 3f3e8d4..34526fc 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -66,7 +66,7 @@
Content-Type: text/plain
Date: Thu, 15 Aug 2013 12:42:42 GMT
ETag: "vVa/YgiE1+Gh0WfoFJAcSg=="
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}/{docid}/{attname}
@@ -172,7 +172,7 @@
Date: Thu, 15 Aug 2013 12:38:04 GMT
ETag: "2-ce91aed0129be8f9b0f650a2edcfd0a4"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs/recipe.txt
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
@@ -243,7 +243,7 @@
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:13 GMT
ETag: "7-05185cf5fcdf4b6da360af939431d466"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index adbf03e..03b1de1 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -59,7 +59,7 @@
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "12-151bb8678d45aaa949ec3698ef1c7e78"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}/{docid}
@@ -150,7 +150,7 @@
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "1-917fa2381192822767f010b95b45325b"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -227,7 +227,7 @@
Date: Wed, 14 Aug 2013 20:31:39 GMT
ETag: "1-917fa2381192822767f010b95b45325b"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
@@ -299,7 +299,7 @@
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:13 GMT
ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
@@ -365,7 +365,7 @@
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "1-e86fdf912560c2321a5fcefc6264e6d9"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Italian",
@@ -429,7 +429,7 @@ Basic Attachments Info
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -491,7 +491,7 @@ It's possible to retrieve document with all attached files content by using
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:32:40 GMT
ETag: "4-f1bcae4bf7bbb92310079e632abfe3f4"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -533,7 +533,7 @@ query parameter:
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -594,7 +594,7 @@ about compressed attachments size and used codec.
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -660,7 +660,7 @@ the ``revs=true`` parameter to the request URL:
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:38:26 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -719,7 +719,7 @@ document by supplying the ``revs_info`` argument to the query:
Content-Length: 802
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:40:55 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -807,7 +807,7 @@ requested.
Content-Length: 271
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:40:55 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -847,7 +847,7 @@ response:
Content-Length: 41
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:27 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "not_found",
@@ -875,7 +875,7 @@ with :http:get:`/{db}/{docid}` request:
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:30:22 GMT
ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_deleted": true,
@@ -947,7 +947,7 @@ Alternatively, you can supply the current revision number in the
Date: Wed, 14 Aug 2013 20:33:56 GMT
ETag: "2-790895a73b63fb91dd863388398483dd"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
@@ -983,7 +983,7 @@ string or :http:header:`If-Match`:
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "1-917fa2381192822767f010b95b45325b"
Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Original",
@@ -1019,7 +1019,7 @@ string for the target document by appending the ``rev`` parameter to the
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "2-62e778c9ec09214dd685a981dcc24074""
Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Original",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index 0b44920..ce08277 100644
--- a/share/doc/src/api/server/authn.rst
+++ b/share/doc/src/api/server/authn.rst
@@ -51,7 +51,7 @@ CouchDB must compute password hash with every request):
Content-Length: 177
Content-Type: application/json
Date: Mon, 03 Dec 2012 00:44:47 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"couchdb":"Welcome",
@@ -143,7 +143,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Length: 43
Content-Type: application/json
Date: Mon, 03 Dec 2012 01:23:14 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=cm9vdDo1MEJCRkYwMjq0LO0ylOIwShrgt8y-UkhI-c6BGw; Version=1; Path=/; HttpOnly
{"ok":true,"name":"root","roles":["_admin"]}
@@ -172,7 +172,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Type: application/json
Date: Mon, 03 Dec 2012 01:32:46 GMT
Location: http://localhost:5984/blog/_design/sofa/_rewrite/recent-posts
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=cm9vdDo1MEJDMDEzRTp7Vu5GKCkTxTVxwXbpXsBARQWnhQ; Version=1; Path=/; HttpOnly
{"ok":true,"name":null,"roles":["_admin"]}
@@ -207,7 +207,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Length: 175
Content-Type: application/json
Date: Fri, 09 Aug 2013 20:27:45 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=cm9vdDo1MjA1NTBDMTqmX2qKt1KDR--GUC80DQ6-Ew_XIw; Version=1; Path=/; HttpOnly
{
@@ -255,7 +255,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Length: 12
Content-Type: application/json
Date: Fri, 09 Aug 2013 20:30:12 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=; Version=1; Path=/; HttpOnly
{
@@ -317,7 +317,7 @@ headers to CouchDB with related request:
Content-Length: 190
Content-Type: application/json
Date: Fri, 14 Jun 2013 10:16:03 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
{
"info": {
@@ -430,7 +430,7 @@ Both snippets produces similar request and response pair:
Content-Length : 167
Content-Type : application/json
Date : Tue, 23 Jul 2013 06:51:15 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 22e312d..f58403f 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -46,7 +46,7 @@
Content-Length: 179
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:33:33 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"couchdb": "Welcome",
@@ -105,7 +105,7 @@
Content-Length: 1690
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:37:31 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
[
{
@@ -194,7 +194,7 @@
Content-Length: 52
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:57:48 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
[
"_users",
@@ -253,7 +253,7 @@
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 10 Aug 2013 07:02:41 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -415,7 +415,7 @@ jumping to ``offset`` bytes towards the beginning of the file first:
Content-Length: 692
Content-Type: application/json
Date: Sun, 11 Aug 2013 20:38:50 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"history": [
@@ -695,7 +695,7 @@ a 404 error.
Content-Length: 12
Content-Type: application/json
Date: Sat, 10 Aug 2013 11:33:50 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -738,7 +738,7 @@ a 404 error.
Content-Length: 187
Content-Type: application/json
Date: Sat, 10 Aug 2013 11:41:11 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"couchdb": {
@@ -939,7 +939,7 @@ structure is as follows:
ETag: "DGRWWQFLUDWN5MRKSLKQ425XV"
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Pragma: no-cache
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"uuids": [
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/server/configuration.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/configuration.rst b/share/doc/src/api/server/configuration.rst
index 41270dd..e974328 100644
--- a/share/doc/src/api/server/configuration.rst
+++ b/share/doc/src/api/server/configuration.rst
@@ -53,7 +53,7 @@ CouchDB instance.
Content-Length: 4148
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:01:42 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"attachments": {
@@ -75,7 +75,7 @@ CouchDB instance.
"max_document_size": "4294967296",
"os_process_timeout": "5000",
"uri_file": "/var/lib/couchdb/couch.uri",
- "util_driver_dir": "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib",
+ "util_driver_dir": "/usr/lib64/couchdb/erlang/lib/couch-1.5.0/priv/lib",
"view_index_dir": "/var/lib/couchdb"
},
"daemons": {
@@ -188,7 +188,7 @@ CouchDB instance.
Content-Length: 444
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:10:40 GMT
- Server: CouchDB/1.4.0+build.c843cef (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"allow_jsonp": "false",
@@ -239,7 +239,7 @@ CouchDB instance.
Content-Length: 8
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:12:59 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"debug"
@@ -290,7 +290,7 @@ CouchDB instance.
Content-Length: 8
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:12:59 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"debug"
@@ -327,6 +327,6 @@ CouchDB instance.
Content-Length: 7
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:29:03 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"info"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 279e124..85d0dbb 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -54,7 +54,7 @@ supports querying, deleting or creating new admin accounts:
Content-Length: 196
Content-Type: application/json
Date: Fri, 30 Nov 2012 11:37:18 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
.. code-block:: json
@@ -85,7 +85,7 @@ encrypt it.
Content-Length: 89
Content-Type: application/json
Date: Fri, 30 Nov 2012 11:39:18 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index c1bd182..d42e5b8 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -196,7 +196,7 @@ its contents should be readable for the user that runs the CouchDB service.
::
[couchdb]
- util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.3.0/priv/lib
+ util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
.. _config/couchdb/uuid:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/http.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index f225092..68981bf 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -368,7 +368,7 @@ specify the ``-k`` option as the message reads:
.. code-block:: bash
shell> curl -k https://127.0.0.1:6984/
- {"couchdb":"Welcome","version":"1.3.0"}
+ {"couchdb":"Welcome","version":"1.5.0"}
All done.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index 235142d..079f2f4 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -218,4 +218,4 @@ message. This is returned when requesting ``GET /``.
[vendor]
name = The Apache Software Foundation
- version = 1.3.0
+ version = 1.5.0
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/externals.rst b/share/doc/src/externals.rst
index 9b4530f..9068e75 100644
--- a/share/doc/src/externals.rst
+++ b/share/doc/src/externals.rst
@@ -233,7 +233,7 @@ And then start CouchDB and try:
>
< HTTP/1.1 200
< Transfer-Encoding: chunked
- < Server: CouchDB/1.3.0 (Erlang OTP/R14B)
+ < Server: CouchDB (Erlang/OTP)
< Date: Mon, 27 Sep 2010 01:13:37 GMT
< Content-Type: text/plain
< Connection: keep-alive
@@ -244,7 +244,7 @@ And then start CouchDB and try:
The corresponding CouchDB logs look like::
- Apache CouchDB 1.3.0 (LogLevel=info) is starting.
+ Apache CouchDB 1.5.0 (LogLevel=info) is starting.
Apache CouchDB has started. Time to relax.
[info] [<0.31.0>] Apache CouchDB has started on http://127.0.0.1:5984/
[info] [<0.105.0>] 127.0.0.1 - - 'GET' /_hello 200
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/api.rst b/share/doc/src/intro/api.rst
index f617df0..9779ea9 100644
--- a/share/doc/src/intro/api.rst
+++ b/share/doc/src/intro/api.rst
@@ -62,9 +62,9 @@ CouchDB replies, all excited to get going:
"uuid": "85fb71bf700c17267fef77535820e371",
"vendor": {
"name": "The Apache Software Foundation",
- "version": "1.4.0"
+ "version": "1.5.0"
},
- "version": "1.4.0"
+ "version": "1.5.0"
}
You get back a JSON string, that, if parsed into a native object or data
@@ -136,7 +136,7 @@ curl elaborates::
> Accept: */*
>
< HTTP/1.1 201 Created
- < Server: CouchDB/0.9.0 (Erlang OTP/R12B)
+ < Server: CouchDB (Erlang/OTP)
< Date: Sun, 05 Jul 2009 22:48:28 GMT
< Content-Type: text/plain;charset=utf-8
< Content-Length: 12
@@ -242,7 +242,7 @@ code.
::
- < Server: CouchDB/0.10.1 (Erlang OTP/R13B)
+ < Server: CouchDB (Erlang/OTP)
The :header:`Server` header is good for diagnostics. It tells us which
CouchDB version and which underlying Erlang version we are talking to.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/maintenance/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/compaction.rst b/share/doc/src/maintenance/compaction.rst
index c2859bf..a24e008 100644
--- a/share/doc/src/maintenance/compaction.rst
+++ b/share/doc/src/maintenance/compaction.rst
@@ -58,7 +58,7 @@ On success, HTTP status :http:statuscode:`202` is returned immediately:
Content-Length: 12
Content-Type: text/plain; charset=utf-8
Date: Wed, 19 Jun 2013 09:43:52 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
.. code-block:: javascript
@@ -76,7 +76,7 @@ for the request. If you don't, you will be aware about with HTTP status
Content-Length: 78
Content-Type: application/json
Date: Wed, 19 Jun 2013 09:43:44 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
{"error":"bad_content_type","reason":"Content-Type must be application/json"}
@@ -92,7 +92,7 @@ information about it via :ref:`database information resource <api/db>`::
Content-Length: 246
Content-Type: application/json
Date: Wed, 19 Jun 2013 16:51:20 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
{
"committed_update_seq": 76215,
@@ -122,7 +122,7 @@ is actually running. To track the compaction progress you may query the
Content-Length: 175
Content-Type: application/json
Date: Wed, 19 Jun 2013 16:27:23 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
[
{
[05/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Better introduction into CouchDB.
Import articles from Guide to CouchDB:
- Why CouchDB?
- Eventual Consistency
- Getting Started
+ Technical Overview from Wiki
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/7c4a8c4e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/7c4a8c4e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/7c4a8c4e
Branch: refs/heads/replicator-redesign
Commit: 7c4a8c4e3975a1410f21f338caf12926f75f1639
Parents: 627806e
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Sep 2 00:53:46 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 50 ++-
share/doc/images/intro-consistency-01.png | Bin 0 -> 35605 bytes
share/doc/images/intro-consistency-02.png | Bin 0 -> 48145 bytes
share/doc/images/intro-consistency-03.png | Bin 0 -> 17333 bytes
share/doc/images/intro-consistency-04.png | Bin 0 -> 13744 bytes
share/doc/images/intro-consistency-05.png | Bin 0 -> 25592 bytes
share/doc/images/intro-consistency-06.png | Bin 0 -> 56651 bytes
share/doc/images/intro-consistency-07.png | Bin 0 -> 53634 bytes
share/doc/images/intro-tour-01.png | Bin 0 -> 56231 bytes
share/doc/images/intro-tour-02.png | Bin 0 -> 125209 bytes
share/doc/images/intro-tour-03.png | Bin 0 -> 62323 bytes
share/doc/images/intro-tour-04.png | Bin 0 -> 72533 bytes
share/doc/images/intro-tour-05.png | Bin 0 -> 73625 bytes
share/doc/images/intro-tour-06.png | Bin 0 -> 78923 bytes
share/doc/images/intro-tour-07.png | Bin 0 -> 121770 bytes
share/doc/images/intro-tour-08.png | Bin 0 -> 130063 bytes
share/doc/images/intro-tour-09.png | Bin 0 -> 131956 bytes
share/doc/images/intro-tour-10.png | Bin 0 -> 88116 bytes
share/doc/images/intro-why-01.png | Bin 0 -> 25755 bytes
share/doc/images/intro-why-02.png | Bin 0 -> 5937 bytes
share/doc/images/intro-why-03.png | Bin 0 -> 5134 bytes
share/doc/src/couchapp/index.rst | 2 +
share/doc/src/index.rst | 15 +-
share/doc/src/intro.rst | 315 ---------------
share/doc/src/intro/consistency.rst | 465 +++++++++++++++++++++
share/doc/src/intro/curl.rst | 122 ++++++
share/doc/src/intro/futon.rst | 186 +++++++++
share/doc/src/intro/index.rst | 50 +++
share/doc/src/intro/overview.rst | 387 ++++++++++++++++++
share/doc/src/intro/tour.rst | 534 +++++++++++++++++++++++++
share/doc/src/intro/why.rst | 315 +++++++++++++++
31 files changed, 2110 insertions(+), 331 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 188714c..dcc1150 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -109,6 +109,13 @@ html_files = \
html/_sources/install/mac.txt \
html/_sources/install/unix.txt \
html/_sources/install/windows.txt \
+ html/_sources/intro/consistency.txt \
+ html/_sources/intro/curl.txt \
+ html/_sources/intro/futon.txt \
+ html/_sources/intro/index.txt \
+ html/_sources/intro/overview.txt \
+ html/_sources/intro/tour.txt \
+ html/_sources/intro/why.txt \
html/_sources/query-server/index.txt \
html/_sources/query-server/erlang.txt \
html/_sources/query-server/javascript.txt \
@@ -131,7 +138,6 @@ html_files = \
html/_sources/contributing.txt \
html/_sources/externals.txt \
html/_sources/index.txt \
- html/_sources/intro.txt \
html/_sources/json-structure.txt \
html/_static/ajax-loader.gif \
html/_static/basic.css \
@@ -216,6 +222,13 @@ html_files = \
html/install/mac.html \
html/install/unix.html \
html/install/windows.html \
+ html/intro/consistency.html \
+ html/intro/curl.html \
+ html/intro/futon.html \
+ html/intro/index.html \
+ html/intro/overview.html \
+ html/intro/tour.html \
+ html/intro/why.html \
html/query-server/index.html \
html/query-server/erlang.html \
html/query-server/javascript.html \
@@ -237,7 +250,6 @@ html_files = \
html/whatsnew/index.html \
html/externals.html \
html/index.html \
- html/intro.html \
html/json-structure.html \
html/objects.inv \
html/genindex.html \
@@ -258,7 +270,31 @@ image_files = \
../images/futon-editeddoc.png \
../images/futon-overview.png \
../images/futon-replform.png \
- ../images/logo.png
+ ../images/intro-consistency-01.png \
+ ../images/intro-consistency-02.png \
+ ../images/intro-consistency-03.png \
+ ../images/intro-consistency-04.png \
+ ../images/intro-consistency-05.png \
+ ../images/intro-consistency-06.png \
+ ../images/intro-consistency-07.png \
+ ../images/intro-tour-01.png \
+ ../images/intro-tour-02.png \
+ ../images/intro-tour-03.png \
+ ../images/intro-tour-04.png \
+ ../images/intro-tour-05.png \
+ ../images/intro-tour-06.png \
+ ../images/intro-tour-07.png \
+ ../images/intro-tour-08.png \
+ ../images/intro-tour-09.png \
+ ../images/intro-tour-10.png \
+ ../images/intro-why-01.png \
+ ../images/intro-why-02.png \
+ ../images/intro-why-03.png \
+ ../images/logo.png \
+ ../images/views-intro-01.png \
+ ../images/views-intro-02.png \
+ ../images/views-intro-03.png \
+ ../images/views-intro-04.png
src_files = \
../src/api/basics.rst \
@@ -321,6 +357,13 @@ src_files = \
../src/install/mac.rst \
../src/install/unix.rst \
../src/install/windows.rst \
+ ../src/intro/consistency.rst \
+ ../src/intro/curl.rst \
+ ../src/intro/futon.rst \
+ ../src/intro/index.rst \
+ ../src/intro/overview.rst \
+ ../src/intro/tour.rst \
+ ../src/intro/why.rst \
../src/query-server/index.rst \
../src/query-server/erlang.rst \
../src/query-server/javascript.rst \
@@ -343,7 +386,6 @@ src_files = \
../src/contributing.rst \
../src/externals.rst \
../src/index.rst \
- ../src/intro.rst \
../src/json-structure.rst \
../src/conf.py
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-01.png b/share/doc/images/intro-consistency-01.png
new file mode 100644
index 0000000..9ae6912
Binary files /dev/null and b/share/doc/images/intro-consistency-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-02.png b/share/doc/images/intro-consistency-02.png
new file mode 100644
index 0000000..06c23ea
Binary files /dev/null and b/share/doc/images/intro-consistency-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-03.png b/share/doc/images/intro-consistency-03.png
new file mode 100644
index 0000000..2164c6c
Binary files /dev/null and b/share/doc/images/intro-consistency-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-04.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-04.png b/share/doc/images/intro-consistency-04.png
new file mode 100644
index 0000000..068fa77
Binary files /dev/null and b/share/doc/images/intro-consistency-04.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-05.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-05.png b/share/doc/images/intro-consistency-05.png
new file mode 100644
index 0000000..a94f9c3
Binary files /dev/null and b/share/doc/images/intro-consistency-05.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-06.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-06.png b/share/doc/images/intro-consistency-06.png
new file mode 100644
index 0000000..af316d4
Binary files /dev/null and b/share/doc/images/intro-consistency-06.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-07.png b/share/doc/images/intro-consistency-07.png
new file mode 100644
index 0000000..7fb5027
Binary files /dev/null and b/share/doc/images/intro-consistency-07.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-01.png b/share/doc/images/intro-tour-01.png
new file mode 100644
index 0000000..41b6420
Binary files /dev/null and b/share/doc/images/intro-tour-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-02.png b/share/doc/images/intro-tour-02.png
new file mode 100644
index 0000000..f263664
Binary files /dev/null and b/share/doc/images/intro-tour-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-03.png b/share/doc/images/intro-tour-03.png
new file mode 100644
index 0000000..47f013b
Binary files /dev/null and b/share/doc/images/intro-tour-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-04.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-04.png b/share/doc/images/intro-tour-04.png
new file mode 100644
index 0000000..33ceccc
Binary files /dev/null and b/share/doc/images/intro-tour-04.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-05.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-05.png b/share/doc/images/intro-tour-05.png
new file mode 100644
index 0000000..08042d7
Binary files /dev/null and b/share/doc/images/intro-tour-05.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-06.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-06.png b/share/doc/images/intro-tour-06.png
new file mode 100644
index 0000000..bb9c7c8
Binary files /dev/null and b/share/doc/images/intro-tour-06.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-07.png b/share/doc/images/intro-tour-07.png
new file mode 100644
index 0000000..dc009a8
Binary files /dev/null and b/share/doc/images/intro-tour-07.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-08.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-08.png b/share/doc/images/intro-tour-08.png
new file mode 100644
index 0000000..6976f57
Binary files /dev/null and b/share/doc/images/intro-tour-08.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-09.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-09.png b/share/doc/images/intro-tour-09.png
new file mode 100644
index 0000000..f41b306
Binary files /dev/null and b/share/doc/images/intro-tour-09.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-10.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-10.png b/share/doc/images/intro-tour-10.png
new file mode 100644
index 0000000..e95bc66
Binary files /dev/null and b/share/doc/images/intro-tour-10.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-why-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-why-01.png b/share/doc/images/intro-why-01.png
new file mode 100644
index 0000000..c927450
Binary files /dev/null and b/share/doc/images/intro-why-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-why-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-why-02.png b/share/doc/images/intro-why-02.png
new file mode 100644
index 0000000..a5bb4ce
Binary files /dev/null and b/share/doc/images/intro-why-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-why-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-why-03.png b/share/doc/images/intro-why-03.png
new file mode 100644
index 0000000..1f5e536
Binary files /dev/null and b/share/doc/images/intro-why-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/couchapp/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/index.rst b/share/doc/src/couchapp/index.rst
index d01b91e..0985d49 100644
--- a/share/doc/src/couchapp/index.rst
+++ b/share/doc/src/couchapp/index.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. _couchapp:
+
========
CouchApp
========
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index 047088e..c41cc9f 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -10,24 +10,15 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-Introduction
-============
-|Apache CouchDB(TM)|_ is a document database built for the web.
+|Apache CouchDB(TM)|_ |release| Documentation
+=============================================
-If you would like to help document the project, please send a note to the
-`developer mailing list <http://couchdb.apache.org/#mailing-list>`_.
-
-This is a work in progress.
-
-Contents
-========
-
.. toctree::
:maxdepth: 3
:numbered:
- intro
+ intro/index
install/index
config/index
replication/index
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst
deleted file mode 100644
index 57eb235..0000000
--- a/share/doc/src/intro.rst
+++ /dev/null
@@ -1,315 +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.
-
-============
-Introduction
-============
-
-There are two interfaces to CouchDB, the built-in Futon web-based
-interface and the CouchDB API accessed through the HTTP REST interface.
-The former is the simplest way to view and monitor your CouchDB
-installation and perform a number of basic database and system
-operations. More information on using the Futon interface can be found
-in :ref:`using-futon`.
-
-The primary way to interact with the CouchDB API is to use a client
-library or other interface that provides access to the underlying
-functionality through your chosen language or platform. However, since
-the API is supported through HTTP REST, you can interact with your
-CouchDB with any solution that supports the HTTP protocol.
-
-There are a number of different tools that talk the HTTP protocol and
-allow you to set and configure the necessary information. One tool for
-this that allows for access from the command-line is ``curl``. See
-:ref:`using-curl`.
-
-.. _using-futon:
-
-Using Futon
-===========
-
-Futon is a native web-based interface built into CouchDB. It provides a
-basic interface to the majority of the functionality, including the
-ability to create, update, delete and view documents and views, provides
-access to the configuration parameters, and an interface for initiating
-replication.
-
-The default view is the Overview page which provides you with a list of
-the databases. The basic structure of the page is consistent regardless
-of the section you are in. The main panel on the left provides the main
-interface to the databases, configuration or replication systems. The
-side panel on the right provides navigation to the main areas of Futon
-interface:
-
-.. figure:: ../images/futon-overview.png
- :align: center
- :alt: Futon Overview
-
- Futon Overview
-
-The main sections are:
-
-- Overview
-
- The main overview page, which provides a list of the databases and
- provides the interface for querying the database and creating and
- updating documents. See :ref:`futon-management`.
-
-- Configuration
-
- An interface into the configuration of your CouchDB installation. The
- interface allows you to edit the different configurable parameters.
- For more details on configuration, see :ref:`config` section.
-
-- Replicator
-
- An interface to the replication system, enabling you to initiate
- replication between local and remote databases. See
- :ref:`futon-replication`.
-
-- Status
-
- Displays a list of the running background tasks on the server.
- Background tasks include view index building, compaction and
- replication. The Status page is an interface to the
- :ref:`Active Tasks <api/server/active_tasks>` API call.
-
-- Verify Installation
-
- The Verify Installation allows you to check whether all of the
- components of your CouchDB installation are correctly installed.
-
-- Test Suite
-
- The Test Suite section allows you to run the built-in test suite.
- This executes a number of test routines entirely within your browser
- to test the API and functionality of your CouchDB installation. If
- you select this page, you can run the tests by using the Run All
- button. This will execute all the tests, which may take some time.
-
-.. _futon-management:
-
-Managing Databases and Documents
---------------------------------
-
-You can manage databases and documents within Futon using the main
-Overview section of the Futon interface.
-
-To create a new database, click the Create Database ELLIPSIS button. You
-will be prompted for the database name, as shown in the figure below.
-
-.. figure:: ../images/futon-createdb.png
- :align: center
- :alt: Creating a Database
-
- Creating a Database
-
-Once you have created the database (or selected an existing one), you
-will be shown a list of the current documents. If you create a new
-document, or select an existing document, you will be presented with the
-edit document display.
-
-Editing documents within Futon requires selecting the document and then
-editing (and setting) the fields for the document individually before
-saving the document back into the database.
-
-For example, the figure below shows the editor for a single document, a
-newly created document with a single ID, the document ``_id`` field.
-
-.. figure:: ../images/futon-editdoc.png
- :align: center
- :alt: Editing a Document
-
- Editing a Document
-
-To add a field to the document:
-
-1. Click Add Field.
-
-2. In the fieldname box, enter the name of the field you want to create.
- For example, “company”.
-
-3. Click the green tick next to the field name to confirm the field name
- change.
-
-4. Double-click the corresponding Value cell.
-
-5. Enter a company name, for example “Example”.
-
-6. Click the green tick next to the field value to confirm the field
- value.
-
-7. The document is still not saved as this point. You must explicitly
- save the document by clicking the Save Document button at the top of
- the page. This will save the document, and then display the new
- document with the saved revision information (the ``_rev`` field).
-
- .. figure:: ../images/futon-editeddoc.png
- :align: center
- :alt: Edited Document
-
- Edited Document
-
-The same basic interface is used for all editing operations within Futon.
-You *must* remember to save the individual element (fieldname, value)
-using the green tick button, before then saving the document.
-
-.. _futon-replication:
-
-Configuring Replication
------------------------
-
-When you click the Replicator option within the Tools menu you are
-presented with the Replicator screen. This allows you to start
-replication between two databases by filling in or select the
-appropriate options within the form provided.
-
-.. figure:: ../images/futon-replform.png
- :align: center
- :alt: Replication Form
-
- Replication Form
-
-To start a replication process, either the select the local database or
-enter a remote database name into the corresponding areas of the form.
-Replication occurs from the database on the left to the database on the
-right.
-
-If you are specifying a remote database name, you must specify the full
-URL of the remote database (including the host, port number and database
-name). If the remote instance requires authentication, you can specify
-the username and password as part of the URL, for example
-``http://username:pass@remotehost:5984/demo``.
-
-To enable continuous replication, click the Continuous checkbox.
-
-To start the replication process, click the Replicate button. The
-replication process should start and will continue in the background. If
-the replication process will take a long time, you can monitor the
-status of the replication using the Status option under the Tools menu.
-
-Once replication has been completed, the page will show the information
-returned when the replication process completes by the API.
-
-The Replicator tool is an interface to the underlying replication API.
-For more information, see :ref:`api/server/replicate`. For more information on
-replication, see :ref:`replication`.
-
-.. _using-curl:
-
-Using ``curl``
-==============
-
-The ``curl`` utility is a command line tool available on Unix, Linux,
-Mac OS X and Windows and many other platforms. ``curl`` provides easy
-access to the HTTP protocol (among others) directly from the
-command-line and is therefore an ideal way of interacting with CouchDB
-over the HTTP REST API.
-
-For simple ``GET`` requests you can supply the URL of the request. For
-example, to get the database information:
-
-.. code-block:: bash
-
- shell> curl http://127.0.0.1:5984
-
-This returns the database information (formatted in the output below for
-clarity):
-
-.. code-block:: json
-
- {
- "couchdb": "Welcome",
- "uuid": "85fb71bf700c17267fef77535820e371",
- "vendor": {
- "name": "The Apache Software Foundation",
- "version": "1.4.0"
- },
- "version": "1.4.0"
- }
-
-
-.. note:: For some URLs, especially those that include special characters such
- as ampersand, exclamation mark, or question mark, you should quote
- the URL you are specifying on the command line. For example:
-
- .. code-block:: bash
-
- shell> curl 'http://couchdb:5984/_uuids?count=5'
-
-You can explicitly set the HTTP command using the ``-X`` command line
-option. For example, when creating a database, you set the name of the
-database in the URL you send using a PUT request:
-
-.. code-block:: bash
-
- shell> curl -X PUT http://127.0.0.1:5984/demo
- {"ok":true}
-
-But to obtain the database information you use a ``GET`` request (with
-the return information formatted for clarity):
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/demo
- {
- "compact_running" : false,
- "doc_count" : 0,
- "db_name" : "demo",
- "purge_seq" : 0,
- "committed_update_seq" : 0,
- "doc_del_count" : 0,
- "disk_format_version" : 5,
- "update_seq" : 0,
- "instance_start_time" : "1306421773496000",
- "disk_size" : 79
- }
-
-For certain operations, you must specify the content type of request,
-which you do by specifying the ``Content-Type`` header using the ``-H``
-command-line option:
-
-.. code-block:: bash
-
- shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids
-
-You can also submit 'payload' data, that is, data in the body of the
-HTTP request using the ``-d`` option. This is useful if you need to
-submit JSON structures, for example document data, as part of the
-request. For example, to submit a simple document to the ``demo``
-database:
-
-.. code-block:: bash
-
- shell> curl -H 'Content-Type: application/json' \
- -X POST http://127.0.0.1:5984/demo \
- -d '{"company": "Example, Inc."}'
- {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
- "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
-
-In the above example, the argument after the ``-d`` option is the JSON
-of the document we want to submit.
-
-The document can be accessed by using the automatically generated
-document ID that was returned:
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
- {"_id":"8843faaf0b831d364278331bc3001bd8",
- "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
- "company":"Example, Inc."}
-
-The API samples in the :ref:`api/basics` show the HTTP command, URL and any
-payload information that needs to be submitted (and the expected return
-value). All of these examples can be reproduced using ``curl`` with the
-command-line examples shown above.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/consistency.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/consistency.rst b/share/doc/src/intro/consistency.rst
new file mode 100644
index 0000000..d10040b
--- /dev/null
+++ b/share/doc/src/intro/consistency.rst
@@ -0,0 +1,465 @@
+.. 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.
+
+
+.. _intro/consistency:
+
+====================
+Eventual Consistency
+====================
+
+In the previous chapter, we saw that CouchDB's flexibility allows us to
+evolve our data as our applications grow and change. In this chapter,
+we'll explore how working "with the grain" of CouchDB promotes simplicity in
+our applications and helps us naturally build scalable, distributed systems.
+
+
+Working with the Grain
+======================
+
+A *distributed system* is a system that operates robustly over a wide network.
+A particular feature of network computing is that network links can
+potentially disappear, and there are plenty of strategies for managing this
+type of network segmentation. CouchDB differs from others by accepting
+eventual consistency, as opposed to putting absolute consistency ahead of raw
+availability, like `RDBMS`_ or `Paxos`_. What these systems have in common is
+an awareness that data acts differently when many people are accessing it
+simultaneously. Their approaches differ when it comes to which aspects of
+*consistency*, *availability*, or *partition* tolerance they prioritize.
+
+Engineering distributed systems is tricky. Many of the caveats and "gotchas"
+you will face over time aren't immediately obvious. We don't have all the
+solutions, and CouchDB isn't a panacea, but when you work with CouchDB's
+grain rather than against it, the path of least resistance leads you to
+naturally scalable applications.
+
+Of course, building a distributed system is only the beginning. A website
+with a database that is available only half the time is next to worthless.
+Unfortunately, the traditional relational database approach to consistency
+makes it very easy for application programmers to rely on global state,
+global clocks, and other high availability no-nos, without even realizing
+that they're doing so. Before examining how CouchDB promotes scalability,
+we'll look at the constraints faced by a distributed system. After we've seen
+the problems that arise when parts of your application can't rely on being
+in constant contact with each other, we'll see that CouchDB provides an
+intuitive and useful way for modeling applications around high availability.
+
+.. _RDBMS: http://en.wikipedia.org/wiki/Relational_database_management_system
+.. _Paxos: http://en.wikipedia.org/wiki/Paxos_%28computer_science%29
+
+
+.. _cap:
+
+The CAP Theorem
+===============
+
+The CAP theorem describes a few different strategies for distributing
+application logic across networks. CouchDB's solution uses replication to
+propagate application changes across participating nodes. This is a
+fundamentally different approach from consensus algorithms and relational
+databases, which operate at different intersections of consistency,
+availability, and partition tolerance.
+
+The CAP theorem, shown in :ref:`intro/consistency-01`,
+identifies three distinct concerns:
+
+- **Consistency**:
+ All database clients see the same data, even with concurrent updates.
+- **Availability**:
+ All database clients are able to access some version of the data.
+- **Partition tolerance**:
+ The database can be split over multiple servers.
+
+Pick two.
+
+.. _intro/consistency-01:
+
+.. figure:: ../../images/intro-consistency-01.png
+ :align: center
+ :alt: The CAP theorem
+
+ Figure 1. The CAP theorem
+
+When a system grows large enough that a single database node is unable to
+handle the load placed on it, a sensible solution is to add more servers.
+When we add nodes, we have to start thinking about how to partition data
+between them. Do we have a few databases that share exactly the same data?
+Do we put different sets of data on different database servers?
+Do we let only certain database servers write data and let others handle
+the reads?
+
+Regardless of which approach we take, the one problem we'll keep bumping into
+is that of keeping all these database servers in sync. If you write some
+information to one node, how are you going to make sure that a read request
+to another database server reflects this newest information? These events
+might be milliseconds apart. Even with a modest collection of database
+servers, this problem can become extremely complex.
+
+When it's absolutely critical that all clients see a consistent view of the
+database, the users of one node will have to wait for any other nodes to come
+into agreement before being able to read or write to the database.
+In this instance, we see that availability takes a backseat to consistency.
+However, there are situations where availability trumps consistency:
+
+ Each node in a system should be able to make decisions purely based on
+ local state. If you need to do something under high load with failures
+ occurring and you need to reach agreement, you're lost. If you're
+ concerned about scalability, any algorithm that forces you to run
+ agreement will eventually become your bottleneck. Take that as a given.
+
+ -- Werner Vogels, Amazon CTO and Vice President
+
+If availability is a priority, we can let clients write data to one node of
+the database without waiting for other nodes to come into agreement.
+If the database knows how to take care of reconciling these operations between
+nodes, we achieve a sort of "eventual consistency" in exchange for high
+availability. This is a surprisingly applicable trade-off for many applications.
+
+Unlike traditional relational databases, where each action performed is
+necessarily subject to database-wide consistency checks,
+CouchDB makes it really simple to build applications that sacrifice immediate
+consistency for the huge performance improvements that come with simple
+distribution.
+
+
+Local Consistency
+=================
+
+Before we attempt to understand how CouchDB operates in a cluster,
+it's important that we understand the inner workings of a single CouchDB node.
+The CouchDB API is designed to provide a convenient but thin wrapper around
+the database core. By taking a closer look at the structure of the database
+core, we'll have a better understanding of the API that surrounds it.
+
+
+The Key to Your Data
+--------------------
+
+At the heart of CouchDB is a powerful *B-tree* storage engine.
+A B-tree is a sorted data structure that allows for searches, insertions,
+and deletions in logarithmic time. As :ref:`intro/consistency-02`
+illustrates, CouchDB uses this B-tree storage engine for all internal data,
+documents, and views. If we understand one, we will understand them all.
+
+
+.. _intro/consistency-02:
+
+.. figure:: ../../images/intro-consistency-02.png
+ :align: center
+ :alt: Anatomy of a view request
+
+ Figure 2. Anatomy of a view request
+
+
+CouchDB uses MapReduce to compute the results of a view. MapReduce makes use
+of two functions, "map" and "reduce", which are applied to each document in
+isolation. Being able to isolate these operations means that view computation
+lends itself to parallel and incremental computation. More important,
+because these functions produce key/value pairs, CouchDB is able to insert
+them into the B-tree storage engine, sorted by key. Lookups by key,
+or key range, are extremely efficient operations with a B-tree,
+described in `big O` notation as ``O(log N)`` and ``O(log N + K)``,
+respectively.
+
+In CouchDB, we access documents and view results by key or key range.
+This is a direct mapping to the underlying operations performed on CouchDB's
+B-tree storage engine. Along with document inserts and updates,
+this direct mapping is the reason we describe CouchDB's API as being a thin
+wrapper around the database core.
+
+Being able to access results by key alone is a very important restriction
+because it allows us to make huge performance gains. As well as the massive
+speed improvements, we can partition our data over multiple nodes,
+without affecting our ability to query each node in isolation.
+`BigTable`_, `Hadoop`_, `SimpleDB`_, and `memcached`_ restrict object lookups
+by key for exactly these reasons.
+
+.. _BigTable: http://en.wikipedia.org/wiki/BigTable
+.. _Hadoop: http://hadoop.apache.org
+.. _SimpleDB: http://aws.amazon.com/simpledb/
+.. _memcached: http://memcached.org
+
+
+No Locking
+----------
+
+A table in a relational database is a single data structure. If you want to
+modify a table -- say, update a row -- the database system must ensure
+that nobody else is trying to update that row and that nobody can read from
+that row while it is being updated. The common way to handle this uses what's
+known as a lock. If multiple clients want to access a table, the first client
+gets the lock, making everybody else wait. When the first client's request is
+processed, the next client is given access while everybody else waits,
+and so on. This serial execution of requests, even when they arrived in
+parallel, wastes a significant amount of your server's processing power.
+Under high load, a relational database can spend more time figuring out who
+is allowed to do what, and in which order, than it does doing any actual work.
+
+.. note::
+ Modern relational databases avoid locks by implementing MVCC under
+ the hood, but hide it from the end user, requiring them to coordinate
+ concurrent changes of single rows or fields.
+
+Instead of locks, CouchDB uses `Multi-Version Concurrency Control` (MVCC) to
+manage concurrent access to the database. :ref:`intro/consistency-03`
+illustrates the differences between MVCC and traditional locking mechanisms.
+MVCC means that CouchDB can run at full speed, all the time,
+even under high load. Requests are run in parallel, making excellent use of
+every last drop of processing power your server has to offer.
+
+
+.. _intro/consistency-03:
+
+.. figure:: ../../images/intro-consistency-03.png
+ :align: center
+ :alt: MVCC means no locking
+
+ Figure 3. MVCC means no locking
+
+
+Documents in CouchDB are versioned, much like they would be in a regular
+version control system such as `Subversion`_. If you want to change
+a value in a document, you create an entire new version of that document
+and save it over the old one. After doing this, you end up with two versions
+of the same document, one old and one new.
+
+How does this offer an improvement over locks? Consider a set of requests
+wanting to access a document. The first request reads the document.
+While this is being processed, a second request changes the document.
+Since the second request includes a completely new version of the document,
+CouchDB can simply append it to the database without having to wait for the
+read request to finish.
+
+When a third request wants to read the same document, CouchDB will point it
+to the new version that has just been written. During this whole process,
+the first request could still be reading the original version.
+
+A read request will always see the most recent snapshot of your database at
+the time of the beginning of the request.
+
+.. _Subversion: http://subversion.apache.org/
+
+
+Validation
+==========
+
+As application developers, we have to think about what sort of input we
+should accept and what we should reject. The expressive power to do this type
+of validation over complex data within a traditional relational database
+leaves a lot to be desired. Fortunately, CouchDB provides a powerful way to
+perform per-document validation from within the database.
+
+CouchDB can validate documents using JavaScript functions similar to those
+used for MapReduce. Each time you try to modify a document,
+CouchDB will pass the validation function a copy of the existing document,
+a copy of the new document, and a collection of additional information,
+such as user authentication details. The validation function now has the
+opportunity to approve or deny the update.
+
+By working with the grain and letting CouchDB do this for us,
+we save ourselves a tremendous amount of CPU cycles that would otherwise have
+been spent serializing object graphs from SQL, converting them into domain
+objects, and using those objects to do application-level validation.
+
+
+Distributed Consistency
+=======================
+
+Maintaining consistency within a single database node is relatively easy for
+most databases. The real problems start to surface when you try to maintain
+consistency between multiple database servers. If a client makes a write
+operation on server `A`, how do we make sure that this is consistent with
+server `B`, or `C`, or `D`? For relational databases, this is a very complex
+problem with entire books devoted to its solution. You could use
+multi-master, master/slave, partitioning, sharding, write-through caches,
+and all sorts of other complex techniques.
+
+
+Incremental Replication
+=======================
+
+CouchDB's operations take place within the context of a single document.
+As CouchDB achieves eventual consistency between multiple databases by using
+incremental replication you no longer have to worry about your database
+servers being able to stay in constant communication. Incremental replication
+is a process where document changes are periodically copied between servers.
+We are able to build what's known as a *shared nothing* cluster of databases
+where each node is independent and self-sufficient, leaving no single point
+of contention across the system.
+
+Need to scale out your CouchDB database cluster? Just throw in another server.
+
+As illustrated in :ref:`intro/consistency-04`, with CouchDB's incremental
+replication, you can synchronize your data between any two databases however
+you like and whenever you like. After replication, each database is able
+to work independently.
+
+You could use this feature to synchronize database servers within a cluster
+or between data centers using a job scheduler such as cron,
+or you could use it to synchronize data with your laptop for offline work as
+you travel. Each database can be used in the usual fashion,
+and changes between databases can be synchronized later in both directions.
+
+
+.. _intro/consistency-04:
+
+.. figure:: ../../images/intro-consistency-04.png
+ :align: center
+ :alt: Incremental replication between CouchDB nodes
+
+ Figure 4. Incremental replication between CouchDB nodes
+
+
+What happens when you change the same document in two different databases and
+want to synchronize these with each other? CouchDB's replication system
+comes with automatic conflict detection and resolution. When CouchDB detects
+that a document has been changed in both databases, it flags this document
+as being in conflict, much like they would be in a regular version control
+system.
+
+This isn't as troublesome as it might first sound. When two versions of a
+document conflict during replication, the winning version is saved as the
+most recent version in the document's history. Instead of throwing the losing
+version away, as you might expect, CouchDB saves this as a previous version
+in the document's history, so that you can access it if you need to. This
+happens automatically and consistently, so both databases will make exactly
+the same choice.
+
+It is up to you to handle conflicts in a way that makes sense for your
+application. You can leave the chosen document versions in place,
+revert to the older version, or try to merge the two versions and save the
+result.
+
+
+Case Study
+==========
+
+Greg Borenstein, a friend and coworker, built a small library for converting
+Songbird playlists to JSON objects and decided to store these in CouchDB as
+part of a backup application. The completed software uses CouchDB's MVCC and
+document revisions to ensure that Songbird playlists are backed up robustly
+between nodes.
+
+.. note::
+ `Songbird`_ is a free software media player with an integrated web browser,
+ based on the Mozilla XULRunner platform. Songbird is available for Microsoft
+ Windows, Apple Mac OS X, Solaris, and Linux.
+
+ .. _Songbird: http://en.wikipedia.org/wiki/Songbird_%28software%29
+
+Let's examine the workflow of the Songbird backup application,
+first as a user backing up from a single computer, and then using Songbird to
+synchronize playlists between multiple computers. We'll see how document
+revisions turn what could have been a hairy problem into something that *just
+works*.
+
+The first time we use this backup application, we feed our playlists to the
+application and initiate a backup. Each playlist is converted to a JSON
+object and handed to a CouchDB database. As illustrated in
+:ref:`intro/consistency-05`, CouchDB hands back the document ID and
+revision of each playlist as it's saved to the database.
+
+
+.. _intro/consistency-05:
+
+.. figure:: ../../images/intro-consistency-05.png
+ :align: center
+ :alt: Backing up to a single database
+
+ Figure 5. Backing up to a single database
+
+
+After a few days, we find that our playlists have been updated and we want to
+back up our changes. After we have fed our playlists to the backup
+application, it fetches the latest versions from CouchDB,
+along with the corresponding document revisions. When the application hands
+back the new playlist document, CouchDB requires that the document revision
+is included in the request.
+
+CouchDB then makes sure that the document revision handed to it in the
+request matches the current revision held in the database. Because CouchDB
+updates the revision with every modification, if these two are out of sync it
+suggests that someone else has made changes to the document between the time
+we requested it from the database and the time we sent our updates. Making
+changes to a document after someone else has modified it without first
+inspecting those changes is usually a bad idea.
+
+Forcing clients to hand back the correct document revision is the heart of
+CouchDB's optimistic concurrency.
+
+We have a laptop we want to keep synchronized with our desktop computer.
+With all our playlists on our desktop, the first step is to
+"restore from backup" onto our laptop. This is the first time we've done this,
+so afterward our laptop should hold an exact replica of our desktop playlist
+collection.
+
+After editing our Argentine Tango playlist on our laptop to add a few new
+songs we've purchased, we want to save our changes. The backup application
+replaces the playlist document in our laptop CouchDB database and a new
+document revision is generated. A few days later, we remember our new songs
+and want to copy the playlist across to our desktop computer. As illustrated
+in :ref:`intro/consistency-06`, the backup application copies the new document
+and the new revision to the desktop CouchDB database. Both CouchDB databases
+now have the same document revision.
+
+
+.. _intro/consistency-06:
+
+.. figure:: ../../images/intro-consistency-06.png
+ :align: center
+ :alt: Synchronizing between two databases
+
+ Figure 6. Synchronizing between two databases
+
+
+Because CouchDB tracks document revisions, it ensures that updates like these
+will work only if they are based on current information. If we had made
+modifications to the playlist backups between synchronization,
+things wouldn't go as smoothly.
+
+We back up some changes on our laptop and forget to synchronize. A few days
+later, we're editing playlists on our desktop computer, make a backup,
+and want to synchronize this to our laptop. As illustrated in
+:ref:`intro/consistency-07`, when our backup application tries to replicate
+between the two databases, CouchDB sees that the changes being sent from our
+desktop computer are modifications of out-of-date documents and helpfully
+informs us that there has been a conflict.
+
+Recovering from this error is easy to accomplish from an application
+perspective. Just download CouchDB's version of the playlist and provide an
+opportunity to merge the changes or save local modifications into a new
+playlist.
+
+
+.. _intro/consistency-07:
+
+.. figure:: ../../images/intro-consistency-07.png
+ :align: center
+ :alt: Synchronization conflicts between two databases
+
+ Figure 7. Synchronization conflicts between two databases
+
+
+Wrapping Up
+===========
+
+CouchDB's design borrows heavily from web architecture and the lessons
+learned deploying massively distributed systems on that architecture.
+By understanding why this architecture works the way it does,
+and by learning to spot which parts of your application can be easily
+distributed and which parts cannot, you'll enhance your ability to design
+distributed and scalable applications, with CouchDB or without it.
+
+We've covered the main issues surrounding CouchDB's consistency model and
+hinted at some of the benefits to be had when you work *with* CouchDB and not
+against it. But enough theory -- let's get up and running and see what all the
+fuss is about!
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/curl.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/curl.rst b/share/doc/src/intro/curl.rst
new file mode 100644
index 0000000..06b62b5
--- /dev/null
+++ b/share/doc/src/intro/curl.rst
@@ -0,0 +1,122 @@
+.. 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.
+
+.. _intro/curl:
+
+==============================
+cURL: Your Command Line Friend
+==============================
+
+The ``curl`` utility is a command line tool available on Unix, Linux,
+Mac OS X and Windows and many other platforms. ``curl`` provides easy
+access to the HTTP protocol (among others) directly from the
+command-line and is therefore an ideal way of interacting with CouchDB
+over the HTTP REST API.
+
+For simple ``GET`` requests you can supply the URL of the request. For
+example, to get the database information:
+
+.. code-block:: bash
+
+ shell> curl http://127.0.0.1:5984
+
+This returns the database information (formatted in the output below for
+clarity):
+
+.. code-block:: json
+
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "vendor": {
+ "name": "The Apache Software Foundation",
+ "version": "1.4.0"
+ },
+ "version": "1.4.0"
+ }
+
+
+.. note:: For some URLs, especially those that include special characters such
+ as ampersand, exclamation mark, or question mark, you should quote
+ the URL you are specifying on the command line. For example:
+
+ .. code-block:: bash
+
+ shell> curl 'http://couchdb:5984/_uuids?count=5'
+
+You can explicitly set the HTTP command using the ``-X`` command line
+option. For example, when creating a database, you set the name of the
+database in the URL you send using a PUT request:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://127.0.0.1:5984/demo
+ {"ok":true}
+
+But to obtain the database information you use a ``GET`` request (with
+the return information formatted for clarity):
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/demo
+ {
+ "compact_running" : false,
+ "doc_count" : 0,
+ "db_name" : "demo",
+ "purge_seq" : 0,
+ "committed_update_seq" : 0,
+ "doc_del_count" : 0,
+ "disk_format_version" : 5,
+ "update_seq" : 0,
+ "instance_start_time" : "1306421773496000",
+ "disk_size" : 79
+ }
+
+For certain operations, you must specify the content type of request,
+which you do by specifying the ``Content-Type`` header using the ``-H``
+command-line option:
+
+.. code-block:: bash
+
+ shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids
+
+You can also submit 'payload' data, that is, data in the body of the
+HTTP request using the ``-d`` option. This is useful if you need to
+submit JSON structures, for example document data, as part of the
+request. For example, to submit a simple document to the ``demo``
+database:
+
+.. code-block:: bash
+
+ shell> curl -H 'Content-Type: application/json' \
+ -X POST http://127.0.0.1:5984/demo \
+ -d '{"company": "Example, Inc."}'
+ {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
+ "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
+
+In the above example, the argument after the ``-d`` option is the JSON
+of the document we want to submit.
+
+The document can be accessed by using the automatically generated
+document ID that was returned:
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
+ {"_id":"8843faaf0b831d364278331bc3001bd8",
+ "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
+ "company":"Example, Inc."}
+
+The API samples in the :ref:`api/basics` show the HTTP command, URL and any
+payload information that needs to be submitted (and the expected return
+value). All of these examples can be reproduced using ``curl`` with the
+command-line examples shown above.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/futon.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/futon.rst b/share/doc/src/intro/futon.rst
new file mode 100644
index 0000000..3f93f5e
--- /dev/null
+++ b/share/doc/src/intro/futon.rst
@@ -0,0 +1,186 @@
+.. 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.
+
+.. _intro/futon:
+
+===================================
+Futon: Web GUI Administration Panel
+===================================
+
+Futon is a native web-based interface built into CouchDB. It provides a
+basic interface to the majority of the functionality, including the
+ability to create, update, delete and view documents and views, provides
+access to the configuration parameters, and an interface for initiating
+replication.
+
+The default view is the Overview page which provides you with a list of
+the databases. The basic structure of the page is consistent regardless
+of the section you are in. The main panel on the left provides the main
+interface to the databases, configuration or replication systems. The
+side panel on the right provides navigation to the main areas of Futon
+interface:
+
+.. figure:: ../../images/futon-overview.png
+ :align: center
+ :alt: Futon Overview
+
+ Futon Overview
+
+The main sections are:
+
+- Overview
+
+ The main overview page, which provides a list of the databases and
+ provides the interface for querying the database and creating and
+ updating documents. See :ref:`futon-management`.
+
+- Configuration
+
+ An interface into the configuration of your CouchDB installation. The
+ interface allows you to edit the different configurable parameters.
+ For more details on configuration, see :ref:`config` section.
+
+- Replicator
+
+ An interface to the replication system, enabling you to initiate
+ replication between local and remote databases. See
+ :ref:`futon-replication`.
+
+- Status
+
+ Displays a list of the running background tasks on the server.
+ Background tasks include view index building, compaction and
+ replication. The Status page is an interface to the
+ :ref:`Active Tasks <api/server/active_tasks>` API call.
+
+- Verify Installation
+
+ The Verify Installation allows you to check whether all of the
+ components of your CouchDB installation are correctly installed.
+
+- Test Suite
+
+ The Test Suite section allows you to run the built-in test suite.
+ This executes a number of test routines entirely within your browser
+ to test the API and functionality of your CouchDB installation. If
+ you select this page, you can run the tests by using the Run All
+ button. This will execute all the tests, which may take some time.
+
+
+.. _futon-management:
+
+Managing Databases and Documents
+================================
+
+You can manage databases and documents within Futon using the main
+Overview section of the Futon interface.
+
+To create a new database, click the Create Database ELLIPSIS button. You
+will be prompted for the database name, as shown in the figure below.
+
+.. figure:: ../../images/futon-createdb.png
+ :align: center
+ :alt: Creating a Database
+
+ Creating a Database
+
+Once you have created the database (or selected an existing one), you
+will be shown a list of the current documents. If you create a new
+document, or select an existing document, you will be presented with the
+edit document display.
+
+Editing documents within Futon requires selecting the document and then
+editing (and setting) the fields for the document individually before
+saving the document back into the database.
+
+For example, the figure below shows the editor for a single document, a
+newly created document with a single ID, the document ``_id`` field.
+
+.. figure:: ../../images/futon-editdoc.png
+ :align: center
+ :alt: Editing a Document
+
+ Editing a Document
+
+To add a field to the document:
+
+1. Click Add Field.
+
+2. In the fieldname box, enter the name of the field you want to create.
+ For example, “company”.
+
+3. Click the green tick next to the field name to confirm the field name
+ change.
+
+4. Double-click the corresponding Value cell.
+
+5. Enter a company name, for example “Example”.
+
+6. Click the green tick next to the field value to confirm the field
+ value.
+
+7. The document is still not saved as this point. You must explicitly
+ save the document by clicking the Save Document button at the top of
+ the page. This will save the document, and then display the new
+ document with the saved revision information (the ``_rev`` field).
+
+ .. figure:: ../../images/futon-editeddoc.png
+ :align: center
+ :alt: Edited Document
+
+ Edited Document
+
+The same basic interface is used for all editing operations within Futon.
+You *must* remember to save the individual element (fieldname, value)
+using the green tick button, before then saving the document.
+
+
+.. _futon-replication:
+
+Configuring Replication
+=======================
+
+When you click the Replicator option within the Tools menu you are
+presented with the Replicator screen. This allows you to start
+replication between two databases by filling in or select the
+appropriate options within the form provided.
+
+.. figure:: ../../images/futon-replform.png
+ :align: center
+ :alt: Replication Form
+
+ Replication Form
+
+To start a replication process, either the select the local database or
+enter a remote database name into the corresponding areas of the form.
+Replication occurs from the database on the left to the database on the
+right.
+
+If you are specifying a remote database name, you must specify the full
+URL of the remote database (including the host, port number and database
+name). If the remote instance requires authentication, you can specify
+the username and password as part of the URL, for example
+``http://username:pass@remotehost:5984/demo``.
+
+To enable continuous replication, click the Continuous checkbox.
+
+To start the replication process, click the Replicate button. The
+replication process should start and will continue in the background. If
+the replication process will take a long time, you can monitor the
+status of the replication using the Status option under the Tools menu.
+
+Once replication has been completed, the page will show the information
+returned when the replication process completes by the API.
+
+The Replicator tool is an interface to the underlying replication API.
+For more information, see :ref:`api/server/replicate`. For more information on
+replication, see :ref:`replication`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/index.rst b/share/doc/src/intro/index.rst
new file mode 100644
index 0000000..900dca2
--- /dev/null
+++ b/share/doc/src/intro/index.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.
+
+
+.. _intro:
+
+============
+Introduction
+============
+
+CouchDB is a database that completely embraces the web. Store your data with
+JSON documents. Access your documents with your web browser, :ref:`via HTTP
+<api/basics>`. :ref:`Query <api/doc>`, :ref:`combine <views>`,
+and :ref:`transform <listfun>` your documents with :ref:`JavaScript
+<query-server/js>`. CouchDB works well with modern web and mobile apps. You can
+even serve web apps directly out of CouchDB. And you can distribute your data,
+or your apps, efficiently using CouchDB’s :ref:`incremental replication
+<replication/intro>`. CouchDB supports master-master setups with
+:ref:`automatic conflict <replication/conflicts>` detection.
+
+CouchDB comes with a suite of features, such as on-the-fly document
+transformation and real-time :ref:`change notifications <changes>`, that makes
+:ref:`web app <couchapp>` development a breeze. It even comes with an easy
+to use :ref:`web administration console <intro/futon>`. You guessed it,
+served up directly out of CouchDB! We care a lot about `distributed scaling`_.
+CouchDB is highly available and partition tolerant, but is also :ref:`eventually
+consistent <intro/consistency>`. And we care *a lot* about your data.
+CouchDB has a fault-tolerant storage engine that puts the safety of your data
+first.
+
+.. _distributed scaling: http://en.wikipedia.org/wiki/CAP_theorem
+
+.. toctree::
+ :maxdepth: 2
+
+ overview
+ why
+ consistency
+ tour
+ futon
+ curl
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/overview.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/overview.rst b/share/doc/src/intro/overview.rst
new file mode 100644
index 0000000..b36f8f1
--- /dev/null
+++ b/share/doc/src/intro/overview.rst
@@ -0,0 +1,387 @@
+.. 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.
+
+
+.. _intro/overview:
+
+==================
+Technical Overview
+==================
+
+Document Storage
+================
+
+A CouchDB server hosts named databases, which store **documents**.
+Each document is uniquely named in the database, and CouchDB provides
+a `RESTful`_ :ref:`HTTP API <api/basics>` for reading and updating (add, edit,
+delete) database documents.
+
+Documents are the primary unit of data in CouchDB and consist of any number
+of fields and attachments. Documents also include metadata that’s maintained
+by the database system. Document fields are uniquely named and contain values
+of :ref:`varying types <json>` (text, number, boolean, lists, etc),
+and there is no set limit to text size or element count.
+
+The CouchDB document update model is lockless and optimistic.
+Document edits are made by client applications loading documents,
+applying changes, and saving them back to the database. If another client
+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
+entirely or failing completely. The database never contains partially saved
+or edited documents.
+
+.. _RESTful: http://en.wikipedia.org/wiki/REST
+
+
+ACID Properties
+===============
+
+The CouchDB file layout and commitment system features all `Atomic Consistent
+Isolated Durable` (`ACID`_) properties. On-disk, CouchDB never overwrites
+committed data or associated structures, ensuring the database file is always
+in a consistent state. This is a "crash-only" design where the CouchDB
+server does not go through a shut down process, it's simply terminated.
+
+Document updates (add, edit, delete) are serialized, except for binary blobs
+which are written concurrently. Database readers are never locked out and
+never have to wait on writers or other readers. Any number of clients can be
+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.
+
+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.
+Sequence IDs are used later for incrementally finding changes in a database.
+TheseBb-tree indexes are updated simultaneously when documents are saved or
+deleted. The index updates always occur at the end of the file (append-only
+updates).
+
+Documents have the advantage of data being already conveniently packaged for
+storage rather than split out across numerous tables and rows in most
+databases systems. When documents are committed to disk, the document fields
+and metadata are packed into buffers, sequentially one document after another
+(helpful later for efficient building of views).
+
+When CouchDB documents are updated, all data and associated indexes are
+flushed to disk and the transactional commit always leaves the database
+in a completely consistent state. Commits occur in two steps:
+
+#. All document data and associated index updates are synchronously flushed
+ to disk.
+
+#. The updated database header is written in two consecutive, identical chunks
+ to make up the first 4k of the file, and then synchronously flushed to disk.
+
+In the event of an OS crash or power failure during step 1,
+the partially flushed updates are simply forgotten on restart. If such a
+crash happens during step 2 (committing the header), a surviving copy of the
+previous identical headers will remain, ensuring coherency of all previously
+committed data. Excepting the header area, consistency checks or fix-ups
+after a crash or a power failure are never necessary.
+
+.. _ACID: http://en.wikipedia.org/wiki/ACID
+.. _MVCC: http://en.wikipedia.org/wiki/Multiversion_concurrency_control
+.. _B-trees: http://en.wikipedia.org/wiki/B-tree
+
+
+Compaction
+==========
+
+Wasted space is recovered by occasional compaction. On schedule, or when the
+database file exceeds a certain amount of wasted space, the compaction process
+clones all the active data to a new file and then discards the old file.
+The database remains completely online the entire time and all updates and
+reads are allowed to complete successfully. The old file is deleted only when
+all the data has been copied and all users transitioned to the new file.
+
+
+Views
+=====
+
+ACID properties only deal with storage and updates, we also need the ability
+to show our data in interesting and useful ways. Unlike SQL databases where
+data must be carefully decomposed into tables, data in CouchDB is stored in
+semi-structured documents. CouchDB documents are flexible and each has its
+own implicit structure, which alleviates the most difficult problems and
+pitfalls of bi-directionally replicating table schemas and their contained data.
+
+But beyond acting as a fancy file server, a simple document model for data
+storage and sharing is too simple to build real applications on -- it simply
+doesn't do enough of the things we want and expect. We want to slice and dice
+and see our data in many different ways. What is needed is a way to filter,
+organize and report on data that hasn't been decomposed into tables.
+
+.. seealso::
+
+ :ref:`views`
+
+
+View Model
+----------
+
+To address this problem of adding structure back to unstructured and
+semi-structured data, CouchDB integrates a view model. Views are the method
+of aggregating and reporting on the documents in a database, and are built
+on-demand to aggregate, join and report on database documents. Views are built
+dynamically and don’t affect the underlying document, you can have as many
+different view representations of the same data as you like.
+
+View definitions are strictly virtual and only display the documents from the
+current database instance, making them separate from the data they display
+and compatible with replication. CouchDB views are defined inside special
+**design documents** and can replicate across database instances like
+regular documents, so that not only data replicates in CouchDB,
+but entire application designs replicate too.
+
+
+Javascript View Functions
+-------------------------
+
+Views are defined using Javascript functions acting as the map part in a
+`map-reduce system`_. A :ref:`view function <viewfun>` takes a CouchDB document
+as an argument and then does whatever computation it needs to do to determine
+the data that is to be made available through the view, if any.
+It can add multiple rows to the view based on a single document,
+or it can add no rows at all.
+
+.. _map-reduce system: http://en.wikipedia.org/wiki/MapReduce
+
+.. seealso::
+
+ :ref:`viewfun`
+
+
+View Indexes
+------------
+
+Views are a dynamic representation of the actual document contents of a
+database, and CouchDB makes it easy to create useful views of data.
+But generating a view of a database with hundreds of thousands or millions of
+documents is time and resource consuming, it's not something the system
+should do from scratch each time.
+
+To keep view querying fast, the view engine maintains indexes of its views,
+and incrementally updates them to reflect changes in the database.
+CouchDB’s core design is largely optimized around the need for efficient,
+incremental creation of views and their indexes.
+
+Views and their functions are defined inside special "design" documents,
+and a design document may contain any number of uniquely named view functions.
+When a user opens a view and its index is automatically updated, all the views
+in the same design document are indexed as a single group.
+
+The view builder uses the database sequence ID to determine if the view group
+is fully up-to-date with the database. If not, the view engine examines the
+all database documents (in packed sequential order) changed since the last
+refresh. Documents are read in the order they occur in the disk file,
+reducing the frequency and cost of disk head seeks.
+
+The views can be read and queried simultaneously while also being refreshed.
+If a client is slowly streaming out the contents of a large view,
+the same view can be concurrently opened and refreshed for another client
+without blocking the first client. This is true for any number of
+simultaneous client readers, who can read and query the view while the index
+is concurrently being refreshed for other clients without causing problems
+for the readers.
+
+As documents are examined, their previous row values are removed from the
+view indexes, if they exist. If the document is selected by a view function,
+the function results are inserted into the view as a new row.
+
+When view index changes are written to disk, the updates are always appended
+at the end of the file, serving to both reduce disk head seek times during
+disk commits and to ensure crashes and power failures can not cause
+corruption of indexes. If a crash occurs while updating a view index,
+the incomplete index updates are simply lost and rebuilt incrementally from
+its previously committed state.
+
+
+Security and Validation
+=======================
+
+To protect who can read and update documents, CouchDB has a simple reader
+access and update validation model that can be extended to implement custom
+security models.
+
+.. seealso::
+
+ :ref:`api/db/security`
+
+
+Administrator Access
+--------------------
+
+CouchDB database instances have administrator accounts. Administrator
+accounts can create other administrator accounts and update design documents.
+Design documents are special documents containing view definitions and other
+special formulas, as well as regular fields and blobs.
+
+
+Update Validation
+-----------------
+
+As documents written to disk, they can be validated dynamically by javascript
+functions for both security and data validation. When the document passes
+all the formula validation criteria, the update is allowed to continue.
+If the validation fails, the update is aborted and the user client gets an
+error response.
+
+Both the user's credentials and the updated document are given as inputs to
+the validation formula, and can be used to implement custom security models
+by validating a user's permissions to update a document.
+
+A basic "author only" update document model is trivial to implement,
+where document updates are validated to check if the user is listed in an
+"author" field in the existing document. More dynamic models are also possible,
+like checking a separate user account profile for permission settings.
+
+The update validations are enforced for both live usage and replicated
+updates, ensuring security and data validation in a shared, distributed system.
+
+.. seealso::
+
+ :ref:`vdufun`
+
+
+Distributed Updates and Replication
+===================================
+
+CouchDB is a peer-based distributed database system, it allows for users and
+servers to access and update the same shared data while disconnected and then
+bi-directionally replicate those changes later.
+
+The CouchDB document storage, view and security models are designed to work
+together to make true bi-directional replication efficient and reliable.
+Both documents and designs can replicate, allowing full database applications
+(including application design, logic and data) to be replicated to laptops
+for offline use, or replicated to servers in remote offices where slow or
+unreliable connections make sharing data difficult.
+
+The replication process is incremental. At the database level,
+replication only examines documents updated since the last replication.
+Then for each updated document, only fields and blobs that have changed are
+replicated across the network. If replication fails at any step, due to network
+problems or crash for example, the next replication restarts at the same
+document where it left off.
+
+Partial replicas can be created and maintained. Replication can be filtered
+by a javascript function, so that only particular documents or those meeting
+specific criteria are replicated. This can allow users to take subsets of a
+large shared database application offline for their own use, while maintaining
+normal interaction with the application and that subset of data.
+
+
+Conflicts
+---------
+
+Conflict detection and management are key issues for any distributed edit
+system. The CouchDB storage system treats edit conflicts as a common state,
+not an exceptional one. The conflict handling model is simple and
+"non-destructive" while preserving single document semantics and allowing for
+decentralized conflict resolution.
+
+CouchDB allows for any number of conflicting documents to exist
+simultaneously in the database, with each database instance deterministically
+deciding which document is the "winner" and which are conflicts. Only the
+winning document can appear in views, while "losing" conflicts are still
+accessible and remain in the database until deleted or purged during
+database compaction. Because conflict documents are still regular documents,
+they replicate just like regular documents and are subject to the same
+security and validation rules.
+
+When distributed edit conflicts occur, every database replica sees the same
+winning revision and each has the opportunity to resolve the conflict.
+Resolving conflicts can be done manually or, depending on the nature of the
+data and the conflict, by automated agents. The system makes decentralized
+conflict resolution possible while maintaining single document database
+semantics.
+
+Conflict management continues to work even if multiple disconnected users or
+agents attempt to resolve the same conflicts. If resolved conflicts result in
+more conflicts, the system accommodates them in the same manner, determining
+the same winner on each machine and maintaining single document semantics.
+
+.. seealso::
+
+ :ref:`replication/conflicts`
+
+
+Applications
+------------
+
+Using just the basic replication model, many traditionally single server
+database applications can be made distributed with almost no extra work.
+CouchDB replication is designed to be immediately useful for basic database
+applications, while also being extendable for more elaborate and full-featured
+uses.
+
+With very little database work, it is possible to build a distributed
+document management application with granular security and full revision
+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
+==============
+
+CouchDB is built on the `Erlang OTP platform`_, a functional,
+concurrent programming language and development platform. Erlang was
+developed for real-time telecom applications with an extreme emphasis on
+reliability and availability.
+
+Both in syntax and semantics, Erlang is very different from conventional
+programming languages like C or Java. Erlang uses lightweight "processes" and
+message passing for concurrency, it has no shared state threading and all
+data is immutable. The robust, concurrent nature of Erlang is ideal for a
+database server.
+
+CouchDB is designed for lock-free concurrency, in the conceptual model and
+the actual Erlang implementation. Reducing bottlenecks and avoiding locks
+keeps the entire system working predictably under heavy loads. CouchDB can
+accommodate many clients replicating changes, opening and updating documents,
+and querying views whose indexes are simultaneously being refreshed for
+other clients, without needing locks.
+
+For higher availability and more concurrent users, CouchDB is designed for
+"shared nothing" clustering. In a "shared nothing" cluster, each machine
+is independent and replicates data with its cluster mates, allowing individual
+server failures with zero downtime. And because consistency scans
+and fix-ups aren’t needed on restart,
+if the entire cluster fails -- due to a power outage in a datacenter,
+for example -- the entire CouchDB distributed system becomes immediately
+available after a restart.
+
+CouchDB is built from the start with a consistent vision of a distributed
+document database system. Unlike cumbersome attempts to bolt distributed
+features on top of the same legacy models and databases,
+it is the result of careful ground-up design, engineering and integration.
+The document, view, security and replication models, the special purpose query
+language, the efficient and robust disk layout and the concurrent and reliable
+nature of the Erlang platform are all carefully integrated for a reliable
+and efficient system.
+
+.. _Erlang OTP platform: http://www.erlang.org/
[47/50] [abbrv] git commit: updated refs/heads/replicator-redesign to
066d69b
Posted by de...@apache.org.
Fix license check.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/b1440504
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/b1440504
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/b1440504
Branch: refs/heads/replicator-redesign
Commit: b14405041b87867878cd1088bfcca41f3b72f3c6
Parents: 17e0b7c
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 17:35:39 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 17:35:39 2013 +0400
----------------------------------------------------------------------
license.skip | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b1440504/license.skip
----------------------------------------------------------------------
diff --git a/license.skip b/license.skip
index 08c4864..914253b 100644
--- a/license.skip
+++ b/license.skip
@@ -60,7 +60,7 @@
^share/doc/Makefile.in
^share/doc/build/.*
^share/doc/ext/__pycache__/.*
-^share/doc/ext/*.pyc
+^share/doc/ext/.*.pyc
^share/doc/ext/httpdomain.py
^share/doc/ext/http-api-descr.json
^share/doc/images/.*