You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by dc...@apache.org on 2013/09/28 01:58:56 UTC
[4/4] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 083bb15
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/1781-reorganize-and-improve-docs
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.