FreeBSD Manual Pages

home | help

APACHECOUCHDB(1) Apache CouchDB APACHECOUCHDB(1)

NAME
apachecouchdb - Apache CouchDB 3.5.1

INTRODUCTION
CouchDB is a database that completely embraces the web. Store your data
with JSON documents. Access your documents with your web browser, via
HTTP. Query, combine, and transform your documents with JavaScript.
CouchDB works well with modern web and mobile apps. You can distribute
your data, efficiently using CouchDBs incremental replication. CouchDB
supports master-master setups with automatic conflict detection.

CouchDB comes with a suite of features, such as on-the-fly document
transformation and real-time change notifications, that make web devel-
opment a breeze. It even comes with an easy to use web administration
console, served directly out of CouchDB! We care a lot about -
distributed scaling. CouchDB is highly available and partition toler-
ant, but is also eventually consistent. And we care a lot about your
data. CouchDB has a fault-tolerant storage engine that puts the safety
of your data first.

In this section youll learn about every basic bit of CouchDB, see upon
what conceptions and technologies it built and walk through short tuto-
rial that teach how to use CouchDB.

Technical Overview
Document Storage
A CouchDB server hosts named databases, which store documents. Each
document is uniquely named in the database, and CouchDB provides a -
RESTful HTTP API for reading and updating (add, edit, delete) database
documents.

Documents are the primary unit of data in CouchDB and consist of any
number of fields and attachments. Documents also include metadata thats
maintained by the database system. Document fields are uniquely named
and contain values of varying types (text, number, boolean, lists,
etc), and there is no set limit to text size or element count.

The CouchDB document update model is lockless and optimistic. Document
edits are made by client applications loading documents, applying
changes, and saving them back to the database. If another client edit-
ing the same document saves their changes first, the client gets an
edit conflict error on save. To resolve the update conflict, the latest
document version can be opened, the edits reapplied and the update
tried again.

Single document updates (add, edit, delete) are all or nothing, either
succeeding entirely or failing completely. The database never contains
partially saved or edited documents.

ACID Properties
The CouchDB file layout and commitment system features all Atomic Con-
sistent Isolated Durable (ACID) properties. On-disk, CouchDB never
overwrites committed data or associated structures, ensuring the data-
base file is always in a consistent state. This is a crash-only design
where the CouchDB server does not go through a shut down process, its
simply terminated.

Document updates (add, edit, delete) are serialized, except for binary
blobs which are written concurrently. Database readers are never locked
out and never have to wait on writers or other readers. Any number of
clients can be reading documents without being locked out or inter-
rupted by concurrent updates, even on the same document. CouchDB read
operations use a Multi-Version Concurrency Control (MVCC) model where
each client sees a consistent snapshot of the database from the begin-
ning to the end of the read operation. This means that CouchDB can
guarantee transactional semantics on a per-document basis.

Documents are indexed in B-trees by their name (DocID) and a Sequence
ID. Each update to a database instance generates a new sequential num-
ber. Sequence IDs are used later for incrementally finding changes in
a database. These B-tree indexes are updated simultaneously when docu-
ments are saved or deleted. The index updates always occur at the end
of the file (append-only updates).

Documents have the advantage of data being already conveniently pack-
aged for storage rather than split out across numerous tables and rows
in most database systems. When documents are committed to disk, the
document fields and metadata are packed into buffers, sequentially one
document after another (helpful later for efficient building of views).

When CouchDB documents are updated, all data and associated indexes are
flushed to disk and the transactional commit always leaves the database
in a completely consistent state. Commits occur in two steps:

1. All document data and associated index updates are synchronously
flushed to disk.

2. The updated database header is written in two consecutive, identical
chunks to make up the first 4k of the file, and then synchronously
flushed to disk.

In the event of an OS crash or power failure during step 1, the par-
tially flushed updates are simply forgotten on restart. If such a crash
happens during step 2 (committing the header), a surviving copy of the
previous identical headers will remain, ensuring coherency of all pre-
viously committed data. Excepting the header area, consistency checks
or fix-ups after a crash or a power failure are never necessary.

Compaction
Wasted space is recovered by occasional compaction. On schedule, or
when the database file exceeds a certain amount of wasted space, the
compaction process clones all the active data to a new file and then
discards the old file. The database remains completely online the en-
tire time and all updates and reads are allowed to complete success-
fully. The old database file is deleted only when all the data has been
copied and all users transitioned to the new file.

Views
ACID properties only deal with storage and updates, but we also need
the ability to show our data in interesting and useful ways. Unlike SQL
databases where data must be carefully decomposed into tables, data in
CouchDB is stored in semi-structured documents. CouchDB documents are
flexible and each has its own implicit structure, which alleviates the
most difficult problems and pitfalls of bi-directionally replicating
table schemas and their contained data.

But beyond acting as a fancy file server, a simple document model for
data storage and sharing is too simple to build real applications on
it simply doesnt do enough of the things we want and expect. We want to
slice and dice and see our data in many different ways. What is needed
is a way to filter, organize and report on data that hasnt been decom-
posed into tables.

SEE ALSO:

CouchDB Guide:

• Show Functions

List Functions
WARNING:
List functions are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

listfun(head, req)

Arguments

• head View Head Information

• req Request object.

Returns
Last chunk.

Return type
string

While Show Functions are used to customize document presentation, List
Functions are used for the same purpose, but on View Functions results.

The following list function formats the view and represents it as a
very simple HTML page:

function(head, req){
start({
'headers': {
'Content-Type': 'text/html'
}
});
send('<html><body><table>');
send('<tr><th>ID</th><th>Key</th><th>Value</th></tr>');
while(row = getRow()){
send(''.concat(
'<tr>',
'<td>' + toJSON(row.id) + '</td>',
'<td>' + toJSON(row.key) + '</td>',
'<td>' + toJSON(row.value) + '</td>',
'</tr>'
));
}
send('</table></body></html>');
}

Templates and styles could obviously be used to present data in a nicer
fashion, but this is an excellent starting point. Note that you may
also use registerType() and provides() functions in a similar way as
for Show Functions! However, note that provides() expects the return
value to be a string when used inside a list function, so youll need to
use start() to set any custom headers and stringify your JSON before
returning it.

SEE ALSO:

CouchDB Guide:

• Transforming Views with List Functions

Update Functions
updatefun(doc, req)

Arguments

• doc The document that is being processed.

• req Request object

Returns
Two-element array: the first element is the (updated or
new) document, which is committed to the database. If the
first element is null no document will be committed to
the database. If you are updating an existing document,
it should already have an _id set, and if you are creat-
ing a new document, make sure to set its _id to some-
thing, either generated based on the input or the
req.uuid provided. The second element is the response
that will be sent back to the caller.

Update handlers are functions that clients can request to invoke
server-side logic that will create or update a document. This feature
allows a range of use cases such as providing a server-side last modi-
fied timestamp, updating individual fields in a document without first
getting the latest revision, etc.

When the request to an update handler includes a document ID in the
URL, the server will provide the function with the most recent version
of that document. You can provide any other values needed by the up-
date handler function via the POST/PUT entity body or query string pa-
rameters of the request.

A basic example that demonstrates all use-cases of update handlers:

function(doc, req){
if (!doc){
if ('id' in req && req['id']){
// create new document
return [{'_id': req['id']}, 'New World']
}
// change nothing in database
return [null, 'Empty World']
}
doc['world'] = 'hello';
doc['edited_by'] = req['userCtx']['name']
return [doc, 'Edited World!']
}

Filter Functions
filterfun(doc, req)

Arguments

• doc The document that is being processed

• req Request object

Returns
Boolean value: true means that doc passes the filter
rules, false means that it does not.

Filter functions mostly act like Show Functions and List Functions:
they format, or filter the changes feed.

Classic Filters
By default the changes feed emits all database documents changes. But
if youre waiting for some special changes, processing all documents is
inefficient.

Filters are special design document functions that allow the changes
feed to emit only specific documents that pass filter rules.

Lets assume that our database is a mailbox and we need to handle only
new mail events (documents with the status new). Our filter function
would look like this:

function(doc, req){
// we need only `mail` documents
if (doc.type != 'mail'){
return false;
}
// we're interested only in `new` ones
if (doc.status != 'new'){
return false;
}
return true; // passed!
}

Filter functions must return true if a document passed all the rules.
Now, if you apply this function to the changes feed it will emit only
changes about new mails:

GET /somedatabase/_changes?filter=mailbox/new_mail HTTP/1.1

{"results":[
{"seq":"1-g1AAAAF9eJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBMZc4EC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HqQ_kQG3qgSQqnoCqvJYgCRDA5ACKpxPWOUCiMr9hFUegKi8T1jlA4hKkDuzAC2yZRo","id":"df8eca9da37dade42ee4d7aa3401f1dd","changes":[{"rev":"1-c2e0085a21d34fa1cecb6dc26a4ae657"}]},
{"seq":"9-g1AAAAIreJyVkEsKwjAURUMrqCOXoCuQ5MU0OrI70XyppcaRY92J7kR3ojupaSPUUgqWwAu85By4t0AITbJYo5k7aUNSAnyJ_SGFf4gEkvOyLPMsFtHRL8ZKaC1M0v3eq5ALP-X2a0G1xYKhgnONpmenjT04o_v5tOJ3LV5itTES_uP3FX9ppcAACaVsQAo38hNd_eVFt8ZklVljPqSPYLoH06PJhG0Cxq7-yhQcz-B4_fQCjFuqBjjewVF3E9cORoExSrpU_gHBTo5m","id":"df8eca9da37dade42ee4d7aa34024714","changes":[{"rev":"1-29d748a6e87b43db967fe338bcb08d74"}]},
],
"last_seq":"10-g1AAAAIreJyVkEsKwjAURR9tQR25BF2B5GMaHdmdaNIk1FLjyLHuRHeiO9Gd1LQRaimFlsALvOQcuLcAgGkWKpjbs9I4wYSvkDu4cA-BALkoyzLPQhGc3GKSCqWEjrvfexVy6abc_SxQWwzRVHCuYHaxSpuj1aqfTyp-3-IlSrdakmH8oeKvrRSIkJhSNiKFjdyEm7uc6N6YTKo3iI_pw5se3vRsMiETE23WgzJ5x8s73n-9EMYNTUc4Pt5RdxPVDkYJYxR3qfwLwW6OZw"}

Note that the value of last_seq is 10-.., but we received only two
records. Seems like any other changes were for documents that havent
passed our filter.

We probably need to filter the changes feed of our mailbox by more than
a single status value. Were also interested in statuses like spam to
update spam-filter heuristic rules, outgoing to let a mail daemon actu-
ally send mails, and so on. Creating a lot of similar functions that
actually do similar work isnt good idea - so we need a dynamic filter.

You may have noticed that filter functions take a second argument named
request. This allows the creation of dynamic filters based on query pa-
rameters, user context and more.

The dynamic version of our filter looks like this:

function(doc, req){
// we need only `mail` documents
if (doc.type != 'mail'){
return false;
}
// we're interested only in requested status
if (doc.status != req.query.status){
return false;
}
return true; // passed!
}

and now we have passed the status query parameter in the request to let
our filter match only the required documents:

GET /somedatabase/_changes?filter=mailbox/by_status&status=new HTTP/1.1

and we can easily change filter behavior with:

GET /somedatabase/_changes?filter=mailbox/by_status&status=spam HTTP/1.1

{"results":[
{"seq":"6-g1AAAAIreJyVkM0JwjAYQD9bQT05gk4gaWIaPdlNNL_UUuPJs26im-gmuklMjVClFFoCXyDJe_BSAsA4jxVM7VHpJEswWyC_ktJfRBzEzDlX5DGPDv5gJLlSXKfN560KMfdTbL4W-FgM1oQzpmByskqbvdWqnc8qfvvHCyTXWuBu_K7iz38VCOOUENqjwg79hIvfvOhamQahROoVYn3-I5huwXSvm5BJsTbLTk3B8QiO58-_YMoMkT0cr-BwdRElmFKSNKniDcAcjmM","id":"8960e91220798fc9f9d29d24ed612e0d","changes":[{"rev":"3-cc6ff71af716ddc2ba114967025c0ee0"}]},
],
"last_seq":"10-g1AAAAIreJyVkEsKwjAURR9tQR25BF2B5GMaHdmdaNIk1FLjyLHuRHeiO9Gd1LQRaimFlsALvOQcuLcAgGkWKpjbs9I4wYSvkDu4cA-BALkoyzLPQhGc3GKSCqWEjrvfexVy6abc_SxQWwzRVHCuYHaxSpuj1aqfTyp-3-IlSrdakmH8oeKvrRSIkJhSNiKFjdyEm7uc6N6YTKo3iI_pw5se3vRsMiETE23WgzJ5x8s73n-9EMYNTUc4Pt5RdxPVDkYJYxR3qfwLwW6OZw"}

Combining filters with a continuous feed allows creating powerful
event-driven systems.

View Filters
View filters are the same as classic filters above, with one small dif-
ference: they use the map instead of the filter function of a view, to
filter the changes feed. Each time a key-value pair is emitted from the
map function, a change is returned. This allows avoiding filter func-
tions that mostly do the same work as views.

To use them just pass filter=_view and view=designdoc/viewname as re-
quest parameters to the changes feed:

GET /somedatabase/_changes?filter=_view&view=dname/viewname HTTP/1.1

NOTE:
Since view filters use map functions as filters, they cant show any
dynamic behavior since request object is not available.

SEE ALSO:

CouchDB Guide:

• Guide to filter change notification

Validate Document Update Functions
validatefun(newDoc, oldDoc, userCtx, secObj)

Arguments

• newDoc New version of document that will be stored.

• oldDoc Previous version of document that is already
stored.

• userCtx User Context Object

• secObj Security Object

Throws forbidden error to gracefully prevent document storing.

Throws unauthorized error to prevent storage and allow the user
to re-auth.

A design document may contain a function named validate_doc_update
which can be used to prevent invalid or unauthorized document update
requests from being stored. The function is passed the new document
from the update request, the current document stored in the database, a
User Context Object containing information about the user writing the
document (if present), and a Security Object with lists of database se-
curity roles.

Validation functions typically examine the structure of the new docu-
ment to ensure that required fields are present and to verify that the
requesting user should be allowed to make changes to the document prop-
erties. For example, an application may require that a user must be
authenticated in order to create a new document or that specific docu-
ment fields be present when a document is updated. The validation func-
tion can abort the pending document write by throwing one of two error
objects:

// user is not authorized to make the change but may re-authenticate
throw({ unauthorized: 'Error message here.' });

// change is not allowed
throw({ forbidden: 'Error message here.' });

Document validation is optional, and each design document in the data-
base may have at most one validation function. When a write request is
received for a given database, the validation function in each design
document in that database is called in an unspecified order. If any of
the validation functions throw an error, the write will not succeed.

Example: The _design/_auth ddoc from _users database uses a validation
function to ensure that documents contain some required fields and are
only modified by a user with the _admin role:

function(newDoc, oldDoc, userCtx, secObj) {
if (newDoc._deleted === true) {
// allow deletes by admins and matching users
// without checking the other fields
if ((userCtx.roles.indexOf('_admin') !== -1) ||
(userCtx.name == oldDoc.name)) {
return;
} else {
throw({forbidden: 'Only admins may delete other user docs.'});
}
}

if ((oldDoc && oldDoc.type !== 'user') || newDoc.type !== 'user') {
throw({forbidden : 'doc.type must be user'});
} // we only allow user docs for now

if (!newDoc.name) {
throw({forbidden: 'doc.name is required'});
}

if (!newDoc.roles) {
throw({forbidden: 'doc.roles must exist'});
}

if (!isArray(newDoc.roles)) {
throw({forbidden: 'doc.roles must be an array'});
}

if (newDoc._id !== ('org.couchdb.user:' + newDoc.name)) {
throw({
forbidden: 'Doc ID must be of the form org.couchdb.user:name'
});
}

if (oldDoc) { // validate all updates
if (oldDoc.name !== newDoc.name) {
throw({forbidden: 'Usernames can not be changed.'});
}
}

if (newDoc.password_sha && !newDoc.salt) {
throw({
forbidden: 'Users with password_sha must have a salt.' +
'See /_utils/script/couch.js for example code.'
});
}

var is_server_or_database_admin = function(userCtx, secObj) {
// see if the user is a server admin
if(userCtx.roles.indexOf('_admin') !== -1) {
return true; // a server admin
}

// see if the user a database admin specified by name
if(secObj && secObj.admins && secObj.admins.names) {
if(secObj.admins.names.indexOf(userCtx.name) !== -1) {
return true; // database admin
}
}

// see if the user a database admin specified by role
if(secObj && secObj.admins && secObj.admins.roles) {
var db_roles = secObj.admins.roles;
for(var idx = 0; idx < userCtx.roles.length; idx++) {
var user_role = userCtx.roles[idx];
if(db_roles.indexOf(user_role) !== -1) {
return true; // role matches!
}
}
}

return false; // default to no admin
}

if (!is_server_or_database_admin(userCtx, secObj)) {
if (oldDoc) { // validate non-admin updates
if (userCtx.name !== newDoc.name) {
throw({
forbidden: 'You may only update your own user document.'
});
}
// validate role updates
var oldRoles = oldDoc.roles.sort();
var newRoles = newDoc.roles.sort();

if (oldRoles.length !== newRoles.length) {
throw({forbidden: 'Only _admin may edit roles'});
}

for (var i = 0; i < oldRoles.length; i++) {
if (oldRoles[i] !== newRoles[i]) {
throw({forbidden: 'Only _admin may edit roles'});
}
}
} else if (newDoc.roles.length > 0) {
throw({forbidden: 'Only _admin may set roles'});
}
}

// no system roles in users db
for (var i = 0; i < newDoc.roles.length; i++) {
if (newDoc.roles[i][0] === '_') {
throw({
forbidden:
'No system roles (starting with underscore) in users db.'
});
}
}

// no system names as names
if (newDoc.name[0] === '_') {
throw({forbidden: 'Username may not start with underscore.'});
}

var badUserNameChars = [':'];

for (var i = 0; i < badUserNameChars.length; i++) {
if (newDoc.name.indexOf(badUserNameChars[i]) >= 0) {
throw({forbidden: 'Character `' + badUserNameChars[i] +
'` is not allowed in usernames.'});
}
}
}

NOTE:
The return statement is used only for function, it has no impact on
the validation process.

SEE ALSO:

CouchDB Guide:

• Validation Functions

Guide to Views
Views are the primary tool used for querying and reporting on CouchDB
documents. There youll learn how they work and how to use them to
build effective applications with CouchDB.

Introduction to Views
Views are useful for many purposes:

• Filtering the documents in your database to find those relevant to a
particular process.

• Extracting data from your documents and presenting it in a specific
order.

• Building efficient indexes to find documents by any value or struc-
ture that resides in them.

• Use these indexes to represent relationships among documents.

• Finally, with views you can make all sorts of calculations on the
data in your documents. For example, if documents represent your com-
panys financial transactions, a view can answer the question of what
the spending was in the last week, month, or year.

What Is a View?
Lets go through the different use cases. First is extracting data that
you might need for a special purpose in a specific order. For a front
page, we want a list of blog post titles sorted by date. Well work with
a set of example documents as we walk through how views work:

{
"_id":"biking",
"_rev":"AE19EBC7654",

"title":"Biking",
"body":"My biggest hobby is mountainbiking. The other day...",
"date":"2009/01/30 18:04:11"
}

{
"_id":"bought-a-cat",
"_rev":"4A3BBEE711",

"title":"Bought a Cat",
"body":"I went to the pet store earlier and brought home a little kitty...",
"date":"2009/02/17 21:13:39"
}

{
"_id":"hello-world",
"_rev":"43FBA4E7AB",

"title":"Hello World",
"body":"Well hello and welcome to my new blog...",
"date":"2009/01/15 15:52:20"
}

Three will do for the example. Note that the documents are sorted by
_id, which is how they are stored in the database. Now we define a
view. Bear with us without an explanation while we show you some code:

function(doc) {
if(doc.date && doc.title) {
emit(doc.date, doc.title);
}
}

This is a map function, and it is written in JavaScript. If you are not
familiar with JavaScript but have used C or any other C-like language
such as Java, PHP, or C#, this should look familiar. It is a simple
function definition.

You provide CouchDB with view functions as strings stored inside the
views field of a design document. To create this view you can use this
command:

curl -X PUT http://admin:password@127.0.0.1:5984/db/_design/my_ddoc
-d '{"views":{"my_filter":{"map":
"function(doc) { if(doc.date && doc.title) { emit(doc.date, doc.title); }}"}}}'

You dont run the JavaScript function yourself. Instead, when you query
your view, CouchDB takes the source code and runs it for you on every
document in the database your view was defined in. You query your view
to retrieve the view result using the following command:

curl -X GET http://admin:password@127.0.0.1:5984/db/_design/my_ddoc/_view/my_filter

All map functions have a single parameter doc. This is a single docu-
ment in the database. Our map function checks whether our document has
a date and a title attribute luckily, all of our documents have them
and then calls the built-in emit() function with these two attributes
as arguments.

The emit() function always takes two arguments: the first is key, and
the second is value. The emit(key, value) function creates an entry in
our view result. One more thing: the emit() function can be called mul-
tiple times in the map function to create multiple entries in the view
results from a single document, but we are not doing that yet.

CouchDB takes whatever you pass into the emit() function and puts it
into a list (see Table 1, View results below). Each row in that list
includes the key and value. More importantly, the list is sorted by key
(by doc.date in our case). The most important feature of a view result
is that it is sorted by key. We will come back to that over and over
again to do neat things. Stay tuned.

Table 1. View results:
+---------------------+--------------+
| Key | Value |
+---------------------+--------------+
| 2009/01/15 15:52:20 | Hello World |
+---------------------+--------------+
| 2009/01/30 18:04:11 | Biking |
+---------------------+--------------+
| 2009/02/17 21:13:39 | Bought a Cat |
+---------------------+--------------+

When you query your view, CouchDB takes the source code and runs it for
you on every document in the database. If you have a lot of documents,
that takes quite a bit of time and you might wonder if it is not horri-
bly inefficient to do this. Yes, it would be, but CouchDB is designed
to avoid any extra costs: it only runs through all documents once, when
you first query your view. If a document is changed, the map function
is only run once, to recompute the keys and values for that single doc-
ument.

The view result is stored in a B-tree, just like the structure that is
responsible for holding your documents. View B-trees are stored in
their own file, so that for high-performance CouchDB usage, you can
keep views on their own disk. The B-tree provides very fast lookups of
rows by key, as well as efficient streaming of rows in a key range. In
our example, a single view can answer all questions that involve time:
Give me all the blog posts from last week or last month or this year.
Pretty neat.

When we query our view, we get back a list of all documents sorted by
date. Each row also includes the post title so we can construct links
to posts. Table 1 is just a graphical representation of the view re-
sult. The actual result is JSON-encoded and contains a little more
metadata:

{
"total_rows": 3,
"offset": 0,
"rows": [
{
"key": "2009/01/15 15:52:20",
"id": "hello-world",
"value": "Hello World"
},

{
"key": "2009/01/30 18:04:11",
"id": "biking",
"value": "Biking"
},

{
"key": "2009/02/17 21:13:39",
"id": "bought-a-cat",
"value": "Bought a Cat"
}

]
}

Now, the actual result is not as nicely formatted and doesnt include
any superfluous whitespace or newlines, but this is better for you (and
us!) to read and understand. Where does that id member in the result
rows come from? That wasnt there before. Thats because we omitted it
earlier to avoid confusion. CouchDB automatically includes the document
ID of the document that created the entry in the view result. Well use
this as well when constructing links to the blog post pages.

WARNING:
Do not emit the entire document as the value of your emit(key,
value) statement unless youre sure you know you want it. This stores
an entire additional copy of your document in the views secondary
index. Views with emit(key, doc) take longer to update, longer to
write to disk, and consume significantly more disk space. The only
advantage is that they are faster to query than using the ?in-
clude_docs=true parameter when querying a view.

Consider the trade-offs before emitting the entire document. Often
it is sufficient to emit only a portion of the document, or just a
single key / value pair, in your views.

Efficient Lookups
Lets move on to the second use case for views: building efficient in-
dexes to find documents by any value or structure that resides in them.
We already explained the efficient indexing, but we skipped a few de-
tails. This is a good time to finish this discussion as we are looking
at map functions that are a little more complex.

First, back to the B-trees! We explained that the B-tree that backs the
key-sorted view result is built only once, when you first query a view,
and all subsequent queries will just read the B-tree instead of execut-
ing the map function for all documents again. What happens, though,
when you change a document, add a new one, or delete one? Easy: CouchDB
is smart enough to find the rows in the view result that were created
by a specific document. It marks them invalid so that they no longer
show up in view results. If the document was deleted, were good the
resulting B-tree reflects the state of the database. If a document got
updated, the new document is run through the map function and the re-
sulting new lines are inserted into the B-tree at the correct spots.
New documents are handled in the same way. The B-tree is a very effi-
cient data structure for our needs, and the crash-only design of
CouchDB databases is carried over to the view indexes as well.

To add one more point to the efficiency discussion: usually multiple
documents are updated between view queries. The mechanism explained in
the previous paragraph gets applied to all changes in the database
since the last time the view was queried in a batch operation, which
makes things even faster and is generally a better use of your re-
sources.

Find One
On to more complex map functions. We said find documents by any value
or structure that resides in them. We already explained how to extract
a value by which to sort a list of views (our date field). The same
mechanism is used for fast lookups. The URI to query to get a views re-
sult is /database/_design/designdocname/_view/viewname. This gives you
a list of all rows in the view. We have only three documents, so things
are small, but with thousands of documents, this can get long. You can
add view parameters to the URI to constrain the result set. Say we know
the date of a blog post. To find a single document, we would use
/blog/_design/docs/_view/by_date?key="2009/01/30 18:04:11" to get the
Biking blog post. Remember that you can place whatever you like in the
key parameter to the emit() function. Whatever you put in there, we can
now use to look up exactly and fast.

Note that in the case where multiple rows have the same key (perhaps we
design a view where the key is the name of the posts author), key
queries can return more than one row.

Find Many
We talked about getting all posts for last month. If its February now,
this is as easy as:

/blog/_design/docs/_view/by_date?startkey="2010/01/01 00:00:00"&endkey="2010/02/00 00:00:00"

The startkey and endkey parameters specify an inclusive range on which
we can search.

To make things a little nicer and to prepare for a future example, we
are going to change the format of our date field. Instead of a string,
we are going to use an array, where individual members are part of a
timestamp in decreasing significance. This sounds fancy, but it is
rather easy. Instead of:

{
"date": "2009/01/31 00:00:00"
}

we use:

{
"date": [2009, 1, 31, 0, 0, 0]
}

Our map function does not have to change for this, but our view result
looks a little different:

Table 2. New view results:
+---------------------------+--------------+
| Key | Value |
+---------------------------+--------------+
| [2009, 1, 15, 15, 52, 20] | Hello World |
+---------------------------+--------------+
| [2009, 2, 17, 21, 13, 39] | Biking |
+---------------------------+--------------+
| [2009, 1, 30, 18, 4, 11] | Bought a Cat |
+---------------------------+--------------+

And our queries change to:

/blog/_design/docs/_view/by_date?startkey=[2010, 1, 1, 0, 0, 0]&endkey=[2010, 2, 1, 0, 0, 0]

For all you care, this is just a change in syntax, not meaning. But it
shows you the power of views. Not only can you construct an index with
scalar values like strings and integers, you can also use JSON struc-
tures as keys for your views. Say we tag our documents with a list of
tags and want to see all tags, but we dont care for documents that have
not been tagged.

{
...
tags: ["cool", "freak", "plankton"],
...
}

{
...
tags: [],
...
}

function(doc) {
if(doc.tags.length > 0) {
for(var idx in doc.tags) {
emit(doc.tags[idx], null);
}
}
}

This shows a few new things. You can have conditions on structure
(if(doc.tags.length > 0)) instead of just values. This is also an exam-
ple of how a map function calls emit() multiple times per document.
And finally, you can pass null instead of a value to the value parame-
ter. The same is true for the key parameter. Well see in a bit how
that is useful.

Reversed Results
To retrieve view results in reverse order, use the descending=true
query parameter. If you are using a startkey parameter, you will find
that CouchDB returns different rows or no rows at all. Whats up with
that?

Its pretty easy to understand when you see how view query options work
under the hood. A view is stored in a tree structure for fast lookups.
Whenever you query a view, this is how CouchDB operates:

1. Starts reading at the top, or at the position that startkey speci-
fies, if present.

2. Returns one row at a time until the end or until it hits endkey, if
present.

If you specify descending=true, the reading direction is reversed, not
the sort order of the rows in the view. In addition, the same two-step
procedure is followed.

Say you have a view result that looks like this:
+-----+-------+
| Key | Value |
+-----+-------+
| 0 | foo |
+-----+-------+
| 1 | bar |
+-----+-------+
| 2 | baz |
+-----+-------+

Here are potential query options: ?startkey=1&descending=true. What
will CouchDB do? See #1 above: it jumps to startkey, which is the row
with the key 1, and starts reading backward until it hits the end of
the view. So the particular result would be:
+-----+-------+
| Key | Value |
+-----+-------+
| 1 | bar |
+-----+-------+
| 0 | foo |
+-----+-------+

This is very likely not what you want. To get the rows with the indexes
1 and 2 in reverse order, you need to switch the startkey to endkey:
endkey=1&descending=true:
+-----+-------+
| Key | Value |
+-----+-------+
| 2 | baz |
+-----+-------+
| 1 | bar |
+-----+-------+

Now that looks a lot better. CouchDB started reading at the bottom of
the view and went backward until it hit endkey.

The View to Get Comments for Posts
We use an array key here to support the group_level reduce query para-
meter. CouchDBs views are stored in the B-tree file structure. Because
of the way B-trees are structured, we can cache the intermediate reduce
results in the non-leaf nodes of the tree, so reduce queries can be
computed along arbitrary key ranges in logarithmic time. See Figure 1,
Comments map function.

In the blog app, we use group_level reduce queries to compute the count
of comments both on a per-post and total basis, achieved by querying
the same view index with different methods. With some array keys, and
assuming each key has the value 1:

["a","b","c"]
["a","b","e"]
["a","c","m"]
["b","a","c"]
["b","a","g"]

the reduce view:

function(keys, values, rereduce) {
return sum(values)
}

or:

_sum

which is a built-in CouchDB reduce function (the others are _count and
_stats). _sum here returns the total number of rows between the start
and end key. So with startkey=["a","b"]&endkey=["b"] (which includes
the first three of the above keys) the result would equal 3. The effect
is to count rows. If youd like to count rows without depending on the
row value, you can switch on the rereduce parameter:

function(keys, values, rereduce) {
if (rereduce) {
return sum(values);
} else {
return values.length;
}
}

NOTE:
The JavaScript function above could be effectively replaced by the
built-in _count.
[image: Comments map function] [image] Figure 1. Comments map func-
tion.UNINDENT

This is the reduce view used by the example app to count comments,
while utilizing the map to output the comments, which are more useful
than just 1 over and over. It pays to spend some time playing around
with map and reduce functions. Fauxton is OK for this, but it doesnt
give full access to all the query parameters. Writing your own test
code for views in your language of choice is a great way to explore
the nuances and capabilities of CouchDBs incremental MapReduce sys-
tem.

Anyway, with a group_level query, youre basically running a series of
reduce range queries: one for each group that shows up at the level
you query. Lets reprint the key list from earlier, grouped at level
1:

["a"] 3
["b"] 2

And at group_level=2:

["a","b"] 2
["a","c"] 1
["b","a"] 2

Using the parameter group=true makes it behave as though it were
group_level=999, so in the case of our current example, it would give
the number 1 for each key, as there are no exactly duplicated keys.

Reduce/Rereduce
We briefly talked about the rereduce parameter to the reduce function.
Well explain whats up with it in this section. By now, you should have
learned that your view result is stored in B-tree index structure for
efficiency. The existence and use of the rereduce parameter is tightly
coupled to how the B-tree index works.

Consider the map result are:

"afrikaans", 1
"afrikaans", 1
"chinese", 1
"chinese", 1
"chinese", 1
"chinese", 1
"french", 1
"italian", 1
"italian", 1
"spanish", 1
"vietnamese", 1
"vietnamese", 1

Example 1. Example view result (mmm, food)

When we want to find out how many dishes there are per origin, we can
reuse the simple reduce function shown earlier:

function(keys, values, rereduce) {
return sum(values);
}

Figure 2, The B-tree index shows a simplified version of what the
B-tree index looks like. We abbreviated the key strings.
[image: The B-tree index] [image] Figure 2. The B-tree index.UNINDENT

The view result is what computer science grads call a pre-order walk
through the tree. We look at each element in each node starting from
the left. Whenever we see that there is a subnode to descend into, we
descend and start reading the elements in that subnode. When we have
walked through the entire tree, were done.

You can see that CouchDB stores both keys and values inside each leaf
node. In our case, it is simply always 1, but you might have a value
where you count other results and then all rows have a different
value. Whats important is that CouchDB runs all elements that are
within a node into the reduce function (setting the rereduce parame-
ter to false) and stores the result inside the parent node along with
the edge to the subnode. In our case, each edge has a 3 representing
the reduce value for the node it points to.

NOTE:
In reality, nodes have more than 1,600 elements in them. CouchDB
computes the result for all the elements in multiple iterations over
the elements in a single node, not all at once (which would be dis-
astrous for memory consumption).

Now lets see what happens when we run a query. We want to know how many
chinese entries we have. The query option is simple: ?key="chinese".
See Figure 3, The B-tree index reduce result.
[image: The B-tree index reduce result] [image] Figure 3. The B-tree
index reduce result.UNINDENT

CouchDB detects that all values in the subnode include the chinese
key. It concludes that it can take just the 3 values associated with
that node to compute the final result. It then finds the node left to
it and sees that its a node with keys outside the requested range
(key= requests a range where the beginning and the end are the same
value). It concludes that it has to use the chinese elements value
and the other nodes value and run them through the reduce function
with the rereduce parameter set to true.

The reduce function effectively calculates 3 + 1 at query time and
returns the desired result. The next example shows some pseudocode
that shows the last invocation of the reduce function with actual
values:

function(null, [3, 1], true) {
return sum([3, 1]);
}

Now, we said your reduce function must actually reduce your values. If
you see the B-tree, it should become obvious what happens when you dont
reduce your values. Consider the following map result and reduce func-
tion. This time we want to get a list of all the unique labels in our
view:

"abc", "afrikaans"
"cef", "afrikaans"
"fhi", "chinese"
"hkl", "chinese"
"ino", "chinese"
"lqr", "chinese"
"mtu", "french"
"owx", "italian"
"qza", "italian"
"tdx", "spanish"
"xfg", "vietnamese"
"zul", "vietnamese"

We dont care for the key here and only list all the labels we have. Our
reduce function removes duplicates:

function(keys, values, rereduce) {
var unique_labels = {};
values.forEach(function(label) {
if(!unique_labels[label]) {
unique_labels[label] = true;
}
});

return unique_labels;
}

This translates to Figure 4, An overflowing reduce index.

We hope you get the picture. The way the B-tree storage works means
that if you dont actually reduce your data in the reduce function, you
end up having CouchDB copy huge amounts of data around that grow lin-
early, if not faster, with the number of rows in your view.

CouchDB will be able to compute the final result, but only for views
with a few rows. Anything larger will experience a ridiculously slow
view build time. To help with that, CouchDB since version 0.10.0 will
throw an error if your reduce function does not reduce its input val-
ues.
[image: An overflowing reduce index] [image] Figure 4. An overflowing
reduce index.UNINDENT

One vs. Multiple Design Documents
A common question is: when should I split multiple views into multiple
design documents, or keep them together?

Each view you create corresponds to one B-tree. All views in a single
design document will live in the same set of index files on disk (one
file per database shard; in 2.0+ by default, 8 files per node).

The most practical consideration for separating views into separate
documents is how often you change those views. Views that change often,
and are in the same design document as other views, will invalidate
those other views indexes when the design document is written, forcing
them all to rebuild from scratch. Obviously you will want to avoid this
in production!

However, when you have multiple views with the same map function in the
same design document, CouchDB will optimize and only calculate that map
function once. This lets you have two views with different reduce func-
tions (say, one with _sum and one with _stats) but build only a single
copy of the mapped index. It also saves disk space and the time to
write multiple copies to disk.

Another benefit of having multiple views in the same design document is
that the index files can keep a single index of backwards references
from docids to rows. CouchDB needs these back refs to invalidate rows
in a view when a document is deleted (otherwise, a delete would force a
total rebuild!)

One other consideration is that each separate design document will
spawn another (set of) couchjs processes to generate the view, one per
shard. Depending on the number of cores on your server(s), this may be
efficient (using all of the idle cores you have) or inefficient (over-
loading the CPU on your servers). The exact situation will depend on
your deployment architecture.

So, should you use one or multiple design documents? The choice is
yours.

Lessons Learned
• If you dont use the key field in the map function, you are probably
doing it wrong.

• If you are trying to make a list of values unique in the reduce func-
tions, you are probably doing it wrong.

• If you dont reduce your values to a single scalar value or a small
fixed-sized object or array with a fixed number of scalar values of
small sizes, you are probably doing it wrong.

Wrapping Up
Map functions are side effectfree functions that take a document as ar-
gument and emit key/value pairs. CouchDB stores the emitted rows by
constructing a sorted B-tree index, so row lookups by key, as well as
streaming operations across a range of rows, can be accomplished in a
small memory and processing footprint, while writes avoid seeks. Gener-
ating a view takes O(N), where N is the total number of rows in the
view. However, querying a view is very quick, as the B-tree remains
shallow even when it contains many, many keys.

Reduce functions operate on the sorted rows emitted by map view func-
tions. CouchDBs reduce functionality takes advantage of one of the
fundamental properties of B-tree indexes: for every leaf node (a sorted
row), there is a chain of internal nodes reaching back to the root.
Each leaf node in the B-tree carries a few rows (on the order of tens,
depending on row size), and each internal node may link to a few leaf
nodes or other internal nodes.

The reduce function is run on every node in the tree in order to calcu-
late the final reduce value. The end result is a reduce function that
can be incrementally updated upon changes to the map function, while
recalculating the reduction values for a minimum number of nodes. The
initial reduction is calculated once per each node (inner and leaf) in
the tree.

When run on leaf nodes (which contain actual map rows), the reduce
functions third parameter, rereduce, is false. The arguments in this
case are the keys and values as output by the map function. The func-
tion has a single returned reduction value, which is stored on the in-
ner node that a working set of leaf nodes have in common, and is used
as a cache in future reduce calculations.

When the reduce function is run on inner nodes, the rereduce flag is
true. This allows the function to account for the fact that it will be
receiving its own prior output. When rereduce is true, the values
passed to the function are intermediate reduction values as cached from
previous calculations. When the tree is more than two levels deep, the
rereduce phase is repeated, consuming chunks of the previous levels
output until the final reduce value is calculated at the root node.

A common mistake new CouchDB users make is attempting to construct com-
plex aggregate values with a reduce function. Full reductions should
result in a scalar value, like 5, and not, for instance, a JSON hash
with a set of unique keys and the count of each. The problem with this
approach is that youll end up with a very large final value. The number
of unique keys can be nearly as large as the number of total keys, even
for a large set. It is fine to combine a few scalar calculations into
one reduce function; for instance, to find the total, average, and
standard deviation of a set of numbers in a single function.

If youre interested in pushing the edge of CouchDBs incremental reduce
functionality, have a look at Googles paper on Sawzall, which gives ex-
amples of some of the more exotic reductions that can be accomplished
in a system with similar constraints.

Views Collation
Basics
View functions specify a key and a value to be returned for each row.
CouchDB collates the view rows by this key. In the following example,
the LastName property serves as the key, thus the result will be sorted
by LastName:

function(doc) {
if (doc.Type == "customer") {
emit(doc.LastName, {FirstName: doc.FirstName, Address: doc.Address});
}
}

CouchDB allows arbitrary JSON structures to be used as keys. You can
use JSON arrays as keys for fine-grained control over sorting and
grouping.

Examples
The following clever trick would return both customer and order docu-
ments. The key is composed of a customer _id and a sorting token. Be-
cause the key for order documents begins with the _id of a customer
document, all the orders will be sorted by customer. Because the sort-
ing token for customers is lower than the token for orders, the cus-
tomer document will come before the associated orders. The values 0 and
1 for the sorting token are arbitrary.

function(doc) {
if (doc.Type == "customer") {
emit([doc._id, 0], null);
} else if (doc.Type == "order") {
emit([doc.customer_id, 1], null);
}
}

To list a specific customer with _id XYZ, and all of that customers or-
ders, limit the startkey and endkey ranges to cover only documents for
that customers _id:

startkey=["XYZ"]&endkey=["XYZ", {}]

It is not recommended to emit the document itself in the view. Instead,
to include the bodies of the documents when requesting the view, re-
quest the view with ?include_docs=true.

Sorting by Dates
It maybe be convenient to store date attributes in a human readable
format (i.e. as a string), but still sort by date. This can be done by
converting the date to a number in the emit() function. For example,
given a document with a created_at attribute of 'Wed Jul 23 16:29:21
+0100 2013', the following emit function would sort by date:

emit(Date.parse(doc.created_at).getTime(), null);

Alternatively, if you use a date format which sorts lexicographically,
such as "2013/06/09 13:52:11 +0000" you can just

emit(doc.created_at, null);

and avoid the conversion. As a bonus, this date format is compatible
with the JavaScript date parser, so you can use new Date(doc.cre-
ated_at) in your client side JavaScript to make date sorting easy in
the browser.

String Ranges
If you need start and end keys that encompass every string with a given
prefix, it is better to use a high value Unicode character, than to use
a 'ZZZZ' suffix.

That is, rather than:

startkey="abc"&endkey="abcZZZZZZZZZ"

You should use:

startkey="abc"&endkey="abc\ufff0"

Collation Specification
This section is based on the view_collation function in -
view_collation.js:

// special values sort before all other types
null
false
true

// then numbers
1
2
3.0
4

// then text, case sensitive
"a"
"A"
"aa"
"b"
"B"
"ba"
"bb"

// then arrays. compared element by element until different.
// Longer arrays sort after their prefixes
["a"]
["b"]
["b","c"]
["b","c", "a"]
["b","d"]
["b","d", "e"]

// then object, compares each key value in the list until different.
// larger objects sort after their subset objects.
{a:1}
{a:2}
{b:1}
{b:2}
{b:2, a:1} // Member order does matter for collation.
// CouchDB preserves member order
// but doesn't require that clients will.
// this test might fail if used with a js engine
// that doesn't preserve order
{b:2, c:2}

Comparison of strings is done using ICU which implements the Unicode
Collation Algorithm, giving a dictionary sorting of keys. This can
give surprising results if you were expecting ASCII ordering. Note
that:

• All symbols sort before numbers and letters (even the high symbols
like tilde, 0x7e)

• Differing sequences of letters are compared without regard to case,
so a < aa but also A < aa and a < AA

• Identical sequences of letters are compared with regard to case, with
lowercase before uppercase, so a < A

You can demonstrate the collation sequence for 7-bit ASCII characters
like this:

require 'rubygems'
require 'restclient'
require 'json'

DB="http://adm:pass@127.0.0.1:5984/collator"

RestClient.delete DB rescue nil
RestClient.put "#{DB}",""

(32..126).each do |c|
RestClient.put "#{DB}/#{c.to_s(16)}", {"x"=>c.chr}.to_json
end

RestClient.put "#{DB}/_design/test", <<EOS
{
"views":{
"one":{
"map":"function (doc) { emit(doc.x,null); }"
}
}
}
EOS

puts RestClient.get("#{DB}/_design/test/_view/one")

This shows the collation sequence to be:

` ^ _ - , ; : ! ? . ' " ( ) [ ] { } @ * / \ & # % + < = > | ~ $ 0 1 2 3 4 5 6 7 8 9
a A b B c C d D e E f F g G h H i I j J k K l L m M n N o O p P q Q r R s S t T u U v V w W x X y Y z Z

Key ranges
Take special care when querying key ranges. For example: the query:

startkey="Abc"&endkey="AbcZZZZ"

will match ABC and abc1, but not abc. This is because UCA sorts as:

abc < Abc < ABC < abc1 < AbcZZZZZ

For most applications, to avoid problems you should lowercase the
startkey:

startkey="abc"&endkey="abcZZZZZZZZ"

will match all keys starting with [aA][bB][cC]

Complex keys
The query startkey=["foo"]&endkey=["foo",{}] will match most array keys
with foo in the first element, such as ["foo","bar"] and
["foo",["bar","baz"]]. However it will not match ["foo",{"an":"ob-
ject"}]

_all_docs
The _all_docs view is a special case because it uses ASCII collation
for doc ids, not UCA:

startkey="_design/"&endkey="_design/ZZZZZZZZ"

will not find _design/abc because Z comes before a in the ASCII se-
quence. A better solution is:

startkey="_design/"&endkey="_design0"

Raw collation
To squeeze a little more performance out of views, you can specify "op-
tions":{"collation":"raw"} within the view definition for native Er-
lang collation, especially if you dont require UCA. This gives a dif-
ferent collation sequence:

1
false
null
true
{"a":"a"},
["a"]
"a"

Beware that {} is no longer a suitable high key sentinel value. Use a
string like "\ufff0" instead.

Joins With Views
Linked Documents
If your map function emits an object value which has {'_id': XXX} and
you query view with include_docs=true parameter, then CouchDB will
fetch the document with id XXX rather than the document which was
processed to emit the key/value pair.

This means that if one document contains the ids of other documents, it
can cause those documents to be fetched in the view too, adjacent to
the same key if required.

For example, if you have the following hierarchically-linked documents:

[
{ "_id": "11111" },
{ "_id": "22222", "ancestors": ["11111"], "value": "hello" },
{ "_id": "33333", "ancestors": ["22222","11111"], "value": "world" }
]

You can emit the values with the ancestor documents adjacent to them in
the view like this:

function(doc) {
if (doc.value) {
emit([doc.value, 0], null);
if (doc.ancestors) {
for (var i in doc.ancestors) {
emit([doc.value, Number(i)+1], {_id: doc.ancestors[i]});
}
}
}
}

The result you get is:

{
"total_rows": 5,
"offset": 0,
"rows": [
{
"id": "22222",
"key": [
"hello",
0
],
"value": null,
"doc": {
"_id": "22222",
"_rev": "1-0eee81fecb5aa4f51e285c621271ff02",
"ancestors": [
"11111"
],
"value": "hello"
}
},
{
"id": "22222",
"key": [
"hello",
1
],
"value": {
"_id": "11111"
},
"doc": {
"_id": "11111",
"_rev": "1-967a00dff5e02add41819138abb3284d"
}
},
{
"id": "33333",
"key": [
"world",
0
],
"value": null,
"doc": {
"_id": "33333",
"_rev": "1-11e42b44fdb3d3784602eca7c0332a43",
"ancestors": [
"22222",
"11111"
],
"value": "world"
}
},
{
"id": "33333",
"key": [
"world",
1
],
"value": {
"_id": "22222"
},
"doc": {
"_id": "22222",
"_rev": "1-0eee81fecb5aa4f51e285c621271ff02",
"ancestors": [
"11111"
],
"value": "hello"
}
},
{
"id": "33333",
"key": [
"world",
2
],
"value": {
"_id": "11111"
},
"doc": {
"_id": "11111",
"_rev": "1-967a00dff5e02add41819138abb3284d"
}
}
]
}

which makes it very cheap to fetch a document plus all its ancestors in
one query.

Note that the "id" in the row is still that of the originating docu-
ment. The only difference is that include_docs fetches a different
doc.

The current revision of the document is resolved at query time, not at
the time the view is generated. This means that if a new revision of
the linked document is added later, it will appear in view queries even
though the view itself hasnt changed. To force a specific revision of a
linked document to be used, emit a "_rev" property as well as "_id".

Using View Collation
Author Christopher Lenz

Date 2007-10-05

Source http://www.cmlenz.net/archives/2007/10/couchdb-joins

Just today, there was a discussion on IRC on how youd go about modeling
a simple blogging system with post and comment entities, where any blog
post might have N comments. If youd be using an SQL database, youd ob-
viously have two tables with foreign keys and youd be using joins. (At
least until you needed to add some denormalization).

But what would the obvious approach in CouchDB look like?

Approach #1: Comments Inlined
A simple approach would be to have one document per blog post, and
store the comments inside that document:

{
"_id": "myslug",
"_rev": "123456",
"author": "john",
"title": "My blog post",
"content": "Bla bla bla ",
"comments": [
{"author": "jack", "content": ""},
{"author": "jane", "content": ""}
]
}

NOTE:
Of course the model of an actual blogging system would be more ex-
tensive, youd have tags, timestamps, etc, etc. This is just to
demonstrate the basics.

The obvious advantage of this approach is that the data that belongs
together is stored in one place. Delete the post, and you automatically
delete the corresponding comments, and so on.

You may be thinking that putting the comments inside the blog post doc-
ument would not allow us to query for the comments themselves, but youd
be wrong. You could trivially write a CouchDB view that would return
all comments across all blog posts, keyed by author:

function(doc) {
for (var i in doc.comments) {
emit(doc.comments[i].author, doc.comments[i].content);
}
}

Now you could list all comments by a particular user by invoking the
view and passing it a ?key="username" query string parameter.

However, this approach has a drawback that can be quite significant for
many applications: To add a comment to a post, you need to:

• Fetch the blog post document

• Add the new comment to the JSON structure

• Send the updated document to the server

Now if you have multiple client processes adding comments at roughly
the same time, some of them will get a HTTP 409 Conflict error on step
3 (thats optimistic concurrency in action). For some applications this
makes sense, but in many other apps, youd want to append new related
data regardless of whether other data has been added in the meantime.

The only way to allow non-conflicting addition of related data is by
putting that related data into separate documents.

Approach #2: Comments Separate
Using this approach youd have one document per blog post, and one docu-
ment per comment. The comment documents would have a backlink to the
post they belong to.

The blog post document would look similar to the above, minus the com-
ments property. Also, wed now have a type property on all our documents
so that we can tell the difference between posts and comments:

{
"_id": "myslug",
"_rev": "123456",
"type": "post",
"author": "john",
"title": "My blog post",
"content": "Bla bla bla "
}

The comments themselves are stored in separate documents, which also
have a type property (this time with the value comment), and addition-
ally feature a post property containing the ID of the post document
they belong to:

{
"_id": "ABCDEF",
"_rev": "123456",
"type": "comment",
"post": "myslug",
"author": "jack",
"content": ""
}

{
"_id": "DEFABC",
"_rev": "123456",
"type": "comment",
"post": "myslug",
"author": "jane",
"content": ""
}

To list all comments per blog post, youd add a simple view, keyed by
blog post ID:

function(doc) {
if (doc.type == "comment") {
emit(doc.post, {author: doc.author, content: doc.content});
}
}

And youd invoke that view passing it a ?key="post_id" query string pa-
rameter.

Viewing all comments by author is just as easy as before:

function(doc) {
if (doc.type == "comment") {
emit(doc.author, {post: doc.post, content: doc.content});
}
}

So this is better in some ways, but it also has a disadvantage. Imag-
ine you want to display a blog post with all the associated comments on
the same web page. With our first approach, we needed just a single re-
quest to the CouchDB server, namely a GET request to the document. With
this second approach, we need two requests: a GET request to the post
document, and a GET request to the view that returns all comments for
the post.

That is okay, but not quite satisfactory. Just imagine you wanted to
add threaded comments: youd now need an additional fetch per comment.
What wed probably want then would be a way to join the blog post and
the various comments together to be able to retrieve them with a single
HTTP request.

This was when Damien Katz, the author of CouchDB, chimed in to the dis-
cussion on IRC to show us the way.

Optimization: Using the Power of View Collation
Obvious to Damien, but not at all obvious to the rest of us: its fairly
simple to make a view that includes both the content of the blog post
document, and the content of all the comments associated with that
post. The way you do that is by using complex keys. Until now weve been
using simple string values for the view keys, but in fact they can be
arbitrary JSON values, so lets make some use of that:

function(doc) {
if (doc.type == "post") {
emit([doc._id, 0], null);
} else if (doc.type == "comment") {
emit([doc.post, 1], null);
}
}

Okay, this may be confusing at first. Lets take a step back and look at
what views in CouchDB are really about.

CouchDB views are basically highly efficient on-disk dictionaries that
map keys to values, where the key is automatically indexed and can be
used to filter and/or sort the results you get back from your views.
When you invoke a view, you can say that youre only interested in a
subset of the view rows by specifying a ?key=foo query string parame-
ter. Or you can specify ?startkey=foo and/or ?endkey=bar query string
parameters to fetch rows over a range of keys. Finally, by adding ?in-
clude_docs=true to the query, the result will include the full body of
each emitted document.

Its also important to note that keys are always used for collating
(i.e. sorting) the rows. CouchDB has well defined (but as of yet un-
documented) rules for comparing arbitrary JSON objects for collation.
For example, the JSON value ["foo", 2] is sorted after (considered
greater than) the values ["foo"] or ["foo", 1, "bar"], but before e.g.
["foo", 2, "bar"]. This feature enables a whole class of tricks that
are rather non-obvious

SEE ALSO:

• Homebrew

FreeBSD
FreeBSD requires the use of GNU Make. Where make is specified in this
documentation, substitute gmake.

You can install this by running:

pkg install gmake

Installing
Once you have satisfied the dependencies you should run:

./configure

If you wish to customize the installation, pass --help to this script.

If everything was successful you should see the following message:

You have configured Apache CouchDB, time to relax.

Relax.

To build CouchDB you should run:

make release

Try gmake if make is giving you any problems.

If include paths or other compiler options must be specified, they can
be passed to rebar, which compiles CouchDB, with the ERL_CFLAGS envi-
ronment variable. Likewise, options may be passed to the linker with
the ERL_LDFLAGS environment variable:

make release ERL_CFLAGS="-I/usr/local/include/js -I/usr/local/lib/erlang/usr/include"

If everything was successful you should see the following message:

... done
You can now copy the rel/couchdb directory anywhere on your system.
Start CouchDB with ./bin/couchdb from within that directory.

Relax.

Note: a fully-fledged ./configure with the usual GNU Autotools options
for package managers and a corresponding make install are in develop-
ment, but not part of the 2.0.0 release.

User Registration and Security
For OS X, in the steps below, substitute /Users/couchdb for
/home/couchdb.

You should create a special couchdb user for CouchDB.

On many Unix-like systems you can run:

adduser --system \
--shell /bin/bash \
--group --gecos \
"CouchDB Administrator" couchdb

On Mac OS X you can use the Workgroup Manager to create users up to
version 10.9, and dscl or sysadminctl after version 10.9. Search Apples
support site to find the documentation appropriate for your system. As
of recent versions of OS X, this functionality is also included in
Server.app, available through the App Store only as part of OS X
Server.

You must make sure that the user has a working POSIX shell and a
writable home directory.

You can test this by:

• Trying to log in as the couchdb user

• Running pwd and checking the present working directory

As a recommendation, copy the rel/couchdb directory into /home/couchdb
or /Users/couchdb.

Ex: copy the built couchdb release to the new users home directory:

cp -R /path/to/couchdb/rel/couchdb /home/couchdb

Change the ownership of the CouchDB directories by running:

chown -R couchdb:couchdb /home/couchdb

Change the permission of the CouchDB directories by running:

find /home/couchdb -type d -exec chmod 0770 {} \;

Update the permissions for your ini files:

chmod 0644 /home/couchdb/etc/*

First Run
NOTE:
Be sure to create an admin user before trying to start CouchDB!

You can start the CouchDB server by running:

sudo -i -u couchdb /home/couchdb/bin/couchdb

This uses the sudo command to run the couchdb command as the couchdb
user.

When CouchDB starts it should eventually display following messages:

{database_does_not_exist,[{mem3_shards,load_shards_from_db,"_users" ...

Dont be afraid, we will fix this in a moment.

To check that everything has worked, point your web browser to:

http://127.0.0.1:5984/_utils/index.html

From here you should verify your installation by pointing your web
browser to:

http://localhost:5984/_utils/index.html#verifyinstall

Your installation is not complete. Be sure to complete the Setup steps
for a single node or clustered installation.

Running as a Daemon
CouchDB no longer ships with any daemonization scripts.

The CouchDB team recommends runit to run CouchDB persistently and reli-
ably. According to official site:
runit is a cross-platform Unix init scheme with service supervision,
a replacement for sysvinit, and other init schemes. It runs on
GNU/Linux, *BSD, MacOSX, Solaris, and can easily be adapted to other
Unix operating systems.

Configuration of runit is straightforward; if you have questions, con-
tact the CouchDB user mailing list or IRC-channel #couchdb in FreeNode
network.

Lets consider configuring runit on Ubuntu 18.04. The following steps
should be considered only as an example. Details will vary by operating
system and distribution. Check your systems package management tools
for specifics.

Install runit:

sudo apt-get install runit

Create a directory where logs will be written:

sudo mkdir /var/log/couchdb
sudo chown couchdb:couchdb /var/log/couchdb

Create directories that will contain runit configuration for CouchDB:

sudo mkdir /etc/sv/couchdb
sudo mkdir /etc/sv/couchdb/log

Create /etc/sv/couchdb/log/run script:

#!/bin/sh
exec svlogd -tt /var/log/couchdb

Basically it determines where and how exactly logs will be written.
See man svlogd for more details.

Create /etc/sv/couchdb/run:

#!/bin/sh
export HOME=/home/couchdb
exec 2>&1
exec chpst -u couchdb /home/couchdb/bin/couchdb

This script determines how exactly CouchDB will be launched. Feel free
to add any additional arguments and environment variables here if nec-
essary.

Make scripts executable:

sudo chmod u+x /etc/sv/couchdb/log/run
sudo chmod u+x /etc/sv/couchdb/run

Then run:

sudo ln -s /etc/sv/couchdb/ /etc/service/couchdb

In a few seconds runit will discover a new symlink and start CouchDB.
You can control CouchDB service like this:

sudo sv status couchdb
sudo sv stop couchdb
sudo sv start couchdb

Naturally now CouchDB will start automatically shortly after system
starts.

You can also configure systemd, launchd or SysV-init daemons to launch
CouchDB and keep it running using standard configuration files. Consult
your system documentation for more information.

Installation on Windows
There are two ways to install CouchDB on Windows.

Installation from binaries
This is the simplest way to go.

WARNING:
Windows 8, 8.1, and 10 require the .NET Framework v3.5 to be in-
stalled.

1. Get the latest Windows binaries from the CouchDB web site. Old re-
leases are available at archive.

2. Follow the installation wizard steps. Be sure to install CouchDB to
a path with no spaces, such as C:\CouchDB.

3. Your installation is not complete. Be sure to complete the Setup
steps for a single node or clustered installation.

4. Open up Fauxton

5. Its time to Relax!

NOTE:
In some cases you might been asked to reboot Windows to complete in-
stallation process, because of using on different Microsoft Visual
C++ runtimes by CouchDB.

NOTE:
Upgrading note

Its recommended to uninstall previous CouchDB version before upgrad-
ing, especially if the new one is built against different Erlang re-
lease. The reason is simple: there may be leftover libraries with
alternative or incompatible versions from old Erlang release that
may create conflicts, errors and weird crashes.

In this case, make sure you backup of your local.ini config and
CouchDB database/index files.

Silent Install
The Windows installer supports silent installs. Here are some sample
commands, supporting the new features of the 3.0 installer.

Install CouchDB without a service, but with an admin user:password of
admin:hunter2:

msiexec /i apache-couchdb-3.0.0.msi /quiet ADMINUSER=admin ADMINPASSWORD=hunter2 /norestart

The same as above, but also install and launch CouchDB as a service:

msiexec /i apache-couchdb-3.0.0.msi /quiet INSTALLSERVICE=1 ADMINUSER=admin ADMINPASSWORD=hunter2 /norestart

Unattended uninstall of CouchDB to target directory D:CouchDB:

msiexec /x apache-couchdb-3.0.0.msi INSTALLSERVICE=1 APPLICATIONFOLDER="D:\CouchDB" ADMINUSER=admin ADMINPASSWORD=hunter2 /quiet /norestart

Unattended uninstall if the installer file is unavailable:

msiexec /x {4CD776E0-FADF-4831-AF56-E80E39F34CFC} /quiet /norestart

Add /l* log.txt to any of the above to generate a useful logfile for
debugging.

Installation from sources
SEE ALSO:
Glazier: Automate building of CouchDB from source on Windows

Installation on macOS
Installation using the Apache CouchDB native application
The easiest way to run CouchDB on macOS is through the native macOS ap-
plication. Just follow the below instructions:

1. Download Apache CouchDB for macOS. Old releases are available at -
archive.

2. Double click on the Zip file

3. Drag and drop the Apache CouchDB.app into Applications folder

Thats all, now CouchDB is installed on your Mac:

1. Run Apache CouchDB application

2. Open up Fauxton, the CouchDB admin interface

3. Verify the install by clicking on Verify, then Verify Installation.

4. Your installation is not complete. Be sure to complete the Setup
steps for a single node or clustered installation.

5. Time to Relax!

Installation with Homebrew
CouchDB can be installed via Homebrew. Fetch the newest version of
Homebrew and all formulae and install CouchDB with the following com-
mands:

brew update
brew install couchdb

Installation from source
Installation on macOS is possible from source. Download the source tar-
ball, extract it, and follow the instructions in the INSTALL.Unix.md
file.

Running as a Daemon
CouchDB itself no longer ships with any daemonization scripts.

The CouchDB team recommends runit to run CouchDB persistently and reli-
ably. Configuration of runit is straightforward; if you have questions,
reach out to the CouchDB user mailing list.

Naturally, you can configure launchd or other init daemons to launch
CouchDB and keep it running using standard configuration files.

Consult your system documentation for more information.

Installation on FreeBSD
Installation
Use the pre-built binary packages to install CouchDB:

pkg install couchdb3

Alternatively, it is possible installing CouchDB from the Ports Collec-
tion:

cd /usr/ports/databases/couchdb3
make install clean

NOTE:
Be sure to create an admin user before starting CouchDB for the
first time!

Service Configuration
The port is shipped with a script that integrates CouchDB with FreeBSDs
rc.d service framework. The following options for /etc/rc.conf or
/etc/rc.conf.local are supported (defaults shown):

couchdb3_enable="NO"
couchdb3_user="couchdb"
couchdb3_erl_flags="-couch_ini /usr/local/libexec/couchdb3/etc/default.ini /usr/local/etc/couchdb3/local.ini"
couchdb3_chdir="/var/db/couchdb3"

After enabling the couchdb3 service (by setting couchdb3_enable to
"YES"), use the following command to start CouchDB:

service couchdb3 start

This script responds to the arguments start, stop, status, rcvar etc.
If the service is not yet enabled in rc.conf, use onestart to start it
up ad-hoc.

The service will also use settings from the following config files:

• /usr/local/libexec/couchdb3/etc/default.ini

• /usr/local/etc/couchdb3/local.ini

The default.ini should be left read-only, and will be replaced on up-
grades and re-installs without warning. Therefore administrators
should use default.ini as a reference and only modify the local.ini
file.

Post Install
The installation is not complete. Be sure to complete the Setup steps
for a single node or clustered installation.

Also note that the port will probably show some messages after the in-
stallation happened. Make note of these instructions, although they
can be found in the ports tree for later reference.

Installation via Docker
Apache CouchDB provides convenience binary Docker images through Docker
Hub at apache/couchdb. This is our upstream release; it is usually mir-
rored downstream at Dockers top-level couchdb as well.

At least these tags are always available on the image:

• latest - always the latest

• 3: always the latest 3.x version

• 2: always the latest 2.x version

• 1, 1.7, 1.7.2: CouchDB 1.7.2 (convenience only; no longer supported)

• 1-couchperuser, 1.7-couchperuser, 1.7.2-couchperuser: CouchDB 1.7.2
with couchperuser plugin (convenience only; no longer supported)

These images expose CouchDB on port 5984 of the container, run every-
thing as user couchdb (uid 5984), and support use of a Docker volume
for data at /opt/couchdb/data.

Your installation is not complete. Be sure to complete the Setup steps
for a single node or clustered installation.

Further details on the Docker configuration are available in our -
couchdb-docker git repository.

Installation via Snap
Apache CouchDB provides convenience binary Snap builds through the
Ubuntu snapcraft repository under the name couchdb snap. These are
available in separate snap channels for each major/minor release
stream, e.g., 2.x, 3.3, and a latest stream.

Once youve completed installing snapd, you can install the CouchDB snap
via:

$ sudo snap install couchdb

After installation, set up an admin password and a cookie using a snap
hook. Then, restart the snap for changes to take effect:

$ sudo snap set couchdb admin=[your-password] setcookie=[your-cookie]
$ sudo snap restart couchdb

CouchDB will be installed (read only) at /snap/couchdb/current/. Data
files will be written to /var/snap/couchdb/common/data, and (writable)
configuration files will be stored in /var/snap/couchdb/current/etc.

NOTE:
Your installation is not complete. Follow the Setup steps for a sin-
gle node or clustered installation.

Snaps use AppArmor and are closely tied to systemd. They enforce that
only writable files are housed under /var/snap. Ensure that /var has
sufficient space for your data requirements.

To view logs, access them via journalctl snap.couchdb or using the snap
logs command:

$ sudo snap logs couchdb -f

When installing from a specific channel, snaps are automatically re-
freshed with new revisions. Revert to a previous installation with:

$ sudo snap revert couchdb

After this, updates will no longer be received. View installed snaps
and alternative channels using the list and info commands:

$ snap list
$ snap info couchdb

As easily as they are installed, snaps can be removed:

$ sudo snap remove couchdb
$ sudo snap remove couchdb --purge

The first command stops the server, removes couchdb from the list, and
the filesystem (keeping a backup for about 30 days if space permits).
If you reinstall couchdb, it tries to restore the backup. The second
command removes couchdb and purges any backups.

When troubleshooting couchdb snap, check the logs first. Youll likely
need to inspect /var/snap/couchdb/current/etc/local.ini to verify the
data directory or modify admin settings, port, or address bindings.
Also, anything related to Erlang runtime check /var/snap/couchdb/cur-
rent/etc/vm.args to view the erlang name.

The most common issue is couchdb not finding the database files. Ensure
that local.ini includes the following stanza and points to your data
files:

[couchdb]
;max_document_size = 4294967296 ; bytes
;os_process_timeout = 5000
database_dir = /var/snap/couchdb/common/data
view_index_dir = /var/snap/couchdb/common/data

NOTE:
Remember, you cannot modify the /snap/couchdb/ directory, even with
sudo, as the filesystem is mounted read-only for security reasons.

For additional details on the snap build process, refer to our -
couchdb-pkg git repository. This includes instructions on setting up a
cluster using the command line.

Installation on Kubernetes
Apache CouchDB provides a Helm chart to enable deployment to Kuber-
netes.

To install the chart with the release name my-release:

helm repo add couchdb https://apache.github.io/couchdb-helm

helm repo update

helm install --name my-release couchdb/couchdb

Further details on the configuration options are available in the Helm
chart readme.

Search Plugin Installation
Added in version 3.0.

CouchDB can build and query full-text search indexes using an external
Java service that embeds Apache Lucene. Typically, this service is in-
stalled on the same host as CouchDB and communicates with it over the
loopback network.

The search plugin is runtime-compatible with Java JDKs 6, 7 and 8.
Building a release from source requires JDK 6. It will not work with
any newer version of Java. Sorry about that.

Installation of Binary Packages
Binary packages that bundle all the necessary dependencies of the
search plugin are available on GitHub. The files in each release
should be unpacked into a directory on the Java classpath. If you do
not have a classpath already set, or you wish to explicitly set the
classpath location for Clouseau, then add the line:

-classpath '/path/to/clouseau/*'

to the server command below. If clouseau is installed in /opt/clouseau
the line would be:

-classpath '/opt/clouseau/*'

The service expects to find a couple of configuration files convention-
ally called clouseau.ini and log4j.properties with the following con-
tent:

clouseau.ini:

[clouseau]

; the name of the Erlang node created by the service, leave this unchanged
name=clouseau@127.0.0.1

; set this to the same distributed Erlang cookie used by the CouchDB nodes
cookie=brumbrum

; the path where you would like to store the search index files
dir=/path/to/index/storage

; the number of search indexes that can be open simultaneously
max_indexes_open=500

log4j.properties:

log4j.rootLogger=debug, CONSOLE
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d{ISO8601} %c [%p] %m%n

Once these files are in place the service can be started with an invo-
cation like the following:

java -server \
-Xmx2G \
-Dsun.net.inetaddr.ttl=30 \
-Dsun.net.inetaddr.negative.ttl=30 \
-Dlog4j.configuration=file:/path/to/log4j.properties \
-XX:OnOutOfMemoryError="kill -9 %p" \
-XX:+UseConcMarkSweepGC \
-XX:+CMSParallelRemarkEnabled \
com.cloudant.clouseau.Main \
/path/to/clouseau.ini

Chef
The CouchDB cookbook can build the search plugin from source and in-
stall it on a server alongside CouchDB.

Kubernetes
Users running CouchDB on Kubernetes via the Helm chart can add the
search service to each CouchDB Pod by setting enableSearch: true in the
chart values.

Additional Details
The Search User Guide provides detailed information on creating and
querying full-text indexes using this plugin.

The source code for the plugin and additional configuration documenta-
tion is available on GitHub at -
https://github.com/cloudant-labs/clouseau.

Nouveau Server Installation
Added in version 3.4.0.

Nouveau server is runtime-compatible with Java 11 or higher.

Enable Nouveau
You need to enable nouveau in CouchDB configuration;

[nouveau]
enable = true

Installation of Binary Packages
The Java side of nouveau is a set of jar files, one for nouveau itself
and the rest for dependencies (like Lucene and Dropwizard).

To start the nouveau server:

java -jar /path/to/nouveau.jar server /path/to/nouveau.yaml

Ensure that all the jar files from the release are in the same direc-
tory as nouveau.jar

We ship a basic nouveau.yaml configuration with useful defaults; see
that file for details.

nouveau.yaml:

maxIndexesOpen: 100
commitIntervalSeconds: 30
idleSeconds: 60
rootDir: target/indexes

As a DropWizard project you can also use the many configuration options
that it supports. See configuration reference.

By default Nouveau will attempt a clean shutdown if sent a TERM signal,
committing any outstanding index updates, completing any in-progress
segment merges, and finally closes all indexes. This is not essential
and you may safely kill the JVM without letting it do this, though any
uncommitted changes are necessarily lost. Once the JVM is started again
this indexing work will be attempted again.

Securing Nouveau
By default Nouveau uses HTTP without client authentication as it is
commonly deployed on the same server as CouchDB itself. It is however
possible to deploy Nouveau with robust security and this is strongly
recommended when Nouveau is running on a separate server, even over a
private network you trust.

To enforce secure communications between CouchDB and the Nouveau server
you need to modify configuration in both.

We use mutual TLS to achieve private communication and ensure the iden-
tity of client and server.

Configuring CouchDB to authenticate to Nouveau
You can configure CouchDB to connect to a secured Nouveau server as
follows;

[nouveau]
url = https://hostname:port
ssl_key_file = path to keyfile
ssl_cert_file = path to certfile
ssl_cacert_file = path to cacertfile
ssl_password = password

You must set ssl_key_file and ssl_cert_file to activate client certifi-
cates. You might also need to set ssl_password if the ssl_key_file is
password-protected and might need to set ssl_cacert_file if the Nouveau
servers certificate is signed by a private CA.

Configuring Nouveau to authenticate clients
Nouveau is built on the dropwizard framework, which directly supports
the HTTPS transport.

Acquiring or generating client and server certificates are out of scope
of this documentation and we assume they have been created from here
onward. We further assume the user can construct a Java keystore.

in nouveau.yaml you should remove all connectors of type h2c and add
new ones using h2;

server:
applicationConnectors:
- type: h2
port: 5987
keyStorePath: <path to keystore>
keyStorePassword: <password to keystore>
needClientAuth: true
validateCerts: true
validatePeers: true

If youre using self-generated certificates you will also need to set
the trustStorePath and trustStorePassword attributes.

Docker
There is a version of of the semi-official CouchDB Docker image avail-
able under the *-nouveau tags (eg, 3.4-nouveau).

Compose
A minimal CouchDB/Nouveau cluster can be create with this compose:

services:
couchdb:
image: couchdb:3
environment:
COUCHDB_USER: admin
COUCHDB_PASSWORD: admin
volumes:
- couchdb:/opt/couchdb/data
ports:
- 5984:5984
configs:
- source: nouveau.ini
target: /opt/couchdb/etc/local.d/nouveau.ini

nouveau:
image: couchdb:3-nouveau

volumes:
couchdb:

configs:
nouveau.ini:
content: |
[couchdb]
single_node=true
[nouveau]
enable = true
url = http://nouveau:5987

NOTE:
This is not production ready, but it is a quick way to get Nouveau
running.

Upgrading from prior CouchDB releases
Important Notes
• Always back up your data/ and etc/ directories prior to upgrading
CouchDB.

• We recommend that you overwrite your etc/default.ini file with the
version provided by the new release. New defaults sometimes contain
mandatory changes to enable default functionality. Always places your
customizations in etc/local.ini or any etc/local.d/*.ini file.

Upgrading from CouchDB 2.x
If you are coming from a prior release of CouchDB 2.x, upgrading is
simple.

Standalone (single) node upgrades
If you are running a standalone (single) CouchDB node:

1. Plan for downtime.

2. Backup everything.

3. Check for new recommended settings in the shipped etc/local.ini
file, and merge any changes desired into your own local settings
file(s).

4. Stop CouchDB.

5. Upgrade CouchDB in place.

6. Be sure to create an admin user if you do not have one. CouchDB 3.0+
require an admin user to start (the admin party has ended).

7. Start CouchDB.

8. Relax! Youre done.

Cluster upgrades
CouchDB 2.x and 3.x are explicitly designed to allow mixed clusters
during the upgrade process. This allows you to perform a rolling
restart across a cluster, upgrading one node at a time, for a zero
downtime upgrade. The process is also entirely scriptable within your
configuration management tool of choice.

Were proud of this feature, and you should be, too!

If you are running a CouchDB cluster:

1. Backup everything.

2. Check for new recommended settings in the shipped etc/local.ini
file, and merge any changes desired into your own local settings
file(s), staging these changes to occur as you upgrade the node.

3. Stop CouchDB on a single node.

4. Upgrade that CouchDB install in place.

5. Start CouchDB.

6. Double-check that the node has re-joined the cluster through the
/_membership endpoint. If your load balancer has health check func-
tionality driven by the /_up endpoint, check whether it thinks the
node is healthy as well.

7. Repeat the last 4 steps on the remaining nodes in the cluster.

8. Relax! Youre done.

Upgrading from CouchDB 1.x
To upgrade from CouchDB 1.x, first upgrade to a version of CouchDB 2.x.
You will need to convert all databases to CouchDB 2.x format first; see
the Upgrade Notes there for instructions. Then, upgrade to CouchDB 3.x.

Troubleshooting an Installation
First Install
If your CouchDB doesnt start after youve just installed, check the fol-
lowing things:

• On UNIX-like systems, this is usually this is a permissions issue.
Ensure that youve followed the User Registration and Security
chown/chmod commands. This problem is indicated by the presence of
the keyword eacces somewhere in the error output from CouchDB itself.

• Some Linux distributions split up Erlang into multiple packages. For
your distribution, check that you really installed all the required
Erlang modules. This varies from platform to platform, so youll just
have to work it out for yourself. For example, on recent versions of
Ubuntu/Debian, the erlang package includes all Erlang modules.

• Confirm that Erlang itself starts up with crypto (SSL) support:

## what version of erlang are you running? Ensure it is supported
erl -noshell -eval 'io:put_chars(erlang:system_info(otp_release)).' -s erlang halt
## are the erlang crypto (SSL) libraries working?
erl -noshell -eval 'case application:load(crypto) of ok -> io:put_chars("yay_crypto\n") ; _ -> exit(no_crypto) end.' -s init stop

• Next, identify where your Erlang CouchDB libraries are installed.
This will typically be the lib/ subdirectory of the release that you
have installed.

• Use this to start up Erlang with the CouchDB libraries in its path:

erl -env ERL_LIBS $ERL_LIBS:/path/to/couchdb/lib -couch_ini -s crypto

• In that Erlang shell, lets check that the key libraries are running.
The %% lines are comments, so you can skip them:

%% test SSL support. If this fails, ensure you have the OTP erlang-crypto library installed
crypto:md5_init().

%% test Snappy compression. If this fails, check your CouchDB configure script output or alternatively
%% if your distro comes with erlang-snappy make sure you're using only the CouchDB supplied version
snappy:compress("gogogogogogogogogogogogogogo").

%% test the CouchDB JSON encoder. CouchDB uses different encoders in each release, this one matches
%% what is used in 2.0.x.
jiffy:decode(jiffy:encode(<<"[1,2,3,4,5]">>)).

%% this is how you quit the erlang shell.
q().

• The output should resemble this, or an error will be thrown:

Erlang/OTP 17 [erts-6.2] [source] [64-bit] [smp:2:2] [async-threads:10] [kernel-poll:false]

Eshell V6.2 (abort with ^G)
1> crypto:md5_init().
<<1,35,69,103,137,171,205,239,254,220,186,152,118,84,50,
16,0,0,0,0,0,0,0,0,0,0,0,0,0,...>>
2> snappy:compress("gogogogogogogogogogogogogogo").
{ok,<<28,4,103,111,102,2,0>>}
3> jiffy:decode(jiffy:encode(<<"[1,2,3,4,5]">>)).
<<"[1,2,3,4,5]">>
4> q().

• At this point the only remaining dependency is your systems Unicode
support library, ICU, and the Spidermonkey Javascript VM from
Mozilla. Make sure that your LD_LIBRARY_PATH or equivalent for
non-Linux systems (DYLD_LIBRARY_PATH on macOS) makes these available
to CouchDB. Linux example running as normal user:

LD_LIBRARY_PATH=/usr/local/lib:/usr/local/spidermonkey/lib couchdb

Linux example running as couchdb user:

echo LD_LIBRARY_PATH=/usr/local/lib:/usr/local/spidermonkey/lib couchdb | sudo -u couchdb sh

• If you receive an error message including the key word eaddrinuse,
such as this:

Failure to start Mochiweb: eaddrinuse

edit your ``etc/default.ini`` or ``etc/local.ini`` file and change the
``[chttpd] port = 5984`` line to an available port.

• If you receive an error including the string:

OS Process Error {os_process_error,{exit_status,127}}

then it is likely your SpiderMonkey JavaScript VM installation is not
correct. Please recheck your build dependencies and try again.

• If you receive an error including the string:

OS Process Error {os_process_error,{exit_status,139}}

this is caused by the fact that SELinux blocks access to certain areas
of the file system. You must re-configure SELinux, or you can fully
disable SELinux using the command:

setenforce 0

• If you are still not able to get CouchDB to start at this point, keep
reading.

Quick Build
Having problems getting CouchDB to run for the first time? Follow this
simple procedure and report back to the user mailing list or IRC with
the output of each step. Please put the output of these steps into a
paste service (such as https://paste.ee/) rather than including the
output of your entire run in IRC or the mailing list directly.

1. Note down the name and version of your operating system and your
processor architecture.

2. Note down the installed versions of CouchDBs dependencies.

3. Follow the checkout instructions to get a fresh copy of CouchDBs
trunk.

4. Configure from the couchdb directory:

./configure

5. Build the release:

make release

6. Run the couchdb command and log the output:

cd rel/couchdb
bin/couchdb

7. Use your systems kernel trace tool and log the output of the above
command.

a. For example, linux systems should use strace:

strace bin/couchdb 2> strace.out

8. Report back to the mailing list (or IRC) with the output of each
step.

Upgrading
Are you upgrading from CouchDB 1.x? Install CouchDB into a fresh direc-
tory. CouchDBs directory layout has changed and may be confused by li-
braries present from previous releases.

Runtime Errors
Erlang stack trace contains system_limit, open_port, or emfile
Modern Erlang has a default limit of 65536 ports (8196 on Windows),
where each open file handle, tcp connection, and linked-in driver uses
one port. OSes have different soft and hard limits on the number of
open handles per process, often as low as 1024 or 4096 files. Youve
probably exceeded this.

There are two settings that need changing to increase this value. Con-
sult your OS documentation for how to increase the limit for your
process. Under Linux and systemd, this setting can be adjusted via sys-
temctl edit couchdb and adding the lines:

[Service]
LimitNOFILE=65536

to the file in the editor.

To increase this value higher than 65536, you must also add the Erlang
+Q parameter to your etc/vm.args file by adding the line:

+Q 102400

The old ERL_MAX_PORTS environment variable is ignored by the version of
Erlang supplied with CouchDB.

Lots of memory being used on startup
Is your CouchDB using a lot of memory (several hundred MB) on startup?
This one seems to especially affect Dreamhost installs. Its really an
issue with the Erlang VM pre-allocating data structures when ulimit is
very large or unlimited. A detailed discussion can be found on the er-
lang-questions list, but the short answer is that you should decrease
ulimit -n or lower the vm.args parameter +Q to something reasonable
like 1024.

The same issue can be manifested in some docker configurations which
default ulimit max files to unlimited. In those cases its also recom-
mended to set a lower nofile ulimit, something like 65536. In docker
compose files that can be done as:

ulimits:
nofiles: 65535

Function raised exception (Cannot encode undefined value as JSON)
If you see this in the CouchDB error logs, the JavaScript code you are
using for either a map or reduce function is referencing an object mem-
ber that is not defined in at least one document in your database. Con-
sider this document:

{
"_id":"XYZ123",
"_rev":"1BB2BB",
"field":"value"
}

and this map function:

function(doc) {
emit(doc.name, doc.address);
}

This will fail on the above document, as it does not contain a name or
address member. Instead, use guarding to make sure the function only
accesses members when they exist in a document:

function(doc) {
if(doc.name && doc.address) {
emit(doc.name, doc.address);
}
}

While the above guard will work in most cases, its worth bearing
JavaScripts understanding of false values in mind. Testing against a
property with a value of 0 (zero), '' (empty String), false or null
will return false. If this is undesired, a guard of the form if
(doc.foo !== undefined) should do the trick.

This error can also be caused if a reduce function does not return a
value. For example, this reduce function will cause an error:

function(key, values) {
sum(values);
}

The function needs to return a value:

function(key, values) {
return sum(values);
}

Erlang stack trace contains bad_utf8_character_code
CouchDB 1.1.1 and later contain stricter handling of UTF8 encoding. If
you are replicating from older versions to newer versions, then this
error may occur during replication.

A number of work-arounds exist; the simplest is to do an in-place up-
grade of the relevant CouchDB and then compact prior to replicating.

Alternatively, if the number of documents impacted is small, use fil-
tered replication to exclude only those documents.

FIPS mode
Operating systems can be configured to disallow the use of OpenSSL MD5
hash functions in order to prevent use of MD5 for cryptographic pur-
poses. CouchDB makes use of MD5 hashes for verifying the integrity of
data (and not for cryptography) and will not run without the ability to
use MD5 hashes.

The message below indicates that the operating system is running in
FIPS mode, which, among other restrictions, does not allow the use of
OpenSSLs MD5 functions:

md5_dgst.c(82): OpenSSL internal error, assertion failed: Digest MD5 forbidden in FIPS mode!
[os_mon] memory supervisor port (memsup): Erlang has closed
[os_mon] cpu supervisor port (cpu_sup): Erlang has closed
Aborted

A workaround for this is provided with the --erlang-md5 compile flag.
Use of the flag results in CouchDB substituting the OpenSSL MD5 func-
tion calls with equivalent calls to Erlangs built-in library er-
lang:md5. NOTE: there may be a performance penalty associated with this
workaround.

Because CouchDB does not make use of MD5 hashes for cryptographic pur-
poses, this workaround does not defeat the purpose of FIPS mode, pro-
vided that the system owner is aware of and consents to its use.

Debugging startup
If youve compiled from scratch and are having problems getting CouchDB
to even start up, you may want to see more detail. Start by enabling
logging at the debug level:

[log]
level = debug

You can then pass the -init_debug +W i +v +V -emu_args flags in the
ERL_FLAGS environment variable to turn on additional debugging informa-
tion that CouchDB developers can use to help you.

Then, reach out to the CouchDB development team using the links pro-
vided on the CouchDB home page for assistance.

macOS Known Issues
undefined error, exit_status 134
Sometimes the Verify Installation fails with an undefined error. This
could be due to a missing dependency with Mac. In the logs, you will
find couchdb exit_status,134.

Installing the missing nspr via brew install nspr resolves the issue.
(see: https://github.com/apache/couchdb/issues/979)

SETUP
CouchDB 2.x can be deployed in either a single-node or a clustered con-
figuration. This section covers the first-time setup steps required for
each of these configurations.

Single Node Setup
Many users simply need a single-node CouchDB 2.x installation. Opera-
tionally, it is roughly equivalent to the CouchDB 1.x series. Note that
a single-node setup obviously doesnt take any advantage of the new
scaling and fault-tolerance features in CouchDB 2.x.

After installation and initial startup, visit Fauxton at
http://127.0.0.1:5984/_utils#setup. You will be asked to set up CouchDB
as a single-node instance or set up a cluster. When you click Sin-
gle-Node-Setup, you will get asked for an admin username and password.
Choose them well and remember them.

You can also bind CouchDB to a public address, so it is accessible
within your LAN or the public, if you are doing this on a public VM.
Or, you can keep the installation private by binding only to 127.0.0.1
(localhost). Binding to 0.0.0.0 will bind to all addresses. The wizard
then configures your admin username and password and creates the three
system databases _users, _replicator and _global_changes for you.

Another option is to set the configuration parameter [couchdb] sin-
gle_node=true in your local.ini file. When doing this, CouchDB will
create the system database for you on restart.

Alternatively, if you dont want to use the Setup Wizard or set that
value, and run 3.x as a single node with a server administrator already
configured via config file, make sure to create the three system data-
bases manually on startup:

curl -X PUT http://adm:pass@127.0.0.1:5984/_users

curl -X PUT http://adm:pass@127.0.0.1:5984/_replicator

curl -X PUT http://adm:pass@127.0.0.1:5984/_global_changes

Note that the last of these is not necessary if you do not expect to be
using the global changes feed. Feel free to delete this database if you
have created it, it has grown in size, and you do not need the function
(and do not wish to waste system resources on compacting it regularly.)

Cluster Set Up
This section describes everything you need to know to prepare, install,
and set up your first CouchDB 2.x/3.x cluster.

CouchDB in clustered mode uses the port 5984, just as in a standalone
configuration. Port 5986, previously used in CouchDB 2.x, has been re-
moved in CouchDB 3.x. All endpoints previously accessible at that port
are now available under the /_node/{node-name}/... hierarchy via the
primary 5984 port.

CouchDB uses Erlang-native clustering functionality to achieve a clus-
tered installation. Erlang uses TCP port 4369 (EPMD) to find other
nodes, so all servers must be able to speak to each other on this port.
In an Erlang cluster, all nodes are connected to all other nodes, in a
mesh network configuration.

Every Erlang application running on that machine (such as CouchDB) then
uses automatically assigned ports for communication with other nodes.
Yes, this means random ports. This will obviously not work with a fire-
wall, but it is possible to force an Erlang application to use a spe-
cific port range.

This documentation will use the range TCP 9100-9200, but this range is
unnecessarily broad. If you only have a single Erlang application run-
ning on a machine, the range can be limited to a single port:
9100-9100, since the ports erlang assigns are for inbound connections
only. Three CouchDB nodes running on a single machine, as in a develop-
ment cluster scenario, would need three ports in this range.

WARNING:
If you expose the distribution port to the Internet or any other un-
trusted network, then the only thing protecting you is the Erlang -
cookie.

Configure and Test the Communication with Erlang
Make CouchDB use correct IP|FQDN and the open ports
In file etc/vm.args change the line -name couchdb@127.0.0.1 to -name
couchdb@<reachable-ip-address|fully-qualified-domain-name> which de-
fines the name of the node. Each node must have an identifier that al-
lows remote systems to talk to it. The node name is of the form
<name>@<reachable-ip-address|fully-qualified-domain-name>.

The name portion can be couchdb on all nodes, unless you are running
more than 1 CouchDB node on the same server with the same IP address or
domain name. In that case, we recommend names of couchdb1, couchdb2,
etc.

The second portion of the node name must be an identifier by which
other nodes can access this node either the nodes fully qualified do-
main name (FQDN) or the nodes IP address. The FQDN is preferred so that
you can renumber the nodes IP address without disruption to the clus-
ter. (This is common in cloud-hosted environments.)

WARNING:
Changing the name later is somewhat cumbersome (i.e. moving shards),
which is why you will want to set it once and not have to change it.

Open etc/vm.args, on all nodes, and add -kernel inet_dist_listen_min
9100 and -kernel inet_dist_listen_max 9200 like below:

-name ...
-setcookie ...
...
-kernel inet_dist_listen_min 9100
-kernel inet_dist_listen_max 9200

Again, a small range is fine, down to a single port (set both to 9100)
if you only ever run a single CouchDB node on each machine.

Confirming connectivity between nodes
For this test, you need 2 servers with working hostnames. Let us call
them server1.test.com and server2.test.com. They reside at 192.168.0.1
and 192.168.0.2, respectively.

On server1.test.com:

erl -name bus@192.168.0.1 -setcookie 'brumbrum' -kernel inet_dist_listen_min 9100 -kernel inet_dist_listen_max 9200

Then on server2.test.com:

erl -name car@192.168.0.2 -setcookie 'brumbrum' -kernel inet_dist_listen_min 9100 -kernel inet_dist_listen_max 9200

An explanation to the commands:

• erl the Erlang shell.

• -name bus@192.168.0.1 the name of the Erlang node and its IP
address or FQDN.

• -setcookie 'brumbrum' the password used when nodes connect to
each other.

• -kernel inet_dist_listen_min 9100 the lowest port in the
range.

• -kernel inet_dist_listen_max 9200 the highest port in the
range.

This gives us 2 Erlang shells. shell1 on server1, shell2 on server2.
Time to connect them. Enter the following, being sure to end the line
with a period (.):

In shell1:

net_kernel:connect_node('car@192.168.0.2').

This will connect to the node called car on the server called
192.168.0.2.

If that returns true, then you have an Erlang cluster, and the fire-
walls are open. This means that 2 CouchDB nodes on these two servers
will be able to communicate with each other successfully. If you get
false or nothing at all, then you have a problem with the firewall,
DNS, or your settings. Try again.

If youre concerned about firewall issues, or having trouble connecting
all nodes of your cluster later on, repeat the above test between all
pairs of servers to confirm connectivity and system configuration is
correct.

Preparing CouchDB nodes to be joined into a cluster
Before you can add nodes to form a cluster, you must have them listen-
ing on an IP address accessible from the other nodes in the cluster.
You should also ensure that a few critical settings are identical
across all nodes before joining them.

The settings we recommend you set now, before joining the nodes into a
cluster, are:

1. etc/vm.args settings as described in the previous two sections

2. At least one server administrator user (and password)

3. Bind the nodes clustered interface (port 5984) to a reachable IP ad-
dress

4. A consistent UUID. The UUID is used in identifying the cluster when
replicating. If this value is not consistent across all nodes in the
cluster, replications may be forced to rewind the changes feed to
zero, leading to excessive memory, CPU and network use.

5. A consistent httpd secret. The secret is used in calculating and
evaluating cookie and proxy authentication, and should be set con-
sistently to avoid unnecessary repeated session cookie requests.

As of CouchDB 3.0, steps 4 and 5 above are automatically performed for
you when using the setup API endpoints described below.

If you use a configuration management tool, such as Chef, Ansible, Pup-
pet, etc., then you can place these settings in a .ini file and dis-
tribute them to all nodes ahead of time. Be sure to pre-encrypt the
password (cutting and pasting from a test instance is easiest) if you
use this route to avoid CouchDB rewriting the file.

If you do not use configuration management, or are just experimenting
with CouchDB for the first time, use these commands once per server to
perform steps 2-4 above. Be sure to change the password to something
secure, and again, use the same password on all nodes. You may have to
run these commands locally on each node; if so, replace
<server-IP|FQDN> below with 127.0.0.1.

# First, get two UUIDs to use later on. Be sure to use the SAME UUIDs on all nodes.
curl http://<server-IP|FQDN>:5984/_uuids?count=2

# CouchDB will respond with something like:
# {"uuids":["60c9e8234dfba3e2fdab04bf92001142","60c9e8234dfba3e2fdab04bf92001cc2"]}
# Copy the provided UUIDs into your clipboard or a text editor for later use.
# Use the first UUID as the cluster UUID.
# Use the second UUID as the cluster shared http secret.

# Create the admin user and password:
curl -X PUT http://<server-IP|FQDN>:5984/_node/_local/_config/admins/admin -d '"password"'

# Now, bind the clustered interface to all IP addresses available on this machine
curl -X PUT http://<server-IP|FQDN>:5984/_node/_local/_config/chttpd/bind_address -d '"0.0.0.0"'

# If not using the setup wizard / API endpoint, the following 2 steps are required:
# Set the UUID of the node to the first UUID you previously obtained:
curl -X PUT http://<server-IP|FQDN>:5984/_node/_local/_config/couchdb/uuid -d '"FIRST-UUID-GOES-HERE"'

# Finally, set the shared http secret for cookie creation to the second UUID:
curl -X PUT http://<server-IP|FQDN>:5984/_node/_local/_config/chttpd_auth/secret -d '"SECOND-UUID-GOES-HERE"'

The Cluster Setup Wizard
CouchDB 2.x/3.x comes with a convenient Cluster Setup Wizard as part of
the Fauxton web administration interface. For first-time cluster setup,
and for experimentation, this is your best option.

It is strongly recommended that the minimum number of nodes in a clus-
ter is 3. For more explanation, see the Cluster Theory section of this
documentation.

After installation and initial start-up of all nodes in your cluster,
ensuring all nodes are reachable, and the pre-configuration steps
listed above, visit Fauxton at http://<server1>:5984/_utils#setup. You
will be asked to set up CouchDB as a single-node instance or set up a
cluster.

When you click Setup Cluster you are asked for admin credentials again,
and then to add nodes by IP address. To get more nodes, go through the
same install procedure for each node, using the same machine to perform
the setup process. Be sure to specify the total number of nodes you
expect to add to the cluster before adding nodes.

Now enter each nodes IP address or FQDN in the setup wizard, ensuring
you also enter the previously set server admin username and password.

Once you have added all nodes, click Setup and Fauxton will finish the
cluster configuration for you.

To check that all nodes have been joined correctly, visit
http://<server-IP|FQDN>:5984/_membership on each node. The returned
list should show all of the nodes in your cluster:

{
"all_nodes": [
"couchdb@server1.test.com",
"couchdb@server2.test.com",
"couchdb@server3.test.com"
],
"cluster_nodes": [
"couchdb@server1.test.com",
"couchdb@server2.test.com",
"couchdb@server3.test.com"
]
}

The cluster_nodes section is the list of expected nodes; the all_nodes
section is the list of actually connected nodes. Be sure the two lists
match.

Now your cluster is ready and available! You can send requests to any
one of the nodes, and all three will respond as if you are working with
a single CouchDB cluster.

For a proper production setup, youd now set up an HTTP reverse proxy in
front of the cluster, for load balancing and SSL termination. We recom-
mend HAProxy, but others can be used. Sample configurations are avail-
able in the Best Practices section.

The Cluster Setup API
If you would prefer to manually configure your CouchDB cluster, CouchDB
exposes the _cluster_setup endpoint for that purpose. After installa-
tion and initial setup/config, we can set up the cluster. On each node
we need to run the following command to set up the node:

curl -X POST -H "Content-Type: application/json" http://admin:password@127.0.0.1:5984/_cluster_setup -d '{"action": "enable_cluster", "bind_address":"0.0.0.0", "username": "admin", "password":"password", "node_count":"3"}'

After that we can join all the nodes together. Choose one node as the
setup coordination node to run all these commands on. This setup coor-
dination node only manages the setup and requires all other nodes to be
able to see it and vice versa. It has no special purpose beyond the
setup process; CouchDB does not have the concept of a primary node in a
cluster.

Setup will not work with unavailable nodes. All nodes must be online
and properly preconfigured before the cluster setup process can begin.

To join a node to the cluster, run these commands for each node you
want to add:

curl -X POST -H "Content-Type: application/json" http://admin:password@<setup-coordination-node>:5984/_cluster_setup -d '{"action": "enable_cluster", "bind_address":"0.0.0.0", "username": "admin", "password":"password", "port": 5984, "node_count": "3", "remote_node": "<remote-node-ip>", "remote_current_user": "<remote-node-username>", "remote_current_password": "<remote-node-password>" }'
curl -X POST -H "Content-Type: application/json" http://admin:password@<setup-coordination-node>:5984/_cluster_setup -d '{"action": "add_node", "host":"<remote-node-ip>", "port": <remote-node-port>, "username": "admin", "password":"password"}'

This will join the two nodes together. Keep running the above commands
for each node you want to add to the cluster. Once this is done run the
following command to complete the cluster setup and add the system
databases:

curl -X POST -H "Content-Type: application/json" http://admin:password@<setup-coordination-node>:5984/_cluster_setup -d '{"action": "finish_cluster"}'

Verify install:

curl http://admin:password@<setup-coordination-node>:5984/_cluster_setup

Response:

{"state":"cluster_finished"}

Verify all cluster nodes are connected:

curl http://admin:password@<setup-coordination-node>:5984/_membership

Response:

{
"all_nodes": [
"couchdb@couch1.test.com",
"couchdb@couch2.test.com",
"couchdb@couch3.test.com",
],
"cluster_nodes": [
"couchdb@couch1.test.com",
"couchdb@couch2.test.com",
"couchdb@couch3.test.com",
]
}

If the cluster is enabled and all_nodes and cluster_nodes lists dont
match, use curl to add nodes with PUT /_node/_lo-
cal/_nodes/couchdb@<reachable-ip-address|fully-qualified-domain-name>
and remove nodes with DELETE /_node/_local/_nodes/couchdb@<reach-
able-ip-address|fully-qualified-domain-name>

You CouchDB cluster is now set up.

CONFIGURATION
Introduction To Configuring
Configuration files
By default, CouchDB reads configuration files from the following loca-
tions, in the following order:

1. etc/default.ini

2. etc/default.d/*.ini

3. etc/local.ini

4. etc/local.d/*.ini

Configuration files in the *.d/ directories are sorted by name, that
means for example a file with the name etc/local.d/00-shared.ini is
loaded before etc/local.d/10-server-specific.ini.

All paths are specified relative to the CouchDB installation directory:
/opt/couchdb recommended on UNIX-like systems, C:\CouchDB recommended
on Windows systems, and a combination of two directories on macOS: Ap-
plications/Apache CouchDB.app/Contents/Resources/couchdbx-core/etc for
the default.ini and default.d directories, and one of
/Users/<your-user>/Library/Application Support/CouchDB2/etc/couchdb or
/Users/<your-user>/Library/Preferences/couchdb2-local.ini for the lo-
cal.ini and local.d directories.

Settings in successive documents override the settings in earlier en-
tries. For example, setting the chttpd/bind_address parameter in lo-
cal.ini would override any setting in default.ini.

WARNING:
The default.ini file may be overwritten during an upgrade or re-in-
stallation, so localised changes should be made to the local.ini
file or files within the local.d directory.

The configuration file chain may be changed by setting the ERL_FLAGS
environment variable:

export ERL_FLAGS="-couch_ini /path/to/my/default.ini /path/to/my/local.ini"

or by placing the -couch_ini .. flag directly in the etc/vm.args file.
Passing -couch_ini .. as a command-line argument when launching couchdb
is the same as setting the ERL_FLAGS environment variable.

WARNING:
The environment variable/command-line flag overrides any -couch_ini
option specified in the etc/vm.args file. And, BOTH of these options
completely override CouchDB from searching in the default locations.
Use these options only when necessary, and be sure to track the con-
tents of etc/default.ini, which may change in future releases.

If there is a need to use different vm.args or sys.config files, for
example, in different locations to the ones provided by CouchDB, or you
dont want to edit the original files, the default locations may be
changed by setting the COUCHDB_ARGS_FILE or COUCHDB_SYSCONFIG_FILE en-
vironment variables:

export COUCHDB_ARGS_FILE="/path/to/my/vm.args"
export COUCHDB_SYSCONFIG_FILE="/path/to/my/sys.config"

Parameter names and values
All parameter names are case-sensitive. Every parameter takes a value
of one of five types: boolean, integer, string, tuple and proplist.
Boolean values can be written as true or false.

Parameters with value type of tuple or proplist are following the Er-
lang requirement for style and naming.

Setting parameters via the configuration file
Changed in version 3.3: added ability to have = in parameter names

Changed in version 3.3: removed the undocumented ability to have
multi-line values.

The common way to set some parameters is to edit the local.ini file
(location explained above).

For example:

; This is a comment
[section]
param = value ; inline comments are allowed

Each configuration file line may contains section definition, parameter
specification, empty (space and newline characters only) or commented
line. You can set up inline commentaries for sections or parameters.

The section defines group of parameters that are belongs to some spe-
cific CouchDB subsystem. For instance, httpd section holds not only
HTTP server parameters, but also others that directly interacts with
it.

The parameter specification contains two parts divided by the equal
sign (=): the parameter name on the left side and the parameter value
on the right one. The leading and following whitespace for = is an op-
tional to improve configuration readability.

Since version 3.3 its possible to use = in parameter names, but only
when the parameter and value are separated `` = , i.e. the equal sign
is surrounded by at least one space on each side. This might be useful
in the ``[jwt_keys] section, where base64 encoded keys may contain some
= characters.

The semicolon (;) signals the start of a comment. Everything after this
character is ignored by CouchDB.

After editing the configuration file, CouchDB should be restarted to
apply any changes.

Setting parameters via the HTTP API
Alternatively, configuration parameters can be set via the HTTP API.
This API allows changing CouchDB configuration on-the-fly without re-
quiring a server restart:

curl -X PUT http://adm:pass@localhost:5984/_node/<name@host>/_config/uuids/algorithm -d '"random"'

The old parameters value is returned in the response:

"sequential"

You should be careful changing configuration via the HTTP API since its
possible to make CouchDB unreachable, for example, by changing the
chttpd/bind_address:

curl -X PUT http://adm:pass@localhost:5984/_node/<name@host>/_config/chttpd/bind_address -d '"10.10.0.128"'

If you make a typo or the specified IP address is not available from
your network, CouchDB will be unreachable. The only way to resolve this
will be to remote into the server, correct the config file, and restart
CouchDB. To protect yourself against such accidents you may set the
chttpd/config_whitelist of permitted configuration parameters for up-
dates via the HTTP API. Once this option is set, further changes to
non-whitelisted parameters must take place via the configuration file,
and in most cases, will also require a server restart before taking ef-
fect.

Configuring the local node
While the HTTP API allows configuring all nodes in the cluster, as a
convenience, you can use the literal string _local in place of the node
name, to interact with the local nodes configuration. For example:

curl -X PUT http://adm:pass@localhost:5984/_node/_local/_config/uuids/algorithm -d '"random"'

Base Configuration
Base CouchDB Options
[couchdb]

attachment_stream_buffer_size
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.

[couchdb]
attachment_stream_buffer_size = 4096

database_dir
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 de-
fault).

[couchdb]
database_dir = /var/lib/couchdb

default_security
Changed in version 3.0: admin_only is now the default.

Default security object for databases if not explicitly
set. When set to everyone, anyone can performs reads and
writes. When set to admin_only, only admins can read and
write. When set to admin_local, sharded databases can be
read and written by anyone but the shards can only be
read and written by admins.

[couchdb]
default_security = admin_only

enable_database_recovery
Enable this to only soft-delete databases when DELETE
/{db} DELETE requests are made. This will rename all
shards of the database with a suffix of the form <db-
name>.YMD.HMS.deleted.couchdb. You can then manually
delete these files later, as desired.

Default is false.

[couchdb]
enable_database_recovery = false

file_compression
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/de-
compressor

• deflate_N: use zlibs deflate; N is the compression
level which ranges from 1 (fastest, lowest compression
ratio) to 9 (slowest, highest compression ratio)

[couchdb]
file_compression = snappy

maintenance_mode
A CouchDB node may be put into two distinct maintenance
modes by setting this configuration parameter.

• true: The node will not respond to clustered requests
from other nodes and the /_up endpoint will return a
404 response.

• nolb: The /_up endpoint will return a 404 response.

• false: The node responds normally, /_up returns a 200
response.

It is expected that the administrator has configured a
load balancer in front of the CouchDB nodes in the clus-
ter. This load balancer should use the /_up endpoint to
determine whether or not to send HTTP requests to any
particular node. For HAProxy, the following config is ap-
propriate:

http-check disable-on-404
option httpchk GET /_up

max_dbs_open
This option places an upper bound on the number of data-
bases that can be open at once. CouchDB reference counts
database accesses internally and will close idle data-
bases 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.

[couchdb]
max_dbs_open = 100

max_document_size
Changed in version 3.0.0.

Limit maximum document body size. Size is calculated
based on the serialized Erlang representation of the JSON
document body, because that reflects more accurately the
amount of storage consumed on disk. In particular, this
limit does not include attachments.

HTTP requests which create or update documents will fail
with error code 413 if one or more documents is larger
than this configuration value.

In case of _update handlers, document size is checked af-
ter the transformation and right before being inserted
into the database.

[couchdb]
max_document_size = 8000000 ; bytes

WARNING:
Before version 2.1.0 this setting was implemented by
simply checking http request body sizes. For individ-
ual document updates via PUT that approximation was
close enough, however that is not the case for
_bulk_docs endpoint. After 2.1.0 a separate configura-
tion parameter was defined:
chttpd/max_http_request_size, which can be used to
limit maximum http request sizes. After upgrade, it is
advisable to review those settings and adjust them ac-
cordingly.

os_process_timeout
If an external process, such as a query server or exter-
nal process, runs for this amount of milliseconds 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.

[couchdb]
os_process_timeout = 5000 ; 5 sec

single_node
Added in version 3.0.0.

When this configuration setting is set to true, automati-
cally create the system databases on startup. Must be set
false for a clustered CouchDB installation.

uri_file
This file contains the full URI that can be used to ac-
cess this instance of CouchDB. It is used to help dis-
cover 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).

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

users_db_security_editable
Added in version 3.0.0.

When this configuration setting is set to false, reject
any attempts to modify the _users database security ob-
ject. Modification of this object is deprecated in 3.x
and will be completely disallowed in CouchDB 4.x.

users_db_suffix
Specifies the suffix (last component of a name) of the
system database for storing CouchDB users.

[couchdb]
users_db_suffix = _users

WARNING:
If you change the database name, do not forget to re-
move or clean up the old database, since it will no
longer be protected by CouchDB.

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

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

uuid Added in version 1.3.

Unique identifier for this CouchDB cluster.

[couchdb]
uuid = 0a959b9b8227188afc2ac26ccdf345a6

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

[couchdb]
view_index_dir = /var/lib/couchdb

write_xxhash_checksums
Added in version 3.4.

Changed in version 3.5.

Before version 3.4 the default value was false, and as of
version 3.5 it changed to true.

During reads, both xxHash and the legacy checksum algo-
rithm can be used to verify data integrity. And it would
still be possible to safely downgrade to version 3.4,
which would be able to verify both xxHash and legacy
checksums:

[couchdb]
write_xxhash_checksums = true

js_engine
Changed in version 3.4.

Select the default Javascript engine. Available options
are spidermonkey and quickjs. The default setting is spi-
dermonkey:

[couchdb]
js_engine = spidermonkey

Configuring Clustering
Cluster Options
[cluster]

Sets the default number of shards for newly created databases.
The default value, 2, splits a database into 2 separate parti-
tions.

[cluster]
q = 2

For systems with only a few, heavily accessed, large databases,
or for servers with many CPU cores, consider increasing this
value to 4 or 8.

The value of q can also be overridden on a per-DB basis, at DB
creation time.

SEE ALSO:
Views Collation

Using Limits and Skipping Rows
By default, views return all results. Thats ok when the number of re-
sults is small, but this may lead to problems when there are billions
results, since the client may have to read them all and consume all
available memory.

But its possible to reduce output result rows by specifying limit query
parameter. For example, retrieving the list of recipes using the by_ti-
tle view and limited to 5 returns only 5 records, while there are total
2667 records in view:

Request:

GET /recipes/_design/recipes/_view/by_title?limit=5 HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "9Q6Q2GZKPH8D5F8L7PB6DBSS9"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
"offset" : 0,
"rows" : [
{
"id" : "3-tiersalmonspinachandavocadoterrine",
"key" : "3-tier salmon, spinach and avocado terrine",
"value" : [
null,
"3-tier salmon, spinach and avocado terrine"
]
},
{
"id" : "Aberffrawcake",
"key" : "Aberffraw cake",
"value" : [
null,
"Aberffraw cake"
]
},
{
"id" : "Adukiandorangecasserole-microwave",
"key" : "Aduki and orange casserole - microwave",
"value" : [
null,
"Aduki and orange casserole - microwave"
]
},
{
"id" : "Aioli-garlicmayonnaise",
"key" : "Aioli - garlic mayonnaise",
"value" : [
null,
"Aioli - garlic mayonnaise"
]
},
{
"id" : "Alabamapeanutchicken",
"key" : "Alabama peanut chicken",
"value" : [
null,
"Alabama peanut chicken"
]
}
],
"total_rows" : 2667
}

To omit some records you may use skip query parameter:

Request:

GET /recipes/_design/recipes/_view/by_title?limit=3&skip=2 HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "H3G7YZSNIVRRHO5FXPE16NJHN"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
"offset" : 2,
"rows" : [
{
"id" : "Adukiandorangecasserole-microwave",
"key" : "Aduki and orange casserole - microwave",
"value" : [
null,
"Aduki and orange casserole - microwave"
]
},
{
"id" : "Aioli-garlicmayonnaise",
"key" : "Aioli - garlic mayonnaise",
"value" : [
null,
"Aioli - garlic mayonnaise"
]
},
{
"id" : "Alabamapeanutchicken",
"key" : "Alabama peanut chicken",
"value" : [
null,
"Alabama peanut chicken"
]
}
],
"total_rows" : 2667
}

WARNING:
Using limit and skip parameters is not recommended for results pagi-
nation. Read pagination recipe why its so and how to make it better.

Sending multiple queries to a view
Added in version 2.2.

POST /{db}/_design/{ddoc}/_view/{view}/queries
Executes multiple specified view queries against the view func-
tion from the specified design document.

Parameters

• db Database name

• ddoc Design document name

• view View function name

Request Headers

• Content-Type .INDENT 2.0

• application/json

• Accept .INDENT 2.0

• application/json

Request JSON Object

Response Headers

• Content-Type .INDENT 2.0

• application/json

• ETag Response signature

• Transfer-Encoding chunked

Response JSON Object

• results (array) An array of result objects - one for each
query. Each result object contains the same fields as the re-
sponse to a regular view request.

Status Codes

• 200 OK Request completed successfully

• 400 Bad Request Invalid request

• 401 Unauthorized Read permission required

• 403 Forbidden Insufficient permissions / Too many requests
with invalid credentials

• 404 Not Found Specified database, design document or view is
missing

• 500 Internal Server Error View function execution error

Request:

POST /recipes/_design/recipes/_view/by_title/queries HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:5984

{
"queries": [
{
"keys": [
"meatballs",
"spaghetti"
]
},
{
"limit": 3,
"skip": 2
}
]
}

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 20 Dec 2016 11:17:07 GMT
ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
"results" : [
{
"offset": 0,
"rows": [
{
"id": "SpaghettiWithMeatballs",
"key": "meatballs",
"value": 1
},
{
"id": "SpaghettiWithMeatballs",
"key": "spaghetti",
"value": 1
},
{
"id": "SpaghettiWithMeatballs",
"key": "tomato sauce",
"value": 1
}
],
"total_rows": 3
},
{
"offset" : 2,
"rows" : [
{
"id" : "Adukiandorangecasserole-microwave",
"key" : "Aduki and orange casserole - microwave",
"value" : [
null,
"Aduki and orange casserole - microwave"
]
},
{
"id" : "Aioli-garlicmayonnaise",
"key" : "Aioli - garlic mayonnaise",
"value" : [
null,
"Aioli - garlic mayonnaise"
]
},
{
"id" : "Alabamapeanutchicken",
"key" : "Alabama peanut chicken",
"value" : [
null,
"Alabama peanut chicken"
]
}
],
"total_rows" : 2667
}
]
}

/{db}/_design/{ddoc}/_search/{index}
WARNING:
Search endpoints require a running search plugin connected to each
cluster node. See Search Plugin Installation for details.

Added in version 3.0.

GET /{db}/_design/{ddoc}/_search/{index}
Executes a search request against the named index in the speci-
fied design document.

Parameters

• db Database name

• ddoc Design document name

• index Search index name

Request Headers

• Accept .INDENT 2.0

• application/json

• text/plain

Query Parameters

• bookmark (string) A bookmark received from a previous search.
This parameter enables paging through the results. If there
are no more results after the bookmark, you get a response
with an empty rows array and the same bookmark, confirming the
end of the result list.

• counts (json) An array of names of string fields for which
counts are requested. The response contains counts for each
unique value of this field name among the documents that match
the search query. Faceting must be enabled for this parameter
to function.

• drilldown (json) This field can be used several times. Each
use defines a pair with a field name and a value. The search
matches only documents containing the value that was provided
in the named field. It differs from using "fieldname:value" in
the q parameter only in that the values are not analyzed.
Faceting must be enabled for this parameter to function.

• group_field (string) Field by which to group search matches.
:query number group_limit: Maximum group count. This field can
be used only if group_field is specified.

• group_sort (json) This field defines the order of the groups
in a search that uses group_field. The default sort order is
relevance.

• highlight_fields (json) Specifies which fields to highlight.
If specified, the result object contains a highlights field
with an entry for each specified field.

• highlight_pre_tag (string) A string that is inserted before
the highlighted word in the highlights output.

• highlight_post_tag (string) A string that is inserted after
the highlighted word in the highlights output.

• highlight_number (number) Number of fragments that are re-
turned in highlights. If the search term occurs less often
than the number of fragments that are specified, longer frag-
ments are returned.

• highlight_size (number) Number of characters in each fragment
for highlights.

• include_docs (boolean) Include the full content of the docu-
ments in the response.

• include_fields (json) A JSON array of field names to include
in search results. Any fields that are included must be in-
dexed with the store:true option.

• limit (number) Limit the number of the returned documents to
the specified number. For a grouped search, this parameter
limits the number of documents per group.

• q (string) Alias for query.

• query (string) Required. The Lucene query string.

• ranges (json) This field defines ranges for faceted, numeric
search fields. The value is a JSON object where the fields
names are faceted numeric search fields, and the values of the
fields are JSON objects. The field names of the JSON objects
are names for ranges. The values are strings that describe the
range, for example [0 TO 10].

• sort (json) Specifies the sort order of the results. In a
grouped search (when group_field is used), this parameter
specifies the sort order within a group. The default sort or-
der is relevance. A JSON string of the form "fieldname<type>"
or -fieldname<type> for descending order, where fieldname is
the name of a string or number field, and type is either a
number, a string, or a JSON array of strings. The type part is
optional, and defaults to number. Some examples are "foo",
"-foo", "bar<string>", "-foo<number>" and ["-foo<number>",
"bar<string>"]. String fields that are used for sorting must
not be analyzed fields. Fields that are used for sorting must
be indexed by the same indexer that is used for the search
query.

• stale (string) Set to ok to allow the use of an out-of-date
index.

Response Headers

• Content-Type .INDENT 2.0

• application/json

• text/plain; charset=utf-8

• ETag Response signature

• Transfer-Encoding chunked

Response JSON Object

• rows (array) Array of view row objects. By default the infor-
mation returned contains only the document ID and revision.

• total_rows (number) Number of documents in the database/view.

• bookmark (string) Opaque identifier to enable pagination.

Status Codes

• 200 OK Request completed successfully

• 400 Bad Request Invalid request

• 401 Unauthorized Read permission required

• 403 Forbidden Insufficient permissions / Too many requests
with invalid credentials

• 404 Not Found Specified database, design document or view is
missed

NOTE:
You must enable faceting before you can use the counts, drilldown,
and ranges parameters.

NOTE:
Faceting and grouping are not supported on partitioned searches, so
the following query parameters should not be used on those requests:
counts, drilldown, ranges, and group_field, group_limit,
group_sort``.

SEE ALSO:
For more information about how search works, see the Search User
Guide.

/{db}/_design/{ddoc}/_search_info/{index}
WARNING:
Search endpoints require a running search plugin connected to each
cluster node. See Search Plugin Installation for details.

Added in version 3.0.

GET /{db}/_design/{ddoc}/_search_info/{index}

Parameters

• db Database name

• ddoc Design document name

• index Search index name

Status Codes

• 200 OK Request completed successfully

• 400 Bad Request Request body is wrong (malformed or
missing one of the mandatory fields)

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error A server error (or other
kind of error) occurred

Request:

GET /recipes/_design/cookbook/_search_info/ingredients HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"name": "_design/cookbook/ingredients",
"search_index": {
"pending_seq": 7125496,
"doc_del_count": 129180,
"doc_count": 1066173,
"disk_size": 728305827,
"committed_seq": 7125496
}
}

/{db}/_design/{ddoc}/_nouveau/{index}
WARNING:
Nouveau is an experimental feature. Future releases might change how
the endpoints work and might invalidate existing indexes.

WARNING:
Nouveau endpoints require a running nouveau server. See Nouveau
Server Installation for details.

Added in version 3.4.0.

GET /{db}/_design/{ddoc}/_nouveau/{index}
Executes a nouveau request against the named index in the speci-
fied design document.

Parameters

• db Database name

• ddoc Design document name

• index Nouveau index name

Request Headers

• Accept .INDENT 2.0

• application/json

Query Parameters

• include_docs (boolean) Include the full content of the docu-
ments in the response.

• locale (string) The (Java) locale used to parse numbers in
range queries. Defaults to the JDK default locale if not
specified. Some examples are de , us, gb.

• limit (number) Limit the number of the returned documents to
the specified number.

• q (string) Required. The Lucene query string.

• ranges (json) This field defines ranges for numeric search
fields. The value is a JSON object where the fields names are
numeric search fields, and the values of the fields are arrays
of JSON objects. The objects must have a label, min and max
value (of type string, number, number respectively), and op-
tional min_inclusive and max_inclusive properties (defaulting
to true if not specified). Example: {"bar":[{"la-
bel":"cheap","min":0,"max":100}]}

• sort (json) Specifies the sort order of the results. The de-
fault sort order is relevance. A JSON string of the form
"fieldname" or "-fieldname" for descending order, where field-
name is the name of a string or double field. You can use a
single string to sort by one field or an array of strings to
sort by several fields in the same order as the array. Some
examples are "relevance", "bar", "-foo" and ["-foo", "bar"].

• top_n (number) Limit the number of facets returned by group,
defaulting to 10 with a maximum of 1000.

• update (boolean) Set to false to allow the use of an
out-of-date index.

Response Headers

• Content-Type .INDENT 2.0

• application/json

• Transfer-Encoding chunked

Response JSON Object

• hits (array) Array of search hits. By default the information
returned contains only the document ID and revision.

• total_hits (number) Number of matches for the query.

• total_hits_relation (string) EQUAL_TO if total_hits is exact.
GREATER_THAN_OR_EQUAL_TO if not.

• bookmark (string) Opaque identifier to enable pagination.

Status Codes

• 200 OK Request completed successfully

• 400 Bad Request Invalid request

• 401 Unauthorized Read permission required

• 403 Forbidden Insufficient permissions / Too many requests
with invalid credentials

• 404 Not Found Specified database, design document or view is
missed

NOTE:
Faceting is not supported on partitioned searches, so the following
query parameters should not be used on those requests: counts and
ranges.

SEE ALSO:
For more information about how nouveau works, see the Nouveau User
Guide.

/{db}/_design/{ddoc}/_nouveau_info/{index}
WARNING:
Nouveau is an experimental feature. Future releases might change how
the endpoints work and might invalidate existing indexes.

WARNING:
Nouveau endpoints require a running nouveau server. See Nouveau
Server Installation for details.

Added in version 3.4.0.

GET /{db}/_design/{ddoc}/_nouveau_info/{index}

Parameters

• db Database name

• ddoc Design document name

• index Search index name

Status Codes

• 200 OK Request completed successfully

• 400 Bad Request Request body is wrong (malformed or
missing one of the mandatory fields)

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error A server error (or other
kind of error) occurred

Request:

GET /recipes/_design/cookbook/_nouveau_info/ingredients HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"name": "_design/cookbook/ingredients",
"search_index": {
"num_docs": 1000,
"update_seq": 5000,
"disk_size": 1048576
}
}

/{db}/_design/{ddoc}/_show/{func}
WARNING:
Show functions are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

GET /{db}/_design/{ddoc}/_show/{func}

POST /{db}/_design/{ddoc}/_show/{func}
Applies show function for null document.

The request and response parameters are depended upon function
implementation.

Parameters

• db Database name

• ddoc Design document name

• func Show function name

Response Headers

• ETag Response signature

Query Parameters

• format (string) Format of the returned response. Used
by provides() function

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error Query server error

Function:

function(doc, req) {
if (!doc) {
return {body: "no doc"}
} else {
return {body: doc.description}
}
}

Request:

GET /recipes/_design/recipe/_show/description HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Length: 6
Content-Type: text/html; charset=utf-8
Date: Wed, 21 Aug 2013 12:34:07 GMT
Etag: "7Z2TO7FPEMZ0F4GH0RJCRIOAU"
Server: CouchDB (Erlang/OTP)
Vary: Accept

no doc

/{db}/_design/{ddoc}/_show/{func}/{docid}
WARNING:
Show functions are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

GET /{db}/_design/{ddoc}/_show/{func}/{docid}

POST /{db}/_design/{ddoc}/_show/{func}/{docid}
Applies show function for the specified document.

The request and response parameters are depended upon function
implementation.

Parameters

• db Database name

• ddoc Design document name

• func Show function name

• docid Document ID

Response Headers

• ETag Response signature

Query Parameters

• format (string) Format of the returned response. Used
by provides() function

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error Query server error

Function:

function(doc, req) {
if (!doc) {
return {body: "no doc"}
} else {
return {body: doc.description}
}
}

Request:

GET /recipes/_design/recipe/_show/description/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Length: 88
Content-Type: text/html; charset=utf-8
Date: Wed, 21 Aug 2013 12:38:08 GMT
Etag: "8IEBO8103EI98HDZL5Z4I1T0C"
Server: CouchDB (Erlang/OTP)
Vary: Accept

An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.

/{db}/_design/{ddoc}/_list/{func}/{view}
WARNING:
List functions are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

GET /{db}/_design/{ddoc}/_list/{func}/{view}

POST /{db}/_design/{ddoc}/_list/{func}/{view}
Applies list function for the view function from the same design
document.

The request and response parameters are depended upon function
implementation.

Parameters

• db Database name

• ddoc Design document name

• func List function name

• view View function name

Response Headers

• ETag Response signature

• Transfer-Encoding chunked

Query Parameters

• format (string) Format of the returned response. Used
by provides() function

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error Query server error

Function:

function(head, req) {
var row = getRow();
if (!row){
return 'no ingredients'
}
send(row.key);
while(row=getRow()){
send(', ' + row.key);
}
}

Request:

GET /recipes/_design/recipe/_list/ingredients/by_name HTTP/1.1
Accept: text/plain
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Wed, 21 Aug 2013 12:49:15 GMT
Etag: "D52L2M1TKQYDD1Y8MEYJR8C84"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
Vary: Accept

meatballs, spaghetti, tomato sauce

/{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
WARNING:
List functions are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}

POST /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
Applies list function for the view function from the other de-
sign document.

The request and response parameters are depended upon function
implementation.

Parameters

• db Database name

• ddoc Design document name

• func List function name

• other-ddoc Other design document name that holds view
function

• view View function name

Response Headers

• ETag Response signature

• Transfer-Encoding chunked

Query Parameters

• format (string) Format of the returned response. Used
by provides() function

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error Query server error

Function:

function(head, req) {
var row = getRow();
if (!row){
return 'no ingredients'
}
send(row.key);
while(row=getRow()){
send(', ' + row.key);
}
}

Request:

GET /recipes/_design/ingredient/_list/ingredients/recipe/by_ingredient?key="spaghetti" HTTP/1.1
Accept: text/plain
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Wed, 21 Aug 2013 12:49:15 GMT
Etag: "5L0975X493R0FB5Z3043POZHD"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
Vary: Accept

spaghetti

/{db}/_design/{ddoc}/_update/{func}
POST /{db}/_design/{ddoc}/_update/{func}
Executes update function on server side for null document.

Parameters

• db Database name

• ddoc Design document name

• func Update function name

Response Headers

• X-Couch-Id Created/updated documents ID

• X-Couch-Update-NewRev Created/updated documents revi-
sion

Status Codes

• 200 OK No document was created or updated

• 201 Created Document was created or updated

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error Query server error

Function:

function(doc, req) {
if (!doc){
return [null, {'code': 400,
'json': {'error': 'missed',
'reason': 'no document to update'}}]
} else {
doc.ingredients.push(req.body);
return [doc, {'json': {'status': 'ok'}}];
}
}

Request:

POST /recipes/_design/recipe/_update/ingredients HTTP/1.1
Accept: application/json
Content-Length: 10
Content-Type: application/json
Host: localhost:5984

"something"

Response:

HTTP/1.1 404 Object Not Found
Cache-Control: must-revalidate
Content-Length: 52
Content-Type: application/json
Date: Wed, 21 Aug 2013 14:00:58 GMT
Server: CouchDB (Erlang/OTP)

{
"error": "missed",
"reason": "no document to update"
}

/{db}/_design/{ddoc}/_update/{func}/{docid}
PUT /{db}/_design/{ddoc}/_update/{func}/{docid}
Executes update function on server side for the specified docu-
ment.

Parameters

• db Database name

• ddoc Design document name

• func Update function name

• docid Document ID

Response Headers

• X-Couch-Id Created/updated documents ID

• X-Couch-Update-NewRev Created/updated documents revi-
sion

Status Codes

• 200 OK No document was created or updated

• 201 Created Document was created or updated

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

• 500 Internal Server Error Query server error

Function:

Request:

PUT /recipes/_design/recipe/_update/ingredients/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
Content-Length: 5
Content-Type: application/json
Host: localhost:5984

"love"

Response:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 16
Content-Type: application/json
Date: Wed, 21 Aug 2013 14:11:34 GMT
Server: CouchDB (Erlang/OTP)
X-Couch-Id: SpaghettiWithMeatballs
X-Couch-Update-NewRev: 12-a5e099df5720988dae90c8b664496baf

{
"status": "ok"
}

/{db}/_design/{ddoc}/_rewrite/{path}
WARNING:
Rewrites are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

ANY /{db}/_design/{ddoc}/_rewrite/{path}
Rewrites the specified path by rules defined in the specified
design document. The rewrite rules are defined by the rewrites
field of the design document. The rewrites field can either be a
string containing the a rewrite function or an array of rule de-
finitions.

Using a stringified function for rewrites
Added in version 2.0: When the rewrites field is a stringified func-
tion, the query server is used to pre-process and route requests.

The function takes a Request2 object.

The return value of the function will cause the server to rewrite the
request to a new location or immediately return a response.

To rewrite the request, return an object containing the following prop-
erties:

• path (string): Rewritten path.

• query (array): Rewritten query. If omitted, the original query keys
are used.

• headers (object): Rewritten headers. If omitted, the original request
headers are used.

• method (string): HTTP method of rewritten request ("GET", "POST",
etc). If omitted, the original request method is used.

• body (string): Body for "POST"/"PUT" requests. If omitted, the origi-
nal request body is used.

To immediately respond to the request, return an object containing the
following properties:

• code (number): Returned HTTP status code (200, 404, etc).

• body (string): Body of the response to user.

Example A. Restricting access.

function(req2) {
var path = req2.path.slice(4),
isWrite = /^(put|post|delete)$/i.test(req2.method),
isFinance = req2.userCtx.roles.indexOf("finance") > -1;
if (path[0] == "finance" && isWrite && !isFinance) {
// Deny writes to DB "finance" for users
// having no "finance" role
return {
code: 403,
body: JSON.stringify({
error: "forbidden".
reason: "You are not allowed to modify docs in this DB"
})
};
}
// Pass through all other requests
return { path: "../../../" + path.join("/") };
}

Example B. Different replies for JSON and HTML requests.

function(req2) {
var path = req2.path.slice(4),
h = headers,
wantsJson = (h.Accept || "").indexOf("application/json") > -1,
reply = {};
if (!wantsJson) {
// Here we should prepare reply object
// for plain HTML pages
} else {
// Pass through JSON requests
reply.path = "../../../"+path.join("/");
}
return reply;
}

Using an array of rules for rewrites
When the rewrites field is an array of rule objects, the server will
rewrite the request based on the first matching rule in the array.

Each rule in the array is an object with the following fields:

• method (string): HTTP request method to bind the request method to
the rule. If omitted, uses "*", which matches all methods.

• from (string): The pattern used to compare against the URL and de-
fine dynamic variables.

• to (string): The path to rewrite the URL to. It can contain vari-
ables depending on binding variables discovered during pattern
matching and query args (URL args and from the query member).

• query (object): Query args passed to the rewritten URL. They may
contain dynamic variables.

The to and from paths may contains string patterns with leading : or
* characters to define dynamic variables in the match.

The first rule in the rewrites array that matches the incoming re-
quest is used to define the rewrite. To match the incoming request,
the rules method must match the requests HTTP method and the rules
from must match the requests path using the following pattern match-
ing logic.

• The from pattern and URL are first split on / to get a list of to-
kens. For example, if from field is /somepath/:var/* and the URL
is /somepath/a/b/c, the tokens are somepath, :var, and * for the
from pattern and somepath, a, b, and c for the URL.

• Each token starting with : in the pattern will match the corre-
sponding token in the URL and define a new dynamic variable whose
name is the remaining string after the : and value is the token
from the URL. In this example, the :var token will match b and set
var = a.

• The star token * in the pattern will match any number of tokens in
the URL and must be the last token in the pattern. It will define
a dynamic variable with the remaining tokens. In this example, the
* token will match the b and c tokens and set * = b/c.

• The remaining tokens must match exactly for the pattern to be con-
sidered a match. In this example, somepath in the pattern matches
somepath in the URL and all tokens in the URL have matched, caus-
ing this rule to be a match.

Once a rule is found, the request URL is rewritten using the to and
query fields. Dynamic variables are substituted into the : and *
variables in these fields to produce the final URL.

If no rule matches, a 404 Not Found response is returned.

Examples:
+-------------------------------+----------+------------------+--------+
| Rule | URL | Rewrite to | Tokens |
+-------------------------------+----------+------------------+--------+
| | /a | /some | |
| {from: | | | |
| /a, to: | | | |
| /some} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b/c | /some/b/c | |
| {from: /a/*, | | | |
| to: | | | |
| /some/*} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b?k=v | /some?k=v | k=v |
| {from: /a/b, | | | |
| to: | | | |
| /some} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b | /some/b?var=b | var=b |
| {from: /a/b, | | | |
| to: | | | |
| /some/:var} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b/c | /some/b/c?foo=b | foo=b |
| {from: /a/:foo/, | | | |
| to: | | | |
| /some/:foo/} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b | /some/?k=b&foo=b | foo=b |
| {from: /a/:foo, | | | |
| to: /some, | | | |
| query: { k: | | | |
| :foo }} | | | |
+-------------------------------+----------+------------------+--------+
| | /a?foo=b | /some/?b&foo=b | foo=b |
| {from: /a, | | | |
| to: | | | |
| /some/:foo} | | | |
+-------------------------------+----------+------------------+--------+

Request method, header, query parameters, request payload and re-
sponse body are dependent on the endpoint to which the URL will be
rewritten.

param db
Database name

param ddoc
Design document name

param path
URL path to rewrite

Partitioned Databases
Partitioned databases allow for data colocation in a cluster, which
provides significant performance improvements for queries constrained
to a single partition.

See the guide for getting started with partitioned databases

/{db}/_partition/{partition_id}
GET /{db}/_partition/{partition_id}
This endpoint returns information describing the provided parti-
tion. It includes document and deleted document counts along
with external and active data sizes.

Parameters

• db Database name

• partition_id Name of the partition to query

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

Request:

GET /db/_partition/sensor-260 HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 119
Content-Type: application/json
Date: Thu, 24 Jan 2019 17:19:59 GMT
Server: CouchDB/2.3.0-a1e11cea9 (Erlang OTP/21)

{
"db_name": "my_new_db",
"doc_count": 1,
"doc_del_count": 0,
"partition": "sensor-260",
"sizes": {
"active": 244,
"external": 347
}
}

/{db}/_partition/{partition_id}/_all_docs
GET /{db}/_partition/{partition_id}/_all_docs
This endpoint is a convenience endpoint for automatically set-
ting bounds on the provided partition range. Similar results can
be had by using the global /db/_all_docs endpoint with appropri-
ately configured values for start_key and end_key.

Refer to the view endpoint documentation for a complete descrip-
tion of the available query parameters and the format of the re-
turned data.

Parameters

• db Database name

• partition_id Partition name

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

Request:

GET /db/_partition/sensor-260/_all_docs HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

{
"offset": 0,
"rows": [
{
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"key": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"value": {
"rev": "1-05ed6f7abf84250e213fcb847387f6f5"
}
}
],
"total_rows": 1
}

/{db}/_partition/{partition_id}/_design/{ddoc}/_view/{view}
GET /{db}/_partition/{partition_id}/_design/{ddoc}/_view/{view}
This endpoint is responsible for executing a partitioned query.
The returned view result will only contain rows with the speci-
fied partition name.

Refer to the view endpoint documentation for a complete descrip-
tion of the available query parameters and the format of the re-
turned data.

Parameters

• db Database name

• partition_id Partition name

• ddoc Design document id

• view View name

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

GET /db/_partition/sensor-260/_design/sensor-readings/_view/by_sensor HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

{
"offset": 0,
"rows": [
{
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"key": [
"sensor-260",
"0"
],
"value": null
},
{
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"key": [
"sensor-260",
"1"
],
"value": null
},
{
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"key": [
"sensor-260",
"2"
],
"value": null
},
{
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"key": [
"sensor-260",
"3"
],
"value": null
}
],
"total_rows": 4
}

/{db}/_partition/{partition_id}/_find
POST /{db}/_partition/{partition_id}/_find
This endpoint is responsible for finding a partition query by
its ID. The returned view result will only contain rows with
the specified partition id.

Refer to the find endpoint documentation for a complete descrip-
tion of the available parameters and the format of the returned
data.

Parameters

• db Database name

• partition_id Name of the partition to query

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

/{db}/_partition/{partition_id}/_explain
POST /{db}/_partition/{partition_id}/_explain
This endpoint shows which index is being used by the query.

Refer to the explain endpoint documentation for a complete de-
scription of the available parameters and the format of the re-
turned data.

Parameters

• db Database name

• partition_id Name of the partition to query

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

Local (non-replicating) Documents
The local (non-replicating) document interface allows you to create lo-
cal documents that are not replicated to other databases. These docu-
ments can be used to hold configuration or other information that is
required specifically on the local CouchDB instance.

Local documents have the following limitations:

• Local documents are not replicated to other databases.

• Local documents are not output by views, or the /{db}/_all_docs view.

From CouchDB 2.0, Local documents can be listed by using the
/{db}/_local_docs endpoint.

Local documents can be used when you want to store configuration or
other information for the current (local) instance of a given database.

A list of the available methods and URL paths are provided below:
+-----------+-------------------+---------------------+
| Method | Path | Description |
+-----------+-------------------+---------------------+
| GET, POST | /{db}/_local_docs | Returns a list of |
| | | all the non-repli- |
| | | cated documents in |
| | | the database |
+-----------+-------------------+---------------------+
| POST | /{db}/_lo- | Returns a list of |
| | cal_docs/queries | specified |
| | | non-replicated doc- |
| | | uments in the data- |
| | | base |
+-----------+-------------------+---------------------+
| GET | /{db}/_local/{do- | Returns the latest |
| | cid} | revision of the |
| | | non-replicated doc- |
| | | ument |
+-----------+-------------------+---------------------+
| PUT | /{db}/_local/{do- | Inserts a new ver- |
| | cid} | sion of the |
| | | non-replicated doc- |
| | | ument |
+-----------+-------------------+---------------------+
| DELETE | /{db}/_local/{do- | Deletes the |
| | cid} | non-replicated doc- |
| | | ument |
+-----------+-------------------+---------------------+
| COPY | /{db}/_local/{do- | Copies the |
| | cid} | non-replicated doc- |
| | | ument |
+-----------+-------------------+---------------------+

/{db}/_local_docs
GET /{db}/_local_docs
Returns a JSON structure of all of the local documents in a
given database. The information is returned as a JSON structure
containing meta information about the return structure, includ-
ing a list of all local documents and basic contents, consisting
the ID, revision and key. The key is the from the local docu-
ments _id.

Parameters

• db Database name

Request Headers

• Accept .INDENT 2.0

• application/json

• text/plain

Query Parameters

• conflicts (boolean) Includes conflicts information in re-
sponse. Ignored if include_docs isnt true. Default is false.

• descending (boolean) Return the local documents in descending
by key order. Default is false.

• endkey (string) Stop returning records when the specified key
is reached. Optional.

• end_key (string) Alias for endkey param.

• endkey_docid (string) Stop returning records when the speci-
fied local document ID is reached. Optional.

• end_key_doc_id (string) Alias for endkey_docid param.

• include_docs (boolean) Include the full content of the local
documents in the return. Default is false.

• inclusive_end (boolean) Specifies whether the specified end
key should be included in the result. Default is true.

• key (string) Return only local documents that match the spec-
ified key. Optional.

• keys (string) Return only local documents that match the
specified keys. Optional.

• limit (number) Limit the number of the returned local docu-
ments to the specified number. Optional.

• skip (number) Skip this number of records before starting to
return the results. Default is 0.

• startkey (string) Return records starting with the specified
key. Optional.

• start_key (string) Alias for startkey param.

• startkey_docid (string) Return records starting with the
specified local document ID. Optional.

• start_key_doc_id (string) Alias for startkey_docid param.

• update_seq (boolean) Response includes an update_seq value
indicating which sequence id of the underlying database the
view reflects. Default is false.

Response Headers

• Content-Type .INDENT 2.0

• application/json

• text/plain; charset=utf-8

Response JSON Object

• offset (number) Offset where the local document list started

• rows (array) Array of view row objects. By default the infor-
mation returned contains only the local document ID and revi-
sion.

• total_rows (number) Number of local documents in the data-
base. Note that this is not the number of rows returned in the
actual query.

• update_seq (number) Current update sequence for the database

Status Codes

• 200 OK Request completed successfully

• 401 Unauthorized Unauthorized request to a protected API

• 403 Forbidden Insufficient permissions / Too many requests
with invalid credentials

Request:

GET /db/_local_docs HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 23 Dec 2017 16:22:56 GMT
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
"offset": null,
"rows": [
{
"id": "_local/localdoc01",
"key": "_local/localdoc01",
"value": {
"rev": "0-1"
}
},
{
"id": "_local/localdoc02",
"key": "_local/localdoc02",
"value": {
"rev": "0-1"
}
},
{
"id": "_local/localdoc03",
"key": "_local/localdoc03",
"value": {
"rev": "0-1"
}
},
{
"id": "_local/localdoc04",
"key": "_local/localdoc04",
"value": {
"rev": "0-1"
}
},
{
"id": "_local/localdoc05",
"key": "_local/localdoc05",
"value": {
"rev": "0-1"
}
}
],
"total_rows": null
}

POST /{db}/_local_docs
POST /{db}/_local_docs functionality supports identical parame-
ters and behavior as specified in the GET /{db}/_local_docs API
but allows for the query string parameters to be supplied as
keys in a JSON object in the body of the POST request.

Parameters

• db Database name

Status Codes

• 401 Unauthorized Unauthorized request to a protected
API

• 403 Forbidden Insufficient permissions / Too many re-
quests with invalid credentials

Request:

POST /db/_local_docs HTTP/1.1
Accept: application/json
Content-Length: 70
Content-Type: application/json
Host: localhost:5984

{
"keys" : [
"_local/localdoc02",
"_local/localdoc05"
]
}

The returned JSON is the all documents structure, but with only
the selected keys in the output:

Response:

{
"total_rows" : null,
"rows" : [
{
"value" : {
"rev" : "0-1"
},
"id" : "_local/localdoc02",
"key" : "_local/localdoc02"
},
{
"value" : {
"rev" : "0-1"
},
"id" : "_local/localdoc05",
"key" : "_local/localdoc05"
}
],
"offset" : null
}

/{db}/_local_docs/queries
POST /{db}/_local_docs/queries
Querying with specified keys will return local documents only.
You can also combine keys with other query parameters, such as
limit and skip.

Parameters

• db Database name

Request Headers

• Content-Type .INDENT 2.0

• application/json

• Accept .INDENT 2.0

• application/json

Request JSON Object

Response Headers

• Content-Type .INDENT 2.0

• application/json

• text/plain; charset=utf-8

• Transfer-Encoding chunked

Response JSON Object

• results (array) An array of result objects - one for each
query. Each result object contains the same fields as the re-
sponse to a regular _local_docs request.

Status Codes

• 200 OK Request completed successfully

• 400 Bad Request Invalid request

• 401 Unauthorized Unauthorized request to a protected API

• 403 Forbidden Insufficient permissions / Too many requests
with invalid credentials

• 404 Not Found Specified database is missing

• 500 Internal Server Error Query execution error

Request:

POST /db/_local_docs/queries HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:5984

{
"queries": [
{
"keys": [
"_local/localdoc05",
"_local/not-exist",
"_design/recipe",
"spaghetti"
]
}
]
}

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Thu, 20 Jul 2023 21:45:37 GMT
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
"results": [
{
"total_rows": null,
"offset": null,
"rows": [
{
"id": "_local/localdoc05",
"key": "_local/localdoc05",
"value": {
"rev": "0-1"
}
},
{
"key": "_local/not-exist",
"error": "not_found"
}
]
},
{
"total_rows": null,
"offset": null,
"rows": [
{
"id": "_local/localdoc04",
"key": "_local/localdoc04",
"value": {
"rev": "0-1"
}
}
]
}
]
}

NOTE:
Similar to _design_docs/queries, /{db}/_local_docs/queries
will only return local documents. The difference is to-
tal_rows and offset are always null.

/{db}/_local/{docid}
GET /{db}/_local/{docid}
Gets the specified local document. The semantics are identical
to accessing a standard document in the specified database, ex-
cept that the document is not replicated. See GET /{db}/{docid}.

Parameters

• db Database name

• docid Document ID

PUT /{db}/_local/{docid}
Stores the specified local document. The semantics are identical
to storing a standard document in the specified database, except
that the document is not replicated. See PUT /{db}/{docid}.

Parameters

• db Database name

• docid Document ID

DELETE /{db}/_local/{docid}
Deletes the specified local document. The semantics are identi-
cal to deleting a standard document in the specified database,
except that the document is not replicated. See DELETE
/{db}/{docid}.

COPY /{db}/_local/{docid}
Copies the specified local document. The semantics are identical
to copying a standard document in the specified database, except
that the document is not replicated. See COPY /{db}/{docid}.

JSON STRUCTURE REFERENCE
The following appendix provides a quick reference to all the JSON
structures that you can supply to CouchDB, or get in return to re-
quests.

Design Document
+-------------------+--------------------------+
| Field | Description |
+-------------------+--------------------------+
| _id | Design Document ID |
+-------------------+--------------------------+
| _rev | Design Document Revision |
+-------------------+--------------------------+
| views | View |
+-------------------+--------------------------+
| viewname | View Definition |
+-------------------+--------------------------+
| map | Map Function for View |
+-------------------+--------------------------+
| reduce (optional) | Reduce Function for View |
+-------------------+--------------------------+

{
"body": "undefined",
"cookie": {
"AuthSession": "cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
"m": "3234"
},
"form": {},
"headers": {
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
"Accept-Encoding": "gzip,deflate,sdch",
"Accept-Language": "en-US,en;q=0.8",
"Connection": "keep-alive",
"Cookie": "m=3234:t|3247:t|6493:t|6967:t|34e2:|18c3:t|2c69:t|5acb:t|ca3:t|c01:t|5e55:t|77cb:t|2a03:t|1d98:t|47ba:t|64b8:t|4a01:t; AuthSession=cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
"Host": "127.0.0.1:5984",
"User-Agent": "Mozilla/5.0 (Windows NT 5.2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7"
},
"id": "foo",
"info": {
"committed_update_seq": 2701412,
"compact_running": false,
"db_name": "mailbox",
"disk_format_version": 6,
"doc_count": 2262757,
"doc_del_count": 560,
"instance_start_time": "1347601025628957",
"purge_seq": 0,
"sizes": {
"active": 7580843252,
"disk": 14325313673,
"external": 7803423459
},
"update_seq": 2701412
},
"method": "GET",
"path": [
"mailbox",
"_design",
"request",
"_show",
"dump",
"foo"
],
"peer": "127.0.0.1",
"query": {},
"raw_path": "/mailbox/_design/request/_show/dump/foo",
"requested_path": [
"mailbox",
"_design",
"request",
"_show",
"dump",
"foo"
],
"secObj": {
"admins": {
"names": [
"Bob"
],
"roles": []
},
"members": {
"names": [
"Mike",
"Alice"
],
"roles": []
}
},
"userCtx": {
"db": "mailbox",
"name": "Mike",
"roles": [
"user"
]
},
"uuid": "3184f9d1ea934e1f81a24c71bde5c168"
}

WARNING:
The body, base64 and json object keys are overlapping each other
where the last one wins. Since most realizations of key-value ob-
jects do not preserve the key order or if they are mixed, confusing
situations can occur. Try to use only one of them.

NOTE:
Any custom property makes CouchDB raise an internal exception. Fur-
thermore, the Response object could be a simple string value which
would be implicitly wrapped into a {"body": ...} object.

{
"admins": {
"names": [
"Bob"
],
"roles": []
},
"members": {
"names": [
"Mike",
"Alice"
],
"roles": []
}
}

{
"db": "mailbox",
"name": null,
"roles": [
"_admin"
]
}

{
"total_rows": 42,
"offset": 3
}

QUERY SERVER
The Query server is an external process that communicates with CouchDB
by JSON protocol through stdio interface and processes all design func-
tions calls, such as JavaScript views.

The default query server is written in JavaScript, running via Mozilla
SpiderMonkey. You can use other languages by setting a Query server
key in the language property of a design document or the Content-Type
header of a temporary view. Design documents that do not specify a lan-
guage property are assumed to be of type javascript.

Query Server Protocol
A Query Server is an external process that communicates with CouchDB
via a simple, custom JSON protocol over stdin/stdout. It is used to
processes all design functions calls: views, shows, lists, filters, up-
dates and validate_doc_update.

CouchDB communicates with the Query Server process through stdin/stdout
with JSON messages that are terminated by a newline character. Messages
that are sent to the Query Server are always array-typed and follow the
pattern [<command>, <*arguments>]\n.

NOTE:
In the documentation examples, we omit the trailing \n for greater
readability. Also, examples contain formatted JSON values while real
data is transferred in compact mode without formatting spaces.

reset
Command
reset

Arguments
Query server state (optional)

Returns
true

This resets the state of the Query Server and makes it forget all pre-
vious input. If applicable, this is the point to run garbage collec-
tion.

CouchDB sends:

["reset"]

The Query Server answers:

true

To set up new Query Server state, the second argument is used with ob-
ject data.

CouchDB sends:

["reset", {"reduce_limit": true, "timeout": 5000}]

The Query Server answers:

true

add_lib
Command
add_lib

Arguments
CommonJS library object by views/lib path

Returns
true

Adds CommonJS library to Query Server state for further usage in map
functions.

CouchDB sends:

[
"add_lib",
{
"utils": "exports.MAGIC = 42;"
}
]

The Query Server answers:

true

NOTE:
This library shouldnt have any side effects nor track its own state
or youll have a lot of happy debugging time if something goes wrong.
Remember that a complete index rebuild is a heavy operation and this
is the only way to fix mistakes with shared state.

add_fun
Command
add_fun

Arguments
Map function source code.

Returns
true

When creating or updating a view, this is how the Query Server is sent
the view function for evaluation. The Query Server should parse, com-
pile, and evaluate the function it receives to make it callable later.
If this fails, the Query Server returns an error. CouchDB may store
multiple functions before sending any documents.

CouchDB sends:

[
"add_fun",
"function(doc) { if(doc.score > 50) emit(null, {'player_name': doc.name}); }"
]

The Query Server answers:

true

map_doc
Command
map_doc

Arguments
Document object

Returns
Array of key-value pairs per applied function

When the view function is stored in the Query Server, CouchDB starts
sending all the documents in the database, one at a time. The Query
Server calls the previously stored functions one after another with a
document and stores its result. When all functions have been called,
the result is returned as a JSON string.

CouchDB sends:

[
"map_doc",
{
"_id": "8877AFF9789988EE",
"_rev": "3-235256484",
"name": "John Smith",
"score": 60
}
]

If the function above is the only function stored, the Query Server an-
swers:

[
[
[null, {"player_name": "John Smith"}]
]
]

That is, an array with the result for every function for the given doc-
ument.

If a document is to be excluded from the view, the array should be
empty.

CouchDB sends:

[
"map_doc",
{
"_id": "9590AEB4585637FE",
"_rev": "1-674684684",
"name": "Jane Parker",
"score": 43
}
]

The Query Server answers:

[[]]

reduce
Command
reduce

Arguments

• Reduce function source

• Array of map function results where each item represented in
format [[key, id-of-doc], value]

Returns
Array with pair values: true and another array with reduced re-
sult

If the view has a reduce function defined, CouchDB will enter into the
reduce phase. The Query Server will receive a list of reduce functions
and some map results on which it can apply them.

CouchDB sends:

[
"reduce",
[
"function(k, v) { return sum(v); }"
],
[
[[1, "699b524273605d5d3e9d4fd0ff2cb272"], 10],
[[2, "c081d0f69c13d2ce2050d684c7ba2843"], 20],
[[null, "foobar"], 3]
]
]

The Query Server answers:

[
true,
[33]
]

Note that even though the view server receives the map results in the
form [[key, id-of-doc], value], the function may receive them in a dif-
ferent form. For example, the JavaScript Query Server applies functions
on the list of keys and the list of values.

rereduce
Command
rereduce

Arguments

• Reduce function source

• List of values

When building a view, CouchDB will apply the reduce step directly to
the output of the map step and the rereduce step to the output of a
previous reduce step.

CouchDB will send a list of reduce functions and a list of values, with
no keys or document ids to the rereduce step.

CouchDB sends:

[
"rereduce",
[
"function(k, v, r) { return sum(v); }"
],
[
33,
55,
66
]
]

The Query Server answers:

[
true,
[154]
]

ddoc
Command
ddoc

Arguments
Array of objects.

• First phase (ddoc initialization):

• "new"

• Design document _id

• Design document object

• Second phase (design function execution):

• Design document _id

• Function path as an array of object keys

• Array of function arguments

Returns

• First phase (ddoc initialization): true

• Second phase (design function execution): custom object de-
pending on executed function

This command acts in two phases: ddoc registration and design function
execution.

In the first phase CouchDB sends a full design document content to the
Query Server to let it cache it by _id value for further function exe-
cution.

To do this, CouchDB sends:

[
"ddoc",
"new",
"_design/temp",
{
"_id": "_design/temp",
"_rev": "8-d7379de23a751dc2a19e5638a7bbc5cc",
"language": "javascript",
"shows": {
"request": "function(doc,req){ return {json: req}; }",
"hello": "function(doc,req){ return {body: 'Hello, ' + (doc || {})._id + '!'}; }"
}
}
]

The Query Server answers:

true

After this, the design document will be ready to serve subcommands in
the second phase.

NOTE:
Each ddoc subcommand is the root design document key, so they are
not actually subcommands, but first elements of the JSON path that
may be handled and processed.

The pattern for subcommand execution is common:

["ddoc", <design_doc_id>, [<subcommand>, <funcname>], [<argument1>,
<argument2>, ...]]

shows
WARNING:
Show functions are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

Command
ddoc

SubCommand
shows

Arguments

• Document object or null if document id isnt specified in re-
quest

• Request object

Returns
Array with two elements:

• "resp"

• Response object

Executes show function.

Couchdb sends:

[
"ddoc",
"_design/temp",
[
"shows",
"doc"
],
[
null,
{
"info": {
"db_name": "test",
"doc_count": 8,
"doc_del_count": 0,
"update_seq": 105,
"purge_seq": 0,
"compact_running": false,
"sizes": {
"active": 1535048,
"disk": 15818856,
"external": 15515850
},
"instance_start_time": "1359952188595857",
"disk_format_version": 6,
"committed_update_seq": 105
},
"id": null,
"uuid": "169cb4cc82427cc7322cb4463d0021bb",
"method": "GET",
"requested_path": [
"api",
"_design",
"temp",
"_show",
"request"
],
"path": [
"api",
"_design",
"temp",
"_show",
"request"
],
"raw_path": "/api/_design/temp/_show/request",
"query": {},
"headers": {
"Accept": "*/*",
"Host": "localhost:5984",
"User-Agent": "curl/7.26.0"
},
"body": "undefined",
"peer": "127.0.0.1",
"form": {},
"cookie": {},
"userCtx": {
"db": "api",
"name": null,
"roles": [
"_admin"
]
},
"secObj": {}
}
]
]

The Query Server sends:

[
"resp",
{
"body": "Hello, undefined!"
}
]

lists
WARNING:
List functions are deprecated in CouchDB 3.0, and will be removed in
CouchDB 4.0.

Command
ddoc

SubCommand
lists

Arguments

• View Head Information:

• Request object

Returns
Array. See below for details.

Executes list function.

The communication protocol for list functions is a bit complex so lets
use an example to illustrate.

Assume we have view a function that emits id-rev pairs:

function(doc) {
emit(doc._id, doc._rev);
}

And wed like to emulate _all_docs JSON response with list function. Our
first version of the list functions looks like this:

function(head, req){
start({'headers': {'Content-Type': 'application/json'}});
var resp = head;
var rows = [];
while(row=getRow()){
rows.push(row);
}
resp.rows = rows;
return toJSON(resp);
}

The whole communication session during list function execution could be
divided on three parts:

1. Initialization

The first returned object from the list function is an array with
the following structure:

["start", <chunks>, <headers>]

Where <chunks> is an array of text chunks that will be sent to the
client and <headers> is an object with response HTTP headers.

This message is sent from the Query Server to CouchDB on the start()
call which initializes the HTTP response to the client:

[
"start",
[],
{
"headers": {
"Content-Type": "application/json"
}
}
]

After this, the list function may start to process view rows.

2. View Processing

Since view results can be extremely large, it is not wise to pass
all its rows in a single command. Instead, CouchDB can send view
rows one by one to the Query Server allowing view processing and
output generation to be processed as a stream.

CouchDB sends a special array that carries view row data:

[
"list_row",
{
"id": "0cb42c267fe32d4b56b3500bc503e030",
"key": "0cb42c267fe32d4b56b3500bc503e030",
"value": "1-967a00dff5e02add41819138abb3284d"
}
]

If the Query Server has something to return on this, it returns an
array with a "chunks" item in the head and an array of data in the
tail. For this example it has nothing to return, so the response
will be:

[
"chunks",
[]
]

When there are no more view rows to process, CouchDB sends a
list_end message to signify there is no more data to send:

["list_end"]

3. Finalization

The last stage of the communication process is the returning list
tail: the last data chunk. After this, processing of the list func-
tion will be complete and the client will receive a complete re-
sponse.

For our example the last message is:

[
"end",
[
"{\"total_rows\":2,\"offset\":0,\"rows\":[{\"id\":\"0cb42c267fe32d4b56b3500bc503e030\",\"key\":\"0cb42c267fe32d4b56b3500bc503e030\",\"value\":\"1-967a00dff5e02add41819138abb3284d\"},{\"id\":\"431926a69504bde41851eb3c18a27b1f\",\"key\":\"431926a69504bde41851eb3c18a27b1f\",\"value\":\"1-967a00dff5e02add41819138abb3284d\"}]}"
]
]

In this example, we have returned our result in a single message from
the Query Server. This is okay for small numbers of rows, but for large
data sets, perhaps with millions of documents or millions of view rows,
this would not be acceptable.

Lets fix our list function and see the changes in communication:

function(head, req){
start({'headers': {'Content-Type': 'application/json'}});
send('{');
send('"total_rows":' + toJSON(head.total_rows) + ',');
send('"offset":' + toJSON(head.offset) + ',');
send('"rows":[');
if (row=getRow()){
send(toJSON(row));
}
while(row=getRow()){
send(',' + toJSON(row));
}
send(']');
return '}';
}

Wait, what? - youd like to ask. Yes, wed build JSON response manually
by string chunks, but lets take a look on logs:

[Wed, 24 Jul 2013 05:45:30 GMT] [debug] [<0.19191.1>] OS Process #Port<0.4444> Output :: ["start",["{","\"total_rows\":2,","\"offset\":0,","\"rows\":["],{"headers":{"Content-Type":"application/json"}}]
[Wed, 24 Jul 2013 05:45:30 GMT] [info] [<0.18963.1>] 127.0.0.1 - - GET /blog/_design/post/_list/index/all_docs 200
[Wed, 24 Jul 2013 05:45:30 GMT] [debug] [<0.19191.1>] OS Process #Port<0.4444> Input :: ["list_row",{"id":"0cb42c267fe32d4b56b3500bc503e030","key":"0cb42c267fe32d4b56b3500bc503e030","value":"1-967a00dff5e02add41819138abb3284d"}]
[Wed, 24 Jul 2013 05:45:30 GMT] [debug] [<0.19191.1>] OS Process #Port<0.4444> Output :: ["chunks",["{\"id\":\"0cb42c267fe32d4b56b3500bc503e030\",\"key\":\"0cb42c267fe32d4b56b3500bc503e030\",\"value\":\"1-967a00dff5e02add41819138abb3284d\"}"]]
[Wed, 24 Jul 2013 05:45:30 GMT] [debug] [<0.19191.1>] OS Process #Port<0.4444> Input :: ["list_row",{"id":"431926a69504bde41851eb3c18a27b1f","key":"431926a69504bde41851eb3c18a27b1f","value":"1-967a00dff5e02add41819138abb3284d"}]
[Wed, 24 Jul 2013 05:45:30 GMT] [debug] [<0.19191.1>] OS Process #Port<0.4444> Output :: ["chunks",[",{\"id\":\"431926a69504bde41851eb3c18a27b1f\",\"key\":\"431926a69504bde41851eb3c18a27b1f\",\"value\":\"1-967a00dff5e02add41819138abb3284d\"}"]]
[Wed, 24 Jul 2013 05:45:30 GMT] [debug] [<0.19191.1>] OS Process #Port<0.4444> Input :: ["list_end"]
[Wed, 24 Jul 2013 05:45:30 GMT] [debug] [<0.19191.1>] OS Process #Port<0.4444> Output :: ["end",["]","}"]]

Note, that now the Query Server sends response by lightweight chunks
and if our communication process was extremely slow, the client will
see how response data appears on their screen. Chunk by chunk, without
waiting for the complete result, like they have for our previous list
function.

updates
Command
ddoc

SubCommand
updates

Arguments

• Document object or null if document id wasnt specified in re-
quest

• Request object

Returns
Array with there elements:

• "up"

• Document object or null if nothing should be stored

• Response object

Executes update function.

CouchDB sends:

[
"ddoc",
"_design/id",
[
"updates",
"nothing"
],
[
null,
{
"info": {
"db_name": "test",
"doc_count": 5,
"doc_del_count": 0,
"update_seq": 16,
"purge_seq": 0,
"compact_running": false,
"sizes": {
"active": 7979745,
"disk": 8056936,
"external": 8024930
},
"instance_start_time": "1374612186131612",
"disk_format_version": 6,
"committed_update_seq": 16
},
"id": null,
"uuid": "7b695cb34a03df0316c15ab529002e69",
"method": "POST",
"requested_path": [
"test",
"_design",
"1139",
"_update",
"nothing"
],
"path": [
"test",
"_design",
"1139",
"_update",
"nothing"
],
"raw_path": "/test/_design/1139/_update/nothing",
"query": {},
"headers": {
"Accept": "*/*",
"Accept-Encoding": "identity, gzip, deflate, compress",
"Content-Length": "0",
"Host": "localhost:5984"
},
"body": "",
"peer": "127.0.0.1",
"form": {},
"cookie": {},
"userCtx": {
"db": "test",
"name": null,
"roles": [
"_admin"
]
},
"secObj": {}
}
]
]

The Query Server answers:

[
"up",
null,
{"body": "document id wasn't provided"}
]

or in case of successful update:

[
"up",
{
"_id": "7b695cb34a03df0316c15ab529002e69",
"hello": "world!"
},
{"body": "document was updated"}
]

filters
Command
ddoc

SubCommand
filters

Arguments

• Array of document objects

• Request object

Returns
Array of two elements:

• true

• Array of booleans in the same order of input documents.

Executes filter function.

CouchDB sends:

[
"ddoc",
"_design/test",
[
"filters",
"random"
],
[
[
{
"_id": "431926a69504bde41851eb3c18a27b1f",
"_rev": "1-967a00dff5e02add41819138abb3284d",
"_revisions": {
"start": 1,
"ids": [
"967a00dff5e02add41819138abb3284d"
]
}
},
{
"_id": "0cb42c267fe32d4b56b3500bc503e030",
"_rev": "1-967a00dff5e02add41819138abb3284d",
"_revisions": {
"start": 1,
"ids": [
"967a00dff5e02add41819138abb3284d"
]
}
}
],
{
"info": {
"db_name": "test",
"doc_count": 5,
"doc_del_count": 0,
"update_seq": 19,
"purge_seq": 0,
"compact_running": false,
"sizes": {
"active": 7979745,
"disk": 8056936,
"external": 8024930
},
"instance_start_time": "1374612186131612",
"disk_format_version": 6,
"committed_update_seq": 19
},
"id": null,
"uuid": "7b695cb34a03df0316c15ab529023a81",
"method": "GET",
"requested_path": [
"test",
"_changes?filter=test",
"random"
],
"path": [
"test",
"_changes"
],
"raw_path": "/test/_changes?filter=test/random",
"query": {
"filter": "test/random"
},
"headers": {
"Accept": "application/json",
"Accept-Encoding": "identity, gzip, deflate, compress",
"Content-Length": "0",
"Content-Type": "application/json; charset=utf-8",
"Host": "localhost:5984"
},
"body": "",
"peer": "127.0.0.1",
"form": {},
"cookie": {},
"userCtx": {
"db": "test",
"name": null,
"roles": [
"_admin"
]
},
"secObj": {}
}
]
]

The Query Server answers:

[
true,
[
true,
false
]
]

views
Command
ddoc

SubCommand
views

Arguments
Array of document objects

Returns
Array of two elements:

• true

• Array of booleans in the same order of input documents.

Added in version 1.2.

Executes view function in place of the filter.

Acts in the same way as filters command.

validate_doc_update
Command
ddoc

SubCommand
validate_doc_update

Arguments

• Document object that will be stored

• Document object that will be replaced

• User Context Object

• Security Object

Returns
1

Executes validation function.

CouchDB send:

[
"ddoc",
"_design/id",
["validate_doc_update"],
[
{
"_id": "docid",
"_rev": "2-e0165f450f6c89dc6b071c075dde3c4d",
"score": 10
},
{
"_id": "docid",
"_rev": "1-9f798c6ad72a406afdbf470b9eea8375",
"score": 4
},
{
"name": "Mike",
"roles": ["player"]
},
{
"admins": {},
"members": []
}
]
]

The Query Server answers:

NOTE:
While the only valid response for this command is true, to prevent
the document from being saved, the Query Server needs to raise an
error: forbidden or unauthorized; these errors will be turned into
correct HTTP 403 and HTTP 401 responses respectively.

rewrites
Command
ddoc

SubCommand
rewrites

Arguments

• Request2 object

Returns
1

Executes rewrite function.

CouchDB send:

[
"ddoc",
"_design/id",
["rewrites"],
[
{
"method": "POST",
"requested_path": [
"test",
"_design",
"1139",
"_update",
"nothing"
],
"path": [
"test",
"_design",
"1139",
"_update",
"nothing"
],
"raw_path": "/test/_design/1139/_update/nothing",
"query": {},
"headers": {
"Accept": "*/*",
"Accept-Encoding": "identity, gzip, deflate, compress",
"Content-Length": "0",
"Host": "localhost:5984"
},
"body": "",
"peer": "127.0.0.1",
"cookie": {},
"userCtx": {
"db": "test",
"name": null,
"roles": [
"_admin"
]
},
"secObj": {}
}
]
]

The Query Server answers:

[
"ok",
{
"path": "some/path",
"query": {"key1": "value1", "key2": "value2"},
"method": "METHOD",
"headers": {"Header1": "value1", "Header2": "value2"},
"body": ""
}
]

or in case of direct response:

[
"ok",
{
"headers": {"Content-Type": "text/plain"},
"body": "Welcome!",
"code": 200
}
]

or for immediate redirect:

[
"ok",
{
"headers": {"Location": "http://example.com/path/"},
"code": 302
}
]

Returning errors
When something goes wrong, the Query Server can inform CouchDB by send-
ing a special message in response to the received command.

Error messages prevent further command execution and return an error
description to CouchDB. Errors are logically divided into two groups:

• Common errors. These errors only break the current Query Server com-
mand and return the error info to the CouchDB instance without termi-
nating the Query Server process.

• Fatal errors. Fatal errors signal a condition that cannot be recov-
ered. For instance, if your a design function is unable to import a
third party module, its better to count such error as fatal and ter-
minate whole process.

error
To raise an error, the Query Server should respond with:

["error", "error_name", "reason why"]

The "error_name" helps to classify problems by their type e.g. if its
"value_error" to indicate improper data, "not_found" to indicate a
missing resource and "type_error" to indicate an improper data type.

The "reason why" explains in human-readable terms what went wrong, and
possibly how to resolve it.

For example, calling Update Functions against a non-existent document
could produce the error message:

["error", "not_found", "Update function requires existent document"]

forbidden
The forbidden error is widely used by Validate Document Update Func-
tions to stop further function processing and prevent storage of the
new document revision. Since this is not actually an error, but an as-
sertion against user actions, CouchDB doesnt log it at error level, but
returns HTTP 403 Forbidden response with error information object.

To raise this error, the Query Server should respond with:

{"forbidden": "reason why"}

unauthorized
The unauthorized error mostly acts like forbidden one, but with the
meaning of please authorize first. This small difference helps end
users to understand what they can do to solve the problem. Similar to
forbidden, CouchDB doesnt log it at error level, but returns a HTTP 401
Unauthorized response with an error information object.

To raise this error, the Query Server should respond with:

{"unauthorized": "reason why"}

Logging
At any time, the Query Server may send some information that will be
saved in CouchDBs log file. This is done by sending a special log ob-
ject with a single argument, on a separate line:

["log", "some message"]

CouchDB does not respond, but writes the received message to the log
file:

[Sun, 13 Feb 2009 23:31:30 GMT] [info] [<0.72.0>] Query Server Log Message: some message

These messages are only logged at info level.

JavaScript
NOTE:
While every design function has access to all JavaScript objects,
the table below describes appropriate usage cases. For example, you
may use emit() in Map Functions, but getRow() is not permitted dur-
ing Map Functions.
+----------------+----------------------------+
| JS Function | Reasonable to use in de- |
| | sign doc functions |
+----------------+----------------------------+
| emit() | Map Functions |
+----------------+----------------------------+
| getRow() | List Functions |
+----------------+----------------------------+
| JSON | any |
+----------------+----------------------------+
| isArray() | any |
+----------------+----------------------------+
| log() | any |
+----------------+----------------------------+
| provides() | Show Functions, List Func- |
| | tions |
+----------------+----------------------------+
| registerType() | Show Functions, List Func- |
| | tions |
+----------------+----------------------------+
| require() | any, except Reduce and |
| | Rereduce Functions |
+----------------+----------------------------+
| send() | List Functions |
+----------------+----------------------------+
| start() | List Functions |
+----------------+----------------------------+
| sum() | any |
+----------------+----------------------------+
| toJSON() | any |
+----------------+----------------------------+

Design functions context
Each design function executes in a special context of predefined ob-
jects, modules and functions:

emit(key, value)
Emits a key-value pair for further processing by CouchDB after
the map function is done.

Arguments

• key The view key

• value The keys associated value

function(doc){
emit(doc._id, doc._rev);
}

getRow()
Extracts the next row from a related view result.

Returns
View result row

Return type
object

function(head, req){
send('[');
row = getRow();
if (row){
send(toJSON(row));
while(row = getRow()){
send(',');
send(toJSON(row));
}
}
return ']';
}

JSON JSON object.

isArray(obj)
A helper function to check if the provided value is an Array.

Arguments

• obj Any JavaScript value

Returns
true if obj is Array-typed, false otherwise

Return type
boolean

log(message)
Log a message to the CouchDB log (at the INFO level).

Arguments

• message Message to be logged

function(doc){
log('Procesing doc ' + doc['_id']);
emit(doc['_id'], null);
}

After the map function has run, the following line can be found
in CouchDB logs (e.g. at /var/log/couchdb/couch.log):

[Sat, 03 Nov 2012 17:38:02 GMT] [info] [<0.7543.0>] OS Process #Port<0.3289> Log :: Processing doc 8d300b86622d67953d102165dbe99467

provides(key, func)
Registers callable handler for specified MIME key.

Arguments

• key MIME key previously defined by registerType()

• func MIME type handler

registerType(key, *mimes)
Registers list of MIME types by associated key.

Arguments

• key MIME types

• mimes MIME types enumeration

Predefined mappings (key-array):

• all: */*

• text: text/plain; charset=utf-8, txt

• html: text/html; charset=utf-8

• xhtml: application/xhtml+xml, xhtml

• xml: application/xml, text/xml, application/x-xml

• js: text/javascript, application/javascript, applica-
tion/x-javascript

• css: text/css

• ics: text/calendar

• csv: text/csv

• rss: application/rss+xml

• atom: application/atom+xml

• yaml: application/x-yaml, text/yaml

• multipart_form: multipart/form-data

• url_encoded_form: application/x-www-form-urlencoded

• json: application/json, text/x-json

require(path)
Loads CommonJS module by a specified path. The path should not
start with a slash.

Arguments

• path A CommonJS module path started from design docu-
ment root

Returns
Exported statements

send(chunk)
Sends a single string chunk in response.

Arguments

• chunk Text chunk

function(head, req){
send('Hello,');
send(' ');
send('Couch');
return ;
}

start(init_resp)
Initiates chunked response. As an option, a custom response ob-
ject may be sent at this point. For list-functions only!

NOTE:
list functions may set the HTTP response code and headers by
calling this function. This function must be called before
send(), getRow() or a return statement; otherwise, the query
server will implicitly call this function with the empty ob-
ject ({}).

function(head, req){
start({
"code": 302,
"headers": {
"Location": "http://couchdb.apache.org"
}
});
return "Relax!";
}

sum(arr)
Sum arrs items.

Arguments

• arr Array of numbers

Return type
number

toJSON(obj)
Encodes obj to JSON string. This is an alias for the
JSON.stringify method.

Arguments

• obj JSON-encodable object

Returns
JSON string

CommonJS Modules
Support for CommonJS Modules (introduced in CouchDB 0.11.0) allows you
to create modular design functions without the need for duplication of
functionality.

Heres a CommonJS module that checks user permissions:

function user_context(userctx, secobj) {
var is_admin = function() {
return userctx.indexOf('_admin') != -1;
}
return {'is_admin': is_admin}
}

exports['user'] = user_context

Each module has access to additional global variables:

• module (object): Contains information about the stored module

• id (string): The module id; a JSON path in ddoc context

• current (code): Compiled module code object

• parent (object): Parent frame

• exports (object): Export statements

• exports (object): Shortcut to the module.exports object

The CommonJS module can be added to a design document, like so:

{
"views": {
"lib": {
"security": "function user_context(userctx, secobj) { ... }"
}
},
"validate_doc_update": "function(newdoc, olddoc, userctx, secobj) {
user = require('views/lib/security').user_context(userctx, secobj);
return user.is_admin();
}"
"_id": "_design/test"
}

Modules paths are relative to the design documents views object, but
modules can only be loaded from the object referenced via lib. The lib
structure can still be used for view functions as well, by simply stor-
ing view functions at e.g. views.lib.map, views.lib.reduce, etc.

Erlang
NOTE:
The Erlang query server is disabled by default. Read configuration
guide about reasons why and how to enable it.

Emit(Id, Value)
Emits key-value pairs to view indexer process.

fun({Doc}) ->
<<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
V = proplists:get_value(<<"_id">>, Doc, null),
Emit(<<K>>, V)
end.

FoldRows(Fun, Acc)
Helper to iterate over all rows in a list function.

Arguments

• Fun Function object.

• Acc The value previously returned by Fun.

fun(Head, {Req}) ->
Fun = fun({Row}, Acc) ->
Id = couch_util:get_value(<<"id">>, Row),
Send(list_to_binary(io_lib:format("Previous doc id: ~p~n", [Acc]))),
Send(list_to_binary(io_lib:format("Current doc id: ~p~n", [Id]))),
{ok, Id}
end,
FoldRows(Fun, nil),
""
end.

GetRow()
Retrieves the next row from a related view result.

%% FoldRows background implementation.
%% https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=src/couchdb/couch_native_process.erl;hb=HEAD#l368
%%
foldrows(GetRow, ProcRow, Acc) ->
case GetRow() of
nil ->
{ok, Acc};
Row ->
case (catch ProcRow(Row, Acc)) of
{ok, Acc2} ->
foldrows(GetRow, ProcRow, Acc2);
{stop, Acc2} ->
{ok, Acc2}
end
end.

Log(Msg)

Arguments

• Msg Log a message at the INFO level.

fun({Doc}) ->
<<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
V = proplists:get_value(<<"_id">>, Doc, null),
Log(lists:flatten(io_lib:format("Hello from ~s doc!", [V]))),
Emit(<<K>>, V)
end.

After the map function has run, the following line can be found
in CouchDB logs (e.g. at /var/log/couchdb/couch.log):

[Sun, 04 Nov 2012 11:33:58 GMT] [info] [<0.9144.2>] Hello from 8d300b86622d67953d102165dbe99467 doc!

Send(Chunk)
Sends a single string Chunk in response.

fun(Head, {Req}) ->
Send("Hello,"),
Send(" "),
Send("Couch"),
"!"
end.

The function above produces the following response:

Hello, Couch!

Start(Headers)

Arguments

• Headers Proplist of response object.

Initialize List Functions response. At this point, response code
and headers may be defined. For example, this function redirects
to the CouchDB web site:

fun(Head, {Req}) ->
Start({[{<<"code">>, 302},
{<<"headers">>, {[
{<<"Location">>, <<"http://couchdb.apache.org">>}]
}}
]}),
"Relax!"
end.

PARTITIONED DATABASES
A partitioned database forms documents into logical partitions by using
a partition key. All documents are assigned to a partition, and many
documents are typically given the same partition key. The benefit of
partitioned databases is that secondary indices can be significantly
more efficient when locating matching documents since their entries are
contained within their partition. This means a given secondary index
read will only scan a single partition range instead of having to read
from a copy of every shard.

As a means to introducing partitioned databases, well consider a moti-
vating use case to describe the benefits of this feature. For this ex-
ample, well consider a database that stores readings from a large net-
work of soil moisture sensors.

NOTE:
Before reading this document you should be familiar with the theory
of sharding in CouchDB.

Traditionally, a document in this database may have something like the
following structure:

{
"_id": "sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"_rev":"1-14e8f3262b42498dbd5c672c9d461ff0",
"sensor_id": "sensor-260",
"location": [41.6171031, -93.7705674],
"field_name": "Bob's Corn Field #5",
"readings": [
["2019-01-21T00:00:00", 0.15],
["2019-01-21T06:00:00", 0.14],
["2019-01-21T12:00:00", 0.16],
["2019-01-21T18:00:00", 0.11]
]
}

NOTE:
While this example uses IoT sensors, the main thing to consider is
that there is a logical grouping of documents. Similar use cases
might be documents grouped by user or scientific data grouped by ex-
periment.

So weve got a bunch of sensors, all grouped by the field they monitor
along with their readouts for a given day (or other appropriate time
period).

Along with our documents, we might expect to have two secondary indexes
for querying our database that might look something like:

function(doc) {
if(doc._id.indexOf("sensor-reading-") != 0) {
return;
}
for(var r in doc.readings) {
emit([doc.sensor_id, r[0]], r[1])
}
}

and:

function(doc) {
if(doc._id.indexOf("sensor-reading-") != 0) {
return;
}
emit(doc.field_name, doc.sensor_id)
}

With these two indexes defined, we can easily find all readings for a
given sensor, or list all sensors in a given field.

Unfortunately, in CouchDB, when we read from either of these indexes,
it requires finding a copy of every shard and asking for any documents
related to the particular sensor or field. This means that as our data-
base scales up the number of shards, every index request must perform
more work, which is unnecessary since we are only interested in a small
number of documents. Fortunately for you, dear reader, partitioned
databases were created to solve this precise problem.

What is a partition?
In the previous section, we introduced a hypothetical database that
contains sensor readings from an IoT field monitoring service. In this
particular use case, its quite logical to group all documents by their
sensor_id field. In this case, we would call the sensor_id the parti-
tion key.

A good partition has two basic properties. First, it should have a high
cardinality. That is, a large partitioned database should have many
more partitions than documents in any single partition. A database that
has a single partition would be an anti-pattern for this feature. Sec-
ondly, the amount of data per partition should be small. The general
recommendation is to limit individual partitions to less than ten giga-
bytes (10 GB) of data. Which, for the example of sensor documents,
equates to roughly 60,000 years of data.

NOTE:
The max_partition_size under CouchDB dictates the partition limit.
The default value for this option is 10GiB but can be changed ac-
cordingly. Setting the value for this option to 0 disables the par-
tition limit.

Why use partitions?
The primary benefit of using partitioned databases is for the perfor-
mance of partitioned queries. Large databases with lots of documents
often have a similar pattern where there are groups of related docu-
ments that are queried together.

By using partitions, we can execute queries against these individual
groups of documents more efficiently by placing the entire group within
a specific shard on disk. Thus, the view engine only has to consult one
copy of the given shard range when executing a query instead of execut-
ing the query across all q shards in the database. This mean that you
do not have to wait for all q shards to respond, which is both effi-
cient and faster.

Partitions By Example
To create a partitioned database, we simply need to pass a query string
parameter:

shell> curl -X PUT 'http://adm:pass@127.0.0.1:5984/my_new_db?partitioned=true'
{"ok":true}

To see that our database is partitioned, we can look at the database
information:

shell> curl http://adm:pass@127.0.0.1:5984/my_new_db
{
"cluster": {
"n": 3,
"q": 8,
"r": 2,
"w": 2
},
"compact_running": false,
"db_name": "my_new_db",
"disk_format_version": 7,
"doc_count": 0,
"doc_del_count": 0,
"instance_start_time": "0",
"props": {
"partitioned": true
},
"purge_seq": "0-g1AAAAFDeJzLYWBg4M...",
"sizes": {
"active": 0,
"external": 0,
"file": 66784
},
"update_seq": "0-g1AAAAFDeJzLYWBg4M..."
}

Youll now see that the "props" member contains "partitioned": true.

NOTE:
Every document in a partitioned database (except _design and _local
documents) must have the format partition:docid. More specifically,
the partition for a given document is everything before the first
colon. The document id is everything after the first colon, which
may include more colons.

NOTE:
System databases (such as _users) are not allowed to be partitioned.
This is due to system databases already having their own incompati-
ble requirements on document ids.

Now that weve created a partitioned database, its time to add some doc-
uments. Using our earlier example, we could do this as such:

shell> cat doc.json
{
"_id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"sensor_id": "sensor-260",
"location": [41.6171031, -93.7705674],
"field_name": "Bob's Corn Field #5",
"readings": [
["2019-01-21T00:00:00", 0.15],
["2019-01-21T06:00:00", 0.14],
["2019-01-21T12:00:00", 0.16],
["2019-01-21T18:00:00", 0.11]
]
}
shell> $ curl -X POST -H "Content-Type: application/json" \
http://adm:pass@127.0.0.1:5984/my_new_db -d @doc.json
{
"ok": true,
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"rev": "1-05ed6f7abf84250e213fcb847387f6f5"
}

The only change required to the first example document is that we are
now including the partition name in the document id by prepending it to
the old id separated by a colon.

NOTE:
The partition name in the document id is not magical. Internally,
the database is simply using only the partition for hashing the doc-
ument to a given shard, instead of the entire document id.

Working with documents in a partitioned database is no different than a
non-partitioned database. All APIs are available, and existing client
code will all work seamlessly.

Now that we have created a document, we can get some info about the
partition containing the document:

shell> curl http://adm:pass@127.0.0.1:5984/my_new_db/_partition/sensor-260
{
"db_name": "my_new_db",
"doc_count": 1,
"doc_del_count": 0,
"partition": "sensor-260",
"sizes": {
"active": 244,
"external": 347
}
}

And we can also list all documents in a partition:

shell> curl http://adm:pass@127.0.0.1:5984/my_new_db/_partition/sensor-260/_all_docs
{"total_rows": 1, "offset": 0, "rows":[
{
"id":"sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"key":"sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
"value": {"rev": "1-05ed6f7abf84250e213fcb847387f6f5"}
}
]}

Note that we can use all of the normal bells and whistles available to
_all_docs requests. Accessing _all_docs through the /dbname/_parti-
tion/name/_all_docs endpoint is mostly a convenience so that requests
are guaranteed to be scoped to a given partition. Users are free to use
the normal /dbname/_all_docs to read documents from multiple parti-
tions. Both query styles have the same performance.

Next, well create a design document containing our index for getting
all readings from a given sensor. The map function is similar to our
earlier example except weve accounted for the change in the document
id.

function(doc) {
if(doc._id.indexOf(":sensor-reading-") < 0) {
return;
}
for(var r in doc.readings) {
emit([doc.sensor_id, r[0]], r[1])
}
}

After uploading our design document, we can try out a partitioned
query:

shell> cat ddoc.json
{
"_id": "_design/sensor-readings",
"views": {
"by_sensor": {
"map": "function(doc) { ... }"
}
}
}
shell> $ curl -X POST -H "Content-Type: application/json" http://adm:pass@127.0.0.1:5984/my_new_db -d @ddoc.json
{
"ok": true,
"id": "_design/sensor-readings",
"rev": "1-13859808da293bd72fde3b31be97372a"
}
shell> curl http://adm:pass@127.0.0.1:5984/my_new_db/_partition/sensor-260/_design/sensor-readings/_view/by_sensor
{"total_rows":4,"offset":0,"rows":[
{"id":"sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf","key":["sensor-260","0"],"value":null},
{"id":"sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf","key":["sensor-260","1"],"value":null},
{"id":"sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf","key":["sensor-260","2"],"value":null},
{"id":"sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf","key":["sensor-260","3"],"value":null}
]}

Hooray! Our first partitioned query. For experienced users, that may
not be the most exciting development, given that the only things that
have changed are a slight tweak to the document id, and accessing views
with a slightly different path. However, for anyone who likes perfor-
mance improvements, its actually a big deal. By knowing that the view
results are all located within the provided partition name, our parti-
tioned queries now perform nearly as fast as document lookups!

The last thing well look at is how to query data across multiple parti-
tions. For that, well implement the example sensors by field query
from our initial example. The map function will use the same update to
account for the new document id format, but is otherwise identical to
the previous version:

function(doc) {
if(doc._id.indexOf(":sensor-reading-") < 0) {
return;
}
emit(doc.field_name, doc.sensor_id)
}

Next, well create a new design doc with this function. Be sure to no-
tice that the "options" member contains "partitioned": false.

shell> cat ddoc2.json
{
"_id": "_design/all_sensors",
"options": {
"partitioned": false
},
"views": {
"by_field": {
"map": "function(doc) { ... }"
}
}
}
shell> $ curl -X POST -H "Content-Type: application/json" http://adm:pass@127.0.0.1:5984/my_new_db -d @ddoc2.json
{
"ok": true,
"id": "_design/all_sensors",
"rev": "1-4a8188d80fab277fccf57bdd7154dec1"
}

NOTE:
Design documents in a partitioned database default to being parti-
tioned. Design documents that contain views for queries across mul-
tiple partitions must contain the "partitioned": false member in the
"options" object.

NOTE:
Design documents are either partitioned or global. They cannot con-
tain a mix of partitioned and global indexes.

And to see a request showing us all sensors in a field, we would use a
request like:

shell> curl -u adm:pass http://adm:pass@127.0.0.1:15984/my_new_db/_design/all_sensors/_view/by_field
{"total_rows":1,"offset":0,"rows":[
{"id":"sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf","key":"Bob's Corn Field #5","value":"sensor-260"}
]}

Notice that were not using the /dbname/_partition/... path for global
queries. This is because global queries, by definition, do not cover
individual partitions. Other than having the "partitioned": false para-
meter in the design document, global design documents and queries are
identical in behavior to design documents on non-partitioned databases.

WARNING:
To be clear, this means that global queries perform identically to
queries on non-partitioned databases. Only partitioned queries on a
partitioned database benefit from the performance improvements.

RELEASE NOTES
3.5.x Branch
• Version 3.5.1

• Version 3.5.0

Version 3.5.1
Features
• #5626, #5665: Debian Trixie support

• #5709: Automatic Nouveau and Clouseau index cleanup

• #5697: Add UUID v7 as a uuid algorithm option. The default is still
the default sequential algorithm.

• #5713, #5697, #5701, #5704: Purge improvements and fixes. Optimize it
up to ~30% faster for large batches. max_document_id_number setting
was removed and max_revisions_number set to unlimited by default to
match _bulk_docs and _bulk_get endpoints.

• #5611: Implement the ability to downgrade CouchDB versions

• #5588: Populate zone from COUCHDB_ZONE env variable in Docker

• #5563: Set Erlang/OTP 26 as minimum supported version

• #5546, #5641: Improve Clouseau service checks in clouseau_rpc module.

• #5639: Use OS certificates for replication

• #5728: Configurable reduce limit threshold and ratio

Performance
• #5625: BTree engine term cache

• #5617: Optimize Nouveau searches when index is fresh

• #5598: Use HTTP/2 for Nouveau

• #5701: Optimize revid parsing: 50-90% faster. Should help purge re-
quests as well as _bulk_docs and _bulk_get endpoints.

• #5564: Use the built-in binary hex encode

• #5613: Improve scanner performance

• #5545: Bump process limit to 1M

Bugfixes
• #5722, #5683, #5678, #5646, #5630, #5615, #5696: Scanner fixes. Add
write limiting and switch to traversing documents by sequence IDs in-
stead of by document IDs.

• #5707, #5706, #5706, #5694, #5691, #5669, #5629, #5574, #5573, #5566,
#5553, #5550, #5534, #5730: QuickJS Updates. Optimized string opera-
tions, faster context creation, a lot of bug fixes.

• #5719: Use all ring options for purged_infos

• #5649: Retry call to dreyfus index on noproc errors

• #5663: More informative error if epochs out of order

• #5649: Dreyfus retries on error

• #5643: Fix reduce_limit = log feature

• #5620: Use copy_props in the compactor instead of set_props

• #5632, #5627, #5607: Nouveau fixes. Enhance _nouveau_cleanup. Improve
security on http/2.

• #5614: Stop replication jobs to nodes which are not part of the clus-
ter

• #5596: Fix query args parsing during cluster upgrades

• #5595: Make replicator shutdown a bit more orderly

• #5595: Avoid making a mess in the logs when stopping replicator app

• #5588: Fix couch_util:set_value/3

• #5587: Improve mem3_rep:find_source_seq/4 logging

• #5586: Dont wait indefinitely for replication jobs to stop

• #5578: Use [sync] option in couch_bt_engine:commit_data/1

• #5556: Add guards to fabric:design_docs/1 to prevent function_clause
error

• #5555: Improve replicator client mailbox flush

• #5551: Handle bad_generator and case_clause in ken_server

• #5552: Improve cluster startup logging

• #5552: Improve mem3 supervisor

• #5552: Handle shard opener tables not being initializes better

• #5549: Dont spawn more than one init_delete_dir instance

• #5535: Disk monitor always allows mem3_rep checkpoints

• #5536: Fix mem3_util overlapping shards

• #5533: No cfile support for 32bit systems

• #5688: Handle timeout in dreyfus_fabric_search

• #5548: Fix config key typo in mem3_reshard_dbdoc

• #5540: Ignore extraneous cookie in replicator session plugin

Cleanups
• #5717: Do not check for Dreyfus. Its part of the tree now.

• #5715: Remove Hastings references

• #5714: Cleanup fabric r/w parameter handling

• #5693: Remove explicit erlang module prefix for auto-imported func-
tions

• #5686: Remove erlang: prefix from erlang:error()

• #5686: Fix case_clause when got missing_target error

• #5690: Fix props caching in mem3

• #5680: Implement db doc updating

• #5666: Replace gen_server:format_status/2 with format_status/1

• #5672: Cache and store mem3 shard properties in one place only

• #5644: Remove redundant *_to_list / list_to_* conversion

• #5633: Use config:get_integer/3 in couch_btree

• #5618: DRY out couch_bt_engine header pointer term access

• #5614: Stop replication jobs to nodes which are not part of the clus-
ter

• #5610: Add a range_to_hex/1 utility function

• #5565: Use maps comprehensions and generators in a few places

• #5649: Remove pointless message

• #5649: Remove obsolete clauses from dreyfus

• #5621: Minor couch_btree refactoring

Docs
• #5705: Docs: Update the /_up endpoint docs to include status re-
sponses

• #5653: Document that _all_dbs endpoint supports inclusive_end query
param

• #5575: Document how to mitigate high memory usage in docker

• #5600: Avoid master wording at setup cluster

• #5381: Change unauthorized example to 401 for replication

• #5682: Update install instructions

• #5674: Add setup documentation for two factor authentication

• #5562: Add AI policy

• #5548: Fix reshard doc section name

• #5543: Add https to allowed replication proxy protocols

Tests/CI/Builds
• #5720: Update deps: Fauxton, meck and PropEr

• #5708: Improve search test

• #5702: Increase timeout for process_response/3 to fix flaky tests

• #5703: Use deterministic doc IDs in Mango key test

• #5692: Implement assert_on_status macro

• #5684: Sequester docker ARM builds and fail early

• #5679: Add --disable-spidermonkey to --dev[-with-nouveau]

• #5671: Print request/response body on errors from mango test suite

• #5670: Fix make clean after dev/run --enable-tls

• #5668: Update xxHash

• #5667: Update mochiweb to v3.3.0

• #5664: Disable ppc64le and s390x builds

• #5604: Use ASF fork of gun for cowlib dependency

• #5636: Reduce btree prop test count a bit

• #5633: Fix and improve couch_btree testing

• #5572: Remove a few more instances of Ubuntu Focal

• #5571: Upgrade Erlang for CI

• #5570: Skip macos CI for now and remove Ubuntu Focal

• #5488: Bump Clouseau to 2.25.0

• #5541: Enable Clouseau for the Windows CI

• #5537: Add retries to native full CI stage

• #5531: Fix Erlang cookie configuration in dev/run

• #5662: Remove old Jenkinsfiles

• #5661: Unify CI jobs

Version 3.5.0
Highlights
• #5399, #5441, #5443, #5460, #5461: Implement parallel pread calls:
lets clients issue concurrent pread calls without blocking each other
or having to wait for all writes and fsync calls. This is enabled by
default and can be disabled with [couchdb] use_cfile = false in the
configuration.

CouchDB already employs a multiple-parallel-read and concurrent ser-
ial-write design at the database engine layer, but below that in the
storage engine, each file representing a database shard is required
to route all read / write / sync requests through a single Erlang
process that owns the file descriptor (fd).

An Erlang process can at most execute at the speed of a single CPU
core. Two scenarios can lead to a starvation of the fd-owning Erlang
process message inbox:

• 1000s of concurrent read requests with a constant stream of
writes per shard, or:

• a high latency storage devices like network block storage.

Parallel preads re-implements the Erlang file module in parts as
couch_cfile to allow multiple dup()d file descriptors to be used for
reading and writing. Writes continue to be serialised at the database
engine layer, but reads now are no longer blocked by writes waiting
to commit.

Comes with an extensive test suite that includes property testing to
ensure couch_cfile behaves exactly like Erlangs file in all other
cases.

Performance is always equal or better than before. These scenarios
show preliminary improvements:

• random document reads: 15% more throughput

• read _all_docs: 15% more throughput

• read _all_docs with include_docs=true: 25% more throughput

• read _changes: 4% more throughput

• single document writes: 8% more throughput

• 2000x concurrent clients, random document reads on a 12 node clus-
ter: 30% more throughput

• concurrent constant document writes and concurrent single document
reads on a single shard: 40% more throughput.

This feature is not available on Windows.

• #5435: Improve default chttpd_server options. This helps with faster
processing of many concurrent TCP connections.

• #5347: Fix attachment size calculation. This could lead to shards not
being scheduled for compaction correctly.

• #5494: Implement _top_N and _bottom_N reducers. These reducers return
the top or bottom values from a map-reduce view. N is a number be-
tween 1 and 100. For instance, a _top_5 reducer will return the top 5
highest values for a group level.

• #5498: Implement _first and _last reducers. These reducers return the
first, and respectively, the last view row for a given group level.
For example, _last can be used to retrieve the last timestamp update
for each device_id if we had a key like [device_id, timestamp] if we
query the view with group_level=1.

• #5466: Conflict finder plugin. Enable the couch_scanner_plugin_con-
flict_finder plugin to find conflicting docs across all the data-
bases. It can be configured to report individual revisions or aggre-
gated statistics.

Performance
• #5499: QuickJS rope based string implementation.

• #5451: Optimize config system to use persistent terms.

• #5437: Fix atts_since functionality for document GET requests. Avoids
re-replicating attachment bodies on doc updates.

• #5398: Save 1 write for each committing data to disk by using fdata-
sync while keeping the same level of storage reliability.

Features
• #5526: Default upgrade_hash_on_auth to true. Downgrading to 3.4.1,
3.4.2, or 3.4.3 is safe. Those versions know how to verify these new
password hashes.

• #5517: Enable xxHash file checksums by default. Downgrading to 3.4.x
versions should be safe. Those versions know how to read and verify
xxHash checksums.

• #5527: Update Fauxton and xxHash dependencies.

• #5525: Array opcode optimization for QuickJS.

• #5518: More precise error location reporting for QuickJS.

• #5507, #5510, #5509: Erlang 28 compatibiliity.

• #5516: Detailed node membership info for Prometheus.

• #5489: Allow TLS client certs for Nouveau requests.

• #5452: BigInt support for QuickJS.

• #5439: Nouveau: upgrade dropwizard to 4.0.12.

• #5429: Add simple+pbkdf2 migration password scheme.

• #5424: Scanner: reduce log noise, fix QuickJS plugin mocks, grace-
fully handle broken search indexes.

• #5421: Nouveau: upgrade Lucene to 9.12.1.

• #5414: Remove unused multi_workers option from couch_work_queue.

• #5402: Remove unused, undocumented and detrimental idle check timeout
feature.

• #5395: Remove unused, undocumented and unreliabele pread_limit fea-
ture from couch_file.

• #5385: Clean up fabric_doc_update by introducing an #acc record.

• #5372: Upgrade to Elixir 1.17.

• #5351: Clouseau: show version in /_version endpoint.

• #5338: Scanner: add Nouveau and Clouseau design doc validation.

• #5335: Nouveau: support reading older Lucene 9x indexes.

• #5327, #5329, #5419: Allow switching JavaScript engines at runtime.

• #5326, #5328: Allow clients to specify HTTP request ID, including
UUIDs.

• #5321, #5366, #5413: Add support for SpiderMonkey versions 102, 115
and 128.

• #5317: Add quickjs to the list of welcome features.

Bugfixes
• #5515: Make sure query_limit config takes effect. Raise default limit
from 2^28 to 2^59. Allow infinity as a more ergonomic config value.

• #5522: Reopen indexes closed by Lucene in Nouveau.

• #5508: Fix array from() and at() for QuickJS.

• #5502: Buffer overflow and segfault fix in QuickJS.

• #5469, #5471: Retry closed connections in Nouveau.

• #5463: Fix badarith in Nouveau index query.

• #5447: Fix arithmetic mean in _prometheus.

• #5440: Fix _purged_infos when exceeding purged_infos_limit.

• #5431: Restore the ability to return Error objects from map().

• #5417: Clouseau: add a version check to connected() function to reli-
ably detect if a Clouseau node is ready to be used.

• #5416: Ensure we always map the documents in order in
couch_mrview_updater. While views still built correctly, this behav-
iour simplifies debugging.

• #5373: Fix checksumming in couch_file, consolidate similar functions
and bring test coverage from 66% to 90%.

• #5367: Scanner: be more resilient in the face of non-deterministic
functions.

• #5345: Scanner: be more resilient in the face of incomplete sample
data.

• #5344: Scanner: allow empty doc fields.

• #5341: Improve Mango test reliability.

• #5337: Prevent a broken mem3 app from permanently failing replica-
tion.

• #5334: Fix QuickJS scanner function_clause error.

• #5332: Skip deleted documents in the scanner.

• #5331: Skip validation for design docs in the scanner.

• #5330: Prevent inserting illegal design docs via Mango.

Docs
• #5433: Mango: document Nouveau index type.

• #5432: Add conceptual docs for Mango.

• #5428: Fix wrong link in example in CONTRIBUTING.md.

• #5400: Clarify RHEL9 installation caveats.

• #5380, #5404: Fix various typos.

• #5338: Clouseau: document version in /_version endpoint.

• #5340, #5412: Nouveau: document search cleanup API.

• #5316, #5325, #5426, #5442, #5445: Document various JavaScript engine
incompatibilities, including SpiderMonkey 1.8.5 vs. newer SpiderMon-
key and SpiderMonkey vs. QuickJS.

• #5320, #5374: Improve auto-lockout feature documentation.

• #5323: Nouveau: improve install instructions.

Tests
• #5492: Enable Clouseau testing for FreeBSD

• #5490: Enable Clouseau testing for MacOS

• #5397: Fix negative-steps error in Elixir tests.

Builds
• #5360: Use brew --prefix to find ICU paths on macOS.

Other
Theres always IOPS in the banana stand.

3.4.x Branch
• Version 3.4.3

• Version 3.4.2

• Version 3.4.1

• Version 3.4.0

Version 3.4.3
Highlights
• #5347: Fix attachment size calculation. This could lead to shards not
being scheduled for compaction correctly.

Performance
• #5437: Fix atts_since functionality for document GET requests. Avoids
re-replicating attachment bodies on doc updates.

Features
• #5439: Nouveau: upgrade dropwizard to 4.0.12.

• #5424: Scanner: reduce log noise, fix QuickJS plugin mocks, grace-
fully handle broken search indexes.

• #5421: Nouveau: upgrade Lucene to 9.12.1.

• #5414: Remove unused multi_workers option from couch_work_queue.

• #5385: Clean up fabric_doc_update by introducing an #acc record.

• #5372: Upgrade to Elixir 1.17.

• #5351: Clouseau: show version in /_version endpoint.

• #5338: Scanner: add Nouveau and Clouseau design doc validation.

• #5335: Nouveau: support reading older Lucene 9x indexes.

• #5327, #5329, #5419: Allow switching JavaScript engines at runtime.

• #5326, #5328: Allow clients to specify HTTP request ID, including
UUIDs.

• #5321, #5366, #5413: Add support for SpiderMonkey versions 102, 115
and 128.

• #5317: Add quickjs to the list of welcome features.

• #5471: Add nouveau.connection_closed_errors metric. Bumped when nou-
veau retries closed connections.

Bugfixes
• #5447: Fix arithmetic mean in _prometheus.

• #5440: Fix _purged_infos when exceeding purged_infos_limit.

• #5431: Restore the ability to return Error objects from map().

• #5417: Clouseau: add a version check to connected() function to reli-
ably detect if a Clouseau node is ready to be used.

• #5416: Ensure we always map the documents in order in
couch_mrview_updater. While views still built correctly, this behav-
iour simplifies debugging.

• #5373: Fix checksumming in couch_file, consolidate similar functions
and bring test coverage from 66% to 90%.

• #5367: Scanner: be more resilient in the face of non-deterministic
functions.

• #5345: Scanner: be more resilient in the face of incomplete sample
data.

• #5344: Scanner: allow empty doc fields.

• #5341: Improve Mango test reliability.

• #5337: Prevent a broken mem3 app from permanently failing replica-
tion.

• #5334: Fix QuickJS scanner function_clause error.

• #5332: Skip deleted documents in the scanner.

• #5331: Skip validation for design docs in the scanner.

• #5330: Prevent inserting illegal design docs via Mango.

• #5463, #5453: Fix Nouveau bookmark badarith error.

• #5469: Retry closed nouveau connections.

Docs
• #5433: Mango: document Nouveau index type.

• #5433: Nouveau: document Mango index type.

• #5428: Fix wrong link in example in CONTRIBUTING.md.

• #5400: Clarify RHEL9 installation caveats.

• #5380, #5404: Fix various typos.

• #5338: Clouseau: document version in /_version endpoint.

• #5340, #5412: Nouveau: document search cleanup API.

• #5316, #5325, #5426, #5442, #5445: Document various JavaScript engine
incompatibilities, including SpiderMonkey 1.8.5 vs. newer SpiderMon-
key and SpiderMonkey vs. QuickJS.

• #5320, #5374: Improve auto-lockout feature documentation.

• #5323: Nouveau: improve install instructions.

• #5434: Document use of Nouveau docker image

Tests
• #5397: Fix negative-steps error in Elixir tests.

Builds
• #5360: Use brew --prefix to find ICU paths on macOS.

Version 3.4.2
Highlights
• #5262: Enable supportsConcurrency in TopFieldCollectorManagerSet.
This fixes an issue which prevented creating larger indexes in Nou-
veau.

• #5299: Use LTO and static linking for QuickJS on Windows.

Performance
• #5268: Improve performance of couch_event_server under load.

Features
• #5272: Upgrade Nouveau Lucene to 9.12.0.

• #5286: Add ?top_n=X Nouveau parameter for facets.

• #5290: Send a 404 code for a missing Nouveau index.

• #5292: Add signature to _nouveau_info response.

• #5293: Make Nouveau Gradle script choosable.

• #5294: Return time spent waiting to update Nouveau index before query
starts.

Bugfixes
• #5274: Use normal Lucene syntax for unbounded ranges in Nouveau.

• #5270: Do not generate conflicts from the replicator application.

• #5285: Fix emitting multiple indexes per field per doc returning the
last indexed value with {"store": true}.

• #5289: Fix stored field in search results.

• #5298: Fix unused variable compiler warning in Nouveau.

Docs
• #5260: Correct default q value in POST /{db} section.

• #5281: Use {var} format for parameters instead of $var for scanner
docs.

• #5280: Sync suggested fabric timeout settings with the sources.

• #5287: Document String.prototype.match(undefined) Spidermonkey 1.8.5
vs Spidermonkey 78+ incompatibility.

Version 3.4.1
Highlights
• #5255: Set upgrade_hash_on_auth to false to disable automatic pass-
word hashing upgrades.

Bugfixes
• #5254: Handle the case when the QuickJS scanner has no valid views.

Tests
• #5253: Increase timeout for couch_work_queue test.

Docs
• #5256: Explain holding off 3.4.0 binaries and the reason for making a
3.4.1 release.

Version 3.4.0
Warning
CouchDB version 3.4.0 includes a feature to automatically upgrade pass-
word hashes to a newer algorithm and a configuration option that en-
ables this feature by default. As a consequence, if you are upgrading
to CouchDB version 3.4.0 from an earlier version and then have to roll
back to the earlier version, some of your _users documents might have
already automatically ugpraded to the new algorithm. Your older version
of CouchDB does not understand the resulting password hash and cannot
authenticate the user any more until the earlier password hash is re-
stored manually by an adminstrator.

As a result, the CouchDB team has decided to issue a 3.4.1 release set-
ting the configuration option to disable this new auto-upgrade feature.

The issue was found after the formal 3.4.0 release process has con-
cluded, so the source release is available normally, but the CouchDB
team has not made 3.4.0 convenience binaries available. The team recom-
mends to upgrade to 3.4.1 instead when it is available.

The CouchDB team also recommends enabling the feature by setting the
upgrade_hash_on_auth configuration option to true as soon as you are
safely running on 3.4.1 and have no more need to roll back the version.

Breaking Changes
• #5046: JWT: require valid exp claim by default

Users of JWT rightly expect tokens to be considered invalid once they
expire. It is a surprise to some that this requires a change to the
default configuration. In the interest of security we will now re-
quire a valid exp claim in tokens. Administrators can disable the
check by changing required_claims back to the empty string.

We recommend adding nbf as a required claim if you know your tokens
will include it.

• #5203: Continuous change feeds with descending=true&limit=N

Changes requests with feed=continuous&descending=true&limit=N, when N
is greater than the number of db updates, will no longer wait on db
changes and then repeatedly re-send the first few update sequences.
The request will return immediately after all the existing update se-
quences are streamed back to the client.

Highlights
.-.
/ |
/\ | .-._.) ( ) .-..-. .-. ) (
/ \ |( )( )( / ./.-'_( | ( )
.-' / \| `-' `--': \_/ (__.' `-'-'`--':
(__.' `.

• #4291: Introducing Nouveau (beta) a modern, from-the-ground-up imple-
mentation of Lucene-based full-text search for CouchDB. Please test
this thoroughly and report back any issues you might find.

• Setup instructions

• Usage

• Report a bug

• #4627: Add QuickJS as a JavaScript engine option.
Advantages over SpiderMonkey:

• Significantly smaller and easier to integrate codebase. Were using
~6 C files vs 700+ SM91 C++ files.

• Built with Apache CouchDB as opposed having to maintain a separate
SpiderMonkey package for OSs that dont support it (*cough*Red-
Hat9*cough*).

• Better sandboxing support.

• Preliminary test results show multiple performance improvements.

• 4x faster than SpiderMonkey 1.8.5.

• 5x faster than SpiderMonkey 91.

• 6x reduced memory usage per couchjs process (5MB vs 30MB).

• Allows compiling JavaScript bytecode ahead of time.

• QuickJS can be built alongside SpiderMonkey and toggled on/off at
runtime:

./configure --dev --js-engine=quickjs

• This makes it the default engine. But SpiderMonkey can still be
set in the config option:

[couchdb]
js_engine = spidermonkey | quickjs

• CouchDB also now includes a scanner plugin that, when enabled, can
scan all design docs in all your databases in the background and
report incompatibilities between SpiderMonkey and QuickJS. This
allows you to safely migrate to QuickJS.

• #4570, #4578, #4576: Adopt xxHash in favour of md5 for couch_file
checksums and ETag calculation. 30% performance increase for large
(128K) docs. No difference for smaller docs.

• #4814: Introduce PBKDF2-SHA256 for password hashing. The existing
PBKDF2-SHA1 variant is now deprecated. Increases the default itera-
tion count to 600000. Also introduce a password hash in-memory cache
with a low iteration number, to keep interactive requests fast for a
fixed time.

Entries in the password hash cache are time-limited, unused entries
are automatically deleted, and there is a capacity bound.

Existing hashed user doc entries will be automatically upgraded dur-
ing the next successful authentication. To disable auto-upgrading set
the [chttpd_auth] upgrade_hash_on_auth config setting to false.

• #4512: Mango: add keys-only covering indexes. Improves query response
times for certain queries up to 10x at p(95).

• #4681: Introduce optional countermeasures as we run out of disk
space.

• #4847: Require auth for _replicate endpoint. This continues the 3.x
closed-by-default design goal.

• #5032: Temporarily block access by client IP for repeated authentica-
tion failures. Can be disabled in config.

• Many small performance improvements, see the Performance section.

Features and Enhancements
• #5212: Allow configuring TLS signature_algs and eccs curves for the
clustered port.

• #5136: Print log dir on dev/run startup.

• #5150: Ensure rexi_buffer metric includes the internal buffered mes-
sages.

• #5145: Add aggregate rexi_server and rexi_buffer message queue met-
rics.

• #5093, #5178: Ensure replication jobs migrate after any the shard map
changes.

• #5079: Move to Erlang 25 minimum.

• #5069: Update Fauxton to v1.3.1.

• #5067: Support Erlang/OTP 27.

• #5053: Use the built-in crypto:pbkdf2_hmac function.

• #5036: Remove replication_job_supervisor.

• #5035: Modernise couch_replicator_supervisor.

• #5019: Remove unused build files.

• #5017: Remove unused boot_dev_cluster.sh.

• #5014: Add Couch Scanner module.

• #5013: Improve dist diagnostics.

• #4990: Add dbname to mango exec stats.

• #4987: Replace khash with maps in ddoc_cache_lru.

• #4984: Fabric: switch to maps for view rows.

• #4979: Git ignore top level clouseau directory.

• #4977: Replace khash with maps in couch_event_server.

• #4976: Add metrics for fast vs slow password hashing.

• #4965: Handle multiple response copies for _purged_infos API.

• #4878: Add an option to scrub some sensitive headers from external
json.

• #4834: Wait for newly set admin creds to be hashed in setup.

• #4821: Do not fail compactions if the last step is delayed by ioq.

• #4810: Mango: add $beginsWith operator.

• #4769: Improve replicator error handling.

• #4766: Add new HTTP endpoint /_node/_local/_smoosh/status.

• #4736: Stop client process and clean up if client disconnects.

• #4703: Add _purged_infos endpoint.

• #4685: Add "CouchDB-Replicator/..." user agent to replicator /_ses-
sion requests.

• #4680: Shard splitting: allow resumption of failed jobs and make
timeout configurable.

• #4677: Crash replication jobs on unexpected 4xx errors.

• #4670: Allow setting of additional ibrowse options like prefer_ipv6.

• #4662: Mango: extend _explain with candidate indexes and selector
hints.

• #4625: Add optional logging of security issues when replicating.

• #4623: Better upgrade handling of instance_start_time in replicator.

• #4613: Add option to suppress version info via HTTP header.

• #4601: Add simple fabric benchmark.

• #4581: Support Erlang/OTP 26.

• #4575: Add {verify, verify_peer} for TLS validation.

• #4569: Mango: add keys_examined for execution_stats.

• #4558: Make Erlang/OTP 24 the minimum supported Erlang version.

• #4513: Make timeouts for _view and _search configurable.

• #4483: Add RFC5424 compliant report logging.

• #4475: Add type and descriptions to prometheus output.

• #4443: Automatically enable FIPS mode at runtime.

• #4438: Upgrade hash algorithm for proxy auth.

• #4432: Hide shard-sync and purge documents from _local_docs.

• #4431: Allow definition of JWT roles claim as comma-separated list.

• #4404: Respond with 503 immediately if search not available.

• #4347: Remove failed couch_plugins experiment.

• #5046: JWT: require valid exp claim by default.

• #5065: Update Fauxton UI to version v1.3.1.

Performance
• #5172: Remove unique_integer bottleneck from couch_lru.

• #5168: Update couch_lru to use maps.

• #5104: Update xxhash from upstream tag v0.8.2.

• #5037: Optimise fabric:all_dbs().

• #4911: Optimise and clean up couch_multidb_changes.

• #4852: Optimise _active_tasks.

• #4786, #4789: Add extra timing stats for couch_js engine commands.

• #4679: Fix multipart parse attachment longer than expected error.

• #4672: Remove folsom and reimplement required functionality with new
Erlang/OTP primitives resulting in up to 19x faster histogram opera-
tions.

• #4617: Use a faster sets implementation available since OTP 24.

• #4608: Add metrics for fsync calls and query engine operations.

• #4604: 6x speedup for common mem3:dbname/1 function.

• #4603: Update vm.args settings, increased Erlang distribution buffer
size to 32MB.

• #4598: Speed up internal replicator.

• #4507, #4525: Add more prometheus metrics.

• #4505: Treat JavaScript internal errors as fatal.

• #4494: Treat single-element keys as key.

• #4473: Avoid re-compiling filter view functions.

• #4401: Enforce doc ids _changes filter optimisation limit and raise
it from 100 to 1000.

• #4394: Mango: push fields selection down to data nodes.

Bugfixes
• #5223, #5228, #5226: Fix handling IPv6 addresses for _session end-
points in replicator.

• #5191, #5193: Fix error loop with system freeze when removing a node
from a cluster.

• #5188: Fix units for replicator cluster_start_period config setting.

• #5185: Use an explicit message for replicator doc processor delayed
init. Fixes a rare case when the replicator will never start scanning
and monitoring _replicator dbs for changes.

• #5184: Remove compatibility couch_rand module.

• #5179: Do not leak fabric_rpc workers if coordinator is killed.

• #5205: Cleanly abort responses when path doesnt start with slash.

• #5204, #5203, #5200, #5201: Fix continuous changes feeds with a limit
greater than total.

• #5169: Make sure we never get an inconsistent couch_lru cache.

• #5167: Remove unused close_lru gen_server call.

• #5160: Ensure we run fabric worker cleanup in more cases.

• #5158: Fix PowerShell PSScriptAnalyzer warnings.

• #5153, #5156: Upgrade recon and fix Erlang/OTP 27 compiler warnings.

• #5154: Replace 0/1 to false/true for config keys.

• #5152: Improve worker cleanup on early coordinator exit to reduce the
occurrence of spurious exit:timeout errors in the log.

• #5151: Use atom for config key with_spidermonkey.

• #5147: Add passively closed client monitoring to search.

• #5144: Cleanup deprecated and unused functionality in rexi.

• #5143: Remove unused external functions and local external calls.

• #5130, #5132, #5138, #5163, #5170: Implement persistent node names.

• #5131: Remove unused couch_db_header module.

• #5084, #5126: Simplify and fix hyper. Remove external hyper depen-
dency.

• #5117, #5118: Validate target doc id for COPY method.

• #5111, #5114: Make sure config reload finds new .ini files in .d di-
rectories.

• #5110: Remove last remnant of snap install in ./configure. That hap-
pens in couchdb-pkg now.

• #5089, #5103: Fix _scheduler/docs/... path 500 errors.

• #5101: Fix replicator scheduler job stopping crash.

• #5100: Simplify couchdb.cmd.in and remove app version.

• #5097: Remove couch_io_logger module.

• #5066: Handle multiple Set-Cookie headers in replicator session plu-
gin.

• #5060: Cleanup a few clauses in fabric_view_changes.

• #5030: Always commit if we upgrade 2.x view files. Fixes misleading
wrong signature error.

• #5025: Fix seedlist to not return duplicate json keys.

• #5008: Fix case clause error in replicator _scheduler/docs response.

• #5000: Remove repetitive word in source commends (5000!).

• #4962: Make multidb changes shard map aware.

• #4958: Mango: use rolling execution statistics.

• #4921: Make sure to reply to couch_index_server clients.

• #4910: couch_passwords:verify should always return false for bad in-
puts.

• #4908: Mango: communicate rows read for global stats collection.

• #4906: Flush chttpd_db monitor refs on demonitor.

• #4904: Git ignore all .hypothesis directories.

• #4887: Look up search node name in config for weatherreport.

• #4837: Fix update bug in ets_lru.

• #4811: Prevent delayed opener error from crashing index servers.

• #4794: Fix incorrect raising of database_does_not_exist error.

• #4784: Fix parsing of node name from ERL_FLAGS in remsh.

• #4782, #4891: Mango: prevent occasional duplication of paginated text
results.

• #4761: Fix badrecord error when replicator is logging HTTP usage.

• #4759: TLS: use HTTP rules for hostname verification.

• #4758: Remove sensitive headers from the mochiweb request in pdict.

• #4751: Mango: correct behaviour of fields on _explain.

• #4722: Fix badmatch error when purge requests time out.

• #4716: Fix pending count for reverse changes feed.

• #4709: Mango: improve handling of invalid fields.

• #4704, #4707: Fix empty facet search results.

• #4682: _design_doc/queries with keys should only return design docs.

• #4669: Allow for more than two replicator socket options.

• #4666: Improve error handling in config API.

• #4659: Mango: remove duplicates from indexable_fields/1 results.

• #4658: Fix undefined range in mem3_rep purge replication logic.

• #4653: Fix ability to use ; inside of config values.

• #4629: Fix prometheus to survive mem3_sync termination.

• #4626: Fix purge infos replicating to the wrong shards during shard
splitting.

• #4602: Fix error handling for the _index endpoint and document _in-
dex/_bulk_delete.

• #4555: Fix race condition when creating indexes.

• #4524: Querying _all_docs with non-string key should return an empty
list.

• #4514: GET invalid path under _index should not cause 500 response.

• #4509: Make remsh work with quoted cookie.

• #4503: Add error_info clause for 410 Gone.

• #4491: Fix couch_index to avoid crashes under certain conditions.

• #4485: Catch and log any error from mem3:local_shards in in-
dex_server.

• #4473: Fix prometheus counter metric naming.

• #4458: Mango: Fix text index selection for queries with $regex.

• #4416: Allow _local doc writes to the replicator dbs.

• #4370: Ensure design docs are uploaded individually when replicating
with bulk_get.

• #4363: Fix replication _scheduler/docs total_rows.

• #4360: Fix handling forbidden exceptions from workers in fab-
ric_doc_update.

• #4353: Fix replication job_link.

• #4348: Fix undefined function warning in weatherreport.

• #4343: Fix undef when parsing replication doc body.

Tests
• #5219: Allow for overriding the host on running Mango tests.

• #5192: Clean elixir build artifacts with make clean.

• #5190: Remove flaky couch key tree test.

• #5187: Do not test SpiderMonkey libs when it is disabled on Windows.

• #5183: Remove redundant and racy assertion in the
couchdb_os_proc_pool test.

• #5182: Set minimum Elixir version to 1.15.

• #5180: Bump Clouseau to 2.23.1 in CI.

• #5128: Update Erlang in CI, support Elixir 1.17.

• #5102: Use a shorter 4000 msec replicator scheduling interval for
tests.

• #5078, #5085: Make app and release versions uniform. Remove the un-
used rel version.

• #5068: Fix flakiness in fabric_bench.

• #5054: Update a few deps and improve CI.

• #5050: Update CI OSes.

• #5048: Update CI Erlang versions.

• #5040: Fix invalid call to exit/2 in couch_server.

• #5039: Improve fabric all_dbs test.

• #5024: Fix flaky _changes async test.

• #4982: Fix flaky password hashing test.

• #4980: Fix password test timeout.

• #4973: Handling node number configuration in dev/run.

• #4959: Enable Clouseau for more platforms.

• #4953: Improve retries in dev/run cluster setup.

• #4947: Add tests for _changes endpoint.

• #4938: Add tests for _changes with different parameters.

• #4903: Add extra rev tree changes tests.

• #4902: Fix flaky tests by increasing timeout.

• #4900: More flaky fixes for cluster setup.

• #4899: Reduce EUnit log noise.

• #4898: Simplify couch_changes_tests.erl using macro ?TDEF_FE.

• #4893: Relax restriction on [admins] in dev local.ini.

• #4889: Do not use admin party for integration tests.

• #4873: Fix test for text index creation.

• #4863: Fix flaky users_db_security test.

• #4808: Fix flaky couch_stream test.

• #4806: Mango: do not skip json tests when Clouseau installed.

• #4803: Fix flaky ddoc_cache test some more.

• #4765: Fix flaky mem3 reshard test.

• #4763: Plug hole in unit test coverage of view cursor functions.

• #4726: Support Elixir 1.15.

• #4691: make elixir should match what we run in CI.

• #4632: Fix test database recreation logic.

• #4630: Add extra assert in flaky couch_file test.

• #4620: Add Erlang/OTP 26 to Pull Request CI matrix.

• #4552, #4553: Fix flaky couchjs error test.

• #4453: Fix flaky LRU test that the new super fast macOS CI worker no-
ticed.

• #4422: Clean up JSON index selection and add unit tests.

• #4345: Add test coverage for replicator user_ctx parser.

Docs
• #5221: Add notes about JavaScript engine compatibility issues and how
to use the new scanner feature.

• #5162: Update CVE backport policy.

• #5134: Remove JSON2 reference as we no longer ship our own JSON.

• #5063: Fix duplicate keys in find query.

• #5045: Create Python virtualenv on Windows for docs.

• #5038: Fix small detail about conflicts in Overview section.

• #4999: Change server instance to cluster for UUID docs.

• #4955: Revamp the installation instructions for FreeBSD.

• #4951: Add extension for copying code blocks with just one click.

• #4950: Improve changes feed API documentation.

• #4948: Update Sphinx package version to 7.2.6.

• #4946: Update Sphinx/RTD dependencies.

• #4942: Fix invalid JSON in _db_updates example.

• #4940: Re-wrote snap installation guide lines for 3.3.

• #4933: Set docs version numbers dynamically from file.

• #4928: Add missing installation OSes for convenience binaries.

• #4925: Break long lines for better readability within tables.

• #4774: Amend description of use_index on /{db}/_find.

• #4743: Ban the last monster.

• #4684: Add _design_docs/queries and _local_docs/queries.

• #4645: Add authentication data to examples.

• #4636: Clarify default quorum calculation.

• #4561: Clarify encoding length in performance section.

• #4402: Fix example code in partitioned databases.

Builds
• #4840: Add Debian 12 (bookworm) to CI and binary packages.

Other
Whats new, Scooby-Doo?

3.3.x Branch
• Version 3.3.3

• Version 3.3.2

• Version 3.3.1

• Version 3.3.0

Version 3.3.3
Features and Enhancements
• #4623: Handle replicator instance start time during upgrades better.

• #4653: Fix the ability to use ; in config values.

• #4626: Fix purge infos replicating to the wrong shards during shard
splitting.

• #4669: Make it possible to override [replicator] valid_socket_options
with more than two items.

• #4670: Allow setting of some ibrowse replication options such as
{prefer_ipv6, true}.

• #4679: Fix multipart parser attachment longer than expected error.
Previously there was a small chance attachments were not replicated.

• #4680: Allow restarting failed shard splitting jobs.

• #4722: Fix badmatch error when purge requests time out.

• #4736: Stop client process and clean up if client disconnects when
processing streaming requests.

• #4758: Remove sensitive headers from the mochiweb request in process
dictionary. This should prevent sensitive headers leaking into logs
when a request process crashes.

• #4784: Extract the correct node name from ERL_FLAGS in remsh.

• #4794: Fix incorrect raising of database_does_not_exist error.

• #4821: Wait for compacted indexes to flip. Previously, a timeout dur-
ing compact file flips could lead to crashes and a subsequent recom-
paction.

• #4837: Fix update bug in ets_lru.

• #4847: Require auth for _replicate endpoint.

• #4878: Add an option to scrub some sensitive headers from external
json requests.

Version 3.3.2
Features and Enhancements
• #4529: In Javascript process manager, use a database tag in addition
to a ddoc ID to quickly find processes. This should improve perfor-
mance.

• #4509, #4405: Make remsh work with quoted cookie values.

• #4473: Avoid re-compiling filter view functions. This could speed up
Javascript filter functions.

• #4412: Remove Javascript json2 script and the try/except clause
around seal.

• #4513: Allow configurable timeouts for _view and _search. Search
timeouts can be specified as [fabric] search_timeout and [fabric]
search_permsg. View per-message timeout can be configured as [fabric]
view_permsg_timeout.

• #4438: Proxy auth can now use one of the configured hash algorithms
from chttpd_auth/hash_algorithms to decode authentication tokens.

• #4370: Ensure design docs are uploaded individually when replicating
with _bulk_get. This restores previous behavior before version 3.3.0.

• #4416: Allow _local doc writes to the replicator dbs. Previously
this issue prevented replicating the replicator db itself, since
checkpointing was not working properly.

• #4363: Fix replication _scheduler/docs "total_rows" value.

• #4380: Be more defensive about SpiderMonkey location. An error should
be emitted early if the Spidermonkey library cannot be found.

• #4388: Bump recon to 2.5.3. See the changelog for more details.

• #4476, #4515, #4490, #4350, #4379: Various documentation cleanups and
fixes.

• Fix for CVE-2023-26268.

Version 3.3.1
Features and Enhancements
• #4343, #4344, #4345: Fix undef when parsing replication doc body with
a user_ctx.

• #4346: Add make target to find undef errors.

• #4347: Remove failed couch_plugins experiment, fixes more undef er-
rors.

• #4348: Fix undef error in weatherreport.

• #4353: Allow starting of more than one replication job. (DOH!)

Version 3.3.0
Highlights
• #4308: Replicator was optimized and should be faster. It now uses the
_bulk_get endpoint on the source, and can statistically skip calling
_revs_diff on the target. Benchmark tests replicating 1M documents,
10KB each, from UK to US East show a 3x speed improvement.
[image: Replicator, Tea! Earl Grey! Hot! (Because Picard said so)]
[image]

Features and Enhancements
• #3766, #3970, #3972, #4093, #4102, #4104, #4110, #4111, #4114, #4245,
#4246:, #4266: Add smoosh queue persistence. This allows resuming
smoosh operations after a node restart. This is disabled by default
and can be enabled with [smoosh] persist = true. Optimise smoosh op-
erations and increase test coverage to 90%.

• #3798: Add libicu version and collation algorithm version to
/_node/{node-name}/_versions.

• #3837: The Erlang source tree is now auto-formatted with erlfmt.

• #3845: Clean up the couch_ejson_compare C-module and squash Microsoft
compiler warnings.

• #3832: Add GET variant to _dbs_info endpoint, used to be POST only.

• #3864: Improve erlang_ls configuration.

• #3853: Remove legacy ddoc_cache_opener gen_server and speed up event
routing.

• #3879: Remove use of ERL_OPTS environment variable. All supported Er-
lang versions now use ERL_COMPILER_OPTIONS for the same purpose.

• #3883: Add support for SpiderMonkey 91.

• #3889: Track libicu collator versions in the view header.

• #3952: Make the timeout for receiving requests from attachment writ-
ers configurable.

• #3927: Include index signature in _search_info.

• #3963: Optimtize key tree stemming by using maps instead of sets.
This greatly reduced memory usage for heavily conflicted docs in some
situations.

• #3974: Create new config options in [couchdb] and [smoosh] sections
to enable finer control of compaction logging levels.

• #3983, #3984, #3985, #3987, #4033: Add various functions to couch_de-
bug module.

• #4000: Ensure Object.prototype.toSource() is always available.

• #4018: Update jiffy to 1.1.1 and b64url to 1.0.3.

• #4021: Reduce smoosh compaction log level to debug.

• #4041: Allow and evaluate nested json claim roles in JWT token.

• #4060, #4290: Add support for Erlang 25.

• #4064: Enable replicating purge requests between nodes. Also avoid
applying interactive purges more than once.

• #4069, #4084: Drop support for Erlang < 23, update vm.args settings
to match. Review this if you have customized your vm.args.

• #4083: Support Elixir 13.

• #4085: Add an option to let custodian always use [cluster] n value.

• #4095: Implement winning_revs_only option for the replicator. It
replicates only the winning revisions from the source to the target,
effectively discarding conflicts.

• #4135: Separate search IO from file IO.

• #4140, #4162: Upgrade hash algorithm for cookie auth (sha1 ->
sha256). This introduces a new config setting hash_algorithms. New
cookie values are hashed with sha256, sha1 hashes are still accepted.
Admins can set this to sha256 only. Sha1 will be disallowed in the
next major release. Show supported hash algorithms in
/_node/{node-name}/_versions endpoint.

• #4179: Dont double-encode changes sequence strings in the replicator.

• #4182: Explicitly maintain a fully connected cluster. Previously, it
was possible for the nodes to disconnect, and for that state to per-
sist until the nodes restarted.

• #4198: Redact passwords in log file.

• #4243: Update mochiweb to 3.1.1.

• #4254: The _dbs_info access control is now configured with the
[couchdb] admin_only_all_dbs setting. Defaults to true. This was a
leftover from the 3.0.0 release.

• #4264: active database sizes is now limited to leaf nodes. Previ-
ously, it included intermediate tree nodes, which had the effect that
deleting (large) documents did not decrease active database size. In
addition, smoosh now picks up databases where large documents are
deleted for compaction more eagerly, reclaiming the deleted space
quicker.

• #4270: Shard splitting now uses its own reshard IO priority. It can
be configured to be safely run in the background with production
loads, or with maximum IO available, if admins prefer quicker
progress.

• #4274: Improve validation of replicator job parameters & move _repli-
cator VDU design doc to internal BDU.

• #4280: Add CFLAGS and LDFLAGS to ICU build parameters.

• #4284: Remove all usage of global to avoid potential deadlocks in
replication jobs.

• #4287: Allow = in config key names.

• #4306: Fauxton was updated to version v1.2.9. Changes since v1.2.8
can be found here

• #4317: Write Relax welcome message to standard out on Windows.

Performance
• #3860: Add sharding to couch_index_server, similar to #3366, avoids
processing bottlenecks on servers with a lot of concurrent view in-
dexing going on.

• #3891: Avoid decoding JWT payloads when not necessary.

• #4031: Default [rexi] use_kill_all to true. This improves intra-clus-
ter-node messaging. Set to false if you run a cluster with nodes that
have a version <3.0.0.

• #4052: Optimise couch_util:reorder_results/2,3, which speeds up
_bulk_docs and _revs_diff.

• #4055: Avoid using length/1 guard for >0 or ==0 tests in
couch_key_tree.

• #4056: Optimise couch_key_tree:find_missing/2. This speeds up
_revs_diff.

• #4059: Reduce complexity of possible_ancestors from quadratic to lin-
ear. This speeds up working with heavily conflicted documents signif-
icantly.

• #4091: Optimise couch_util:to_hex/1, this speeds up all operations
that need to encode a revision id into JSON (this is most opera-
tions).

• #4106: Set io_priority in all IO paths. Introduces system io_prior-
ity.

• #4144, #4172: Implement _bulk_get support for the replicator. Back-
ward compatibility is ensured. This speeds up all replications. Add
option to disable new behaviour for legacy setups.

• #4163: Statistically skip _revs_diff in the replicator. This improves
performance for replications into empty targets.

• #4177: Remove the long deprecated bigcouch 0.4 change sequence sup-
port.

• #4238: Optimise _bulk_get endpoint. This speeds up replication of 1M
docs by ~2x. Individual _bulk_get requests are up to 8x faster.

• #3517: Add experimental fix for reduce performance regression due to
expensive repeated AST-transformations on newer SpiderMonkey ver-
sions. Set COUCHDB_QUERY_SERVER_JAVASCRIPT env var to
COUCHDB_QUERY_SERVER_JAVASCRIPT="/opt/couchdb/bin/couchjs
/opt/couchdb/share/server/main-ast-bypass.js".

• #4262: couchjs executable built against Spidermonkey >= 78 will re-
turn the detailed major.minor.patch as opposed to just the major ver-
sion as previously.

Bugfixes
• #3817: Fix undefined function call in weatherreport.

• #3819: Return 400 instead of 500 response code for known invalid
_bulk_docs with new_edits=false request.

• #3861: Add SameSite setting when clearing session cookies.

• #3863: Fix custom TLS distribution for Erlang 20.

• #3870: Always send all cookie attributes.

• #3886: Avoid changes feed rewind after shard move with no subsequent
db updates.

• #3888: Make _stats endpoint resilient against nodes that go offline.

• #3901: Use db-creation time instead of 0 for instance_start_time to
help replicator recognise whether a peer database was deleted and
recreated.

• #3909: Fix new_edits:false and VDU function_clause.

• #3934: Fix replicated_changes typo for purge doc updates.

• #3940: Ensure the multipart parser always monitors the worker and
make sure to wait for attachment uploads before responding.

• #3950: Ignore responses from timed-out or retried ibrowse calls.

• #3969: Fix skip and limit for _all_dbs and _dbs_info.

• #3979: Correctly respond with a 500 code when document updates time
out under heavy load.

• #3992: Show that Search is available if it was available before.
Avoid Search availability disappearing just because a Search node was
temporarily not available.

• #3993: Return a 400 error when decoding a JWT token fails, rather
than crashing and not responding at all.

• #3990: Prevent creation of ddocs with no name through Mango index
creation.

• #4003: Improve index building during shard splitting.

• #4016: Fix function_clause error for replicated changes with a target
VDU.

• #4020: Fix maybe_handle_error clauses.

• #4037: Fix ES{256,384,512} support for JWTs.

• #4040: Handle exit(shutdown) error in chttpd.

• #4043: Fix purge request timeouts (5s -> infinity).

• #4146: The devcontainer has been updated.

• #4050: Handle all_dbs_active in fabric_doc_update.

• #4160: Return a proper 400 error when an invalid object is sent to
_bulk_get.

• #4070: Prevent error:function_clause in check_security/3 if roles
claim is malformed.

• #4075: Fix couch_debug:opened_files* functions.

• #4108: Trim X-Auth-CouchDB-Roles header after reading.

• #4153: The require_valid_user setting is now under chttpd.

• #4161: Fix content-type handling in _session.

• #4176: Fix eventsource _changes feed.

• #4197: Support large (and impractical as-of-yet) q values. Fix shard
open timeouts for q > 64.

• #4199: Fix spurious unlock in close_db_if_idle.

• #4230: Avoid refresh messages piling up in prometheus server.

• #4240: Implement global password hasher process. This fixes a
race-condition when setting new admin passwords in quick succession
on a multicore server.

• #4261, #4271: Clean up stale view checkpoints, improve purge client
cleanup logging

• #4272: Kill all couch_server_N if database_dir changes.

• #4313: Use chttpd config section when patching local _replicate end-
points.

• #4321: Downgrade jiffy to allow building on Windows again.

• #4329, #4323: Ignore build windows binaries in git.

Tests
• #3825: Eliminate Elixir compiler warnings.

• #3830: Reduce skipped Elixir integration tests.

• #3890: Handle not_found lookups removing ddoc cache key.

• #3892: Use Debian Stable for CI, add Erlang 24 to CI.

• #3898: Remove CI support for Ubuntu 16.04.

• #3903, #3914: Refactor Jenkins to dynamically generate stages. Drop
MINIMUM_ERLANG_VERSION to 20, drop the packaging ERLANG_VERSION to
23, add the weatherreport-test as a build step, and add ARM and POWER
back into the matrix.

• #3921:, #3923: Execute various tests in clean database_dir to avoid
subsequent test flakiness.

• #3968: Ensure key tree rev stemming doest take too much memory.

• #3980: Upgrade Mango test dependency nose to nose and fix
flaky-on-Windows tests.

• #4006: Remove CI support for Debian 9.

• #4061, #4082: Update PPC CI builder.

• #4096: Fix flaky validate_doc_update Elixir test.

• #4123: Fix haproxy.cfg.

• #4126: Return a 400 response for a single new_edits=false doc update
without revision.

• #4129: Fix proxyauth_test and removed it from skip list.

• #4132: Address race condition in cpse_incref_decref test.

• #4151: Refactor replication tests to use clustered endpoints.

• #4178: Add test coverage to prevent junk in eventsource.

• #4188: Enable eunit coverage for all applications instead of enabling
it per-application.

• #4202: Fix race condition in ddoc cache LRU test.

• #4203, #4205: Reduce test log noise.

• #4268: Improve flaky _dbs_info test.

• #4319: Fix offline configure and make release.

• #4328: Fix eaddrnotavail in Elixir tests under Windows.

• #4330: Do not run source checks in main CI build.

Docs
• #4164: The CouchDB documentation has been moved into the main CouchDB
repository.

• #4307, #4174: Update Sphinx to version 5.3.0

• #4170: Document the /_node/{node-name}/_versions endpoint.

Builds
• #4097: Stop publication of nightly packages. They were not used any-
where.

• #4322: Reuse installed rebar and rebar3 for mix. Compatible with
Elixir =< 13 only. Elixir 14 is not supported yet.

• #4326: Move Elixir source checks to a separate build step.

Other
• Added pumpkin spice to selected endpoints. Thank you for reading the
3.3.0 release notes.

3.2.x Branch
• Version 3.2.3

• Version 3.2.2

• Version 3.2.1

• Version 3.2.0

Version 3.2.3
Features and Enhancements
• #4529: In Javascript process manager, use a database tag in addition
to a ddoc ID to quickly find processes. This should improve perfor-
mance.

• #4509, #4405: Make remsh work with quoted cookie values.

• Fix for CVE-2023-26268.

Version 3.2.2
Bugfixes
• Fix for CVE-2022-24706. This is a security release for a critical
vulnerability.

• #3963: Optimize compaction and doc updates for conflicted documents
on Erlang versions higher than 21.

• #3852: Add support for SpiderMonkey 91esr.

Version 3.2.1
Features and Enhancements
• #3746: couch_icu_driver collation driver has been removed. ICU colla-
tion functionality is consolidated in the single couch_ejson_compare
module. View performance might slightly increase as there are less
corner cases when the C collation driver fails and falls back to Er-
lang.

• #3787: Update sequences generated from DB info and
_changes?since=now&limit=0 now contain shard uuids as part of their
internal, opaque, representation. As a result, there should be less
chance of experiencing changes feed rewinds with these sequences.

• #3798: ICU driver and collator algorithm versions are returned in the
_node/{node-name}/_versions result.

• #3801: Users with the _metrics role can now read _prometheus metrics.

Bugfixes
• #3780: Avoid changes feed rewinds after shard moves.

• #3779, #3785: Prevent deleted view file cleanup from crashing when
database is deleted while the cleanup process is running.

• #3789: Fix badarith 500 errors when [fabric] request_timeout is set
to infinity.

• #3786: Fix off-by-one limit error for _all_dbs. Also, the auto-in-
jected shard _dbs design doc is removed and replaced with an Erlang
module.

• #3788: Minimize changes feeds rewinds when a node is down.

• #3807: Enable custodian application reporting. Previously, custodian
was accidentally left disabled as it used a hard-coded shards db name
different than _dbs.

• #3805: Cluster setup correctly syncs admin passwords and uses the new
(since 3.2.0) [chttpd_auth] config section instead of the previous
[couch_httpd_auth] section.

• #3810: Local development dev/run script now uses the [chttpd_auth]
section in local.ini instead of [couch_httpd_auth].

• #3773: Fix reduce view collation results for unicode equivalent keys.

Version 3.2.0
Features and Enhancements
• #3364: CouchDBs replicator now implements a Fair Share replication
scheduler. Rather than using a round-robin scheduling mechanism, this
update allows specifying the relative priority of jobs via different
_replicator databases. More information is available in the
_replicator DB docs.
[image: Robert Downey, Jr., thinks that's fair enough for him.] [im-
age]

• #3166: Allow custom JWT claims for roles, via the [jwt_auth]
roles_claim_name config setting.

• #3296, #3312: CouchDB now includes weatherreport and its dependency
custodian, a diagnostic app forked from Bashos riaknostic tool. More
documentation is available in the Cluster Troubleshooting section.

• #2911, #3298, #3425: CouchDB now returns the version of SpiderMonkey
to administrators in the GET /_node/{node-name}/_versions response.

• #3303: CouchDB now treats a 408 response received by the replicator
similar to any 5xx error (by retrying, as opposed to a permanent er-
ror). CouchDB will never return a 408, but some reverse proxies in
front of CouchDB may return this code.

• #3322: _session now accepts gzip encoding.

• #3254: The new $keyMapMatch operator allows Mango to query on the
keys of a map. It is similar to the $elemMatch operator, but instead
of operating on the elements of array, it operates on the keys of a
map.

• #3336: Developers now have access to a .devcontainer configuration
for the 3.x version of CouchDB, right in the source code repository.

• #3347: The default maximum attachment size has been reduced from in-
finity to 1 GiB.

• #3361: Compaction process suspension now appears in the active_tasks
output, allowing administrators to verify that the strict_window
value is being respected.

• #3378: The [admins] section and the [replicator] password are now
redacted from all logs. In addition, #3380 removes user credentials,
user documents and design documents from logfiles as much as possi-
ble. Further, #3489 no longer logs all of the messages received by a
terminated internal Erlang process.

• #3421, #3500: CouchDB now supports SpiderMonkey 78 and 86.

• #3422: CouchDB now supports Erlang/OTP 23 and error_logger reports
for Erlang/OTP >= 21.

• #3566: CouchDB now also supports Erlang/OTP 24.

• #3571: CouchDB no longer supports Erlang/OTP 19.

• #3643: Contribute a custom Erlang network protocol to CouchDB, users
can specify nodes to use TCP or TLS.
[image: The SSL/TLS handshake enables the TLS client and server to
establish the secret keys with which they communicate.] [image]

• #3472, #3473, #3609: Migrate some config options from [httpd] to
[chttpd], migrate some from [couch_httpd_auth] to [chttpd_auth], and
comment all out in the default.ini.

• Config options moved from [httpd] to [chttpd]: allow_jsonp,
changes_timeout, config_whitelist, enable_cors, secure_rewrites,
x_forwarded_host, x_forwarded_proto, x_forwarded_ssl, en-
able_xframe_options, max_http_request_size.

• Config options moved from [couch_httpd_auth] to [chttpd_auth]: au-
thentication_redirect, timeout, auth_cache_size, allow_persis-
tent_cookies, iterations, min_iterations, max_iterations, pass-
word_scheme, proxy_use_secret, public_fields, secret, users_db_pub-
lic, x_auth_roles, x_auth_token, x_auth_username, cookie_domain,
same_site

• #3586: We added a new way of specifying basic auth credentials which
can include various characters previously not allowed to be included
in the url info part of endpoint urls.

• #3483: We added a way of specifying requirements for new user pass-
words using a list of regular expressions.

• #3506, #3416, #3377: CouchDB now provides a Prometheus compatible
endpoint at GET /_node/{node-name}/_prometheus. A configuration op-
tion allows for scraping via a different port (17986) that does not
require authentication, if desired. More information is available at
the Prometheus API endpoint summary.

• #3697, COUCHDB-883 (JIRA): As an opt-in policy, CouchDB can now stop
encoding the plus sign + in non-query parts of URLs, in compliance
with the original CouchDB standards. The opt-in is via the [chttpd]
decode_plus_to_space = true setting. In CouchDB 4.x, this is going to
be an opt-out policy.

• #3724: CouchDB now has new CSP settings for attachments and show/list
functions. This deprecates the old [csp] enable and [csp]
header_value settings, replacing them with the new [csp] utils_enable
and [csp] utils_header_value settings respectively. In addition, new
settings for attachments_enable, attachments_header_value,
showlist_enable and showlist_header_value now are available. Documen-
tation is in the default.ini file.

• #3734, #3733: Users with databases that have low q and n values would
often receive the No DB shards could be opened error when the cluster
is overloaded, due to a hard-coded 100ms timeout. CouchDB now calcu-
lates a more reasonable timeout, based on the number of shards and
the overall maximum fabric request timeout limit, using a geometric
series.

Performance
• #3337: Developer nodes now start faster when using the dev/run
script.

• #3366: The monolithic couch_server process has been sharded for per-
formance. Previously, as a single gen_server, the process would have
a finite throughput that, in busy clusters, is easily breached caus-
ing a sizeable backlog in the message queue, ultimately leading to
failure and errors. No more! The aggregate message queue info is
still available in the _system output. ( #3370 )

• #3208: CouchDB now uses the latest ibrowse 4.4.2 client for the
replicator.

• #3600, #3047, #3019: The default slack channel for smoosh auto-com-
paction has been increased to a more reasonable value, reducing load
on systems that would have normally been idle in CouchDB 2.x (where
no auto-compaction daemon exists).

• #3711: Changes feeds may no longer rewind after shard moves, assuming
the node and range specified by the changes feed nonce can still
match an existing nodes shard.

Bugfixes
• Complete retirement of the JavaScript test suite - replaced by
Elixir. Hooray!

• #3165: Allow configurability of JWT claims that require a value. Also
fixes #3232. Further, #3392 no longer validates claims provided that
CouchDB does not require.

• #3160, #3161: The run_queue statistic now returns valid information
even when using Erlang BEAM dirty CPU and IO queues.

• #3162: Makefiles updated to include local configs & clean configs
when running make devclean.

• #3195: The max_document_size parameter now has a clearer explanation
in default.ini.

• #3207, #2536: Improve the INSTALL.Unix.md file.

• #3212: Base and extra headers are properly combined when making
replicator requests that contain duplicate headers.

• #3201: When using a POST with request body to pass parameters to a
view-like request, the boolean parameters are accepting only JSON
strings, but not booleans. Now, CouchDB accepts true and false for
the stable parameter, in addition to "true" and "false". comment in

• #1988: Attachment operations PUT /db/doc and POST /db now perform
consistent attachment name validation.

• #3249: Documents with lots of conflicts no longer blow up couchjs if
the user calls _changes with a JS filter and with style=all_docs.

• #3144: Respawning compaction jobs to catch up with intervening
changes are now handled correctly by the smoosh monitor.

• #3252: CouchDB now exports the couch_util:json_decode/2 function to
support maps instead of the default data structure.

• #3255, #2558: View files that have incorrect db_headers now reset the
index forcing a rebuild.

• #3271: Attachments that are stored uncompressed but later replicated
to nodes that compress the attachment no longer fail an internal md5
check that would break eventual consistency between nodes.

• #3277: req_body requests that have req_body set already now properly
return the field without parsing.

• #3279: Some default headers were missing from some responses in
replication, including X-CouchDB-Body-Time and X-Couch-Request-ID.

• #3329, #2962: CouchDB no longer returns broken couchjs processes to
the internal viewserver process pool.

• #3340, #1943: PUTs of multipart/related attachments now support a
Transfer-Encoding value of chunked. Hooray!

• #2858, #3359: The cluster setup wizard no longer fails when a request
to / is not made before a request to finish_cluster.

• #3368: Changing the max_dbs_open configuration setting correctly en-
sures that each new couch_server_X property receives 1/num_servers()
of it.

• #3373: Requests to {db}/_changes with a custom filter no longer re-
sult in a fabric request timeout if the request body is not available
to additional cluster nodes, resulting in a more descriptive exit
message and proper JSON object validation in the payload.

• #3409: The internal chttpd_external:json_req_obj/2 function now reads
the cached peer before falling back to a socket read operation.

• #3335, #3617, #3708: The COUCHDB_FAUXTON_DOCROOT environment variable
is now introduced to allow its explicit overriding at startup.

• #3471: http clients should no longer receive stacktraces unexpect-
edly.

• #3491: libicu tests no longer fail on older OS releases such as Cen-
tOS 6 and 7.

• #3541: Usernames and passwords can now contain @ and not break the
CouchDB replicator.

• #3545: The dreyfus_index_manager process now supports offheap message
queues.

• #3551: The replication worker pool now properly cleans up worker
processes as they are done via the worker_trap_exits = false setting.

• #3633, #3631: All code paths for creating databases now fully respect
db creation options, including partitioning options.

• #3424, #3362: When using latest=true and an old revision with con-
flicting children as rev is specified, CouchDB no longer returns an
"error": "case_clause" response.

• #3673: Non-existent attachments now return a 404 when the attachment
is missing.

• #3698: The dev/run development script now allows clusters where n >
5.

• #3700: The maybe_close message is now sent to the correct internal
process.

• #3183: The smoosh operator guide now recommends to use the rpc:multi-
call function.

• #3712: Including a payload within a DELETE operation no longer hangs
the next request made to the same mochiweb acceptor.

• #3715: For clusters with databases where n > [cluster] n, attachments
chunks are longer dropped on quorum writes.

• #3507: If a file is truncated underneath CouchDB, CouchDB will now
log the filename if it finds this situation with a file_truncate_er-
ror.

• #3739: Shards with large purge sequences no longer fail to split in a
shard splitting job.

• #3754: Always return views meta info when limit=0 and sorted=true.

• #3757: Properly sort descending=true view results with a keys list.

• #3763: Stabilize view row sorting order when they are merged by the
coordinator.

Other
• Donuts for everyone! Er, not really - thank you for reading the 3.2
release notes.

3.1.x Branch
• Version 3.1.2

• Version 3.1.1

• Version 3.1.0

Version 3.1.2
This is a security release for a low severity vulnerability. Details of
the issue will be published one week after this release. See the CVE
database for details at a later time.

Version 3.1.1
Features and Enhancements
• #3102, #1600, #2877, #2041: When a client disconnects unexpectedly,
CouchDB will no longer log a normal : unknown error. Bring forth the
rainbows.
[image: The Gravity Falls gnome pukes some rainbows for us.] [image]

• #3109: Drilldown parameters for text index searches may now be speci-
fied as a list of lists, to avoid having to define this redundantly
in a single query. (Some languages dont have this facility.)

• #3132: The new [chttpd] buffer_response option can be enabled to de-
lay the start of a response until the end has been calculated. This
increases memory usage, but simplifies client error handling as it
eliminates the possibility that a response may be deliberately termi-
nated midway through, due to a timeout. This config value may be
changed at runtime, without impacting any in-flight responses.

Performance
Bugfixes
• #2935: The replicator now correctly picks jobs to restart during
rescheduling, where previously with high load it may have failed to
try to restart crashed jobs.

• #2981: When handling extremely large documents (50MB), CouchDB can no
longer time out on a gen_server:call if bypassing the IOQ.

• #2941: CouchDB will no longer fail to compact databases if it finds
files from a 2.x compaction process (prior to an upgrade) on disk.

• #2955 CouchDB now sends the correct CSP header to ensure Fauxton op-
erates correctly with newer browsers.

• #3061, #3080: The couch_index server wont crash and log errors if a
design document is deleted while that index is building, or when a
ddoc is added immediately after database creation.

• #3078: CouchDB now checks for and complains correctly about invalid
parameters on database creation.

• #3090: CouchDB now correctly encodes URLs correctly when encoding the
atts_since query string.

• #2953: Some parameters not allowed for text-index queries on parti-
tioned database are now properly validated and rejected.

• #3118: Text-based search indexes may now be cleaned up correctly,
even if the design document is now invalid.

• #3121: fips is now only reported in the welcome message if FIPS mode
was enabled at boot (such as in vm.args).

• #3128: Using COPY to copy a document will no longer return a JSON re-
sult with two ok fields.

• #3138: Malformed URLs in replication requests or documents will no
longer throw an error.

Other
• JS tests skip faster now.

• More JS tests ported into elixir: reader_acl, reduce_builtin, re-
duce_false, rev_stemming, update_documents, view_collation_raw,
view_compaction, all the view_multi_key tests, view_sandboxing,
view_update_seq.

Version 3.1.0
Features and Enhancements
• #2648: Authentication via JSON Web Token (JWT). Full documentation is
at the friendly link.

• #2770: CouchDB now supports linking against SpiderMonkey 68, the cur-
rent Mozilla SpiderMonkey ESR release. This provides direct support
for packaging on the latest operating system variants, including
Ubuntu 20.04 Focal Fossa.

•

A new Fauxton release is included, with updated dependencies, and a
new optional
CouchDB news page.

Performance
• #2754: Optimized compactor performance, resulting in a 40% speed im-
provement when document revisions approach the revs_limit. The fixes
also include additional metrics on size tracking during the sort and
copy phases, accessible via the GET /_active_tasks endpoint.

• A big bowl of candy! OK, no, not really. If you got this farthank you
for reading.

3.0.x Branch
• Upgrade Notes

• Version 3.0.1

• Version 3.0.0

Upgrade Notes
• #2228: The default maximum document size has been reduced to 8MB.
This means that databases with larger documents will not be able to
replicate into CouchDB 3.0 correctly without modification. This
change has been made in preparation for anticipated hard upper limits
on document size imposed by CouchDB 4.0. For 3.x, the max document
size setting can be relaxed via the [couchdb] max_document_size con-
fig setting.

• #2228: The default database sharding factor q has been reduced to 2
by default. This, combined with automated database resharding (see
below), is a better starting place for new CouchDB databases. As in
CouchDB 2.x, specify ?q=# to change the value upon database creation
if desired. The default can be changed via the config [cluster] q
setting.

• #1523, #2092, #2336, #2475: The node-local HTTP interface, by default
exposed on port 5986, has been removed. All functionality previously
available at that port is now available on the main, clustered inter-
face (by default, port 5984). Examples:

GET /_node/{nodename}/_stats
GET /_node/{nodename}/_system
GET /_node/{nodename}/_all_dbs
GET /_node/{nodename}/_uuids
GET /_node/{nodename}/_config
GET /_node/{nodename}/_config/couchdb/uuid
POST /_node/{nodename}_config/_reload
GET /_node/{nodename}/_nodes/_changes?include_docs=true
PUT /_node/{nodename}/_dbs/{dbname}
POST /_node/{nodename}/_restart
GET /_node/{nodename}/{db-shard}
GET /_node/{nodename}/{db-shard}/{doc}
GET /_node/{nodename}/{db-shard}/{ddoc}/_info

and so on. Documentation has been updated to reflect this change.

WARNING:
The _node endpoint is for adminstrative purposes it is NOT in-
tended as an alternative to the regular endpoints (GET /dbname,
PUT /dbname/docid and so on)

• #2389: CouchDB 3.0 now requires a server admin user to be defined at
startup, or will print an error message and exit. If you do not have
one, be sure to create an admin user. (The Admin Party is now over.)
[image: Dizzy the cat with a Santa hat.] [image] CC-BY-NC 2.0: -
hehaden @ Flickr.UNINDENT

• #2576: CouchDB 3.0 now requires admin-level access for the /_all_dbs
endpoint.

• #2339: All databases are now created by default as admin-only. That
is, the default new database _security object is now:

{
"members" : { "roles" : [ "_admin" ] },
"admins" : { "roles" : [ "_admin" ] }
}

This can be changed after database creation.

• Due to code changes in #2324, it is not possible to upgrade transpar-
ently from CouchDB 1.x to 3.x. In addition, the couchup utility has
been removed from CouchDB 3.0 by #2399. If you are upgrading from
CouchDB 1.x, you must first upgrade to CouchDB 2.3.1 to convert your
database and indexes, using couchup if desired. You can then upgrade
to CouchDB 3.0. Or, you can start a new CouchDB 3.0 installation and
replicate directly from 1.x to 3.0.

• #1833, #2358, #1871, #1857: CouchDB 3.0 supports running only under
the following Erlang/OTP versions:

• 19.x - soft support only. No longer tested, but should work.

• 20.x - must be newer than 20.3.8.11 (20.0, 20.1, 20.2 versions all
invalid)

• 21.x - for 21.2, must be newer than 21.2.3

• 22.x - for 22.0, must be newer than 22.0.5

• #1804: By default, views are limited to return a maximum of 2**28
(268435456) results. This limit can be configured separately for
views and partitioned views via the query_limit and parti-
tion_query_limit values in the ini file [query_server_config] sec-
tion.

• After upgrading all nodes in a cluster to 3.0, add [rexi]
use_kill_all = true to local.ini to save some intra-cluster network
bandwidth.

Deprecated feature removal
The following features, deprecated in CouchDB 2.x, have been removed or
replaced in CouchDB 3.0:

• #2089, #2128, #2251: Local endpoints for replication targets, which
never functioned as expected in CouchDB 2.x, have been completely re-
moved. When replicating databases, always specify a full URL for the
source and target. In addition, the node local _replicator database
is no longer automatically created.

• #2163: The disk_size and data_size fields have been retired from the
database info object returned by GET /{db}/. These were deprecated in
CouchDB 2.x and replaced by the sizes object, which contains the im-
proved file, active and external size metrics. Fauxton has been up-
dated to match.

• #2173: The ability to submit multiple queries against a view using
the POST to /{db}/_design/{ddoc}/_view/{view} with the ?queries= op-
tion has been replaced by the new queries endpoint. The same is true
of the _all_docs, _design_docs, and _local_docs endpoints. Specify a
keys object when POST-ing to these endpoints.

• #2248: CouchDB externals (_external/) have been removed entirely.

• #2208: CouchDB no longer supports the delayed_commits option in the
configuration file. All writes are now full commits. The /_en-
sure_full_commit API endpoint has been retained (as a no-op) for
backwards compatibility with old CouchDB replicators.

• #2395: The security object in the _users database cannot be edited by
default. A setting exists in the configuration file to revert this
behaviour. The ability to override the disable setting is expected to
be removed in CouchDB 4.0.

Deprecated feature warnings
The following features are deprecated in CouchDB 3.0 and will be re-
moved in CouchDB 4.0:

• Show functions (/{db}/{ddoc}/_show)

• List functions (/{db}/{ddoc}/_list)

• Update functions (/{db}/{ddoc}/_update)

• Virtual hosts and ini-file rewrites

• Rewrite functions (/{db}/{ddoc}/_rewrite)

Version 3.0.1
Features and Enhancements
• Fauxton was updated to version v1.2.3.

Bugfixes
• #2441: A memory leak when encoding large binary content was patched.
This should resolve a long-standing gradual memory increase bug in
CouchDB.

• #2613: Simultaneous attempts to create the same new database should
no longer result in a 500 Internal Server Error error.

• #2678: Defaults for the smoosh compaction daemon are now consistent
with the shipped default.ini file.

• #2680: The Windows CouchDB startup batch file will no longer fail to
start CouchDB if incompatible versions of OpenSSL are on the PATH.

• #2741: A small performance improvement in the couch_server process
was made.

• #2745: The require_valid_user exception logic was corrected.

• #2643: The users_db_security_editable setting is now in the correct
section of the default.ini file.

• #2654: Filtered changes feeds that need to rewind partially should no
longer rewind all the way to the beginning of the feed.

• #2655: When deleting a session cookie, CouchDB should now respect the
operator-specified cookie domain, if set.

• #2690: Nodes that re-enter a cluster after a database was created
(while the node was offline or in maintenance mode) should more cor-
rectly handle creating local replicas of that database.

• #2805: Mango operators more correctly handle being passed empty ar-
rays.

• #2716, #2738: The remsh utility will now try and guess the node name
and Erlang cookie of the local installation. It will also respect the
COUCHDB_ARGS_FILE environment variable.

• #2797: The cluster setup workflow now uses the correct logging mod-
ule.

• #2818: Mango now uses a safer method of bookmark creation that pre-
vents unexpectedly creating new Erlang atoms.

• #2756: SpiderMonkey 60+ will no longer corrupt UTF-8 strings when
various JS functions are applied to them.

• Multiple test case improvements, including more ports of JS tests to
Elixir.

Version 3.0.0
Features and Enhancements
• #1789: User-defined partitioned databases.

These special databases support user-driven placement of documents
into the same shard range. JavaScript views and Mango indexes have
specific optimizations for partitioned databases as well.

Two tweakable configuration parameters exist:

• #1842: Partition size limits. By default, each partition is limited
to 10 GiB.

• #1684: Partitioned database support can be disabled via feature
flag in default.ini.

• #1972, #2012: Automated shard splitting. Databases can now be
re-sharded while online to increase the q factor to a larger number.
This can be configured to require specific node and range parameters
upon execution.

• #1910: Automatic background indexing, internally known as ken. This
subsystem ensures secondary indexes (such as JavaScript, Mango, and
text search) are kept up to date, without requiring an external query
to trigger building them. Many configuration parameters are avail-
able.

• #1904: Completely rewritten automatic compaction daemon, internally
known as smoosh. This subsystem automatically triggers background
compaction jobs for both databases and views, based on configurable
thresholds.

• #1889, #2408: New IO Queue subsystem implementation. This is highly
configurable and well-documented.

• #2436, #2455: CouchDB now regression tests against, and officially
supports, running on the arm64v8 (aarch64) and ppc64le (ppc64el) ma-
chine architectures. Convenience binaries are generated on these ar-
chitectures for Debian 10.x (buster) packages, and for the Docker
containers.

• #1875, #2437, #2423: CouchDB now supports linking against SpiderMon-
key 60 or SpiderMonkey 1.8.5. SpiderMonkey 60 provides enhanced sup-
port for ES5, ES6, and ES2016+. Full compatibility information is
available at the ECMAScript compatibility table. Click on Show obso-
lete platforms, then look for FF 60 ESR in the list of engine types.

However, it was discovered that on some ARM 64-bit distributions, SM
60 segfaults frequently, including the SM 60 packages on CentOS 8 and
Debian 10.

As a result, CouchDBs convenience binaries only link against SM 60 on
the ``x86_64`` and ``ppc64le`` architectures. This includes the
Docker image for these architectures.

At present, CouchDB ships with SM 60 linked in on the following bi-
nary distributions:

• Debian buster (10.x)

• CentOS / RedHat 8.x

• macOS (10.10+)

• Windows (7+)

• Docker (3.0.0)

• FreeBSD (CURRENT)

We expect to add SM 60 support to Ubuntu with Focal Fossa (20.04 LTS)
when it ships in April 2020.

It is unlikely we will backport SM 60 packages to older versions of
Debian, CentOS, RedHat, or Ubuntu.

• The Windows installer has many improvements, including:

• Prompts for an admin user/password as CouchDB 3.0 requires * Will
not overwrite existing credentials if in place

• No longer remove user-modified config files, closing #1989 * Also
will not overwrite them on install.

• Checkbox to disable installation of the Windows service

• Silent install support.

• Friendly link to these online release notes in the exit dialog

• Higher resolution icon for HiDPI (500x500)

WARNING:
Windows 8, 8.1, and 10 require the .NET Framework v3.5 to be in-
stalled.

• #2037: Dreyfus, the CouchDB side of the Lucene-powered search solu-
tion, is now shipped with CouchDB. When one or more Clouseau Java
nodes are joined to the cluster, text-based indexes can be enabled in
CouchDB. It is recommended to have as many Clouseau nodes as you have
CouchDB nodes. Search is advertised in the feature list present at
GET / if configured correctly (#2206). Configuration and
installation documentation is available.

• #2411: The /_up endpoint no longer requires authentication, even when
require_valid_user is true.

• #2392: A new _metrics role can be given to a user. This allows that
user access only to the /_node/{node}/_stats and /_node/{node}/_sys-
tem endpoints.

• #1912: A new alternative systemd-journald logging backend has been
added, and can be enabled through the ini file. The new backend does
not include CouchDBs microsecond-accurate timestamps, and uses the
sd-daemon(3) logging levels.

• #2296, #1977: If the configuration file setting [couchdb] single_node
is set to true, CouchDB will automatically create the system data-
bases on startup if they are not present.

• #2338, #2343: POST request to CouchDB views and the /{db}/_all_docs,
/{db}/_local_docs and /{db}/_design_docs endpoints now support the
same functionality as GET. Parameters are passed in the body as a
JSON object, rather than in the URL when using POST.

• #2292: The _scheduler/docs and _scheduler/info endpoints now return
detailed replication stats for running and pending jobs.

• #2282, #2272, #2290: CouchDB now supports specifying separate proxies
for both the source and target in a replication via source_proxy and
target_proxy keys. The API documentation has been updated.

• #2240: Headers are now returned from the /{db}/_changes feed immedi-
ately, even when there are no changes available. This avoids client
blocking.

• #2005, #2006: The name of any node can now be retrieved through the
new API endpoint GET /_node/{node-name}.

• #1766: Timeouts for requests, all_docs, attachments, views, and par-
titioned view requests can all be specified separately in the ini
file under the [fabric] section. See default.ini for more detail.

• #1963: Metrics are now kept on the number of partition and global
view queries, along with the number of timeouts that occur.

• #2452, #2221: A new configuration field [couch_httpd_auth] same_site
has been added to set the value of the CouchDB auth cookies SameSite
attribute. It may be necessary to set this to strict for compatibil-
ity with future versions of Google Chrome. If CouchDB CORS support is
enabled, set this to None.

Performance
• #2277: The couch_server process has been highly optimized, supporting
significantly more load than before.

• #2360: It is now possible to make the rexi interfaces unacked message
limit configurable. A new, more optimized default (5, lowered from
10) has been set. This results in a ~50% improvement on view queries
on large clusters with q 8.

• #2280: Connection sharing for replication now functions correctly
when replicating through a forward proxy. Closes #2271.

• #2195, #2207: Metrics aggregation now supports CouchDB systems that
sleep or hibernate, ensuring that on wakeup does not trigger thou-
sands of unnecessary function calls.

• #1795: Avoid calling fabric:update_docs with empty doc lists.

• #2497: The setup wizard no longer automatically creates the
_global_changes database, as the majority of users do not need this
functionality. This reduces overall CouchDB load.

Bugfixes
• #1752, #2398, #1803: The cluster setup wizard now ensures a consis-
tent UUID and http secret across all nodes in a cluster. CouchDB ad-
min passwords are also synced when the cluster setup wizard is used.
This prevents being logged out when using Fauxton as a server admin
user through a load balancer.

• #2388: A compatibility change has been made to support replication
with future databases containing per-document access control fields.

• #2379: Any replicator error messages will provide an object in the
response, or null, but never a string.

• #2244, #2310: CouchDB will no longer send more data than is requested
when retrieving partial attachment data blocks.

• #2138: Manual operator updates to a databases shard map will not cor-
rupt additional database properties, such as partitioning values.

• #1877: The _purge and _purged_infos_limit endpoints are now correctly
restricted to server admin only.

• #1794: The minimum purge sequence value for a database is now gath-
ered without a clustered _all_docs lookup.

• #2351: A timeout case clause in fabric_db_info has been normalised to
match other case clauses.

• #1897: The /{db}/_bulk_docs endpoint now correctly catches invalid
(i.e., non-hexadecimal) _rev_ values and responds with a 400 Bad Re-
quest error.

• #2321: CouchDB no longer requires Basic auth credentials to reach the
/_session endpoint for login, even when require_valid_user is en-
abled.

• #2295: CouchDB no longer marks a job as failed permanently if the in-
ternal doc processor crashes.

• #2178: View compaction files are now removed on view cleanup.

• #2179: The error message logged when CouchDB does not have a _users
database is now less scary.

• #2153: CouchDB no longer may return a badmatch error when querying
all_docs with a passed keys array.

• #2137: If search is not available, return a 400 Bad Request instead
of a 500 Internal Server Error status code.

• #2077: Any failed fsync(2) calls are now correctly raised to avoid
data corruption arising from retry attempts.

• #2027: Handle epoch mismatch when duplicate UUIDs are created through
invalid operator intervention.

• #2019: If a database is deleted and re-created while internal cluster
replication is still active, CouchDB will no longer retry to delete
it continuously.

• #2003, #2438: CouchDB will no longer automatically reset an index
file if any attempt to read its header fails (such as when the
couch_file process terminates unexpectedly). CouchDB now also han-
dles the case when a view file lacks a proper header.

• #1983: Improve database external size calcuation to be more precise.

• #1971: Correctly compare ETags using weak comparison methods to sup-
port W/ prefix added by some load balancer configurations.

• #1901: Invalid revision specified for a document update will no
longer result in a badarg crash.

• #1845: The end_time field in /_replicate now correctly converts time
to UTC.

• #1824: rexi stream workers are now cleaned up when the coordinator
process is killed, such as when the ddoc cache is refreshed.

• #1770: Invalid database _security objects no longer return a func-
tion_clause error and stack trace.

• #2412: Mango execution stats now correctly count documents read which
werent followed by a match within a given shard.

• #2393, #2143: It is now possible to override the query server envi-
ronment variables COUCHDB_QUERY_SERVER_JAVASCRIPT and
COUCHDB_QUERY_SERVER_COFFEESCRIPT without overwriting the
couchdb/couchdb.cmd startup scripts.

• #2426, #2415: The replicator now better handles the situation where
design document writes to the target fail when replicating with
non-admin credentials.

• #2444, #2413: Replicator error messages are now significantly im-
proved, reducing function_clause responses.

• #2454: The replication auth session plugin now ignores other cookies
it may receive without logging an error.

• #2458: Partitioned queries and dreyfus search functions no longer
fail if there is a single failed node or rexi worker error.

• #1783: Mango text indexes no longer error when given an empty selec-
tor or operators with empty arrays.

• #2466: Mango text indexes no longer error if the indexed document re-
vision no longer exists in the primary index.

• #2486: The $lt, $lte, $gt, and $gte Mango operators are correctly
quoted internally when used in conjunction with a text index search.

• #2493: The couch_auth_cache no longer has a runaway condition in
which it creates millions of monitors on the _users database.

Other
The 3.0.0 release also includes the following minor improvements:

• #2472: CouchDB now logs the correct, clustered URI at startup (by de-
fault: port 5984.)

• #2034, #2416: The path to the Fauxton installation can now be speci-
fied via the COUCHDB_FAUXTON_DOCROOT environment variable.

• #2447: Replication stats are both persisted when jobs are re-created,
as well as properly handled when bulk document batches are split.

• #2410, #2390, #1913: Many metrics were added for Mango use, including
counts of unindexed queries, invalid index queries, docs examined
that do and dont meet cluster quorum, query time, etc.

• #2152, #2504: CouchDB can now be started via a symlink to the binary
on UNIX-based platforms.

• #1844: A new internal API has been added to write custom Erlang re-
quest-level metrics reporting plugins.

• #2293, #1095: The -args_file, -config and -couch_ini parameters may
now be overridden via the COUCHDB_INI_FILES environment variable on
UNIX-based systems.

• #2352: The remsh utility now searches for the Erlang cookie in
ERL_FLAGS as well as vm.args.

• #2324: All traces of the (never fully functional) view-based _changes
feed have been expunged from the code base.

• #2337: The md5 shim (introduced to support FIPS-compliance) is now
used consistently throughout the code base.

• #2270: Negative and non-integer heartbeat values now return 400 Bad
Request.

• #2268: When rescheduling jobs, CouchDB now stops sufficient running
jobs to make room for the pending jobs.

• #2186: CouchDB plugin writers have a new field in which endpoint cre-
dentials may be stashed for later use.

• #2183: dev/run now supports an --extra-args flag to modify the Erlang
runtime environment during development.

• #2105: dev/run no longer fails on unexpected remote end connection
close during cluster setup.

• #2118: Improve couch_epi process replacement mechanism using map
childspecs functionality in modern Erlang.

• #2111: When more than MaxJobs replication jobs are defined, CouchDB
now correctly handles job rotation when some jobs crash.

• #2020: Fix full ring assertion in fabric stream shard replacements

• #1925: Support list for docid when using couch_db:purge_docs/3.

• #1642: io_priority is now set properly on view update and compaction
processes.

• #1865: Purge now supports >100 document IDs in a single request.

• #1861: The vm.args file has improved commentary.

• #1808: Pass document update type for additional checks in be-
fore_doc_update.

• #1835: Module lists are no longer hardcoded in .app files.

• #1798, #1933: Multiple compilation warnings were eliminated.

• #1826: The couch_replicator_manager shim has been fully removed.

• #1820: After restarting CouchDB, JS and Elixir tests now wait up to
30s for it to be ready before timing out.

• #1800: make elixir supports specifying individual tests to run with
tests=.

• #1805: dev/run supports --with-haproxy again.

• #1774: dev/run now supports more than 3 nodes.

• #1779: Refactor Elixir test suite initialization.

• #1769: The Elixir test suite uses Credo for static analysis.

• #1776: All Python code is now formatted using Python black.

• #1786: dev/run: do not create needless dev/data/ directory.

• #2482: A redundant get_ring_opts call has been removed from drey-
fus_fabric_search.

• #2506: CouchDBs release candidates no longer propagate the RC tags
into each Erlang applications version string.

• #2511: recon, the Erlang diagnostic toolkit, has been added to
CouchDBs build process and ships in the release + convenience bina-
ries.

• Fauxton updated to v1.2.3, which includes:

• Support multiple server-generated warnings when running queries

• Partitioned database support

• Search index support

• Remove references to deprecated dbinfo fields

• Improve accessibility for screen readers

• Numerous CSS fixes

• Improved test cases:

• Many, many test race conditions and bugs have been removed (PR list
too long to include here!)

• More test cases were ported to Elixir, including:

• Cluster with and without quorum tests (#1812)

• delayed_commits (#1796)

• multiple_rows (#1958)

• invalid_docids (#1968)

• replication (#2090)

• All attachment_* tests (#1999)

• copy_doc (#2000)

• attachments (#1953)

• erlang_views (#2237)

• auth_cache, cookie_auth, lorem*, multiple_rows, users_db, utf8 (-
#2394)

• etags_head (#2464, #2469)

• #2431: chttpd_purge_tests have been improved in light of CI fail-
ures.

• #2432: Address flaky test failure on t_invalid_view/1.

• #2363: Elixir tests now run against a single node cluster, in line
with the original design of the JavaScript test suite. This is a
permanent change.

• #1893: Add w:3 for lots of doc tests.

• #1939, #1931: Multiple fixes to improve support in constrained CI
environments.

• #2346: Big-endian support for the couch_compress tests.

• #2314: Do not auto-index when testing update=false in Mango.

• #2141: Fix couch_views encoding test.

• #2123: Timeout added for fold_docs-with_different_keys test.

• #2114: EUnit tests now correctly inherit necessary environment
variables.

• #2122: :meck.unload() is now called automatically after every test.

• #2098: Fix cpse_test_purge_replication eunit test.

• #2085, #2086: Fix a flaky mem3_sync_event_listener test.

• #2084: Increase timeouts on two slow btree tests.

• #1960, #1961: Fix for chttpd_socket_buffer_size_test.

• #1922: Tests added for shard splitting functionality.

• #1869: New test added for doc reads with etag If-None-Match header.

• #1831: Re-introduced cpse_test_purge_seqs test.

• #1790: Reorganise couch_flag_config_tests into a proper suite.

• #1785: Use devclean on elixir target for consistency of Makefile.

• #2476: For testing, Triq has been replaced with PropEr as an op-
tional dependency.

• External dependency updates:

• #1870: Mochiweb has been updated to 2.19.0.

• #1938: Folsom has been updated to 0.8.3.

• #2001: ibrowse has been updated to 4.0.1-1.

• #2400: jiffy has been updated to 1.0.1.

• A llama! OK, no, not really. If you got this farthank you for read-
ing.

2.3.x Branch
• Upgrade Notes

• Version 2.3.1

• Version 2.3.0

Upgrade Notes
• #1602: To improve security, there have been major changes in the con-
figuration of query servers, SSL support, and HTTP global handlers:

1. Query servers

Query servers are NO LONGER DEFINED in the .ini files, and can no
longer be altered at run-time.

The JavaScript and CoffeeScript query servers continue to be en-
abled by default. Setup differences have been moved from de-
fault.ini to the couchdb and couchdb.cmd start scripts respec-
tively.

Additional query servers can now be configured using environment
variables:

export COUCHDB_QUERY_SERVER_PYTHON="/path/to/python/query/server.py with args"
couchdb

where the last segment in the environment variable (_PYTHON)
matches the usual lowercase(!) query language in the design doc
language field (here, python.)

Multiple query servers can be configured by using more environment
variables.

You can also override the default servers if you need to set com-
mand- line options (such as couchjs stack size):

export COUCHDB_QUERY_SERVER_JAVASCRIPT="/path/to/couchjs /path/to/main.js -S <STACKSIZE>"
couchdb

2. Native Query Servers

The mango query server continues to be enabled by default. The Er-
lang query server continues to be disabled by default. This change
adds a [native_query_servers] enable_erlang_query_server = BOOL
setting (defaults to false) to enable the Erlang query server.

If the legacy configuration for enabling the query server is de-
tected, that is counted as a true setting as well, so existing
configurations continue to work just fine.

3. SSL Support

Enabling SSL support in the ini file is now easier:

[ssl]
enable = true

If the legacy httpsd configuration is found in your ini file, this
will still enable SSL support, so existing configurations do not
need to be changed.

4. HTTP global handlers

These are no longer defined in the default.ini file, but have been
moved to the couch.app context. If you need to customize your han-
dlers, you can modify the app context using a couchdb.config file
as usual.

• #1602: Also to improve security, the deprecated os_daemons and
couch_httpd_proxy functionality has been completely removed ahead of
the planned CouchDB 3.0 release. We recommend the use of OS-level
daemons such as runit, sysvinit, systemd, upstart, etc. to launch and
maintain OS daemons instead, and the use of a reverse proxy server in
front of CouchDB (such as haproxy) to proxy access to other services
or domains alongside CouchDB.

• #1543: The node-local (default port 5986) /_restart endpoint has been
replaced by the clustered (default port 5984) endpoint
/_node/{node-name}/_restart and /_node/_local/_restart endpoints. The
node-local endpoint has been removed.

• #1764: All python scripts shipped with CouchDB, including couchup and
the dev/run development cluster script, now specify and require
Python 3.x.

• #1396: CouchDB is now compatible with Erlang 21.x.

• #1680: The embedded version of rebar used to build CouchDB has been
updated to the last version of rebar2 available. This assists in
building on non-x86 platforms.

• #1857: Refuse building with known bad versions of Erlang.

Version 2.3.1
Features
• #1811: Add new /{db}/_sync_shards endpoint (admin-only).

• #1870: Update to mochiweb 2.19.0. See also #1875.

• #1857: Refuse building with known bad versions of Erlang.

• #1880: Compaction: Add snooze_period_ms for finer tuning.

Bugfixes
• #1795: Filter out empty missing_revs results in mem3_rep.

• #1384: Fix function_clause error on invalid DB _security objects.

• #1841: Fix end_time field in /_replicate response.

• #1860: Fix read repair in a mixed cluster environment.

• #1862: Fix fabric_open_doc_revs.

• #1865: Support purge requests with more than 100 doc ids.

• #1867: Fix timeout in chttpd_purge_tests.

• #1766: Add default fabric request timeouts.

• #1810: Requests return 400 Bad Request when URL length exceeds 1460
characters. See #1870 for details.

• #1799: Restrict _purge to server admin.

• #1874: This fixes inability to set keys with regex symbols in them.

• #1901: Fix badarg crash on invalid rev for individual doc update.

• #1897: Fix from_json_obj_validate crash when provided rev isnt a
valid hex.

• #1803: Use the same salt for admin passwords on cluster setup.

• #1053: Fix python2 compatibility for couchup.

• #1905: Fix python3 compatibility for couchup.

Version 2.3.0
Features
• (Multiple) Clustered purge is now available. This feature restores
the CouchDB 1.x ability to completely remove any record of a document
from a database. Conditions apply; to use the feature safely, and for
full details, read the complete Clustered Purge documentation.

• #1658: A new config setting is available, allowing an administrator
to configure an initial list of nodes that should be contacted when a
node boots up. Nodes in the seedlist that are successfully reached
will be added to that nodes _nodes database automatically, triggering
a distributed Erlang connection and replication of the internal sys-
tem databases to the new node. This can be used instead of manual
config or the cluster setup wizard to bootstrap a cluster. The
progress of the initial seeding of new nodes is exposed at the GET
/_up endpoint.

• Replication supports ipv6-only peers after updating ibrowse depen-
dency.

• #1708: The UUID of the server/cluster is once again exposed in the
GET / response. This was a regression from CouchDB 1.x.

• #1722: Stats counts between job runs of the replicator are no longer
reset on job restart.

• #1195, #1742: CouchDBs _bulk_get implementation now supports the mul-
tipart/mixed and multipart/related content types if requested, ex-
tending compatibility with third-party replication clients.

Performance
• #1409: CouchDB no longer forces the TCP receive buffer to a fixed
size of 256KB, allowing the operating system to dynamically adjust
the buffer size. This can lead to significantly improved network per-
formance when transferring large attachments.

• #1423: Mango selector matching now occurs at the shard level, reduc-
ing the network traffic within a cluster for a mango query.

• #1423: Long running operations at the node level could exceed the in-
ter-node timeout, leading to a fabric timeout error in the logfile
and a cancellation of the task. Nodes can now ping to stop that from
happening.

• #1560: An optimization to how external data sizes of attachments were
recorded was made.

• #1586: When cleaning up outdated secondary index files, the search is
limited to the index directory of a specific database.

• #1593: The couch_server ETS table now has the read_concurrency option
set, improving access to the global list of open database handles.

• #1593: Messages to update the least-recently used (LRU) cache are not
sent when the [couchdb] update_lru_on_read setting is disabled.

• #1625: All nodes in a cluster now run their own rexi server.

Bugfixes
• #1484: _stats now correctly handles the case where a map function
emits an array of integers. This bug was introduced in 2.2.0.

• #1544: Certain list functions could return a render_error error in-
termittently.

• #1550: Replicator _session support was incompatible with CouchDB in-
stallations using the require_valid_user = true setting.

• #1571: Under very heavy load, it was possible that rexi_server could
die in such a way that its never restarted, leaving a cluster without
the ability to issue RPC calls - effectively rendering the cluster
useless.

• #1574: The built-in _sum reduce function has been improved to check
if the objects being summed are not overflowing the view storage.
Previously, there was no protection for _sum-introduced overflows.

• #1582: Database creation parameters now have improved validation,
giving a more readable error on invalid input.

• #1588: A missing security check has been restored for the noop
/db/_ensure_full_commit call to restore database validation checks.

• #1591: CouchDB now creates missing shard files when accessing a data-
base if necessary. This handles the situation when, on database cre-
ation, no nodes were capable of creating any of the shard files re-
quired for that database.

• #1568: CouchDB now logs a warning if a changes feed is rewound to 0.
This can help diagnose problems in busy or malfunctioning clusters.

• #1596: It is no longer possible that a busy couch_server, under a
specific ordering and timing of events, will incorrectly track
open_async messages in its mailbox.

• #1601, #1654: CouchDB now logs better when an error causes it to read
past the EOF of a database shard. The check for whether CouchDB is
trying to read too many bytes has been correctly separated out from
the error indicating it has attempted to read past the EOF.

• #1613: Local nodes are now filtered out during read repair opera-
tions.

• #1636: A memory leak when replicating over HTTPS and a problem occurs
has been squashed.

• #1635: /_replicate jobs are no longer restarted if parameters havent
changed.

• #1612: JavaScript rewrite functions now send the body of the request
to the rewritten endpoint.

• #1631: The replicator no longer crashes if the user has placed an in-
valid VDU function into one of the _replicator databases.

• #1644, #1647: It is no longer possible to create illegally-named
databases within the reserved system space (_ prefix.)

• #1650: _bulk_get is once again operational for system databases such
as _users.

• #1652: Access to /_active_tasks is once again restricted to server
admins only.

• #1662: The couch_log application no longer crashes when new, addi-
tional information is supplied by a crashing application, or when any
of its own children are restarted.

• #1666: Mango could return an error that would crash the
couch_query_servers application. This is no longer the case.

• #1655: Configuration of ets_lru in chttpd now performs proper error
checking of the specified config value.

• #1667: The snappy dependency has been updated to fix a memory alloca-
tion error.

• #1683: Attempting to create a local document with an invalid revision
no longer throws a badarg exception. Also, when setting new_edits to
false and performing a bulk write operation, local documents are no
longer written into the wrong btree. Finally, it is no longer possi-
ble to create a document with an empty ID during a bulk operation
with new_edits set to false.

• #1721: The couchup convenience script for upgrading from CouchDB 1.x
now also copies a databases _security object on migration.

• #1672: When checking the status of a view compaction immediately af-
ter starting it, the total_changes and changes_done fields are now
immediately populated with valid values.

• #1717: If the .ini config file is read only, an attempt to update the
config through the HTTP API will now result in a proper eacces error
response.

• #1603: CouchDB now returns the correct total_rows result when query-
ing /{db}/_design_docs.

• #1629: Internal load validation functions no longer incorrectly hold
open a deleted database or its host process.

• #1746: Server admins defined in the ini file accessing via HTTP API
no longer result in the auth cache logging the access as a miss in
the statistics.

• #1607: The replicator no longer fails to re-authenticate to open a
remote database when its session cookie times out due to a VDU func-
tion forbidding writes or a non-standard cookie expiration duration.

• #1579: The compaction daemon no longer incorrectly only compacts a
single view shard for databases with a q value greater than 1.

• #1737: CouchDB 2.x now performs as well as 1.x when using a _doc_ids
or _design_docs filter on a changes feed.

Mango
Other
The 2.3.0 release also includes the following minor improvements:

• Improved test cases:

• The Elixir test suite has been merged. These test cases are in-
tended to replace the aging, unmaintainable JavaScript test suite,
and help reduce our dependency on Mozilla Spidermonkey 1.8.5. The
test suite does not yet cover all of the tests that the JS test
suite does. Once it achieves full coverage, the JS test suite will
be removed.

• Many racy test cases improved for reliable CI runs.

• The Makefile targets for list-eunit-* now work correctly on macOS.

• #1732, #1733, #1736: All of the test suites run and pass on the
Windows platform once again.

• #1597: Off-heap messages, a new feature in Erlang 19+, can now be
disabled per module if desired.

• #1682: A new [feature_flags] config section exists for the purpose of
enabling or disabling experimental features by CouchDB developers.

• A narwhal! OK, no, not really. If you got this farthank you for read-
ing.

2.2.x Branch
• Upgrade Notes

• Version 2.2.0

Upgrade Notes
• The minimum supported version of Erlang is now 17, not R16B03. Sup-
port for Erlang 21 is still ongoing and will be provided in a future
release.

• The CouchDB replication client can now use the /_session endpoint
when authenticating against remote CouchDB instances, improving per-
formance since re-authorization does not have to be performed with
every request. Because of this performance improvement, it is recom-
mended to increase the PBKDF2 work factor beyond the default 10 to a
modern default such as 10000. This is done via the local ini file
setting [couch_httpd_auth] iterations = 10000.

Do not do this if an older version of CouchDB is replicating TO this
instance or cluster regularly, since CouchDB < 2.2.0 must perform au-
thentication on every request and replication performance will suf-
fer.

A future version will make this increased number of iterations a de-
fault.

• #820, #1032: Multiple queries can now be made at the POST
/{db}/_all_docs/queries, POST /{db}/_design_docs/queries and POST
/{db}/_local_docs/queries endpoints. Also, a new endpoint POST
/{db}/_design/{ddoc}/_view/{view}/queries has been introduced to re-
place the ?queries parameter formerly provided for making multiple
queries to a view. The old ?queries parameter is now deprecated and
will be removed in a future release of CouchDB.

• The maximum http request limit, which had been lowered in 2.1.0, has
been re-raised to a 4GB limit for now. (#1446). Ongoing discussion
about the path forward for future releases is available in #1200 and
#1253.

• #1118: The least recently used (LRU) cache of databases is now only
updated on database write, not read. This has lead to significant
performance enhancements on very busy clusters. To restore the previ-
ous behaviour, your local ini file can contain the block [couchdb]
update_lru_on_read = true.

• #1153: The CouchDB replicator can now make use of the /_session end-
point rather than relying entirely on HTTP basic authentication head-
ers. This can greatly improve replication performance. We encourage
you to upgrade any nodes or clusters that regularly act as replica-
tion clients to use this new feature, which is enabled by default (-
#1462).

• #1283: The [couchdb] enable_database_recovery feature, which only
soft-deletes databases in response to a DELETE /{db} call, is now
documented in default.ini.

• #1330: CouchDB externals and OS daemons are now officially deprecated
and no longer documented. Support for these features will be com-
pletely removed in a future release of CouchDB (probably 3.0.0).

• #1436: CouchDB proxy authentication now uses a proper chttpd_auth
module, simplifying configuration in local ini files. While this is
not a backward- compatible breaking change, it is best to update your
local ini files to reference the new {chttpd_auth, proxy_authentica-
tion_handler} handler rather than the couch_httpd_auth version, as
couch_httpd is in the process of being deprecated completely.

• #1476, #1477: The obsolete update_notification feature, which was re-
placed by /{db}/_changes feeds c. CouchDB 1.2, has been completely
removed. This feature never worked in 2.0 for databases, only for
shards, making it effectively useless.

Version 2.2.0
Features
• Much improved documentation. Highlights include:

• A complete rewrite of the sharding documentation.

• Developer installation notes (INSTALL.*.rst)

• Much of the content of the original CouchDB Wiki has been imported
into the official docs. (The old CouchDB Wiki is in the process of
being deprecated.)

• Much improved Fauxton functionality. Highlights include:

• Search support in the code editor

• Support for relative Fauxton URLs (i.e., not always at /_utils)

• Replication setup enhancements for various authentication mecha-
nisms

• Fixes for IE10, IE11, and Edge (we hope)

• Resolving conflicts of design documents is now allowed

• #496, COUCHDB-3287: New pluggable storage engine framework has landed
in CouchDB. This internal refactor makes it possible for CouchDB to
use different backends for storing the base database file itself. The
refactor included a full migration of the existing legacy storage en-
gine into the new framework.

• #603: When creating a new database on a cluster without quorum,
CouchDB will now return a 202 Accepted code if possible, indicating
that at least one node has written the database record to disk, and
that other nodes will be updated as they return to an online state.
This replaces the former 500 internal error.

• #1136, #1139: When deleting a database in a cluster without quorum,
CouchDB will no longer throw a 500 error status, but a 202 as long as
at least one node records the deletion, or a 200 when all nodes re-
spond. This fix parallels the one made for #603.

• #745: CouchDB no longer fails to complete replicating databases with
large attachments. The fix for this issue included several related
changes:

• The maximum http request limit, which had been lowered in 2.1.0,
has been re-raised to a 4GB limit for now. (#1446). Ongoing discus-
sion about the path forward for future releases is available in -
#1200 and #1253.

• An update to the replicator http client that improves active socket
accounting, without which CouchDB can cease to be responsive over
the main http interface (#1117)

• The replicators http client no longer performs unconditional re-
tries on failure (#1177)

• A path by which CouchDB could lose track of their RPC workers dur-
ing multipart attachment processing was removed. (#1178)

• When CouchDB transmits a 413 Payload Too Large response on attach-
ment upload, it now correctly flushes the receive socket before
closing the connection to avoid a TCP reset, and to give the client
a better chance of parsing the 413 response. In tandem, the repli-
cator http client correctly closes its own socket after processing
any 413 response. (#1234)

• A fabric process to receive unchunked attachments can no longer or-
phan processes that leave unprocessed binaries in memory until all
available memory is exhausted. (#1264).

• When using CouchDBs native SSL responder (port 6984 by default),
sessions are now timed out by default after 300s. This is to work
around RAM explosion in the BEAM VM when using the Erlang-native
SSL libraries. (#1321

• #822: A new end point /_dbs_info has been added to return information
about a list of specified databases. This endpoint can take the place
of multiple queries to /{db}.

• #875, #1030: couch_peruser installations can now specify a default q
value for each peruser-created database that is different from the
clusters q value. Set this in your local ini file, under [couch_pe-
ruser] q.

• #876, #1068: The couch_peruser database prefix is now configurable
through your local ini file, under [couch_peruser] database_prefix.

• #887: Replicator documents can now include parameters for target
database creation, such as "create_target_params": {"q": "1"}. This
can assist in database resharding or placement.

• #977: When using COPY to copy a document, CouchDB no longer fails if
the new ID includes Unicode characters.

• #1095: Recognize the environment variables ARGS_FILE, SYSCONFIG_FILE,
COUCHDB_ARGS_FILE and COUCHDB_SYSCONFIG_FILE to override where
CouchDB looks for the vm.args and sys.config files at startup.

• #1101, #1425: Mango can now be used to find conflicted documents in a
database by adding conflicts: true to a mango selector.

• #1126: When queried back after saving, replication documents no
longer contain sensitive credential information (such as basic au-
thenticataion headers).

• #1203:

• The compaction daemon now has a snooze period, during which it
waits to start the next compaction after finishing the previous
one. This value is useful in setups with many databases (e.g.
with couch_peruser) or many design docs, which can cause a CPU
spike every check_interval seconds. The setting can be adjusted
in your local ini file via [compaction_daemon] snooze_period.
The current default is a 3 second pause.

• The check_interval has been raised from 300 seconds to 3600 sec-
onds.

• A notice-level log about closing view indexes has been demoted
to the debug level. In a sceario with many design docs, this
would createsignficant load on the logging subsystem every [com-
paction_daemon] check_interval for no discernible benefit.

• #1309, #1435: CouchDB now reports the git sha at the time of build in
the top-level GET / version string, in a new git_sha key. This can be
used to help ensure an unmodified version of CouchDB has been built
and is running on any given machine.

• COUCHDB-2971, #1346: CouchDB now includes a new builtin reduce func-
tion _approx_count_distinct, that uses a HyperLogLog algorithm to es-
timate the number of distinct keys in the view index. The precision
is currently fixed to 2^11 observables, and therefore uses approxi-
mately 1.5KB of memory.

• #1377: CouchDB finalization of view reduces now occurs at the coordi-
nator node. This simplified the built-in _stats function.

• #1392: When running CouchDB under Erlang 19.0 or newer, messages can
now be stored off the process heap. This is extremely useful for Er-
lang processes that can have huge number of messages in their mail-
box, and is now enabled for couch_server, couch_log_server,
ddoc_cache, mem3_shards, and rexi_server whenever possible.

• #1424: The CouchDB native SSL/TLS server httpsd now accepts
socket-level configuration options through the [httpsd] server_op-
tions ini file setting.

• #1440: CouchDB can now be configured to prevent non-admins from ac-
cessing the GET /_all_dbs method by specifying [chttpd] ad-
min_only_all_dbs = true in your local ini file(s). The true setting
will become default in future versions.

• #1171, #1445: CouchDB can now be configured to use the internal Er-
lang MD5 hash function when not available in the external environment
(e.g. FIPS enabled CentOS) at compile time with the configure flag
--enable-md5. Because this implementation is slower, it is not recom-
mended in the general case.

Performance
• #958: The revision stemming algorithm was optimized down from O(N^2)
to O(N) via a depth-first search approach, and then further improved
by calling the stemming operation only when necessary. This new algo-
rithm can be disabled by setting the option [couchdb] stem_interac-
tive_updates = false if necessary.

• #1246: CouchDB now checks for request authorization only once per
each database request, improving the performance of any request that
requires authorization.

Bugfixes
• #832, #1064: Tracking of Couch logging stats has been added back into
the per-node /_node/<node-name>/_stats endpoint.

• #953, #973: Return 404 Not Found on GET /_scheduler, not 405 Method
Not Allowed.

• #955: The /{db}/_bulk_docs endpoint now correctly responds with a 400
Bad Request error if the new_edits parameter is not a boolean.

• #969: CouchDB now returns offset and update_seq values when keys are
provided to the GET or POST /{db}/_all_docs?update_seq=true end-
points. This was affecting PouchDB compatibility.

• #984, #1434: CouchDB views now retain their update_seq after com-
paction, preventing potentially expensive client-side view rewinds
after compaction.

• #1012: Address a theoretical race condition the replication scheduler
could encounter when trying to determine if the cluster is stable
enough to resume handling replication-introduced document updates.

• #1051: Return a user-friendly error message when attempting to create
a CouchDB user with an invalid password field (non-string).

• #1059: DB-specific compaction configurations were not working cor-
rectly. The syntax now also supports shard-level custom compaction
configuration if desired (which it probably isnt.)

• #1097: Compaction daemon will not crash out when trying to check spe-
cific file system mounts that are not real file systems (like /run on
Linux).

• #1198: Fauxton is no longer available on the node-local port (5986,
by default). The node-local port is only to be used for specific ad-
ministrative tasks; removing the Fauxton interface prevents mistaking
the node-local port as the correct CouchDB port (5984, by default).

• #1165: validate_doc_update view functions can once again be imple-
mented directly in Erlang (after enabling the optional Erlang view
server).

• #1223: The couch_config application now correctly handles non-persis-
tent integer and boolean-valued configuration changes.

• #1242: couch_os_daemons may now reside in directories with spaces.

• #1258: CouchDB will now successfully login users, even if password
encryption is very slow.

• #1276: The replication scheduler status for a repeatedly erroring job
now correctly reflects the crashing state in more scenarios.

• #1375: If CouchDB fails authorization but passes authentication, it
no longer drops the user_ctx out of the request.

• #1390: The active size of views (as returned in a database info re-
sponse) no longer is incorrectly calculated in such a way that it
could occasionally be larger than the actual on-disk file size.

• #1401: CouchDB Erlang views no longer crash in the couch_native
process with an unexpected function_clause error.

• #1419: When deleting a file, CouchDB now properly ignores the config-
uration flag enable_database_recovery when set when compacting data-
bases, rather than always retaining the old, renamed, uncompacted
database file.

• #1439: The CouchDB setup wizard now correctly validates bind_ad-
dresses. It also no longer logs credentials by moving logging of in-
ternal wizard setup steps to the debug level from the notice level.

Mango
• #816, #962, #1038: If a user specifies a value for use_index that is
not valid for the selector (does not meet coverage requirements or
proper sort fields), attempt to fall back to a valid index or full DB
scan rather than returning a 400. If we fall back, populate a warn-
ing field in the response. Mango also tries to use indexes where $or
may select a field only when certain values are present.

• #849: When {"seq_indexed": true} is specified, a badmatch error was
returned. This is now fixed.

• #927, #1310: Error messages when attempting to sort incorrectly are
now actually useful.

• #951: When using GET /{db}/_index, only use a partial filter selector
for an index if it is set to something other than the default.

• #961: Do not prefix _design/ to a Mango index name whose user-speci-
fied name already starts with _design/.

• #988, #989: When specifying a use_index value with an invalid index,
correctly return a 400 Bad Request showing that the requested index
is invalid for the request specified.

• #998: The fix for CVE 2017-12635 presented a breaking change to Man-
gos /{db}/_find, which would evaluate all instances of all JSON
fields in a selector. Mango is now tested to ensure it only considers
the last instance of a field, silently ignoring those that appear be-
fore it.

• #1014: Correctly deduce list of indexed fields in a selector when
nested $and operators are specified.

• #1023: Fix an unexpected 500 error if startkey and endkey in a Mango
selector were reversed.

• #1067: Prevent an invalid_cast crash when the couch_proc_manager soft
limit for processes is reached and mango idle processes are stopped.

• #1336: The built-in fields _id and rev will always be covered by any
index, and Mango now correctly ignores their presence in any index
that explicitly includes them for selector matching purposes.

• #1376: Mango now appropriately selects some indexes as usable for
queries, even if not all columns for an index are added to the querys
sort field list.

• Multiple fixes related to using Mango as a front-end for full text
indexing (a feature not shipped with couch, but for which support is
in place as a compile-time addon).

Other
The 2.2.0 release also includes the following minor improvements:

• Developers can, at build time, enable curl libraries & disable Faux-
ton and documentation builds by specifying the new --dev option to
the configure script.

• The mochiweb dependency was bumped to version 2.17.0, in part to ad-
dress the difficult #745 issue.

• Improved compatibility with newer versions of Erlang (20.x)

• Improved release process for CouchDB maintainers and PMC members.

• Multiple test suite improvements, focused on increased coverage,
speed, and reliability.

• Improvements to the Travis CI and Jenkins CI setups, focused on im-
proved long-term project maintenance and automatability.

• Related improvements to the CouchDB deb/rpm packaging and Docker
repositories to make deployment even easier.

• #1007: Move etc/default.ini entries back into [replicator] section
(incorrectly moved to [couch_peruser] section)

• #1245: Increased debug-level logging for shard open errors is now
available.

• #1296: CouchDB by default now always invokes the SMP-enabled BEAM VM,
even on single-processor machines. A future release of Erlang will
remove the non-SMP BEAM VM entirely.

• A pony! OK, no, not really. If you got this farthank you for reading.

2.1.x Branch
• Upgrade Notes

• Version 2.1.2

• Version 2.1.1

• Version 2.1.0

• Fixed Issues

Upgrade Notes
• When upgrading from 2.x to 2.1.1, if you have not customized your
node name in vm.args, be sure to retain your original vm.args file.
The default node name has changed from couchdb@localhost to
couchdb@127.0.0.1, which can prevent CouchDB from accessing existing
databases on the system. You may also change the name option back to
the old value by setting -name couchdb@localhost in etc/vm.args by
hand. The default has changed to meet new guidelines and to provide
additional functionality in the future.

If you receive errors in the logfile, such as internal_server_error :
No DB shards could be opened. or in Fauxton, such as This database
failed to load. you need to make this change.

• The deprecated (and broken) OAuth 1.0 implementation has been re-
moved.

• If user code reads or manipulates replicator document states, con-
sider using the [replicator] update_docs = true compatibility parame-
ter. In that case the replicator will continue updating documents
with transient replication states. However, that will incur a perfor-
mance cost. Consider instead using the _scheduler/docs HTTP endpoint.

• The stale parameter for views and _find has been deprecated in favour
of two new parameters: stable and update. The old stale=ok behaviour
is equivalent to stable=true&update=false, and the old stale=up-
date_after behaviour is equivalent to stable=true&update=lazy. The
deprecated stale parameter will be removed in CouchDB 3.0.

• The new :httpd/max_http_request_size configuration parameter was
added. This has the same behavior as the old
couchdb/max_document_size configuration parameter, which had been un-
fortunately misnamed, and has now been updated to behave as the name
would suggest. Both are documented in the shipped default.ini file.

Note that the default for this new parameter is 64MB instead of 4GB.
If you get errors when trying to PUT or POST and see HTTP 413 return
codes in couchdb logs, this could be the culprit. This can affect
couchup in-place upgrades as well.

• #914: Certain critical config sections are blacklisted from being
modified through the HTTP API. These sections can still be modified
through the standard local.ini or local.d/*.ini files.

• #916: couchjs now disables eval() and the Function() constructor by
default. To restore the original behaviour, add the --eval flag to
the definition of the javascript query server in your local.ini file.

Version 2.1.2
Security
• CVE 2018-8007

Version 2.1.1
Security
• CVE 2017-12635

• CVE 2017-12636

General
• #617: CouchDB now supports compilation and running under Erlang/OTP
20.x.

• #756: The couch_peruser functionality is now really fixed. Really.

• #827: The cookie domain for AuthSession cookies, used in a proxy au-
thentication configuration, can now be customized via the ini file.

• #858: It is now possible to modify shard maps for system databases.

• #732: Due to an Erlang bug (ERL-343), invalid paths can be returned
if volumes are mounted containing whitespace in their name. This
problem surfaced primarily on macOS (Time Machine volumes). CouchDB
now works around this bug in unpatched versions of Erlang by skipping
the free space check performed by the compaction daemon. Erlang it-
self will correctly perform free space checks in version 21.0.

• #824: The current nodes local interface can now be accessed at
/_node/_local/{endpoint} as well as at /_node/<nodename>@<host-
name>/{endpoint}.

• The Dockerfile in the source repository has been retired. For a cur-
rent Dockerfile, see the couchdb-docker repository.

• Fauxton now uses a version of React with a BSD license.

Performance
• #835: CouchDB now no longer decompresses documents just to determine
their uncompressed size. In tests, this has lead to improvements be-
tween 10-40% in both CPU and wall-clock time for database compaction.

• The design document cache (ddoc_cache) has been rewritten to improve
performance.

Mango
• #808: Mango now supports partial indexes. Partial indexes allow docu-
ments to be filtered at indexing time, potentially offering signifi-
cant performance improvements for query selectors that dont map
cleanly to a range query on an index.

• #740: Mango queries can now be paginated. Each query response in-
cludes a bookmark. The bookmark can be provided on a subsequent
query to continue from a specific key.

• #768: Mango _find accepts an execution_stats parameter. If present, a
new object is included in the response which contains information
about the query executed. The object contains the count of total keys
examined (0 for json indexes), total documents examined (when in-
clude_docs=true is used), and the total quorum documents examined
(when fabric doc lookups are used).

• #816 and #866: Mango now requires that all of the fields in a candi-
date index must exist in a querys selector. Previously, this check
was incorrect, and indexes that might only contain a subset of valid
documents might be selected by the query planner if no explicit index
was specified at query time. Further, if a sort field is specified at
query time, that field needs to exist (but could be null) in the re-
sults returned.

Other
The 2.1.1 release also includes the following minor improvements:

• #635: Stop couch_index processes on ddoc update

• #721: Save migrated replicator checkpoint documents immediately

• #688: Reuse http-based replication checkpoints when upgrading to
https

• #729: Recommend the use only of -name and not -sname in vm.args
for compatibility.

• #738: Allow replicator application to always update replicator
docs.

• #605: Add Prefer: return=minimal header options from RFC7240 to
reduce the number of headers in the response.

• #744: Allow a 503 response to be returned to clients (with metric
support)

• #746: Log additional information on crashes from rexi

• #752: Allow Mango $in queries without requiring the index to use
an array

• (multiple) Additional debugging utilities have been added.

• (multiple) Hot code upgrades from 2.0 -> 2.1.1 are now possible.

• (multiple) Improvements to the test suite have been made.

• #765: Mango _explain now includes view parameters as requested by
the user.

• #653: _show and _list should now work for admin-only databases
such as _users.

• #807: Mango index selection should occur only once.

• #804: Unhandled Mango errors are now logged.

• #659: Improve accuracy of the max_document_size check.

• #817: Invalid Base64 in inline attachments is now caught.

• #825: Replication IDs no longer need to be URL encoded when using
the _scheduler/jobs/<job_id> endpoint.

• #838: Do not buffer rexi messages to disconnected nodes.

• #830: The stats collection interval is now configurable in an ini
file, not in the application context. The default value is 10, and
the setting is reloaded every 600 seconds.

• #812: The /{db} endpoint now includes a cluster block with the
databases q, n, and default w and r values. This supplements the
existing /{db}/_shards and /{db}/_shards/{id} detailed information
on sharding and quorum.

• #810: The replicator scheduler crashed counter gauge more reliably
detects replication crashes by reducing the default number of re-
tries from 10 to 5 (reducing the duration from 4 mins to 8 secs).

• COUCHDB-3288: Tolerate mixed clusters for the upcoming pluggable
storage engine work.

• #839: Mango python tests now support Python 3 as well as 2.

• #845: A convenience remsh script has been added to support live
debugging of running systems.

• #846: Replicator logging is now less verbose and more informative
when replication terminates unexpectedly.

• #797: Reduce overflow errors are now returned to the client, al-
lowing views with a single bad reduce to build while not exhaust-
ing the servers RAM usage.

• #881: Mango now allows match on documents where the indexed value
is an object if a range query is issued. Previously, query results
might change in the presence of an index, and operators/selectors
which explicitly depend on a full index scan (such as $exists)
would not return a complete result set.

• #883: Erlang time module compatibility has been improved for re-
leases of Erlang newer than 18.0.

• #933: 410 is now returned when attempting to make a temporary view
request.

• #934: The replicator now has a configurable delay before retrying
to retrieve a document after receiving a missing_doc error.

• #936: jiffy now deduplicates JSON keys.

Version 2.1.0
• The Mango _find endpoint supports a new combination operator, $all-
Match, which matches and returns all documents that contain an array
field with all its elements matching all the specified query crite-
ria.

• New scheduling replicator. The core of the new replicator is a sched-
uler which allows running a large number of replication jobs by
switching between them, stopping some and starting others periodi-
cally. Jobs which fail are backed off exponentially. There is also an
improved inspection and querying API: _scheduler/jobs and _sched-
uler/docs:

• _scheduler/jobs : This endpoint shows active replication jobs.
These are jobs managed by the scheduler. Some of them might be run-
ning, some might be waiting to run, or backed off (penalized) be-
cause they crashed too many times. Semantically this is somewhat
equivalent to _active_tasks but focuses only on replications. Jobs
which have completed or which were never created because of mal-
formed replication documents will not be shown here as they are not
managed by the scheduler. _replicate replications, started form
_replicate endpoint not from a document in a _replicator db, will
also show up here.

• _scheduler/docs : This endpoint is an improvement on having to go
back and read replication documents to query their state. It repre-
sents the state of all the replications started from documents in
_replicator db. Unlike _scheduler/jobs it will also show jobs which
have failed or have completed.

By default, scheduling replicator will not update documents with
transient states like triggered or error anymore, instead _sched-
uler/docs API should be used to query replication document states.

Other scheduling replicator improvements
• Network resource usage and performance was improved by implement-
ing a shared connection pool. This should help in cases of a large
number of connections to the same sources or target. Previously
connection pools were shared only within a single replication job.

• Improved request rate limit handling. Replicator requests will
auto-discover rate limit capacity on targets and sources based on
a proven Additive Increase / Multiplicative Decrease feedback con-
trol algorithm.

• Improved performance by having exponential backoff for all repli-
cation jobs failures. Previously there were some scenarios were
failure led to continuous repeated retries, consuming CPU and disk
resources in the process.

• Improved recovery from long but temporary network failure. Cur-
rently if replications jobs fail to start 10 times in a row, they
will not be retried anymore. This is sometimes desirable, but in
some cases, for example, after a sustained DNS failure which even-
tually recovers, replications reach their retry limit, stop retry-
ing and never recover. Previously it required user intervention to
continue. Scheduling replicator will never give up retrying a
valid scheduled replication job and so it should recover automati-
cally.

• Better handling of filtered replications. Failing user filter code
fetches from the source will not block replicator manager and
stall other replications. Failing filter fetches will also be
backed off exponentially. Another improvement is when filter code
changes on the source, a running replication will detect that and
restart itself with a new replication ID automatically.

The 2.1.0 release also includes the following minor improvements:

• COUCHDB-1946: Hibernate couch_stream after each write (up to 70%
reduction in memory usage during replication of DBs with large at-
tachments)

• COUCHDB-2964: Investigate switching replicator manager change
feeds to using normal instead of longpoll

• COUCHDB-2988: (mango) Allow query selector as changes and replica-
tion filter

• COUCHDB-2992: Add additional support for document size

• COUCHDB-3046: Improve reduce function overflow protection

• COUCHDB-3061: Use vectored reads to search for buried headers in
.couch files. On a modern linux system with SSD, we see improve-
ments up to 15x.

• COUCHDB-3063: stale=ok option replaced with new stable and update
options.

• COUCHDB-3180: Add features list in the welcome message

• COUCHDB-3203: Make auth handlers configurable (in ini files)

• COUCHDB-3234: Track open shard timeouts with a counter instead of
logging

• COUCHDB-3242: Make get view group info timeout in couch_indexer
configurable

• COUCHDB-3249: Add config to disable index all fields (text in-
dexes)

• COUCHDB-3251: Remove hot loop usage of filename:rootname/1

• COUCHDB-3284: 8Kb read-ahead in couch_file causes extra IO and bi-
nary memory usage

• COUCHDB-3298: Optimize writing btree nodes

• COUCHDB-3302: (Improve) Attachment replication over low bandwidth
network connections

• COUCHDB-3307: Limit calls to maybe_add_sys_db_callbacks to once
per db open

• COUCHDB-3318: bypass couch_httpd_vhost if there are none

• COUCHDB-3323: Idle dbs cause excessive overhead

• COUCHDB-3324: Introduce couch_replicator_scheduler

• COUCHDB-3337: End-point _local_docs doesnt conform to query params
of _all_docs

• COUCHDB-3358: (mango) Use efficient set storage for field names

• COUCHDB-3425: Make _doc_ids _changes filter fast-path limit con-
figurable

• #457: TeX/LaTeX/texinfo removed from default docs build chain

• #469: (mango) Choose index based on fields match

• #483: couchup database migration tool

• #582: Add X-Frame-Options support to help protect against click-
jacking

• #593: Allow bind address of 127.0.0.1 in _cluster_setup for single
nodes

• #624: Enable compaction daemon by default

• #626: Allow enable node decom using string true

• (mango) Configurable default limit, defaults to 25.

• (mango) _design documents ignored when querying _all_docs

• (mango) add $allMatch selector

• Add local.d/default.d directories by default and document

• Improved INSTALL.* text files

Fixed Issues
The 2.1.0 release includes fixes for the following issues:

• COUCHDB-1447: X-Couch-Update-NewRev header is missed if custom head-
ers are specified in response of _update handler (missed in 2.0
merge)

• COUCHDB-2731: Authentication DB was not considered a system DB

• COUCHDB-3010: (Superseded fix for replication exponential backoff)

• COUCHDB-3090: Error when handling empty Access-Control-Request-Head-
ers header

• COUCHDB-3100: Fix documentation on require_valid_user

• COUCHDB-3109: 500 when include_docs=true for linked documents

• COUCHDB-3113: fabric:open_revs can return {ok, []}

• COUCHDB-3149: Exception written to the log if db deleted while there
is a change feed running

• COUCHDB-3150: Update all shards with stale=update_after

• COUCHDB-3158: Fix a crash when connection closes for _update

• COUCHDB-3162: Default ssl settings cause a crash

• COUCHDB-3164: Request fails when using
_changes?feed=eventsource&heartbeat=30000

• COUCHDB-3168: Replicator doesnt handle well writing documents to a
target db which has a small max_document_size

• COUCHDB-3173: Views return corrupt data for text fields containing
non-BMP characters

• COUCHDB-3174: max_document_size setting can by bypassed by issuing
multipart/related requests

• COUCHDB-3178: Fabric does not send message when filtering lots of
documents

• COUCHDB-3181: function_clause error when adding attachment to doc in
_users db

• COUCHDB-3184: couch_mrview_compactor:recompact/1 does not handle er-
rors in spawned process

• COUCHDB-3193: fabric:open_revs returns multiple results when one of
the shards has stem_interactive_updates=false

• COUCHDB-3199: Replicator VDU function doesnt account for an already
malformed document in replicator db

• COUCHDB-3202: (mango) do not allow empty field names

• COUCHDB-3220: Handle timeout in _revs_diff

• COUCHDB-3222: (Fix) HTTP code 500 instead of 400 for invalid key dur-
ing document creation

• COUCHDB-3231: Allow fixing users documents (type and roles)

• COUCHDB-3232: user context not passed down in fabric_view_all_docs

• COUCHDB-3238: os_process_limit documentation wrong

• COUCHDB-3241: race condition in couch_server if delete msg for a db
is received before open_result msg

• COUCHDB-3245: Make couchjs -S option take effect again

• COUCHDB-3252: Include main-coffee.js in release artifact (broken Cof-
feeScript view server)

• COUCHDB-3255: Conflicts introduced by recreating docs with attach-
ments

• COUCHDB-3259: Dont trap exits in couch_file

• COUCHDB-3264: POST to _all_docs does not respect conflicts=true

• COUCHDB-3269: view response can hang with filter and limit specified

• COUCHDB-3271: Replications crash with kaboom exit

• COUCHDB-3274: eof in couch_file can be incorrect after error

• COUCHDB-3277: Replication manager crashes when it finds _replicator
db shards which are not part of a mem3 db

• COUCHDB-3286: Validation function throwing unexpected json crashes
with function_clause

• COUCHDB-3289: handle error clause when calling fabric:open_revs

• COUCHDB-3291: Excessively long document IDs prevent replicator from
making progress

• COUCHDB-3293: Allow limiting length of document ID (for CouchDB
proper)

• COUCHDB-3305: (mango) dont crash with invalid input to built in re-
ducer function

• COUCHDB-3362: DELETE attachment on non-existing document creates the
document, rather than returning 404

• COUCHDB-3364: Dont crash compactor when compacting process fails.

• COUCHDB-3367: Require server admin user for db/_compact and
db_view_cleanup endpoints

• COUCHDB-3376: Fix mem3_shards under load

• COUCHDB-3378: Fix mango full text detection

• COUCHDB-3379: Fix couch_auth_cache reinitialization logic

• COUCHDB-3400: Notify couch_index_processes on all shards when ddoc
updated

• COUCHDB-3402: race condition in mem3 startup

• #511: (mango) Return false for empty list

• #595: Return 409 to PUT attachment with non-existent rev

• #623: Ensure replicator _active_tasks entry reports recent pending
changes value

• #627: Pass UserCtx to fabrics all_docs from mango query

• #631: fix couchdb_os_proc_pool eunit timeouts

• #644: Make couch_event_sup:stop/1 synchronous

• #645: Pass db open options to fabric_view_map for _view and _list
queries on _users DB

• #648: Fix couch_replicator_changes_reader:process_change

• #649: Avoid a race when restarting an index updater

• #667: Prevent a terrible race condition

• #677: Make replication filter fetch error for _replicate return a 404

• Fix CORS max_age configuration parameter via Access-Control-Max-Age

• Chunk missing revisions before attempting to save on target (improves
replication for very conflicted, very deep revision tree documents)

• Allow w parameter for attachments

• Return Bad Request when count in /_uuids exceeds max

• Fix crashes when replicator db is deleted

• Skip internal replication if changes already replicated

• Fix encoding issues on _update/../doc_id and PUT attachments

2.0.x Branch
• Version 2.0.0

• Upgrade Notes

• Known Issues

• Breaking Changes

Version 2.0.0
• Native clustering is now supported. Rather than use CouchDB replica-
tion between multiple, distinct CouchDB servers, configure a cluster
of CouchDB nodes. These nodes will use an optimized Erlang-driven in-
ternal replication to ensure data durability and accessibility. Com-
bine a clustered CouchDB with a load balancer (such as haproxy) to
scale CouchDB out horizontally. More details of the clustering fea-
ture are available in the Cluster Management.

• Futon replaced by brand-new, completely re-engineered Fauxton inter-
face. URL remains the same.

• The new Mango Query Server provides a simple JSON-based way to per-
form CouchDB queries without JavaScript or MapReduce. Mango Queries
have a similar indexing speed advantage over JavaScript Queries than
the Erlang Queries have (2x-10x faster indexing depending on doc size
and system configuration). We recommend all new apps start using
Mango as a default. Further details are available in the _find, _in-
dex and _explain API.

• Mango selectors can be used in _changes feeds instead of JavaScript
MapReduce filters. Mango has been tested to be up to an order of mag-
nitude (10x) faster than JavaScript in this application.

• Rewrite rules for URLs can be performed using JavaScript functions.

• Multiple queries can be made of a view with a single HTTP request.

• Views can be queried with sorting turned off ( sorted=false) for a
performance boost.

• The global changes feed has been enhanced. It is now resumable and
persistent.

• New endpoints added (documentation forthcoming):

• /_membership shows all nodes in a cluster

• /_bulk_get speeds up the replication protocol over low-latency con-
nections

• /_node/ api to access individual nodes configuration and compaction
features

• /_cluster_setup api to set up a cluster from scratch.

• /_up api to signal health of a node to a load-balancer

• /db/_local_docs and /db/_design_docs (similar to /db/_all_docs)

• The /_log endpoint was removed.

• Backend interface on port 5986 used for specific cluster admin tasks.
Of interest are the _nodes and _dbs databases visible only through
this interface.

• Support added for Erlang/OTP 17.x, 18.x and 19

• New streamlined build system written for Unix-like systems and Mi-
crosoft Windows

• Configuration has moved from /_config to /_node/{node-name}/_config

• instance_start_time now always reports "0".

Upgrade Notes
• The update sequences returned by the /{db}/_changes feed are no
longer integers. They can be any JSON value. Applications should
treat them as opaque values and return them to CouchDB as-is.

• Temporary views are no longer supported.

• It is possible to have multiple replicator databases. replicator/db
config option has been removed. Instead _replicator and any database
names ending with the /_replicator suffix will be recognized as
replicator databases by the system.

• Note that the semantics of some API calls have changed due to the in-
troduction of the clustering feature. Specifically, make note of the
difference between receiving a 201 and a 202 when storing a document.

• all_or_nothing is no longer supported by the bulk_docs API

• After updating a design document containing a show, an immediate GET
to that same show function may still return results from the previous
definition. This is due to design document caching, which may take a
few seconds to fully evict, or longer (up to ~30s) for a clustered
installation.

Known Issues
All known issues filed against the 2.0 release are contained within the
official CouchDB JIRA instance or CouchDB GitHub Issues.

The following are some highlights of known issues for which fixes did
not land in time for the 2.0.0 release:

• COUCHDB-2980: The replicator (whether invoked via _replicate or a
document stored in the _replicator database) understands two kinds of
source and target:

1. A URL (e.g., https://foo:bar@foo.com/db1), called a remote source
or target

2. A database name (e.g., db1), called a local source or target.

Whenever the latter type is used, this refers to a local unclustered
database, not a clustered one.

In a future release we hope to support local source or target specs
to clustered databases. For now, we recommend always using the URL
format for both source and target specifications.

• COUCHDB-3034: CouchDB will occasionally return 500 errors when multi-
ple clients attempt to PUT or DELETE the same database concurrently.

• COUCHDB-3119: Adding nodes to a cluster fails if the Erlang node name
is not couchdb (of the form couchdb@hostname.)

• COUCHDB-3050: Occasionally the dev/run script used for development
purposes to start a local 3-node cluster will fail to start one or
more nodes.

• COUCHDB-2817: The compaction daemon will only compact views for
shards that contain the design document.

• COUCHDB-2804: The fast_view optimization is not enabled on the clus-
tered interface.

• #656: The OAuth 1.0 support is broken and deprecated. It will be re-
moved in a future version of CouchDB.

Breaking Changes
The following changes in 2.0 represent a significant deviation from
CouchDB 1.x and may alter behaviour of systems designed to work with
older versions of CouchDB:

• #620: POST /dbname no longer returns an ETag response header, in com-
pliance with RFC 7231, Section 7.2.

1.7.x Branch
• Version 1.7.2

• Version 1.7.1

• Version 1.7.0

Version 1.7.2
Security
• CVE 2018-8007

Version 1.7.1
Bug Fix
• #974: Fix access to /db/_all_docs for database members.

Version 1.7.0
Security
• CVE 2017-12635

• CVE 2017-12636

API Changes
• COUCHDB-1356: Return username on POST /_session.

• COUCHDB-1876: Fix duplicated Content-Type for show/update functions.

• COUCHDB-2310: Implement POST /{db}/_bulk_get.

• COUCHDB-2375: 400 Bad Request returned when invalid revision speci-
fied.

• COUCHDB-2845: 400 Bad Request returned when revs is not a list.

Build
• COUCHDB-1964: Replace etap test suite with EUnit.

• COUCHDB-2225: Enforce that shared libraries can be built by the sys-
tem.

• COUCHDB-2761: Support glibc >= 2.20.

• COUCHDB-2747: Support Erlang 18.

• #5b9742c: Support Erlang 19.

• #1545bf4: Remove broken benchmarks.

Database Core
• COUCHDB-2534: Improve checks for db admin/member.

• COUCHDB-2735: Duplicate document _ids created under high edit load.

Documentation
• #c3c9588: Improve documentation of cacert_file ssl option.

• #3266f23: Clarify the purpose of tombstones.

• #75887d9: Improve CouchDB Replication Protocol definition.

• #3b1dc0f: Remove mention of group_level=exact.

• #2a11daa: Remove mention of Test Suite in Futon.

• #01c60f1: Clarify type of key, startkey and endkey params.

Futon
• COUCHDB-241: Support document copying.

• COUCHDB-1011: Run replication filtered by document ids from Futon.

• COUCHDB-1275: Unescape database names in Futon recently used list.

• #f18f82a: Update jquery.ui to 1.10.4 with fixes of potential XSS is-
sues.

HTTP Server
• COUCHDB-2430: Disable Nagles algorithm by default.

• COUCHDB-2583: Dont drop connection by the endpoints which doesnt re-
quire any payload.

• COUCHDB-2673: Properly escape Location: HTTP header.

• COUCHDB-2677: Wrong Expires header weekday.

• COUCHDB-2783: Bind both to IPv4 and IPv6.

• #f30f3dd: Support for user configurable SSL ciphers.

Query Server
• COUCHDB-1447: Custom response headers from design functions get
merged with default ones.

• #7779c11: Upgrade Coffeescript to version 1.10.

jquery.couch.js
• #f9095e7: Fix document copying.

1.6.x Branch
• Upgrade Notes

• Version 1.6.0

Upgrade Notes
The Proxy Authentication handler was renamed to proxy_authentica-
tion_handler to follow the *_authentication_handler form of all other
handlers. The old proxy_authentification_handler name is marked as dep-
recated and will be removed in future releases. Its strongly recom-
mended to update httpd/authentication_handlers option with new value in
case if you had used such handler.

Version 1.6.0
• COUCHDB-2200: support Erlang/OTP 17.0 #35e16032

• Fauxton: many improvements in our experimental new user interface,
including switching the code editor from CodeMirror to Ace as well as
better support for various browsers.

• Add the max_count option (UUIDs Configuration) to allow rate-limiting
the amount of UUIDs that can be requested from the /_uuids handler in
a single request (CVE 2014-2668).

• COUCHDB-1986: increase socket buffer size to improve replication
speed for large documents and attachments, and fix tests on BSD-like
systems. #9a0e561b

• COUCHDB-1953: improve performance of multipart/related requests. -
#ce3e89dc

• COUCHDB-2221: verify that authentication-related configuration set-
tings are well-formed. #dbe769c6

• COUCHDB-1922: fix CORS exposed headers. #4f619833

• Rename proxy_authentification_handler to proxy_authentication_han-
dler. #c66ac4a8

• COUCHDB-1795: ensure the startup script clears the pid file on termi-
nation. #818ef4f9

• COUCHDB-1962: replication can now be performed without having write
access to the source database (#1d5fe2aa), the replication checkpoint
interval is now configurable (#0693f98e).

• COUCHDB-2025: add support for SOCKS5 proxies for replication. -
#fcd76c9

• COUCHDB-1930: redirect to the correct page after submitting a new
document with a different ID than the one suggested by Futon. -
#4906b591

• COUCHDB-1923: add support for attachments and att_encoding_info op-
tions (formerly only available on the documents API) to the view API.
#ca41964b

• COUCHDB-1647: for failed replications originating from a document in
the _replicator database, store the failure reason in the document.
#08cac68b

• A number of improvements for the documentation.

1.5.x Branch
• Version 1.5.1

• Version 1.5.0

WARNING:
Version 1.5.1 contains important security fixes. Previous 1.5.x re-
leases are not recommended for regular usage.

Version 1.5.1
• Add the max_count option (UUIDs Configuration) to allow rate-limiting
the amount of UUIDs that can be requested from the /_uuids handler in
a single request (CVE 2014-2668).

Version 1.5.0
• COUCHDB-1781: The official documentation has been overhauled. A lot
of content from other sources have been merged, and the index page
has been rebuilt to make the docs much more accessible. #54813a7

• A new administration UI, codenamed Fauxton, has been included as an
experimental preview. It can be accessed at /_utils/fauxton/. There
are too many improvements here to list them all. We are looking for
feedback from the community on this preview release.

• COUCHDB-1888: Fixed an issue where admin users would be restricted by
the public_fields feature.

• Fixed an issue with the JavaScript CLI test runner. #be76882, -
#54813a7

• COUCHDB-1867: An experimental plugin feature has been added. See
src/couch_plugin/README.md for details. We invite the community to
test and report any findings.

• COUCHDB-1894: An experimental Node.js-based query server runtime has
been added. See Experimental Features for details. We invite the com-
munity to test and report any findings.

• COUCHDB-1901: Better retry mechanism for transferring attachments
during replication. #4ca2cec

1.4.x Branch
• Upgrade Notes

• Version 1.4.0

WARNING:
1.4.x Branch is affected by the issue described in CVE-2014-2668:
DoS (CPU and memory consumption) via the count parameter to /_uuids.
Upgrading to a more recent release is strongly recommended.

Upgrade Notes
We now support Erlang/OTP R16B and R16B01; the minimum required version
is R14B.

User document role values must now be strings. Other types of values
will be refused when saving the user document.

Version 1.4.0
• COUCHDB-1139: its possible to apply list functions to _all_docs view.
#54fd258e

• COUCHDB-1632: Ignore epilogues in multipart/related MIME attachments.
#2b4ab67a

• COUCHDB-1634: Reduce PBKDF2 work factor. #f726bc4d

• COUCHDB-1684: Support for server-wide changes feed reporting on cre-
ation, updates and deletion of databases. #917d8988

• COUCHDB-1772: Prevent invalid JSON output when using all_or_nothing
of bulk API. #dfd39d57

• Add a configurable whitelist of user document properties. #8d7ab8b1

• COUCHDB-1852: Support Last-Event-ID header in EventSource changes
feeds. #dfd2199a

• Allow storing pre-hashed admin passwords via config API. #c98ba561

• Automatic loading of CouchDB plugins. #3fab6bb5

• Much improved documentation, including an expanded description of
validate_doc_update functions (commit:ef9ac469) and a description of
how CouchDB handles JSON number values (#bbd93f77).

• Split up replicator_db tests into multiple independent tests.

1.3.x Branch
• Upgrade Notes

• Version 1.3.1

• Version 1.3.0

WARNING:
1.3.x Branch is affected by the issue described in CVE-2014-2668:
DoS (CPU and memory consumption) via the count parameter to /_uuids.
Upgrading to a more recent release is strongly recommended.

Upgrade Notes
You can upgrade your existing CouchDB 1.0.x installation to 1.3.0 with-
out any specific steps or migration. When you run CouchDB, the existing
data and index files will be opened and used as normal.

The first time you run a compaction routine on your database within
1.3.0, the data structure and indexes will be updated to the new ver-
sion of the CouchDB database format that can only be read by CouchDB
1.3.0 and later. This step is not reversible. Once the data files have
been updated and migrated to the new version the data files will no
longer work with a CouchDB 1.0.x release.

WARNING:
If you want to retain support for opening the data files in CouchDB
1.0.x you must back up your data files before performing the upgrade
and compaction process.

Version 1.3.1
Replicator
• COUCHDB-1788: Tolerate missing source and target fields in _replica-
tor docs. #869f42e2

Log System
• COUCHDB-1794: Fix bug in WARN level logging from 1.3.0.

• Dont log about missing .compact files. #06f1a8dc

View Server
• COUCHDB-1792: Fix the -S option to couchjs to increase memory limits.
#cfaa66cd

Miscellaneous
• COUCHDB-1784: Improvements to test suite and VPATH build system. -
#01afaa4f

• Improve documentation: better structure, improve language, less du-
plication.

Version 1.3.0
Database core
• COUCHDB-1512: Validate bind address before assignment. #09ead8a0

• Restore max_document_size protection. #bf1eb135

Documentation
• COUCHDB-1523: Import CouchBase documentation and convert them into -
Sphinx docs

Futon
• COUCHDB-509: Added view request duration to Futon. #2d2c7d1e

• COUCHDB-627: Support all timezones. #b1a049bb

• COUCHDB-1383: Futon view editor wont allow you to save original view
after saving a revision. #ce48342

• COUCHDB-1470: Futon raises pop-up on attempt to navigate to
missed/deleted document. #5da40eef

• COUCHDB-1473, COUCHDB-1472: Disable buttons for actions that the user
doesnt have permissions to. #7156254d

HTTP Interface
• COUCHDB-431: Introduce experimental CORS support. #b90e4021

• COUCHDB-764, COUCHDB-514, COUCHDB-430: Fix sending HTTP headers from
_list function, #2a74f88375

• COUCHDB-887: Fix bytes and offset parameters semantic for _log re-
source (explanation) #ad700014

• COUCHDB-986: Added Server-Sent Events protocol to db changes API.
See http://www.w3.org/TR/eventsource/ for details. #093d2aa6

• COUCHDB-1026: Database names are encoded with respect of special
characters in the rewriter now. #272d6415

• COUCHDB-1097: Allow OPTIONS request to shows and lists functions. -
#9f53704a

• COUCHDB-1210: Files starting with underscore can be attached and up-
dated now. #05858792

• COUCHDB-1277: Better query parameter support and code clarity: -
#7e3c69ba

• Responses to documents created/modified via form data POST to
/db/doc or copied with COPY should now include Location header.

• Form data POST to /db/doc now includes an ETag response header.

• ?batch=ok is now supported for COPY and POST /db/doc updates.

• ?new_edits=false is now supported for more operations.

• COUCHDB-1285: Allow configuration of vendor and modules version in
CouchDB welcome message. #3c24a94d

• COUCHDB-1321: Variables in rewrite rules breaks OAuth authentication.
#c307ba95

• COUCHDB-1337: Use MD5 for attachment ETag header value. #6d912c9f

• COUCHDB-1381: Add jquery.couch support for Windows 8 Metro apps. -
#dfc5d37c

• COUCHDB-1441: Limit recursion depth in the URL rewriter. Defaults to
a maximum of 100 invocations but is configurable. #d076976c

• COUCHDB-1442: No longer rewrites the X-CouchDB-Requested-Path during
recursive calls to the rewriter. #56744f2f

• COUCHDB-1501: Changes feed now can take special parameter since=now
to emit changes since current point of time. #3bbb2612

• COUCHDB-1502: Allow users to delete own _users doc. #f0d6f19bc8

• COUCHDB-1511: CouchDB checks roles field for _users database docu-
ments with more care. #41205000

• COUCHDB-1537: Include user name in show/list ETags. #ac320479

• Send a 202 response for _restart. #b213e16f

• Make password hashing synchronous when using the /_config/admins API.
#08071a80

• Add support to serve single file with CouchDB, #2774531ff2

• Allow any 2xx code to indicate success, #0d50103cfd

• Fix _session for IE7.

• Restore 400 error for empty PUT, #2057b895

• Return X-Couch-Id header if doc is created, #98515bf0b9

• Support auth cookies with : characters, #d9566c831d

Log System
• COUCHDB-1380: Minor fixes for logrotate support.

• Improve file I/O error logging and handling, #4b6475da

• Module Level Logging, #b58f069167

• Log 5xx responses at error level, #e896b0b7

• Log problems opening database at ERROR level except for auto-created
system dbs, #41667642f7

Replicator
• COUCHDB-1248: HTTP 500 error now doesnt occurs when replicating with
?doc_ids=null. #bea76dbf

• COUCHDB-1259: Stabilize replication id, #c6252d6d7f

• COUCHDB-1323: Replicator now acts as standalone application. -
#f913ca6e

• COUCHDB-1363: Fix rarely occurred, but still race condition in
changes feed if a quick burst of changes happens while replication is
starting the replication can go stale. #573a7bb9

• COUCHDB-1557: Upgrade some code to use BIFs bring good improvements
for replication.

Security
• COUCHDB-1060: Passwords are now hashed using the PBKDF2 algorithm
with a configurable work factor. #7d418134

Source Repository
• The source repository was migrated from SVN to Git.

Storage System
• Fixed unnecessary conflict when deleting and creating a document in
the same batch.

Test Suite
• COUCHDB-1321: Moved the JS test suite to the CLI.

• COUCHDB-1338: Start CouchDB with port=0. While CouchDB might be al-
ready running on the default port 5984, port number 0 let the TCP
stack figure out a free port to run. #127cbe3

• COUCHDB-1339: Use shell trap to catch dying beam processes during
test runs. #2921c78

• COUCHDB-1389: Improved tracebacks printed by the JS CLI tests.

• COUCHDB-1563: Ensures urlPrefix is set in all ajax requests. -
#07a6af222

• Fix race condition for test running on faster hardware.

• Improved the reliability of a number of tests.

URL Rewriter & Vhosts
• COUCHDB-1026: Database name is encoded during rewriting (allowing em-
bedded /s, etc). #272d6415

UUID Algorithms
• COUCHDB-1373: Added the utc_id algorithm #5ab712a2

Query and View Server
• COUCHDB-111: Improve the errors reported by the JavaScript view
server to provide a more friendly error report when something goes
wrong. #0c619ed

• COUCHDB-410: More graceful error handling for JavaScript vali-
date_doc_update functions.

• COUCHDB-1372: _stats built-in reduce function no longer produces er-
ror for empty view result.

• COUCHDB-1444: Fix missed_named_view error that occurs on existed de-
sign documents and views. #b59ac98b

• COUCHDB-1445: CouchDB tries no more to delete view file if it couldnt
open it, even if the error is emfile.

• COUCHDB-1483: Update handlers requires valid doc ids. #72ea7e38

• COUCHDB-1491: Clean up view tables. #c37204b7

• Deprecate E4X support, #cdfdda2314

Windows
• COUCHDB-1482: Use correct linker flag to build snappy_nif.dll on Win-
dows. #a6eaf9f1

• Allows building cleanly on Windows without cURL, #fb670f5712

1.2.x Branch
• Upgrade Notes

• Version 1.2.2

• Version 1.2.1

• Version 1.2.0

Upgrade Notes
WARNING:
This version drops support for the database format that was intro-
duced in version 0.9.0. Compact your older databases (that have not
been compacted for a long time) before upgrading, or they will be-
come inaccessible.

WARNING:
Version 1.2.1 contains important security fixes. Previous 1.2.x re-
leases are not recommended for regular usage.

Security changes
The interface to the _users and _replicator databases have been changed
so that non-administrator users can see less information:

• In the _users database:

• User documents can now only be read by the respective users, as
well as administrators. Other users cannot read these documents.

• Views can only be defined and queried by administrator users.

• The _changes feed can only be queried by administrator users.

• In the _replicator database:

• Documents now have a forced owner field that corresponds to the au-
thenticated user that created them.

• Non-owner users will not see confidential information like pass-
words or OAuth tokens in replication documents; they can still see
the other contents of those documents. Administrators can see
everything.

• Views can only be defined and queried by administrators.

Database Compression
The new optional (but enabled by default) compression of disk files re-
quires an upgrade of the on-disk format (5 -> 6) which occurs on cre-
ation for new databases and views, and on compaction for existing
files. This format is not supported in previous releases, so rollback
would require replication to the previous CouchDB release or restoring
from backup.

Compression can be disabled by setting compression = none in your lo-
cal.ini [couchdb] section, but the on-disk format will still be up-
graded.

Version 1.2.2
Build System
• Fixed issue in couchdb script where stopped status returns before
process exits.

HTTP Interface
• Reset rewrite counter on new request, avoiding unnecessary request
failures due to bogus rewrite limit reports.

Version 1.2.1
Build System
• Fix couchdb start script.

• Win: fix linker invocations.

Futon
• Disable buttons that arent available for the logged-in user.

HTTP Interface
• No longer rewrites the X-CouchDB-Requested-Path during recursive
calls to the rewriter.

• Limit recursion depth in the URL rewriter. Defaults to a maximum of
100 invocations but is configurable.

Security
• Fixed CVE-2012-5641: Information disclosure via unescaped backslashes
in URLs on Windows

• Fixed CVE-2012-5649: JSONP arbitrary code execution with Adobe Flash

• Fixed CVE-2012-5650: DOM based Cross-Site Scripting via Futon UI

Replication
• Fix potential timeouts.

View Server
• Change use of signals to avoid broken view groups.

Version 1.2.0
Authentication
• Fix use of OAuth with VHosts and URL rewriting.

• OAuth secrets can now be stored in the users system database as an
alternative to key value pairs in the .ini configuration. By default
this is disabled (secrets are stored in the .ini) but can be enabled
via the .ini configuration key use_users_db in the couch_httpd_oauth
section.

• Documents in the _users database are no longer publicly readable.

• Confidential information in the _replication database is no longer
publicly readable.

• Password hashes are now calculated by CouchDB. Clients are no longer
required to do this manually.

• Cookies used for authentication can be made persistent by enabling
the .ini configuration key allow_persistent_cookies in the
couch_httpd_auth section.

Build System
• cURL is no longer required to build CouchDB as it is only used by the
command line JS test runner. If cURL is available when building
CouchJS you can enable the HTTP bindings by passing -H on the command
line.

• Temporarily made make check pass with R15B. A more thorough fix is in
the works (COUCHDB-1424).

• Fixed with-js-include and with-js-lib options.

• Added with-js-lib-name option.

Futon
• The Status screen (active tasks) now displays two new task status
fields: Started on and Updated on.

• Futon remembers view code every time it is saved, allowing to save an
edit that amounts to a revert.

HTTP Interface
• Added a native JSON parser.

• The _active_tasks API now offers more granular fields. Each task type
is now able to expose different properties.

• Added built-in changes feed filter _view.

• Fixes to the _changes feed heartbeat option which caused heartbeats
to be missed when used with a filter. This caused timeouts of contin-
uous pull replications with a filter.

• Properly restart the SSL socket on configuration changes.

OAuth
• Updated bundled erlang_oauth library to the latest version.

Replicator
• A new replicator implementation. It offers more performance and con-
figuration options.

• Passing non-string values to query_params is now a 400 bad request.
This is to reduce the surprise that all parameters are converted to
strings internally.

• Added optional field since_seq to replication objects/documents. It
allows to bootstrap a replication from a specific source sequence
number.

• Simpler replication cancellation. In addition to the current method,
replications can now be canceled by specifying the replication ID in-
stead of the original replication object/document.

Storage System
• Added optional database and view index file compression (using
Googles snappy or zlibs deflate). This feature is enabled by default,
but it can be disabled by adapting local.ini accordingly. The on-disk
format is upgraded on compaction and new DB/view creation to support
this.

• Several performance improvements, most notably regarding database
writes and view indexing.

• Computation of the size of the latest MVCC snapshot data and all its
supporting metadata, both for database and view index files. This in-
formation is exposed as the data_size attribute in the database and
view group information URIs.

• The size of the buffers used for database and view compaction is now
configurable.

• Added support for automatic database and view compaction. This fea-
ture is disabled by default, but it can be enabled via the .ini con-
figuration.

• Performance improvements for the built-in changes feed filters
_doc_ids and _design.

View Server
• Add CoffeeScript (http://coffeescript.org/) as a first class view
server language.

• Fixed old index file descriptor leaks after a view cleanup.

• The requested_path property keeps the pre-rewrite path even when no
VHost configuration is matched.

• Fixed incorrect reduce query results when using pagination parame-
ters.

• Made icu_driver work with Erlang R15B and later.

1.1.x Branch
• Upgrade Notes

• Version 1.1.2

• Version 1.1.1

• Version 1.1.0

Upgrade Notes
WARNING:
Version 1.1.2 contains important security fixes. Previous 1.1.x re-
leases are not recommended for regular usage.

Version 1.1.2
Build System
• Dont ln the couchjs install target on Windows

• Remove ICU version dependency on Windows.

• Improve SpiderMonkey version detection.

HTTP Interface
• ETag of attachment changes only when the attachment changes, not the
document.

• Fix retrieval of headers larger than 4k.

• Allow OPTIONS HTTP method for list requests.

• Dont attempt to encode invalid json.

Log System
• Improvements to log messages for file-related errors.

Replicator
• Fix pull replication of documents with many revisions.

• Fix replication from an HTTP source to an HTTP target.

Security
• Fixed CVE-2012-5641: Information disclosure via unescaped backslashes
in URLs on Windows

• Fixed CVE-2012-5649: JSONP arbitrary code execution with Adobe Flash

• Fixed CVE-2012-5650: DOM based Cross-Site Scripting via Futon UI

View Server
• Avoid invalidating view indexes when running out of file descriptors.

Version 1.1.1
• Support SpiderMonkey 1.8.5

• Add configurable maximum to the number of bytes returned by _log.

• Allow CommonJS modules to be an empty string.

• Bump minimum Erlang version to R13B02.

• Do not run deleted validate_doc_update functions.

• ETags for views include current sequence if include_docs=true.

• Fix bug where duplicates can appear in _changes feed.

• Fix bug where update handlers break after conflict resolution.

• Fix bug with _replicator where include filter could crash couch.

• Fix crashes when compacting large views.

• Fix file descriptor leak in _log

• Fix missing revisions in _changes?style=all_docs.

• Improve handling of compaction at max_dbs_open limit.

• JSONP responses now send text/javascript for Content-Type.

• Link to ICU 4.2 on Windows.

• Permit forward slashes in path to update functions.

• Reap couchjs processes that hit reduce_overflow error.

• Status code can be specified in update handlers.

• Support provides() in show functions.

• _view_cleanup when ddoc has no views now removes all index files.

• max_replication_retry_count now supports infinity.

• Fix replication crash when source database has a document with empty
ID.

• Fix deadlock when assigning couchjs processes to serve requests.

• Fixes to the document multipart PUT API.

• Fixes regarding file descriptor leaks for databases with views.

Version 1.1.0
NOTE:
All CHANGES for 1.0.2 and 1.0.3 also apply to 1.1.0.

Externals
• Added OS Process module to manage daemons outside of CouchDB.

• Added HTTP Proxy handler for more scalable externals.

Futon
• Added a change password-feature to Futon.

HTTP Interface
• Native SSL support.

• Added support for HTTP range requests for attachments.

• Added built-in filters for _changes: _doc_ids and _design.

• Added configuration option for TCP_NODELAY aka Nagle.

• Allow POSTing arguments to _changes.

• Allow keys parameter for GET requests to views.

• Allow wildcards in vhosts definitions.

• More granular ETag support for views.

• More flexible URL rewriter.

• Added support for recognizing Q values and media parameters in HTTP
Accept headers.

• Validate doc ids that come from a PUT to a URL.

Replicator
• Added _replicator database to manage replications.

• Fixed issues when an endpoint is a remote database accessible via
SSL.

• Added support for continuous by-doc-IDs replication.

• Fix issue where revision info was omitted when replicating attach-
ments.

• Integrity of attachment replication is now verified by MD5.

Storage System
• Multiple micro-optimizations when reading data.

URL Rewriter & Vhosts
• Fix for variable substitution

View Server
• Added CommonJS support to map functions.

• Added stale=update_after query option that triggers a view update af-
ter returning a stale=ok response.

• Warn about empty result caused by startkey and endkey limiting.

• Built-in reduce function _sum now accepts lists of integers as input.

• Added view query aliases start_key, end_key, start_key_doc_id and
end_key_doc_id.

1.0.x Branch
• Upgrade Notes

• Version 1.0.4

• Version 1.0.3

• Version 1.0.2

• Version 1.0.1

• Version 1.0.0

Upgrade Notes
Note, to replicate with a 1.0 CouchDB instance you must first upgrade
in-place your current CouchDB to 1.0 or 0.11.1 backporting so that
0.10.x can replicate to 1.0 wouldnt be that hard. All that is required
is patching the replicator to use the application/json content type.

• _log and _temp_views are now admin-only resources.

• _bulk_docs now requires a valid Content-Type header of applica-
tion/json.

• JSONP is disabled by default. An .ini option was added to selectively
enable it.

• The key, startkey and endkey properties of the request object passed
to list and show functions now contain JSON objects representing the
URL encoded string values in the query string. Previously, these
properties contained strings which needed to be converted to JSON be-
fore using.

WARNING:
Version 1.0.4 contains important security fixes. Previous 1.0.x re-
leases are not recommended for regular usage.

Version 1.0.4
HTTP Interface
• Fix missing revisions in _changes?style=all_docs.

• Fix validation of attachment names.

Log System
• Fix file descriptor leak in _log.

Replicator
• Fix a race condition where replications can go stale

Security
• Fixed CVE-2012-5641: Information disclosure via unescaped backslashes
in URLs on Windows

• Fixed CVE-2012-5649: JSONP arbitrary code execution with Adobe Flash

• Fixed CVE-2012-5650: DOM based Cross-Site Scripting via Futon UI

View System
• Avoid invalidating view indexes when running out of file descriptors.

Version 1.0.3
General
• Fixed compatibility issues with Erlang R14B02.

Etap Test Suite
• Etap tests no longer require use of port 5984. They now use a ran-
domly selected port so they wont clash with a running CouchDB.

Futon
• Made compatible with jQuery 1.5.x.

HTTP Interface
• Fix bug that allows invalid UTF-8 after valid escapes.

• The query parameter include_docs now honors the parameter conflicts.
This applies to queries against map views, _all_docs and _changes.

• Added support for inclusive_end with reduce views.

Replicator
• Enabled replication over IPv6.

• Fixed for crashes in continuous and filtered changes feeds.

• Fixed error when restarting replications in OTP R14B02.

• Upgrade ibrowse to version 2.2.0.

• Fixed bug when using a filter and a limit of 1.

Security
• Fixed OAuth signature computation in OTP R14B02.

• Handle passwords with : in them.

Storage System
• More performant queries against _changes and _all_docs when using the
include_docs parameter.

Windows
• Windows builds now require ICU >= 4.4.0 and Erlang >= R14B03. See -
COUCHDB-1152, and COUCHDB-963 + OTP-9139 for more information.

Version 1.0.2
Futon
• Make test suite work with Safari and Chrome.

• Fixed animated progress spinner.

• Fix raw view document link due to overzealous URI encoding.

• Spell javascript correctly in loadScript(uri).

HTTP Interface
• Allow reduce=false parameter in map-only views.

• Fix parsing of Accept headers.

• Fix for multipart GET APIs when an attachment was created during a
local-local replication. See COUCHDB-1022 for details.

Log System
• Reduce lengthy stack traces.

• Allow logging of native <xml> types.

Replicator
• Updated ibrowse library to 2.1.2 fixing numerous replication issues.

• Make sure that the replicator respects HTTP settings defined in the
config.

• Fix error when the ibrowse connection closes unexpectedly.

• Fix authenticated replication (with HTTP basic auth) of design docu-
ments with attachments.

• Various fixes to make replication more resilient for edge-cases.

Storage System
• Fix leaking file handles after compacting databases and views.

• Fix databases forgetting their validation function after compaction.

• Fix occasional timeout errors after successfully compacting large
databases.

• Fix occasional error when writing to a database that has just been
compacted.

• Fix occasional timeout errors on systems with slow or heavily loaded
IO.

• Fix for OOME when compactions include documents with many conflicts.

• Fix for missing attachment compression when MIME types included para-
meters.

• Preserve purge metadata during compaction to avoid spurious view re-
builds.

• Fix spurious conflicts introduced when uploading an attachment after
a doc has been in a conflict. See COUCHDB-902 for details.

• Fix for frequently edited documents in multi-master deployments being
duplicated in _changes and _all_docs. See COUCHDB-968 for details on
how to repair.

• Significantly higher read and write throughput against database and
view index files.

View Server
• Dont trigger view updates when requesting _design/doc/_info.

• Fix for circular references in CommonJS requires.

• Made isArray() function available to functions executed in the query
server.

• Documents are now sealed before being passed to map functions.

• Force view compaction failure when duplicated document data exists.
When this error is seen in the logs users should rebuild their views
from scratch to fix the issue. See COUCHDB-999 for details.

Version 1.0.1
Authentication
•

Enable basic-auth popup when required to access the server, to pre-
vent
people from getting locked out.

Build and System Integration
• Included additional source files for distribution.

Futon
• User interface element for querying stale (cached) views.

HTTP Interface
• Expose committed_update_seq for monitoring purposes.

• Show fields saved along with _deleted=true. Allows for auditing of
deletes.

• More robust Accept-header detection.

Replicator
• Added support for replication via an HTTP/HTTPS proxy.

• Fix pull replication of attachments from 0.11 to 1.0.x.

• Make the _changes feed work with non-integer seqnums.

Storage System
• Fix data corruption bug COUCHDB-844. Please see -
http://couchdb.apache.org/notice/1.0.1.html for details.

Version 1.0.0
Security
• Added authentication caching, to avoid repeated opening and closing
of the users database for each request requiring authentication.

Storage System
• Small optimization for reordering result lists.

• More efficient header commits.

• Use O_APPEND to save lseeks.

• Faster implementation of pread_iolist(). Further improves performance
on concurrent reads.

View Server
• Faster default view collation.

• Added option to include update_seq in view responses.

0.11.x Branch
• Upgrade Notes

• Version 0.11.2

• Version 0.11.1

• Version 0.11.0

Upgrade Notes
WARNING:
Version 0.11.2 contains important security fixes. Previous 0.11.x
releases are not recommended for regular usage.

Changes Between 0.11.0 and 0.11.1
• _log and _temp_views are now admin-only resources.

• _bulk_docs now requires a valid Content-Type header of applica-
tion/json.

• JSONP is disabled by default. An .ini option was added to selectively
enable it.

Changes Between 0.10.x and 0.11.0
show, list, update and validation functions
The req argument to show, list, update and validation functions now
contains the member method with the specified HTTP method of the cur-
rent request. Previously, this member was called verb. method is fol-
lowing RFC 2616 (HTTP 1.1) closer.

_admins -> _security
The /db/_admins handler has been removed and replaced with a
/{db}/_security object. Any existing _admins will be dropped and need
to be added to the security object again. The reason for this is that
the old system made no distinction between names and roles, while the
new one does, so there is no way to automatically upgrade the old ad-
mins list.

The security object has 2 special fields, admins and readers, which
contain lists of names and roles which are admins or readers on that
database. Anything else may be stored in other fields on the security
object. The entire object is made available to validation functions.

json2.js
JSON handling in the query server has been upgraded to use json2.js.
This allows us to use faster native JSON serialization when it is
available.

In previous versions, attempts to serialize undefined would throw an
exception, causing the doc that emitted undefined to be dropped from
the view index. The new behavior is to serialize undefined as null.
Applications depending on the old behavior will need to explicitly
check for undefined.

Another change is that E4Xs XML objects will not automatically be
stringified. XML users will need to call my_xml_object.toXMLString() to
return a string value. #8d3b7ab3

WWW-Authenticate
The default configuration has been changed to avoid causing basic-auth
popups which result from sending the WWW-Authenticate header. To enable
basic-auth popups, uncomment the config option httpd/WWW-Authenticate
line in local.ini.

Query server line protocol
The query server line protocol has changed for all functions except
map, reduce, and rereduce. This allows us to cache the entire design
document in the query server process, which results in faster perfor-
mance for common operations. It also gives more flexibility to query
server implementers and shouldnt require major changes in the future
when adding new query server features.

UTF8 JSON
JSON request bodies are validated for proper UTF-8 before saving, in-
stead of waiting to fail on subsequent read requests.

_changes line format
Continuous changes are now newline delimited, instead of having each
line followed by a comma.

Version 0.11.2
Authentication
• User documents can now be deleted by admins or the user.

Futon
• Add some Futon files that were missing from the Makefile.

HTTP Interface
• Better error messages on invalid URL requests.

Replicator
• Fix bug when pushing design docs by non-admins, which was hanging the
replicator for no good reason.

• Fix bug when pulling design documents from a source that requires ba-
sic-auth.

Security
• Avoid potential DOS attack by guarding all creation of atoms.

• Fixed CVE-2010-2234: Apache CouchDB Cross Site Request Forgery Attack

Version 0.11.1
Build and System Integration
• Output of couchdb help has been improved.

• Fixed compatibility with the Erlang R14 series.

• Fixed warnings on Linux builds.

• Fixed build error when aclocal needs to be called during the build.

• Require ICU 4.3.1.

• Fixed compatibility with Solaris.

Configuration System
• Fixed timeout with large .ini files.

Futon
• Use expando links for over-long document values in Futon.

• Added continuous replication option.

• Added option to replicating test results anonymously to a community
CouchDB instance.

• Allow creation and deletion of config entries.

• Fixed display issues with doc ids that have escaped characters.

• Fixed various UI issues.

HTTP Interface
• Mask passwords in active tasks and logging.

• Update mochijson2 to allow output of BigNums not in float form.

• Added support for X-HTTP-METHOD-OVERRIDE.

• Better error message for database names.

• Disable jsonp by default.

• Accept gzip encoded standalone attachments.

• Made max_concurrent_connections configurable.

• Made changes API more robust.

• Send newly generated document rev to callers of an update function.

JavaScript Clients
• Added tests for couch.js and jquery.couch.js

• Added changes handler to jquery.couch.js.

• Added cache busting to jquery.couch.js if the user agent is msie.

• Added support for multi-document-fetch (via _all_docs) to
jquery.couch.js.

• Added attachment versioning to jquery.couch.js.

• Added option to control ensure_full_commit to jquery.couch.js.

• Added list functionality to jquery.couch.js.

• Fixed issues where bulkSave() wasnt sending a POST body.

Log System
• Log HEAD requests as HEAD, not GET.

• Keep massive JSON blobs out of the error log.

• Fixed a timeout issue.

Replication System
• Refactored various internal APIs related to attachment streaming.

• Fixed hanging replication.

• Fixed keepalive issue.

Security
• Added authentication redirect URL to log in clients.

• Fixed query parameter encoding issue in oauth.js.

• Made authentication timeout configurable.

• Temporary views are now admin-only resources.

Storage System
• Dont require a revpos for attachment stubs.

• Added checking to ensure when a revpos is sent with an attachment
stub, its correct.

• Make file deletions async to avoid pauses during compaction and db
deletion.

• Fixed for wrong offset when writing headers and converting them to
blocks, only triggered when header is larger than 4k.

• Preserve _revs_limit and instance_start_time after compaction.

Test Suite
• Made the test suite overall more reliable.

View Server
• Provide a UUID to update functions (and all other functions) that
they can use to create new docs.

• Upgrade CommonJS modules support to 1.1.1.

• Fixed erlang filter funs and normalize filter fun API.

• Fixed hang in view shutdown.

URL Rewriter & Vhosts
• Allow more complex keys in rewriter.

• Allow global rewrites so system defaults are available in vhosts.

• Allow isolation of databases with vhosts.

• Fix issue with passing variables to query parameters.

Version 0.11.0
Build and System Integration
• Updated and improved source documentation.

• Fixed distribution preparation for building on Mac OS X.

• Added support for building a Windows installer as part of make dist.

• Bug fix for building couch.apps module list.

• ETap tests are now run during make distcheck. This included a number
of updates to the build system to properly support VPATH builds.

• Gavin McDonald set up a build-bot instance. More info can be found at
http://ci.apache.org/buildbot.html

Futon
• Added a button for view compaction.

• JSON strings are now displayed as-is in the document view, without
the escaping of new-lines and quotes. That dramatically improves
readability of multi-line strings.

• Same goes for editing of JSON string values. When a change to a field
value is submitted, and the value is not valid JSON it is assumed to
be a string. This improves editing of multi-line strings a lot.

• Hitting tab in textareas no longer moves focus to the next form
field, but simply inserts a tab character at the current caret posi-
tion.

• Fixed some font declarations.

HTTP Interface
• Provide Content-MD5 header support for attachments.

• Added URL Rewriter handler.

• Added virtual host handling.

Replication
• Added option to implicitly create replication target databases.

• Avoid leaking file descriptors on automatic replication restarts.

• Added option to replicate a list of documents by id.

• Allow continuous replication to be cancelled.

Runtime Statistics
• Statistics are now calculated for a moving window instead of
non-overlapping timeframes.

• Fixed a problem with statistics timers and system sleep.

• Moved statistic names to a term file in the priv directory.

Security
• Fixed CVE-2010-0009: Apache CouchDB Timing Attack Vulnerability.

• Added default cookie-authentication and users database.

• Added Futon user interface for user signup and login.

• Added per-database reader access control lists.

• Added per-database security object for configuration data in valida-
tion functions.

• Added proxy authentication handler

Storage System
• Adds batching of multiple updating requests, to improve throughput
with many writers. Removed the now redundant couch_batch_save module.

• Adds configurable compression of attachments.

View Server
• Added optional raw binary collation for faster view builds where Uni-
code collation is not important.

• Improved view index build time by reducing ICU collation callouts.

• Improved view information objects.

• Bug fix for partial updates during view builds.

• Move query server to a design-doc based protocol.

• Use json2.js for JSON serialization for compatibility with native
JSON.

• Major refactoring of couchjs to lay the groundwork for disabling cURL
support. The new HTTP interaction acts like a synchronous XHR. Exam-
ple usage of the new system is in the JavaScript CLI test runner.

0.10.x Branch
• Upgrade Notes

• Version 0.10.2

• Version 0.10.1

• Version 0.10.0

Upgrade Notes
WARNING:
Version 0.10.2 contains important security fixes. Previous 0.10.x
releases are not recommended for regular usage.

Modular Configuration Directories
CouchDB now loads configuration from the following places (glob(7) syn-
tax) in order:

• PREFIX/default.ini

• PREFIX/default.d/*

• PREFIX/local.ini

• PREFIX/local.d/*

The configuration options for couchdb script have changed to:

-a FILE add configuration FILE to chain
-A DIR add configuration DIR to chain
-n reset configuration file chain (including system default)
-c print configuration file chain and exit

Show and List API change
Show and List functions must have a new structure in 0.10. See -
Formatting_with_Show_and_List for details.

Stricter enforcing of reduciness in reduce-functions
Reduce functions are now required to reduce the number of values for a
key.

View query reduce parameter strictness
CouchDB now considers the parameter reduce=false to be an error for
queries of map-only views, and responds with status code 400.

Version 0.10.2
Build and System Integration
• Fixed distribution preparation for building on Mac OS X.

Security
• Fixed CVE-2010-0009: Apache CouchDB Timing Attack Vulnerability

Replicator
• Avoid leaking file descriptors on automatic replication restarts.

Version 0.10.1
Build and System Integration
• Test suite now works with the distcheck target.

Replicator
• Stability enhancements regarding redirects, timeouts, OAuth.

Query Server
• Avoid process leaks

• Allow list and view to span languages

Stats
• Eliminate new process flood on system wake

Version 0.10.0
Build and System Integration
• Changed couchdb script configuration options.

• Added default.d and local.d configuration directories to load se-
quence.

HTTP Interface
• Added optional cookie-based authentication handler.

• Added optional two-legged OAuth authentication handler.

Storage Format
• Add move headers with checksums to the end of database files for ex-
tra robust storage and faster storage.

View Server
• Added native Erlang views for high-performance applications.

0.9.x Branch
• Upgrade Notes

• Version 0.9.2

• Version 0.9.1

• Version 0.9.0

Upgrade Notes
Response to Bulk Creation/Updates
The response to a bulk creation / update now looks like this

[
{"id": "0", "rev": "3682408536"},
{"id": "1", "rev": "3206753266"},
{"id": "2", "error": "conflict", "reason": "Document update conflict."}
]

Database File Format
The database file format has changed. CouchDB itself does yet not pro-
vide any tools for migrating your data. In the meantime, you can use
third-party scripts to deal with the migration, such as the dump/load
tools that come with the development version (trunk) of couchdb-python.

Renamed count to limit
The view query API has been changed: count has become limit. This is a
better description of what the parameter does, and should be a simple
update in any client code.

Moved View URLs
The view URLs have been moved to design document resources. This means
that paths that used to be like:

http://hostname:5984/mydb/_view/designname/viewname?limit=10

will now look like:

http://hostname:5984/mydb/_design/designname/_view/viewname?limit=10.

See the REST, Hypermedia, and CouchApps thread on dev for details.

Attachments
Names of attachments are no longer allowed to start with an underscore.

Error Codes
Some refinements have been made to error handling. CouchDB will send
400 instead of 500 on invalid query parameters. Most notably, document
update conflicts now respond with 409 Conflict instead of 412 Precondi-
tion Failed. The error code for when attempting to create a database
that already exists is now 412 instead of 409.

ini file format
CouchDB 0.9 changes sections and configuration variable names in con-
figuration files. Old .ini files wont work. Also note that CouchDB now
ships with two .ini files where 0.8 used couch.ini there are now de-
fault.ini and local.ini. default.ini contains CouchDBs standard con-
figuration values. local.ini is meant for local changes. local.ini is
not overwritten on CouchDB updates, so your edits are safe. In addi-
tion, the new runtime configuration system persists changes to the con-
figuration in local.ini.

Version 0.9.2
Build and System Integration
• Remove branch callbacks to allow building couchjs against newer ver-
sions of Spidermonkey.

Replication
• Fix replication with 0.10 servers initiated by an 0.9 server (-
COUCHDB-559).

Version 0.9.1
Build and System Integration
• PID file directory is now created by the SysV/BSD daemon scripts.

• Fixed the environment variables shown by the configure script.

• Fixed the build instructions shown by the configure script.

• Updated ownership and permission advice in README for better secu-
rity.

Configuration and stats system
• Corrected missing configuration file error message.

• Fixed incorrect recording of request time.

Database Core
• Document validation for underscore prefixed variables.

• Made attachment storage less sparse.

• Fixed problems when a database with delayed commits pending is con-
sidered idle, and subject to losing changes when shutdown. (-
COUCHDB-334)

External Handlers
• Fix POST requests.

Futon
• Redirect when loading a deleted view URI from the cookie.

HTTP Interface
• Attachment requests respect the rev query-string parameter.

JavaScript View Server
• Useful JavaScript Error messages.

Replication
• Added support for Unicode characters transmitted as UTF-16 surrogate
pairs.

• URL-encode attachment names when necessary.

• Pull specific revisions of an attachment, instead of just the latest
one.

• Work around a rare chunk-merging problem in ibrowse.

• Work with documents containing Unicode characters outside the Basic
Multilingual Plane.

Version 0.9.0
Build and System Integration
• The couchdb script now supports system chainable configuration files.

• The Mac OS X daemon script now redirects STDOUT and STDERR like
SysV/BSD.

• The build and system integration have been improved for portability.

• Added COUCHDB_OPTIONS to etc/default/couchdb file.

• Remove COUCHDB_INI_FILE and COUCHDB_PID_FILE from etc/default/couchdb
file.

• Updated configure.ac to manually link libm for portability.

• Updated configure.ac to extended default library paths.

• Removed inets configuration files.

• Added command line test runner.

• Created dev target for make.

Configuration and stats system
• Separate default and local configuration files.

• HTTP interface for configuration changes.

• Statistics framework with HTTP query API.

Database Core
• Faster B-tree implementation.

• Changed internal JSON term format.

• Improvements to Erlang VM interactions under heavy load.

• User context and administrator role.

• Update validations with design document validation functions.

• Document purge functionality.

• Ref-counting for database file handles.

Design Document Resource Paths
• Added httpd_design_handlers config section.

• Moved _view to httpd_design_handlers.

• Added ability to render documents as non-JSON content-types with
_show and _list functions, which are also httpd_design_handlers.

Futon Utility Client
• Added pagination to the database listing page.

• Implemented attachment uploading from the document page.

• Added page that shows the current configuration, and allows modifica-
tion of option values.

• Added a JSON source view for document display.

• JSON data in view rows is now syntax highlighted.

• Removed the use of an iframe for better integration with browser his-
tory and bookmarking.

• Full database listing in the sidebar has been replaced by a short
list of recent databases.

• The view editor now allows selection of the view language if there is
more than one configured.

• Added links to go to the raw view or document URI.

• Added status page to display currently running tasks in CouchDB.

• JavaScript test suite split into multiple files.

• Pagination for reduce views.

HTTP Interface
• Added client side UUIDs for idempotent document creation

• HTTP COPY for documents

• Streaming of chunked attachment PUTs to disk

• Remove negative count feature

• Add include_docs option for view queries

• Add multi-key view post for views

• Query parameter validation

• Use stale=ok to request potentially cached view index

• External query handler module for full-text or other indexers.

• Etags for attachments, views, shows and lists

• Show and list functions for rendering documents and views as devel-
oper controlled content-types.

• Attachment names may use slashes to allow uploading of nested direc-
tories (useful for static web hosting).

• Option for a view to run over design documents.

• Added newline to JSON responses. Closes bike-shed.

Replication
• Using ibrowse.

• Checkpoint replications so failures are less expensive.

• Automatically retry of failed replications.

• Stream attachments in pull-replication.

0.8.x Branch
• Version 0.8.1-incubating

• Version 0.8.0-incubating

Version 0.8.1-incubating
Build and System Integration
• The couchdb script no longer uses awk for configuration checks as
this was causing portability problems.

• Updated sudo example in README to use the -i option, this fixes prob-
lems when invoking from a directory the couchdb user cannot access.

Database Core
• Fix for replication problems where the write queues can get backed up
if the writes arent happening fast enough to keep up with the reads.
For a large replication, this can exhaust memory and crash, or slow
down the machine dramatically. The fix keeps only one document in the
write queue at a time.

• Fix for databases sometimes incorrectly reporting that they contain 0
documents after compaction.

• CouchDB now uses ibrowse instead of inets for its internal HTTP
client implementation. This means better replication stability.

Futon
• The view selector dropdown should now work in Opera and Internet Ex-
plorer even when it includes optgroups for design documents. (-
COUCHDB-81)

JavaScript View Server
• Sealing of documents has been disabled due to an incompatibility with
SpiderMonkey 1.9.

• Improve error handling for undefined values emitted by map functions.
(COUCHDB-83)

HTTP Interface
• Fix for chunked responses where chunks were always being split into
multiple TCP packets, which caused problems with the test suite under
Safari, and in some other cases.

• Fix for an invalid JSON response body being returned for some kinds
of views. (COUCHDB-84)

• Fix for connections not getting closed after rejecting a chunked re-
quest. (COUCHDB-55)

• CouchDB can now be bound to IPv6 addresses.

• The HTTP Server header now contains the versions of CouchDB and Er-
lang.

Version 0.8.0-incubating
Build and System Integration
• CouchDB can automatically respawn following a server crash.

• Database server no longer refuses to start with a stale PID file.

• System logrotate configuration provided.

• Improved handling of ICU shared libraries.

• The couchdb script now automatically enables SMP support in Erlang.

• The couchdb and couchjs scripts have been improved for portability.

• The build and system integration have been improved for portability.

Database Core
• The view engine has been completely decoupled from the storage en-
gine. Index data is now stored in separate files, and the format of
the main database file has changed.

• Databases can now be compacted to reclaim space used for deleted doc-
uments and old document revisions.

• Support for incremental map/reduce views has been added.

• To support map/reduce, the structure of design documents has changed.
View values are now JSON objects containing at least a map member,
and optionally a reduce member.

• View servers are now identified by name (for example javascript) in-
stead of by media type.

• Automatically generated document IDs are now based on proper UUID
generation using the crypto module.

• The field content-type in the JSON representation of attachments has
been renamed to content_type (underscore).

Futon
• When adding a field to a document, Futon now just adds a field with
an autogenerated name instead of prompting for the name with a dia-
log. The name is automatically put into edit mode so that it can be
changed immediately.

• Fields are now sorted alphabetically by name when a document is dis-
played.

• Futon can be used to create and update permanent views.

• The maximum number of rows to display per page on the database page
can now be adjusted.

• Futon now uses the XMLHTTPRequest API asynchronously to communicate
with the CouchDB HTTP server, so that most operations no longer block
the browser.

• View results sorting can now be switched between ascending and de-
scending by clicking on the Key column header.

• Fixed a bug where documents that contained a @ character could not be
viewed. (COUCHDB-12)

• The database page now provides a Compact button to trigger database
compaction. (COUCHDB-38)

• Fixed portential double encoding of document IDs and other URI seg-
ments in many instances. (COUCHDB-39)

• Improved display of attachments.

• The JavaScript Shell has been removed due to unresolved licensing is-
sues.

JavaScript View Server
• SpiderMonkey is no longer included with CouchDB, but rather treated
as a normal external dependency. A simple C program (_couchjs) is
provided that links against an existing SpiderMonkey installation and
uses the interpreter embedding API.

• View functions using the default JavaScript view server can now do
logging using the global log(message) function. Log messages are di-
rected into the CouchDB log at INFO level. (COUCHDB-59)

• The global map(key, value) function made available to view code has
been renamed to emit(key, value).

• Fixed handling of exceptions raised by view functions.

HTTP Interface
• CouchDB now uses MochiWeb instead of inets for the HTTP server imple-
mentation. Among other things, this means that the extra configura-
tion files needed for inets (such as couch_httpd.conf) are no longer
used.

• The HTTP interface now completely supports the HEAD method. (-
COUCHDB-3)

• Improved compliance of Etag handling with the HTTP specification. (-
COUCHDB-13)

• Etags are no longer included in responses to document GET requests
that include query string parameters causing the JSON response to
change without the revision or the URI having changed.

• The bulk document update API has changed slightly on both the request
and the response side. In addition, bulk updates are now atomic.

• CouchDB now uses TCP_NODELAY to fix performance problems with persis-
tent connections on some platforms due to nagling.

• Including a ?descending=false query string parameter in requests to
views no longer raises an error.

• Requests to unknown top-level reserved URLs (anything with a leading
underscore) now return a unknown_private_path error instead of the
confusing illegal_database_name.

• The Temporary view handling now expects a JSON request body, where
the JSON is an object with at least a map member, and optional reduce
and language members.

• Temporary views no longer determine the view server based on the Con-
tent-Type header of the POST request, but rather by looking for a
language member in the JSON body of the request.

• The status code of responses to DELETE requests is now 200 to reflect
that that the deletion is performed synchronously.

SECURITY ISSUES / CVES
In the event of a CVE, the Apache CouchDB project will publish a fix as
a patch to the current release series and its immediate predecessor
only (e.g, if the current release is 3.3.3 and the predecessor is
3.2.3, we would publish a 3.3.4 release and a 3.2.4 release).

Further backports may be published at our discretion.

CVE-2010-0009: Apache CouchDB Timing Attack Vulnerability
Date 31.03.2010

Affected
Apache CouchDB 0.8.0 to 0.10.1

Severity
Important

Vendor The Apache Software Foundation

Description
Apache CouchDB versions prior to version 0.11.0 are vulnerable to tim-
ing attacks, also known as side-channel information leakage, due to us-
ing simple break-on-inequality string comparisons when verifying hashes
and passwords.

Mitigation
All users should upgrade to CouchDB 0.11.0. Upgrades from the 0.10.x
series should be seamless. Users on earlier versions should consult
with upgrade notes.

Example
A canonical description of the attack can be found in -
http://codahale.com/a-lesson-in-timing-attacks/

Credit
This issue was discovered by Jason Davies of the Apache CouchDB devel-
opment team.

CVE-2010-2234: Apache CouchDB Cross Site Request Forgery Attack
Date 21.02.2010

Affected
Apache CouchDB 0.8.0 to 0.11.1

Severity
Important

Vendor The Apache Software Foundation

Description
Apache CouchDB versions prior to version 0.11.1 are vulnerable to Cross
Site Request Forgery (CSRF) attacks.

Mitigation
All users should upgrade to CouchDB 0.11.2 or 1.0.1.

Upgrades from the 0.11.x and 0.10.x series should be seamless.

Users on earlier versions should consult with upgrade notes.

Example
A malicious website can POST arbitrary JavaScript code to well known
CouchDB installation URLs (like http://localhost:5984/) and make the
browser execute the injected JavaScript in the security context of
CouchDBs admin interface Futon.

Unrelated, but in addition the JSONP API has been turned off by default
to avoid potential information leakage.

Credit
This CSRF issue was discovered by a source that wishes to stay anony-
mous.

CVE-2010-3854: Apache CouchDB Cross Site Scripting Issue
Date 28.01.2011

Affected
Apache CouchDB 0.8.0 to 1.0.1

Severity
Important

Vendor The Apache Software Foundation

Description
Apache CouchDB versions prior to version 1.0.2 are vulnerable to Cross
Site Scripting (XSS) attacks.

Mitigation
All users should upgrade to CouchDB 1.0.2.

Upgrades from the 0.11.x and 0.10.x series should be seamless.

Users on earlier versions should consult with upgrade notes.

Example
Due to inadequate validation of request parameters and cookie data in
Futon, CouchDBs web-based administration UI, a malicious site can exe-
cute arbitrary code in the context of a users browsing session.

Credit
This XSS issue was discovered by a source that wishes to stay anony-
mous.

CVE-2012-5641: Information disclosure via unescaped backslashes in URLs on
Windows
Date 14.01.2013

Affected
All Windows-based releases of Apache CouchDB, up to and includ-
ing 1.0.3, 1.1.1, and 1.2.0 are vulnerable.

Severity
Moderate

Vendor The Apache Software Foundation

Description
A specially crafted request could be used to access content directly
that would otherwise be protected by inbuilt CouchDB security mecha-
nisms. This request could retrieve in binary form any CouchDB database,
including the _users or _replication databases, or any other file that
the user account used to run CouchDB might have read access to on the
local filesystem. This exploit is due to a vulnerability in the in-
cluded MochiWeb HTTP library.

Mitigation
Upgrade to a supported CouchDB release that includes this fix, such as:

• 1.0.4

• 1.1.2

• 1.2.1

• 1.3.x

All listed releases have included a specific fix for the MochiWeb com-
ponent.

Work-Around
Users may simply exclude any file-based web serving components directly
within their configuration file, typically in local.ini. On a default
CouchDB installation, this requires amending the httpd_global_han-
dlers/favicon.ico and httpd_global_handlers/_utils lines within
httpd_global_handlers:

[httpd_global_handlers]
favicon.ico = {couch_httpd_misc_handlers, handle_welcome_req, <<"Forbidden">>}
_utils = {couch_httpd_misc_handlers, handle_welcome_req, <<"Forbidden">>}

If additional handlers have been added, such as to support Adobes Flash
crossdomain.xml files, these would also need to be excluded.

Acknowledgement
The issue was found and reported by Sriram Melkote to the upstream
MochiWeb project.

References
• https://github.com/melkote/mochiweb/commit/ac2bf

CVE-2012-5649: JSONP arbitrary code execution with Adobe Flash
Date 14.01.2013

Affected
Releases up to and including 1.0.3, 1.1.1, and 1.2.0 are vulner-
able, if administrators have enabled JSONP.

Severity
Moderate

Vendor The Apache Software Foundation

Description
A hand-crafted JSONP callback and response can be used to run arbitrary
code inside client-side browsers via Adobe Flash.

Mitigation
Upgrade to a supported CouchDB release that includes this fix, such as:

• 1.0.4

• 1.1.2

• 1.2.1

• 1.3.x

All listed releases have included a specific fix.

Work-Around
Disable JSONP or dont enable it since its disabled by default.

CVE-2012-5650: DOM based Cross-Site Scripting via Futon UI
Date 14.01.2013

Affected
Apache CouchDB releases up to and including 1.0.3, 1.1.1, and
1.2.0 are vulnerable.

Severity
Moderate

Vendor The Apache Software Foundation

Description
Query parameters passed into the browser-based test suite are not sani-
tised, and can be used to load external resources. An attacker may exe-
cute JavaScript code in the browser, using the context of the remote
user.

Mitigation
Upgrade to a supported CouchDB release that includes this fix, such as:

• 1.0.4

• 1.1.2

• 1.2.1

• 1.3.x

All listed releases have included a specific fix.

Work-Around
Disable the Futon user interface completely, by adapting local.ini and
restarting CouchDB:

[httpd_global_handlers]
_utils = {couch_httpd_misc_handlers, handle_welcome_req, <<"Forbidden">>}

Or by removing the UI test suite components:

• share/www/verify_install.html

• share/www/couch_tests.html

• share/www/custom_test.html

Acknowledgement
This vulnerability was discovered & reported to the Apache Software
Foundation by Frederik Braun.

CVE-2014-2668: DoS (CPU and memory consumption) via the count parameter to
/_uuids
Date 26.03.2014

Affected
Apache CouchDB releases up to and including 1.3.1, 1.4.0, and
1.5.0 are vulnerable.

Severity
Moderate

Vendor The Apache Software Foundation

Description
The /_uuids resources count query parameter is able to take unreason-
able huge numeric value which leads to exhaustion of server resources
(CPU and memory) and to DoS as the result.

Mitigation
Upgrade to a supported CouchDB release that includes this fix, such as:

• 1.5.1

• 1.6.0

All listed releases have included a specific fix to

Work-Around
Disable the /_uuids handler completely, by adapting local.ini and
restarting CouchDB:

[httpd_global_handlers]
_uuids =

CVE-2017-12635: Apache CouchDB Remote Privilege Escalation
Date 14.11.2017

Affected
All Versions of Apache CouchDB

Severity
Critical

Vendor The Apache Software Foundation

Description
Due to differences in CouchDBs Erlang-based JSON parser and
JavaScript-based JSON parser, it is possible to submit _users documents
with duplicate keys for roles used for access control within the data-
base, including the special case _admin role, that denotes administra-
tive users. In combination with CVE-2017-12636 (Remote Code Execution),
this can be used to give non-admin users access to arbitrary shell com-
mands on the server as the database system user.

Mitigation
All users should upgrade to CouchDB 1.7.1 or 2.1.1.

Upgrades from previous 1.x and 2.x versions in the same series should
be seamless.

Users on earlier versions, or users upgrading from 1.x to 2.x should
consult with upgrade notes.

Example
The JSON parser differences result in behaviour that if two roles keys
are available in the JSON, the second one will be used for authorising
the document write, but the first roles key is used for subsequent au-
thorisation for the newly created user. By design, users can not assign
themselves roles. The vulnerability allows non-admin users to give
themselves admin privileges.

We addressed this issue by updating the way CouchDB parses JSON in Er-
lang, mimicking the JavaScript behaviour of picking the last key, if
duplicates exist.

Credit
This issue was discovered by Max Justicz.

CVE-2017-12636: Apache CouchDB Remote Code Execution
Date 14.11.2017

Affected
All Versions of Apache CouchDB

Severity
Critical

Vendor The Apache Software Foundation

Description
CouchDB administrative users can configure the database server via
HTTP(S). Some of the configuration options include paths for operating
system-level binaries that are subsequently launched by CouchDB. This
allows a CouchDB admin user to execute arbitrary shell commands as the
CouchDB user, including downloading and executing scripts from the pub-
lic internet.

Mitigation
All users should upgrade to CouchDB 1.7.1 or 2.1.1.

Upgrades from previous 1.x and 2.x versions in the same series should
be seamless.

Users on earlier versions, or users upgrading from 1.x to 2.x should
consult with upgrade notes.

Credit
This issue was discovered by Joan Touzet of the CouchDB Security team
during the investigation of CVE-2017-12635.

CVE-2018-11769: Apache CouchDB Remote Code Execution
Date 08.08.2018

Affected
Apache CouchDB 1.x and 2.1.2

Severity
Low

Vendor The Apache Software Foundation

Description
CouchDB administrative users can configure the database server via
HTTP(S). Due to insufficient validation of administrator-supplied con-
figuration settings via the HTTP API, it is possible for a CouchDB ad-
ministrator user to escalate their privileges to that of the operating
systems user under which CouchDB runs, by bypassing the blacklist of
configuration settings that are not allowed to be modified via the HTTP
API.

This privilege escalation effectively allows a CouchDB admin user to
gain arbitrary remote code execution, bypassing mitigations for
CVE-2017-12636 and CVE-2018-8007.

Mitigation
All users should upgrade to CouchDB 2.2.0.

Upgrades from previous 2.x versions in the same series should be seam-
less.

Users still on CouchDB 1.x should be advised that the Apache CouchDB
team no longer support 1.x.

In-place mitigation (on any 1.x release, or 2.x prior to 2.2.0) is pos-
sible by removing the _config route from the default.ini file, as fol-
lows:

[httpd_global_handlers]
;_config = {couch_httpd_misc_handlers, handle_config_req}

or by blocking access to the /_config (1.x) or /_node/*/_config routes
at a reverse proxy in front of the service.

CVE-2018-17188: Apache CouchDB Remote Privilege Escalations
Date 17.12.2018

Affected
All Versions of Apache CouchDB

Severity
Medium

Vendor The Apache Software Foundation

Description
Prior to CouchDB version 2.3.0, CouchDB allowed for runtime-configura-
tion of key components of the database. In some cases, this led to vul-
nerabilities where CouchDB admin users could access the underlying op-
erating system as the CouchDB user. Together with other vulnerabili-
ties, it allowed full system entry for unauthenticated users.

These vulnerabilities were fixed and disclosed in the following CVE re-
ports:

• CVE-2018-11769: Apache CouchDB Remote Code Execution

• CVE-2018-8007: Apache CouchDB Remote Code Execution

• CVE-2017-12636: Apache CouchDB Remote Code Execution

• CVE-2017-12635: Apache CouchDB Remote Privilege Escalation

Rather than waiting for new vulnerabilities to be discovered, and fix-
ing them as they come up, the CouchDB development team decided to make
changes to avoid this entire class of vulnerabilities.

With CouchDB version 2.3.0, CouchDB no longer can configure key compo-
nents at runtime. While some flexibility is needed for speciality con-
figurations of CouchDB, the configuration was changed from being avail-
able at runtime to start-up time. And as such now requires shell access
to the CouchDB server.

This closes all future paths for vulnerabilities of this type.

Mitigation
All users should upgrade to CouchDB 2.3.0.

Upgrades from previous 2.x versions in the same series should be seam-
less.

Users on earlier versions should consult with upgrade notes.

Credit
This issue was discovered by the Apple Information Security team.

CVE-2018-8007: Apache CouchDB Remote Code Execution
Date 30.04.2018

Affected
All Versions of Apache CouchDB

Severity
Low

Vendor The Apache Software Foundation

Description
CouchDB administrative users can configure the database server via
HTTP(S). Due to insufficient validation of administrator-supplied con-
figuration settings via the HTTP API, it is possible for a CouchDB ad-
ministrator user to escalate their privileges to that of the operating
systems user that CouchDB runs under, by bypassing the backlist of con-
figuration settings that are not allowed to be modified via the HTTP
API.

This privilege escalation effectively allows a CouchDB admin user to
gain arbitrary remote code execution, bypassing CVE-2017-12636

Mitigation
All users should upgrade to CouchDB 1.7.2 or 2.1.2.

Upgrades from previous 1.x and 2.x versions in the same series should
be seamless.

Users on earlier versions, or users upgrading from 1.x to 2.x should
consult with upgrade notes.

Credit
This issue was discovered by Francesco Oddo of MDSec Labs.

CVE-2020-1955: Apache CouchDB Remote Privilege Escalation
Date 19.05.2020

Affected
3.0.0

Severity
Medium

Vendor The Apache Software Foundation

Description
CouchDB version 3.0.0 shipped with a new configuration setting that
governs access control to the entire database server called re-
quire_valid_user_except_for_up. It was meant as an extension to the
long-standing setting require_valid_user, which in turn requires that
any and all requests to CouchDB will have to be made with valid creden-
tials, effectively forbidding any anonymous requests.

The new require_valid_user_except_for_up is an off-by-default setting
that was meant to allow requiring valid credentials for all endpoints
except for the /_up endpoint.

However, the implementation of this made an error that led to not en-
forcing credentials on any endpoint, when enabled.

CouchDB versions 3.0.1 and 3.1.0 fix this issue.

Mitigation
Users who have not enabled require_valid_user_except_for_up are not af-
fected.

Users who have it enabled can either disable it again, or upgrade to
CouchDB versions 3.0.1 and 3.1.0

Credit
This issue was discovered by Stefan Klein.

CVE-2021-38295: Apache CouchDB Privilege Escalation
Date 12.10.2021

Affected
3.1.1 and below

Severity
Low

Vendor The Apache Software Foundation

Description
A malicious user with permission to create documents in a database is
able to attach a HTML attachment to a document. If a CouchDB admin
opens that attachment in a browser, e.g. via the CouchDB admin inter-
face Fauxton, any JavaScript code embedded in that HTML attachment will
be executed within the security context of that admin. A similar route
is available with the already deprecated _show and _list functionality.

This privilege escalation vulnerability allows an attacker to add or
remove data in any database or make configuration changes.

Mitigation
CouchDB 3.2.0 and onwards adds Content-Security-Policy headers for all
attachment, _show and _list requests. This breaks certain niche
use-cases and there are configuration options to restore the previous
behaviour for those who need it.

CouchDB 3.1.2 defaults to the previous behaviour, but adds configura-
tion options to turn Content-Security-Policy headers on for all af-
fected requests.

Credit
This issue was identified by Cory Sabol of Secure Ideas.

CVE-2022-24706: Apache CouchDB Remote Privilege Escalation
Date 25.04.2022

Affected
3.2.1 and below

Severity
Critical

Vendor The Apache Software Foundation

Description
An attacker can access an improperly secured default installation with-
out authenticating and gain admin privileges.

1. CouchDB opens a random network port, bound to all available inter-
faces in anticipation of clustered operation and/or runtime intro-
spection. A utility process called epmd advertises that random port
to the network. epmd itself listens on a fixed port.

2. CouchDB packaging previously chose a default cookie value for sin-
gle-node as well as clustered installations. That cookie authenti-
cates any communication between Erlang nodes.

The CouchDB documentation has always made recommendations for properly
securing an installation, but not all users follow the advice.

We recommend a firewall in front of all CouchDB installations. The full
CouchDB api is available on registered port 5984 and this is the only
port that needs to be exposed for a single-node install. Installations
that do not expose the separate distribution port to external access
are not vulnerable.

Mitigation
CouchDB 3.2.2 and onwards will refuse to start with the former default
erlang cookie value of monster. Installations that upgrade to this ver-
sions are forced to choose a different value.

In addition, all binary packages have been updated to bind epmd as well
as the CouchDB distribution port to 127.0.0.1 and/or ::1 respectively.

Credit
This issue was identified by Alex Vandiver.

CVE-2023-26268: Apache CouchDB: Information sharing via couchjs processes
Date 02.05.2023

Affected
3.3.1 and below, 3.2.2 and below

Severity
Medium

Vendor The Apache Software Foundation

Description
Design documents with matching document IDs, from databases on the same
cluster, may share a mutable Javascript environment when using these
design document functions:

• validate_doc_update

• list

• filter

• filter views (using view functions as filters)

• rewrite

• update

This doesnt affect map/reduce or search (Dreyfus) index functions.

Mitigation
CouchDB 3.3.2 and 3.2.3 and onwards matches Javascript execution
processes by database names in addition to design document IDs when
processing the affected design document functions.

Workarounds
Avoid using design documents from untrusted sources which may attempt
to cache or store data in the Javascript environment.

Credit
This issue was identified by Nick Vatamaniuc

CVE-2023-45725: Apache CouchDB: Privilege Escalation Using Design Documents

Date 12.12.2023

Affected
3.3.2 and below

Severity
Medium

Vendor The Apache Software Foundation

Description
Design document functions which receive a user http request object may
expose authorization or session cookie headers of the user who accesses
the document.

These design document functions are:

• list

• show

• rewrite

• update

An attacker can leak the session component using an HTML-like output,
insert the session as an external resource (such as an image), or store
the credential in a _local document with an update function.

For the attack to succeed the attacker has to be able to insert the de-
sign documents into the database, then manipulate a user to access a
function from that design document.

Mitigation
CouchDB 3.3.3 scrubs the sensitive headers from http request objects
passed to the query server execution environment.

For versions older than 3.3.3 this patch applied to the loop.js file
would also mitigate the issue:

diff --git a/share/server/loop.js b/share/server/loop.js
--- a/share/server/loop.js
+++ b/share/server/loop.js
@@ -49,6 +49,20 @@ function create_nouveau_sandbox() {
return sandbox;
}

+function scrubReq(args) {
+ var req = args.pop()
+ if (req.method && req.headers && req.peer && req.userCtx) {
+ delete req.cookie
+ for (var p in req.headers) {
+ if (req.headers.hasOwnProperty(p) && ["authorization", "cookie"].indexOf(p.toLowerCase()) !== -1) {
+ delete req.headers[p]
+ }
+ }
+ }
+ args.push(req)
+ return args
+}
+
// Commands are in the form of json arrays:
// ["commandname",..optional args...]\n
//
@@ -85,7 +99,7 @@ var DDoc = (function() {
var funPath = args.shift();
var cmd = funPath[0];
// the first member of the fun path determines the type of operation
- var funArgs = args.shift();
+ var funArgs = scrubReq(args.shift());
if (ddoc_dispatch[cmd]) {
// get the function, call the command with it
var point = ddoc;

Workarounds
Avoid using design documents from untrusted sources which may attempt
to access or manipulate request objects headers.

Credit
This issue was found by Natan Nehorai and reported by Or Peles from the
JFrog Vulnerability Research Team.

It was also independently found by Richard Ellis and Mike Rhodes from
IBM/Cloudant.

REPORTING NEW SECURITY PROBLEMS WITH APACHE COUCHDB
The Apache Software Foundation takes a very active stance in eliminat-
ing security problems and denial of service attacks against Apache
CouchDB.

We strongly encourage folks to report such problems to our private se-
curity mailing list first, before disclosing them in a public forum.

Please note that the security mailing list should only be used for re-
porting undisclosed security vulnerabilities in Apache CouchDB and man-
aging the process of fixing such vulnerabilities. We cannot accept reg-
ular bug reports or other queries at this address. All mail sent to
this address that does not relate to an undisclosed security problem in
the Apache CouchDB source code will be ignored.

If you need to report a bug that isnt an undisclosed security vulnera-
bility, please use the bug reporting page.

Questions about:

• How to configure CouchDB securely

• If a vulnerability applies to your particular application

• Obtaining further information on a published vulnerability

• Availability of patches and/or new releases

should be address to the users mailing list. Please see the mailing
lists page for details of how to subscribe.

The private security mailing address is: security@couchdb.apache.org

Please read how the Apache Software Foundation handles security reports
to know what to expect.

Note that all networked servers are subject to denial of service at-
tacks, and we cannot promise magic workarounds to generic problems
(such as a client streaming lots of data to your server, or re-request-
ing the same URL repeatedly). In general our philosophy is to avoid any
attacks which can cause the server to consume resources in a non-linear
relationship to the size of inputs.

ABOUT COUCHDB DOCUMENTATION
License
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.

"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:

(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and

(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.

You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.

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.

CONTRIBUTING TO THIS DOCUMENTATION
The documentation lives in its own source tree. Well start by forking
and cloning the CouchDB documentation GitHub mirror. That will allow us
to send the contribution to CouchDB with a pull request.

If you dont have a GitHub account yet, it is a good time to get one,
they are free. If you dont want to use GitHub, there are alternate ways
to contributing back, that well cover next time.

Go to https://github.com/apache/couchdb and click the fork button in
the top right. This will create a fork of CouchDB in your GitHub ac-
count. If your account is username, your fork lives at -
https://github.com/username/couchdb. In the header, it tells me my
GitHub Clone URL. We need to copy that and start a terminal:

$ git clone https://github.com/username/couchdb.git
$ cd couchdb/src/docs
$ subl .

Im opening the whole CouchDB documentation source tree in my favourite
editor. It gives me the usual directory listing:

ebin/
ext/
.git/
.gitignore
images/
LICENSE
make.bat
Makefile
NOTICE
rebar.config
src/
static/
templates/
themes/
.travis.yml

The documentation sources live in src/docs/src, you can safely ignore
all the other files and directories.

First we should determine where we want to document this inside the
documentation. We can look through http://docs.couchdb.org/en/latest/
for inspiration. The JSON Structure Reference looks like a fine place
to write this up.

The current state includes mostly tables describing the JSON structure
(after all, thats the title of this chapter), but some prose about the
number representation cant hurt. For future reference, since the topic
in the thread includes views and different encoding in views (as op-
posed to the storage engine), we should remember to make a note in the
views documentation as well, but well leave this for later.

Lets try and find the source file that builds the file -
http://docs.couchdb.org/en/latest/json-structure.html we are in luck,
under share/doc/src we find the file json-structure.rst. That looks
promising. .rst stands for ReStructured Text (see -
http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html for a
markup reference), which is an ASCII format for writing documents, doc-
umentation in this case. Lets have a look and open it.

We see ASCII tables with some additional formatting, all looking like
the final HTML. So far so easy. For now, lets just add to the bottom of
this. We can worry about organising this better later.

We start by adding a new headline:

Number Handling
===============

Now we paste in the rest of the main email of the thread. It is mostly
text, but it includes some code listings. Lets mark them up. Well turn:

ejson:encode(ejson:decode(<<"1.1">>)).
<<"1.1000000000000000888">>

Into:

.. code-block:: erlang

ejson:encode(ejson:decode(<<"1.1">>)).
<<"1.1000000000000000888">>

And we follow along with the other code samples. We turn:

Spidermonkey

into:

Spidermonkey::

And then follow all the other ones.

I cleaned up the text a little but to make it sound more like a docu-
mentation entry as opposed to a post on a mailing list.

The next step would be to validate that we got all the markup right.
Ill leave this for later. For now well contribute our change back to
CouchDB.

First, we commit our changes:

$ > git commit -am 'document number encoding'
[main a84b2cf] document number encoding
1 file changed, 199 insertions(+)

Then we push the commit to our CouchDB fork:

$ git push origin main

Next, we go back to our GitHub page https://github.com/username/couchdb
and click the Pull Request button. Fill in the description with some-
thing useful and hit the Send Pull Request button.

And were done!

Style Guidelines for this Documentation
When you make a change to the documentation, you should make sure that
you follow the style. Look through some files and you will see that the
style is quite straightforward. If you do not know if your formatting
is in compliance with the style, ask yourself the following question:

Is it needed for correct syntax?

If the answer is No. then it is probably not.

These guidelines strive be simple, without contradictions and excep-
tions. The best style is the one that is followed because it seems to
be the natural way of doing it.

The guidelines
The guidelines are in descending priority.

1. Syntax

• Correct syntax is always more important than style. This includes
configuration files, HTML responses, etc.

2. Encoding

• All files are UTF-8.

3. Line ending

• All lines end with \n.

• No trailing whitespace.

4. Line length

• The maximum line length is 90 characters.

5. Links

• All internal links are relative.

6. Indentation

• 4 spaces.

7. Titles

• The highest level titles in a file is over and underlined with =.

• Lower level titles are underlined with the following characters in
descending order:

= - ^ * + # ` : . " ~ _

• Over and underline match the title length.

8. Empty lines

• No empty line at the end of the file.

• Lists may separated each item with an empty line.

AUTHOR
Author name not set

3.5 Nov 06, 2025 APACHECOUCHDB(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=apachecouchdb&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages