3.2. Base Configuration

3.2.1. Base CouchDB Options


Higher values may result in better read performance due to fewer read operations and/or more OS page cache hits. However, they can also increase overall response time for writes when there are many attachment write requests in parallel.

attachment_stream_buffer_size = 4096

Specifies location of CouchDB database files (*.couch named). This location should be writable and readable for the user the CouchDB service runs as (couchdb by default).

database_dir = /var/lib/couchdb

When this config value as false the CouchDB provides guaranty of fsync call before return 201 Created response on each document saving. Setting this config value as true may raise some overall performance with cost of losing durability - it’s strongly not recommended to do such in production:

delayed_commits = false


Delayed commits are a feature of CouchDB that allows it to achieve better write performance for some workloads while sacrificing a small amount of durability. The setting causes CouchDB to wait up to a full second before committing new data after an update. If the server crashes before the header is written then any writes since the last commit are lost.


Changed in version 1.2: Added Google Snappy compression algorithm.

Method used to compress everything that is appended to database and view index files, except for attachments (see the attachments section). Available methods are:

  • none: no compression
  • snappy: use Google Snappy, a very fast compressor/decompressor
  • deflate_N: use zlib’s deflate; N is the compression level which ranges from 1 (fastest, lowest compression ratio) to 9 (slowest, highest compression ratio)
file_compression = snappy

Specifies when to make fsync calls. fsync makes sure that the contents of any file system buffers kept by the operating system are flushed to disk. There is generally no need to modify this parameter.

fsync_options = [before_header, after_header, on_file_open]

This option places an upper bound on the number of databases that can be open at once. CouchDB reference counts database accesses internally and will close idle databases as needed. Sometimes it is necessary to keep more than the default open at once, such as in deployments where many databases will be replicating continuously.

max_dbs_open = 100

Changed in version 1.3: This option now actually works.

Defines a maximum size for JSON documents, in bytes. This limit does not apply to attachments, since they are transferred as a stream of chunks. If you set this to a small value, you might be unable to modify configuration options, database security and other larger documents until a larger value is restored by editing the configuration file.

max_document_size = 4294967296 ; 4 GB

If an external process, such as a query server or external process, runs for this amount of microseconds without returning any results, it will be terminated. Keeping this value smaller ensures you get expedient errors, but you may want to tweak it for your specific needs.

os_process_timeout = 5000 ; 5 sec

This file contains the full URI that can be used to access this instance of CouchDB. It is used to help discover the port CouchDB is running on (if it was set to 0 (e.g. automatically assigned any free one). This file should be writable and readable for the user that runs the CouchDB service (couchdb by default).

uri_file = /var/run/couchdb/couchdb.uri

Specifies location of binary drivers (icu, ejson, etc.). This location and its contents should be readable for the user that runs the CouchDB service.

util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib

New in version 1.3.

Unique identifier for this CouchDB server instance.

uuid = 0a959b9b8227188afc2ac26ccdf345a6

Specifies location of CouchDB view index files. This location should be writable and readable for the user that runs the CouchDB service (couchdb by default).

view_index_dir = /var/lib/couchdb