src/maintenance now follows the style
Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/b4c41ddd Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/b4c41ddd Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/b4c41ddd Branch: refs/heads/master Commit: b4c41dddd9f6bb398219e2860714fb6c1cbbb1b4 Parents: e5d2fc8 Author: Maria Andersson <ma...@dualpose.com> Authored: Fri Feb 6 22:19:44 2015 +0100 Committer: Maria Andersson <ma...@dualpose.com> Committed: Fri Feb 6 22:19:44 2015 +0100 ---------------------------------------------------------------------- src/maintenance/compaction.rst | 134 +++++++++++++++++------------------ src/maintenance/index.rst | 5 +- src/maintenance/performance.rst | 77 ++++++++------------ 3 files changed, 98 insertions(+), 118 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/b4c41ddd/src/maintenance/compaction.rst ---------------------------------------------------------------------- diff --git a/src/maintenance/compaction.rst b/src/maintenance/compaction.rst index f6d0240..fa7d901 100644 --- a/src/maintenance/compaction.rst +++ b/src/maintenance/compaction.rst @@ -12,6 +12,7 @@ .. _compact: +========== Compaction ========== @@ -30,11 +31,10 @@ compacted file's data. When all actual data is successfully transferred to the `compacted` file CouchDB replaces the `target` with the `compacted` file. - .. _compact/db: Database Compaction -------------------- +=================== Database compaction compresses the database file by removing unused file sections created during updates. Old documents revisions are replaced with @@ -47,22 +47,22 @@ Compaction is manually triggered operation per database and runs as a background task. To start it for specific database there is need to send HTTP :post:`/{db}/_compact` sub-resource of the target database:: - curl -H "Content-Type: application/json" -X POST http://localhost:5984/my_db/_compact + curl -H "Content-Type: application/json" -X POST http://localhost:5984/my_db/_compact On success, HTTP status :statuscode:`202` is returned immediately: .. code-block:: http - HTTP/1.1 202 Accepted - Cache-Control: must-revalidate - Content-Length: 12 - Content-Type: text/plain; charset=utf-8 - Date: Wed, 19 Jun 2013 09:43:52 GMT - Server: CouchDB (Erlang/OTP) + HTTP/1.1 202 Accepted + Cache-Control: must-revalidate + Content-Length: 12 + Content-Type: text/plain; charset=utf-8 + Date: Wed, 19 Jun 2013 09:43:52 GMT + Server: CouchDB (Erlang/OTP) .. code-block:: javascript - {"ok":true} + {"ok":true} Although the request body is not used you must still specify :header:`Content-Type` header with :mimetype:`application/json` value @@ -71,115 +71,111 @@ for the request. If you don't, you will be aware about with HTTP status .. code-block:: http - HTTP/1.1 415 Unsupported Media Type - Cache-Control: must-revalidate - Content-Length: 78 - Content-Type: application/json - Date: Wed, 19 Jun 2013 09:43:44 GMT - Server: CouchDB (Erlang/OTP) + HTTP/1.1 415 Unsupported Media Type + Cache-Control: must-revalidate + Content-Length: 78 + Content-Type: application/json + Date: Wed, 19 Jun 2013 09:43:44 GMT + Server: CouchDB (Erlang/OTP) - {"error":"bad_content_type","reason":"Content-Type must be application/json"} + {"error":"bad_content_type","reason":"Content-Type must be application/json"} When the compaction is successful started and running it is possible to get information about it via :ref:`database information resource <api/db>`:: - curl http://localhost:5984/my_db + curl http://localhost:5984/my_db .. code-block:: http - HTTP/1.1 200 OK - Cache-Control: must-revalidate - Content-Length: 246 - Content-Type: application/json - Date: Wed, 19 Jun 2013 16:51:20 GMT - Server: CouchDB (Erlang/OTP) - - { - "committed_update_seq": 76215, - "compact_running": true, - "data_size": 3787996, - "db_name": "my_db", - "disk_format_version": 6, - "disk_size": 17703025, - "doc_count": 5091, - "doc_del_count": 0, - "instance_start_time": "1371660751878859", - "purge_seq": 0, - "update_seq": 76215 - } - + HTTP/1.1 200 OK + Cache-Control: must-revalidate + Content-Length: 246 + Content-Type: application/json + Date: Wed, 19 Jun 2013 16:51:20 GMT + Server: CouchDB (Erlang/OTP) + + { + "committed_update_seq": 76215, + "compact_running": true, + "data_size": 3787996, + "db_name": "my_db", + "disk_format_version": 6, + "disk_size": 17703025, + "doc_count": 5091, + "doc_del_count": 0, + "instance_start_time": "1371660751878859", + "purge_seq": 0, + "update_seq": 76215 + } Note that ``compaction_running`` field is ``true`` indicating that compaction is actually running. To track the compaction progress you may query the :get:`_active_tasks </_active_tasks>` resource:: - curl http://localhost:5984/my_db + curl http://localhost:5984/my_db .. code-block:: http - HTTP/1.1 200 OK - Cache-Control: must-revalidate - Content-Length: 175 - Content-Type: application/json - Date: Wed, 19 Jun 2013 16:27:23 GMT - Server: CouchDB (Erlang/OTP) - - [ - { - "changes_done": 44461, - "database": "my_db", - "pid": "<0.218.0>", - "progress": 58, - "started_on": 1371659228, - "total_changes": 76215, - "type": "database_compaction", - "updated_on": 1371659241 - } - ] - + HTTP/1.1 200 OK + Cache-Control: must-revalidate + Content-Length: 175 + Content-Type: application/json + Date: Wed, 19 Jun 2013 16:27:23 GMT + Server: CouchDB (Erlang/OTP) + + [ + { + "changes_done": 44461, + "database": "my_db", + "pid": "<0.218.0>", + "progress": 58, + "started_on": 1371659228, + "total_changes": 76215, + "type": "database_compaction", + "updated_on": 1371659241 + } + ] .. _compact/views: Views Compaction ----------------- +================ `Views` are also need compaction like databases, unlike databases views are compacted by groups per `design document`. To start their compaction there is need to send HTTP :post:`/{db}/_compact/{ddoc}` request:: - curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_compact/designname + curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_compact/designname .. code-block:: javascript - {"ok":true} + {"ok":true} This compacts the view index from the current version of the specified design document. The HTTP response code is :statuscode:`202` (like :ref:`compaction for databases <compact/db>`) and a compaction background task will be created. - .. _compact/views/cleanup: Views cleanup -^^^^^^^^^^^^^ +------------- View indexes on disk are named after their `MD5` hash of the view definition. When you change a view, old indexes remain on disk. To clean up all outdated view indexes (files named after the MD5 representation of views, that does not exist anymore) you can trigger a :ref:`view cleanup <api/db/view_cleanup>`:: - curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_view_cleanup + curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_view_cleanup .. code-block:: javascript - {"ok":true} - + {"ok":true} .. _compact/auto: Automatic Compaction --------------------- +==================== While both :ref:`database <compact/db>` and :ref:`views <compact/views>` compactions are required be manually triggered, it is also possible to configure http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/b4c41ddd/src/maintenance/index.rst ---------------------------------------------------------------------- diff --git a/src/maintenance/index.rst b/src/maintenance/index.rst index b0072fe..5f23922 100644 --- a/src/maintenance/index.rst +++ b/src/maintenance/index.rst @@ -10,12 +10,11 @@ .. License for the specific language governing permissions and limitations under .. the License. - =================== CouchDB Maintenance =================== .. toctree:: - compaction - performance + compaction + performance http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/b4c41ddd/src/maintenance/performance.rst ---------------------------------------------------------------------- diff --git a/src/maintenance/performance.rst b/src/maintenance/performance.rst index b4f9d59..9161598 100644 --- a/src/maintenance/performance.rst +++ b/src/maintenance/performance.rst @@ -10,7 +10,6 @@ .. License for the specific language governing permissions and limitations under .. the License. - .. _performance: =========== @@ -21,7 +20,6 @@ With up to tens of thousands of documents you will generally find CouchDB to perform well no matter how you write your code. Once you start getting into the millions of documents you need to be a lot more careful. - Disk I/O ======== @@ -36,7 +34,6 @@ that are hundreds of characters long, but your program would be hard to maintain if you only used single character keys. Carefully consider data that is duplicated by putting it in views. - Disk and File System Performance -------------------------------- @@ -45,10 +42,10 @@ up your CouchDB deployment. However, there is one option that can increase the responsiveness of your CouchDB server when disk performance is a bottleneck. From the Erlang documentation for the file module: - On operating systems with thread support, it is possible to let file - operations be performed in threads of their own, allowing other Erlang - processes to continue executing in parallel with the file operations. - See the `command line flag +A in erl(1)`_. + On operating systems with thread support, it is possible to let file + operations be performed in threads of their own, allowing other Erlang + processes to continue executing in parallel with the file operations. + See the `command line flag +A in erl(1)`_. Setting this argument to a number greater than zero can keep your CouchDB installation responsive even during periods of heavy disk utilization. The @@ -57,12 +54,10 @@ variable. For example, to give Erlang four threads with which to perform I/O operations add the following to ``(prefix)/etc/defaults/couchdb`` (or equivalent):: - export ERL_FLAGS="+A 4" - + export ERL_FLAGS="+A 4" .. _command line flag +A in erl(1): http://erlang.org/doc/man/erl.html - System Resource Limits ====================== @@ -71,7 +66,6 @@ large are resource limits imposed by the system and by the application configuration. Raising these limits can allow your deployment to grow beyond what the default configuration will support. - CouchDB Configuration Options ----------------------------- @@ -93,8 +87,8 @@ yourself with the :config:option:`couchdb/max_dbs_open`: .. code-block:: ini - [couchdb] - max_dbs_open = 100 + [couchdb] + max_dbs_open = 100 This option places an upper bound on the number of databases that can be open at one time. CouchDB reference counts database accesses internally and @@ -102,7 +96,6 @@ will close idle databases when it must. Sometimes it is necessary to keep more than the default open at once, such as in deployments where many databases will be continuously replicating. - Erlang ------ @@ -111,7 +104,7 @@ the Erlang runtime system will not allow more than 1024 connections by default. Adding the following directive to ``(prefix)/etc/default/couchdb`` (or equivalent) will increase this limit (in this case to 4096):: - export ERL_MAX_PORTS=4096 + export ERL_MAX_PORTS=4096 CouchDB versions up to 1.1.x also create Erlang Term Storage (`ETS`_) tables for each replication. If you are using a version of CouchDB older than 1.2 and @@ -127,7 +120,6 @@ explanation`_. .. _this tip for a possible workaround: http://erlang.org/pipermail/erlang-questions/2011-December/063119.html .. _this thread for a deeper explanation: http://erlang.org/pipermail/erlang-questions/2011-October/061971.html - PAM and ulimit -------------- @@ -138,9 +130,9 @@ creating a file named ``/etc/security/limits.d/100-couchdb.conf`` with the following contents will ensure that CouchDB can open enough file descriptors to service your increased maximum open databases and Erlang ports:: - #<domain> <type> <item> <value> - couchdb hard nofile 4096 - couchdb soft nofile 4096 + #<domain> <type> <item> <value> + couchdb hard nofile 4096 + couchdb soft nofile 4096 If your system does not use PAM, a `ulimit` command is usually available for use in a custom script to launch CouchDB with increased resource limits. @@ -149,7 +141,6 @@ handle the load. .. _PAM: http://www.linux-pam.org/ - Network ======= @@ -179,15 +170,13 @@ This TCP buffering behaviour can be disabled via .. code-block:: ini - [httpd] - socket_options = [{nodelay, true}] + [httpd] + socket_options = [{nodelay, true}] .. _SO_NODELAY: http://en.wikipedia.org/wiki/Nagle%27s_algorithm .. seealso:: - - Bulk :ref:`load <api/db/all_docs>` and :ref:`store <api/db/bulk_docs>` API. - + Bulk :ref:`load <api/db/all_docs>` and :ref:`store <api/db/bulk_docs>` API. CouchDB ======= @@ -207,7 +196,6 @@ deleted documents (for example, if you are storing short-term data like logfile entries, message queues, etc), you might want to periodically switch to a new database and delete the old one (once the entries in it have all expired). - Document's ID ------------- @@ -225,7 +213,6 @@ sequentially and using an encoding scheme that consumes fewer bytes. For example, something that takes 16 hex digits to represent can be done in 4 base 62 digits (10 numerals, 26 lower case, 26 upper case). - Views ===== @@ -246,7 +233,6 @@ minutes to load into CouchDB but about 4 hours to do view generation). View information isn't replicated - it is rebuilt on each database so you can't do the view generation on a separate sever. - Builtin Reduce Functions ------------------------ @@ -262,32 +248,31 @@ Before: .. code-block:: javascript - { - "_id": "_design/foo", - "views": { - "bar": { - "map": "function (doc) { emit(doc.author, 1); }", - "reduce": "function (keys, values, rereduce) { return sum(values); }" - } + { + "_id": "_design/foo", + "views": { + "bar": { + "map": "function (doc) { emit(doc.author, 1); }", + "reduce": "function (keys, values, rereduce) { return sum(values); }" + } + } } - } After: .. code-block:: javascript - { - "_id": "_design/foo", - "views": { - "bar": { - "map": "function (doc) { emit(doc.author, 1); }", - "reduce": "_sum" - } + { + "_id": "_design/foo", + "views": { + "bar": { + "map": "function (doc) { emit(doc.author, 1); }", + "reduce": "_sum" + } + } } - } .. _mentioned on the mailing list: http://mail-archives.apache.org/mod_mbox/couchdb-user/201003.mbox/%3c5e07e00e-3d69-4a8c-ada3-1b20cf0ba...@julianstahnke.com%3e .. seealso:: - - :ref:`reducefun/builtin` + :ref:`reducefun/builtin`
