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 570669c7884943cc4498ddba88875453fbfa0dfc
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 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 50 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.
--
To stop receiving notification emails like this one, please contact
fli...@apache.org.
