[couchdb-documentation] branch documentbp updated (570669c -> 698797d)

[fl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

flimzy pushed a change to branch documentbp
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.


 discard 570669c  Migrate some FAQ material to the Best Practices documentation
     new 698797d  Migrate some FAQ material to the Best Practices documentation

This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version.  This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:

 * -- * -- B -- O -- O -- O   (570669c)
            \
             N -- N -- N   refs/heads/documentbp (698797d)

You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.

Any revisions marked "omit" are not gone; other references still
refer to them.  Any revisions marked "discard" are gone forever.

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 src/best-practices/index.rst | 1 +
 1 file changed, 1 insertion(+)

-- 
To stop receiving notification emails like this one, please contact
flimzy@apache.org.

[couchdb-documentation] 01/01: Migrate some FAQ material to the Best Practices documentation

[fl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

flimzy pushed a commit to branch documentbp
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 698797d5b4e978315ca7caf6e870a8271698a857
Author: Jonathan Hall <fl...@flimzy.com>
AuthorDate: Thu May 17 18:19:44 2018 +0200

    Migrate some FAQ material to the Best Practices documentation
    
    https://wiki.apache.org/couchdb/Frequently_asked_questions#How_Do_I_Do_Sequences.3F
    https://wiki.apache.org/couchdb/FUQ#Documents
---
 src/best-practices/documents.rst | 50 ++++++++++++++++++++++++++++++++++++++++
 src/best-practices/index.rst     |  1 +
 2 files changed, 51 insertions(+)

diff --git a/src/best-practices/documents.rst b/src/best-practices/documents.rst
new file mode 100644
index 0000000..fe41afe
--- /dev/null
+++ b/src/best-practices/documents.rst
@@ -0,0 +1,50 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _best-practices/documents:
+
+==============================
+Document Design Considerations
+==============================
+
+When designing your database, and your document structure, there are a number of
+best practices to take into consideration. Especially for people accustomed to
+relational databases, some of these techniques may be non-obvious.
+
+Don't rely on CouchDB's auto-UUID generation
+--------------------------------------------
+
+While CouchDB will generate a unique identifier for the ``_id`` field of any doc
+that you create, in most cases you are better off generating them yourself for
+a few reasons:
+
+- If for any reason you miss the ``200 OK`` reply from CouchDB, and storing the
+  document is attempted again, you would end up with the same document content
+  stored under duplicate ``_id``\ s. This could easily happen with intermediary
+  proxies and cache systems that may not inform developers that the failed
+  transaction is being retried.
+- ``_id``\ s are are the only unique enforced value within CouchDB so you might
+  as well make use of this. CouchDB stores its documents in a B+ tree. Each
+  additional or updated document is stored as a leaf node, and may require
+  re-writing intermediary and parent nodes. You may be able to take advantage of
+  sequencing your own ids more effectively than the automatically generated ids
+  if you can arrange them to be sequential yourself.
+
+Alternatives to auto-incrementing sequences
+-------------------------------------------
+
+Because of replication, as well as the distributed nature of CouchDB, it is not
+practical to use auto-incrementing with CouchDB. Sequences are often used to
+ensure unique identifiers for each row in a database table. CouchDB generates
+unique ids on its own and you can specify your own as well, so you don't really
+need a sequence here. If you use a sequence for something else, you will be
+better off finding another way to express it in CouchDB in another way.
diff --git a/src/best-practices/index.rst b/src/best-practices/index.rst
index 362b3f1..53aada3 100644
--- a/src/best-practices/index.rst
+++ b/src/best-practices/index.rst
@@ -24,6 +24,7 @@ system.
 .. toctree::
     :maxdepth: 2
 
+    documents
     forms
     jsdevel
     nginx

-- 
To stop receiving notification emails like this one, please contact
flimzy@apache.org.