You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2015/02/20 01:26:41 UTC
[08/26] documentation commit: updated refs/heads/master to 5a81ace
src/intro now follows the style
Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/daf7fc5f
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/daf7fc5f
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/daf7fc5f
Branch: refs/heads/master
Commit: daf7fc5ff04574f591d05017e9ecf83367677014
Parents: b4c41dd
Author: Maria Andersson <ma...@dualpose.com>
Authored: Fri Feb 6 22:20:12 2015 +0100
Committer: Maria Andersson <ma...@dualpose.com>
Committed: Fri Feb 6 22:20:12 2015 +0100
----------------------------------------------------------------------
src/intro/api.rst | 452 ++++++++++++++++++-----------------------
src/intro/consistency.rst | 84 +++-----
src/intro/curl.rst | 85 ++++----
src/intro/futon.rst | 118 +++++------
src/intro/index.rst | 21 +-
src/intro/overview.rst | 31 +--
src/intro/security.rst | 255 +++++++++++------------
src/intro/tour.rst | 275 ++++++++++++-------------
src/intro/why.rst | 51 ++---
9 files changed, 605 insertions(+), 767 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/daf7fc5f/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/src/intro/api.rst b/src/intro/api.rst
index 83458a0..7472ecf 100644
--- a/src/intro/api.rst
+++ b/src/intro/api.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _intro/api:
============
@@ -38,9 +37,8 @@ The API can be subdivided into the following sections. We'll explore them
individually:
.. contents::
- :depth: 1
- :local:
-
+ :depth: 1
+ :local:
Server
======
@@ -56,15 +54,15 @@ CouchDB replies, all excited to get going:
.. code-block:: javascript
- {
- "couchdb": "Welcome",
- "uuid": "85fb71bf700c17267fef77535820e371",
- "vendor": {
- "name": "The Apache Software Foundation",
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "vendor": {
+ "name": "The Apache Software Foundation",
+ "version": "1.5.0"
+ },
"version": "1.5.0"
- },
- "version": "1.5.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
@@ -76,7 +74,6 @@ response as a result.
.. _curl: http://curl.haxx.se/
-
Databases
=========
@@ -94,25 +91,25 @@ 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
+ curl -X PUT http://127.0.0.1:5984/albums
CouchDB replies:
.. code-block:: javascript
- {"ok":true}
+ {"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
+ 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."}
+ {"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.
@@ -122,56 +119,50 @@ 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 -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 (Erlang/OTP)
- < 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
+ * 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 (Erlang/OTP)
+ < 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.
-
-::
+times, you'll be able to spot the important bits more easily. ::
- * About to connect() to 127.0.0.1 port 5984 (#0)
+ * 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.
+except when debugging networking issues. ::
-::
-
- * Trying 127.0.0.1... connected
- * Connected to 127.0.0.1 (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)
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.
-
-::
+``>``). The ``<`` means the line was sent back to curl by CouchDB. ::
- > PUT /albums-backup HTTP/1.1
+ > 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
@@ -179,11 +170,9 @@ This initiates an HTTP request. Its *method* is :method:`PUT`, the *URI* is
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.
-
-::
+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
+ > 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
@@ -191,34 +180,26 @@ 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.
+:header:`User-Agent` header is irrelevant. ::
-::
-
- > Host: 127.0.0.1:5984
+ > 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.
-
-::
+the hostname that came with the request. ::
- > Accept: */*
+ > Accept: */*
The :header:`Accept` header tells CouchDB that curl accepts any media type.
-We'll look into why this is useful a little later.
+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.
-
-::
+the HTTP response. ::
- < HTTP/1.1 201 Created
+ < 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
@@ -237,29 +218,23 @@ 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.
-
-::
+code. ::
- < Server: CouchDB (Erlang/OTP)
+ < 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.
In general, you can ignore this header, but it is good to know it's there if
-you need it.
+you need it. ::
-::
-
- < Date: Sun, 05 Jul 2009 22:48:28 GMT
+ < 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!
-
-::
+of this! ::
- < Content-Type: text/plain;charset=utf-8
+ < 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
@@ -273,50 +248,41 @@ 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.
- 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/
+ .. _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`.
-
-::
+use it instead of :mimetype:`text/plain`. ::
- < Content-Length: 12
+ < Content-Length: 12
The :header:`Content-Length` header simply tells us how many bytes
-the response body has.
-
-::
+the response body has. ::
- < Cache-Control: must-revalidate
+ < Cache-Control: must-revalidate
This :header:`Cache-Control` header tells you, or any proxy server between
-CouchDB and you, not to cache this response.
+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.
+ {"ok":true}
-::
+We've seen this before. ::
- * Connection #0 to host 127.0.0.1 left intact
- * Closing connection #0
+ * 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
@@ -329,7 +295,7 @@ 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
+ > 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
@@ -340,7 +306,6 @@ 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
=========
@@ -365,13 +330,13 @@ 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"}'
+ 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"}
+ {"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.
@@ -385,26 +350,25 @@ 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::
- 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
+ curl -X GET http://127.0.0.1:5984/_uuids
- CouchDB replies:
+ CouchDB replies:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"uuids":["6e1295ed6c29495e54cc05947f18c8af"]}
+ {"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.
+ 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
+ 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.
@@ -413,7 +377,7 @@ CouchDB replies:
.. code-block:: javascript
- {"_id":"6e1295ed6c29495e54cc05947f18c8af","_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters"}
+ {"_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.
@@ -442,27 +406,27 @@ 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"}'
+ 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."}
+ {"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"}'
+ 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"}
+ {"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
@@ -499,13 +463,12 @@ The revision system also has positive effects on replication and storage
mechanisms, but we'll explore these later in the documents.
.. warning::
-
- The terms *version* and *revision* might sound familiar (if you are
- programming without version control, stop reading this guide 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**.
-
+ The terms *version* and *revision* might sound familiar (if you are
+ programming without version control, stop reading this guide 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
-------------------
@@ -517,31 +480,28 @@ 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.
-
-::
+a few pages back. ::
- curl -vX PUT http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 \
- -d '{"title":"Blackened Sky","artist":"Biffy Clyro","year":2002}'
+ 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.
+ 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"}
+ > 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`
@@ -553,7 +513,6 @@ 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
-----------
@@ -569,46 +528,45 @@ 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"
+ 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.
+ 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
+ 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
+ {
+ "_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
@@ -621,7 +579,6 @@ attachment data.
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
===========
@@ -636,51 +593,50 @@ In a simple :method:`POST` request, you tell CouchDB the *source* and the
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 in the document :ref:`replication/intro`;
-in this document, we'll just show you how to use it.
+We'll take an in-depth look at replication in the document
+:ref:`replication/intro`; in this document, 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
+ 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"
+ 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 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
- }
+ {
+ "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*.
@@ -708,18 +664,17 @@ 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"
+ 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.
+ 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.
@@ -728,43 +683,41 @@ 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"
+ 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"
+ 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 documents.
-
- 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
-
+ **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 documents.
+
+ 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
===========
@@ -774,10 +727,9 @@ 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:`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>`
+ - :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-documentation/blob/daf7fc5f/src/intro/consistency.rst
----------------------------------------------------------------------
diff --git a/src/intro/consistency.rst b/src/intro/consistency.rst
index c104ded..6d7f06c 100644
--- a/src/intro/consistency.rst
+++ b/src/intro/consistency.rst
@@ -10,19 +10,17 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _intro/consistency:
====================
Eventual Consistency
====================
-In the previous document :ref:`intro/why`, we saw that CouchDB's flexibility allows us to
-evolve our data as our applications grow and change. In this topic,
+In the previous document :ref:`intro/why`, we saw that CouchDB's flexibility
+allows us to evolve our data as our applications grow and change. In this topic,
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
======================
@@ -56,7 +54,6 @@ 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
@@ -84,10 +81,10 @@ Pick two.
.. _intro/consistency-01:
.. figure:: ../../images/intro-consistency-01.png
- :align: center
- :alt: The CAP theorem
+ :align: center
+ :alt: The CAP theorem
- Figure 1. 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.
@@ -116,7 +113,7 @@ However, there are situations where availability trumps consistency:
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
+ -- 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.
@@ -130,7 +127,6 @@ CouchDB makes it really simple to build applications that sacrifice immediate
consistency for the huge performance improvements that come with simple
distribution.
-
Local Consistency
=================
@@ -140,7 +136,6 @@ 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
--------------------
@@ -150,15 +145,13 @@ 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
+ :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
@@ -188,7 +181,6 @@ by key for exactly these reasons.
.. _SimpleDB: http://aws.amazon.com/simpledb/
.. _memcached: http://memcached.org
-
No Locking
----------
@@ -205,9 +197,9 @@ 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.
+ 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`
@@ -216,15 +208,13 @@ 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
+ :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
@@ -248,7 +238,6 @@ the time of the beginning of the request.
.. _Subversion: http://subversion.apache.org/
-
Validation
==========
@@ -270,7 +259,6 @@ 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
=======================
@@ -283,7 +271,6 @@ problem with entire books devoted to its solution. You could use
multi-master, single-master, partitioning, sharding, write-through caches,
and all sorts of other complex techniques.
-
Incremental Replication
=======================
@@ -309,15 +296,13 @@ 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
+ :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
@@ -339,7 +324,6 @@ 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
==========
@@ -350,11 +334,11 @@ 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`_ 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
+ .. _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
@@ -368,15 +352,13 @@ 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
+ :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
@@ -411,15 +393,13 @@ 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
+ :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
@@ -439,15 +419,13 @@ 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
+ :align: center
+ :alt: Synchronization conflicts between two databases
+ Figure 7. Synchronization conflicts between two databases
Wrapping Up
===========
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/daf7fc5f/src/intro/curl.rst
----------------------------------------------------------------------
diff --git a/src/intro/curl.rst b/src/intro/curl.rst
index 06b62b5..6ceb4a2 100644
--- a/src/intro/curl.rst
+++ b/src/intro/curl.rst
@@ -34,28 +34,28 @@ clarity):
.. code-block:: json
- {
- "couchdb": "Welcome",
- "uuid": "85fb71bf700c17267fef77535820e371",
- "vendor": {
- "name": "The Apache Software Foundation",
- "version": "1.4.0"
- },
- "version": "1.4.0"
- }
-
+ {
+ "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:
+.. 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
+ .. code-block:: bash
- shell> curl 'http://couchdb:5984/_uuids?count=5'
+ 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:
+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
@@ -69,31 +69,30 @@ the return information formatted for clarity):
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
+ "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:
+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:
+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
@@ -103,11 +102,11 @@ database:
{"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.
+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:
+The document can be accessed by using the automatically generated document ID
+that was returned:
.. code-block:: bash
@@ -117,6 +116,6 @@ document ID that was returned:
"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.
+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-documentation/blob/daf7fc5f/src/intro/futon.rst
----------------------------------------------------------------------
diff --git a/src/intro/futon.rst b/src/intro/futon.rst
index 3f93f5e..8c0c984 100644
--- a/src/intro/futon.rst
+++ b/src/intro/futon.rst
@@ -16,65 +16,61 @@
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:
+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
+ :align: center
+ :alt: Futon Overview
- 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`.
+- Overview
-- Configuration
+ 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`.
- 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.
+- Configuration
-- Replicator
+ 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.
- An interface to the replication system, enabling you to initiate
- replication between local and remote databases. See
- :ref:`futon-replication`.
+- Replicator
-- Status
+ An interface to the replication system, enabling you to initiate replication
+ between local and remote databases. See :ref:`futon-replication`.
- 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.
+- Status
-- Verify Installation
+ 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.
- The Verify Installation allows you to check whether all of the
- components of your CouchDB installation are correctly installed.
+- Verify Installation
-- Test Suite
+ The Verify Installation allows you to check whether all of the
+ components of your CouchDB installation are correctly installed.
- 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.
+- 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:
@@ -88,15 +84,14 @@ 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
+ :align: center
+ :alt: Creating a Database
- 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.
+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
@@ -106,10 +101,10 @@ 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
+ :align: center
+ :alt: Editing a Document
- Editing a Document
+ Editing a Document
To add a field to the document:
@@ -118,15 +113,13 @@ To add a field to the document:
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.
+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.
+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
@@ -134,16 +127,15 @@ To add a field to the document:
document with the saved revision information (the ``_rev`` field).
.. figure:: ../../images/futon-editeddoc.png
- :align: center
- :alt: Edited Document
+ :align: center
+ :alt: Edited Document
- 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
@@ -155,10 +147,10 @@ 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
+ :align: center
+ :alt: Replication Form
- 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.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/daf7fc5f/src/intro/index.rst
----------------------------------------------------------------------
diff --git a/src/intro/index.rst b/src/intro/index.rst
index 1c1088b..c96e87f 100644
--- a/src/intro/index.rst
+++ b/src/intro/index.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _intro:
============
@@ -44,13 +43,13 @@ teach how to use CouchDB.
.. _distributed scaling: http://en.wikipedia.org/wiki/CAP_theorem
.. toctree::
- :maxdepth: 2
-
- overview
- why
- consistency
- tour
- api
- security
- futon
- curl
+ :maxdepth: 2
+
+ overview
+ why
+ consistency
+ tour
+ api
+ security
+ futon
+ curl
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/daf7fc5f/src/intro/overview.rst
----------------------------------------------------------------------
diff --git a/src/intro/overview.rst b/src/intro/overview.rst
index 7804cf9..238ec8c 100644
--- a/src/intro/overview.rst
+++ b/src/intro/overview.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _intro/overview:
==================
@@ -44,7 +43,6 @@ or edited documents.
.. _RESTful: http://en.wikipedia.org/wiki/REST
-
ACID Properties
===============
@@ -97,7 +95,6 @@ after a crash or a power failure are never necessary.
.. _MVCC: http://en.wikipedia.org/wiki/Multiversion_concurrency_control
.. _B-trees: http://en.wikipedia.org/wiki/B-tree
-
Compaction
==========
@@ -108,7 +105,6 @@ The database remains completely online the entire time and all updates and
reads are allowed to complete successfully. The old database file is deleted only when
all the data has been copied and all users transitioned to the new file.
-
Views
=====
@@ -126,9 +122,7 @@ 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`
-
+ :ref:`views`
View Model
----------
@@ -147,7 +141,6 @@ and compatible with replication. CouchDB views are defined inside special
regular documents, so that not only data replicates in CouchDB,
but entire application designs replicate too.
-
Javascript View Functions
-------------------------
@@ -161,9 +154,7 @@ or it can add no rows at all.
.. _map-reduce system: http://en.wikipedia.org/wiki/MapReduce
.. seealso::
-
- :ref:`viewfun`
-
+ :ref:`viewfun`
View Indexes
------------
@@ -210,7 +201,6 @@ 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
=======================
@@ -219,9 +209,7 @@ access and update validation model that can be extended to implement custom
security models.
.. seealso::
-
- :ref:`api/db/security`
-
+ :ref:`api/db/security`
Administrator Access
--------------------
@@ -231,7 +219,6 @@ 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
-----------------
@@ -254,9 +241,7 @@ 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`
-
+ :ref:`vdufun`
Distributed Updates and Replication
===================================
@@ -285,7 +270,6 @@ 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
---------
@@ -317,9 +301,7 @@ 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`
-
+ :ref:`replication/conflicts`
Applications
------------
@@ -345,7 +327,6 @@ 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
==============
@@ -356,7 +337,7 @@ 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
+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.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/daf7fc5f/src/intro/security.rst
----------------------------------------------------------------------
diff --git a/src/intro/security.rst b/src/intro/security.rst
index 922c845..8eb565c 100644
--- a/src/intro/security.rst
+++ b/src/intro/security.rst
@@ -10,25 +10,23 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _intro/security:
-********
+========
Security
-********
+========
In this document, 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.
@@ -79,34 +77,30 @@ identification for certain requests:
- 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.
-
-::
+when you add admin users. ::
- > HOST="http://127.0.0.1:5984"
- > curl -X PUT $HOST/database
- {"ok":true}
+ > 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"'
- ""
+ > 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
@@ -146,29 +140,28 @@ 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`.
- 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
-
+ .. _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."}
+ > 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}
+ > 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.
@@ -187,14 +180,12 @@ 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>`
-
+ :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
@@ -219,19 +210,19 @@ 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'
+ > 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}
+ < 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
@@ -240,11 +231,11 @@ 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}
+ > 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
@@ -252,11 +243,8 @@ 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>`
- :ref:`Cookie Authentication API Reference <api/auth/cookie>`
-
-
-=======================
Authentication Database
=======================
@@ -290,9 +278,8 @@ apart from sensitive personal information like: real name, email, phone, special
internal identifications and more. This is not information that you
want to share with the World.
-
Users Documents
-===============
+---------------
Each CouchDB user is stored in document format. These documents contain
several *mandatory* fields, that CouchDB needs for authentication:
@@ -320,7 +307,7 @@ target user and CouchDB administrators may browse it.
.. _org.couchdb.user:
Why ``org.couchdb.user:`` prefix?
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The reason there is a special prefix before a user's login name is to have
namespaces that users belong to. This prefix is designed to prevent
@@ -330,55 +317,54 @@ For current CouchDB releases, all users belong to the same
``org.couchdb.user`` namespace and this cannot be changed. This may be changed
in future releases.
-
Creating New User
-=================
+-----------------
Creating a new user is a very trivial operation. You just need to do a
:method:`PUT` request with user's data to CouchDB. Let's create a 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"}'
+ 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 the following 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
+ 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)
+ 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"}
+ {"ok":true,"id":"org.couchdb.user:jan","rev":"1-e0ebfb84005b920488fc7a8cc5470cc0"}
The document was successfully created! The user `jan` should now exist in our
database. Let's check if this is true::
- curl -X POST http://localhost:5984/_session -d 'name=jan&password=apple'
+ curl -X POST http://localhost:5984/_session -d 'name=jan&password=apple'
CouchDB should respond with:
.. code-block:: javascript
- {"ok":true,"name":"jan","roles":[]}
+ {"ok":true,"name":"jan","roles":[]}
This means that the username was recognized and the password's hash matches
with the stored one. If we specify an incorrect login and/or password, CouchDB
@@ -386,11 +372,10 @@ will notify us with the following error message:
.. code-block:: javascript
- {"error":"unauthorized","reason":"Name or password is incorrect."}
-
+ {"error":"unauthorized","reason":"Name or password is incorrect."}
Password Changing
-=================
+-----------------
Let's define what is password changing from the point of view of CouchDB and
the authentication database. Since "users" are "documents", this operation is
@@ -401,60 +386,56 @@ replaces it with the *secured hash* depending on the chosen ``password_scheme``.
Summarizing the above process - we need to get the document's content, add
the ``password`` field with the new password in plain text and then store the
-JSON result to the authentication database.
-
-::
+JSON result to the authentication database. ::
- curl -X GET http://localhost:5984/_users/org.couchdb.user:jan
+ 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 the stored document to reduce
-the 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"}'
+ {
+ "_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 the stored document to
+reduce the 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"}
+ {"ok":true,"id":"org.couchdb.user:jan","rev":"2-ed293d3a0ae09f0c624f10538ef33c6f"}
Updated! Now let's check that the password was really changed::
- curl -X POST http://localhost:5984/_session -d 'name=jan&password=apple'
+ 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."}
+ {"error":"unauthorized","reason":"Name or password is incorrect."}
-Looks like the password ``apple`` is wrong, what about ``orange``?
+Looks like the password ``apple`` is wrong, what about ``orange``? ::
-::
-
- curl -X POST http://localhost:5984/_session -d 'name=jan&password=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":[]}
+ {"ok":true,"name":"jan","roles":[]}
Hooray! You may wonder why this was so complex - we need to retrieve user's
document, add a special field to it, post it back - where is that one big
@@ -464,13 +445,11 @@ corner if are logged in. Using that will hide all the implementation details
described above and keep it real simple for you.
.. note::
-
- There is no password confirmation for API request: you should implement it
- on your application layer like Futon does.
-
+ 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
@@ -484,11 +463,11 @@ a comma-separated lis of users document fields that will be publicly available.
Normally, if you request a user document and you're not an administrator or
document's owner, CouchDB will respond with :statuscode:`404`::
- curl http://localhost:5984/_users/org.couchdb.user:robert
+ curl http://localhost:5984/_users/org.couchdb.user:robert
.. code-block:: javascript
- {"error":"not_found","reason":"missing"}
+ {"error":"not_found","reason":"missing"}
This response is constant for both cases when user exists or doesn't exist for
security reasons.
@@ -497,25 +476,23 @@ Now let's share the field ``name``. First, setup the ``public_fields``
configuration option. Remember, that this action requires administrator
privileges. The next command will prompt you for user `admin`'s password:
- curl -X PUT http://localhost:5984/_config/couch_http_auth/public_fields \
+ curl -X PUT http://localhost:5984/_config/couch_http_auth/public_fields \
-H "Content-Type: application/json" \
-d '"name"' \
-u admin
What has changed? Let's check Robert's document once again::
- curl http://localhost:5984/_users/org.couchdb.user:robert
+ curl http://localhost:5984/_users/org.couchdb.user:robert
.. code-block:: javascript
- {"_id":"org.couchdb.user:robert","_rev":"6-869e2d3cbd8b081f9419f190438ecbe7","name":"robert"}
+ {"_id":"org.couchdb.user:robert","_rev":"6-869e2d3cbd8b081f9419f190438ecbe7","name":"robert"}
Good news! Now, we may read the field ``name`` in *every user document without
needing to be an administrator*. Keep in mind though not to publish sensitive
information, especially without user's consent!
-
-==============
Authorization
==============
@@ -543,36 +520,36 @@ normal user are treated as members, and those with server admin credentials
are treated as database admins. To change the default permissions, you must
create a :ref:`_security <api/db/security>` document in the database::
- > curl -X PUT http://localhost:5984/mydatabase/_security \
- -u anna:secret \
- -H "Content-Type: application/json" \
- -d '{"admins": { "names": [], "roles": [] }, "members": { "names": ["jan"], "roles": [] } }'
+ > curl -X PUT http://localhost:5984/mydatabase/_security \
+ -u anna:secret \
+ -H "Content-Type: application/json" \
+ -d '{"admins": { "names": [], "roles": [] }, "members": { "names": ["jan"], "roles": [] } }'
The HTTP request to create the `_security` document must contain the
credentials of a server admin. CouchDB will respond with:
.. code-block:: javascript
- {"ok":true}
+ {"ok":true}
The database is now secured against anonymous reads and writes::
- > curl http://localhost:5984/mydatabase/
+ > curl http://localhost:5984/mydatabase/
.. code-block:: javascript
- {"error":"unauthorized","reason":"You are not authorized to access this db."}
+ {"error":"unauthorized","reason":"You are not authorized to access this db."}
You declared user "jan" as a member in this database, so he is able to read and
write normal documents::
- > curl -u jan:apple http://localhost:5984/mydatabase/
+ > curl -u jan:apple http://localhost:5984/mydatabase/
.. code-block:: javascript
- {"db_name":"mydatabase","doc_count":1,"doc_del_count":0,"update_seq":3,"purge_seq":0,
- "compact_running":false,"disk_size":12376,"data_size":272,"instance_start_time":"1397672867731570",
- "disk_format_version":6,"committed_update_seq":3}
+ {"db_name":"mydatabase","doc_count":1,"doc_del_count":0,"update_seq":3,"purge_seq":0,
+ "compact_running":false,"disk_size":12376,"data_size":272,"instance_start_time":"1397672867731570",
+ "disk_format_version":6,"committed_update_seq":3}
If Jan attempted to create a design doc, however, CouchDB would return a
401 Unauthorized error because the username "jan" is not in the list of
@@ -584,10 +561,10 @@ admin usernames is tedious, though, so you would likely prefer to create a
database admin role and assign that role to the `org.couchdb.user:jan` user
document::
- > curl -X PUT http://localhost:5984/mydatabase/_security \
- -u anna:secret \
- -H "Content-Type: application/json" \
- -d '{"admins": { "names": [], "roles": ["mydatabase_admin"] }, "members": { "names": [], "roles": [] } }'
+ > curl -X PUT http://localhost:5984/mydatabase/_security \
+ -u anna:secret \
+ -H "Content-Type: application/json" \
+ -d '{"admins": { "names": [], "roles": ["mydatabase_admin"] }, "members": { "names": [], "roles": [] } }'
See the :ref:`_security document reference page <api/db/security>` for
additional details about specifying database members and admins.