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.