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 <fli...@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
fli...@apache.org.

Reply via email to