diff options
author | Dave Cottlehuber <dch@apache.org> | 2013-09-28 01:58:42 +0200 |
---|---|---|
committer | Dave Cottlehuber <dch@apache.org> | 2013-09-28 01:58:42 +0200 |
commit | 083bb15e0c8899549ea591b4b7e7136d34b897a3 (patch) | |
tree | 022813fda03328f58808f0cf1cabcea3790dc1af | |
parent | 655809fca32292b1b3ba41bf2177c18e0b6b24a1 (diff) | |
download | couchdb-083bb15e0c8899549ea591b4b7e7136d34b897a3.tar.gz |
docs: update api/database section
-rw-r--r-- | share/doc/src/api/database/common.rst | 26 | ||||
-rw-r--r-- | share/doc/src/api/database/compact.rst | 14 | ||||
-rw-r--r-- | share/doc/src/api/database/misc.rst | 16 | ||||
-rw-r--r-- | share/doc/src/api/database/security.rst | 3 | ||||
-rw-r--r-- | share/doc/src/api/database/temp-views.rst | 10 |
5 files changed, 46 insertions, 23 deletions
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst index 853ff6bb7..a131e39b1 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**: diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst index 6982cb423..81935db2a 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` diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst index d3507a541..ad46e1522 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 diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst index 8ad62e658..ee95ee4cc 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. diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst index 0b576b817..d9ac16df0 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. |