apachecouchdb(1) - FreeBSD Ports 15.1.quarterly Manual Pages

home | help

APACHECOUCHDB(1) Apache CouchDBA(R) APACHECOUCHDB(1)

NAME
apachecouchdb - Apache CouchDBA(R) 3.5.2

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, effi-
ciently using CouchDBas incremental replication. CouchDB supports mas-
ter-master setups with automatic conflict detection.

CouchDB comes with a suite of features, such as on-the-fly document trans-
formation and real-time change notifications, that make web development 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 tolerant, but is also eventually
consistent. And we care a lot about your data. CouchDB has a fault-toler-
ant storage engine that puts the safety of your data first.

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

Technical Overview
Document Storage
A CouchDB server hosts named databases, which store documents. Each docu-
ment 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 thatas main-
tained by the database system. Document fields are uniquely named and con-
tain 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 ed-
its are made by client applications loading documents, applying changes,
and saving them back to the database. If another client editing 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 suc-
ceeding entirely or failing completely. The database never contains par-
tially saved or edited documents.

ACID Properties
The CouchDB file layout and commitment system features all Atomic Consis-
tent Isolated Durable (ACID) properties. On-disk, CouchDB never overwrites
committed data or associated structures, ensuring the database file is al-
ways in a consistent state. This is a acrash-onlya design where the CouchDB
server does not go through a shut down process, itas 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 interrupted by concur-
rent 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 beginning to the end of the
read operation. This means that CouchDB can guarantee transactional seman-
tics 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 number. Se-
quence IDs are used later for incrementally finding changes in a database.
These B-tree indexes are updated simultaneously when documents 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 packaged
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 an-
other (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 partially
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 previously commit-
ted 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 entire time and all up-
dates and reads are allowed to complete successfully. The old database file
is deleted only when all the data has been copied and all users transi-
tioned 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 data-
bases 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 a it simply
doesnat 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 hasnat been decomposed into ta-
bles.

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 a View Head Information

* req a 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 youall 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 a The document that is being processed.

* req a 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 data-
base. If you are updating an existing document, it should
already have an _id set, and if you are creating a new docu-
ment, make sure to set its _id to something, either generated
based on the input or the req.uuid provided. The second ele-
ment 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 al-
lows a range of use cases such as providing a server-side last modified
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 update handler
function via the POST/PUT entity body or query string parameters of the re-
quest.

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 a The document that is being processed

* req a 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
youare waiting for some special changes, processing all documents is inef-
ficient.

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

Letas 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 anew mailsa:

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 havenat passed our
filter.

We probably need to filter the changes feed of our mailbox by more than a
single status value. Weare also interested in statuses like aspama to up-
date spam-filter heuristic rules, aoutgoinga to let a mail daemon actually
send mails, and so on. Creating a lot of similar functions that actually do
similar work isnat 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 parame-
ters, 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 differ-
ence: 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 func-
tion, a change is returned. This allows avoiding filter functions that
mostly do the same work as views.

To use them just pass filter=_view and view=designdoc/viewname as request
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 canat show any dy-
namic 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 a New version of document that will be stored.

* oldDoc a Previous version of document that is already
stored.

* userCtx a User Context Object

* secObj a 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 security roles.

Validation functions typically examine the structure of the new document to
ensure that required fields are present and to verify that the requesting
user should be allowed to make changes to the document properties. For ex-
ample, an application may require that a user must be authenticated in or-
der to create a new document or that specific document fields be present
when a document is updated. The validation function 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 database
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 docu-
ments. There youall learn how they work and how to use them to build ef-
fective applications with CouchDB.

Introduction to Views
Views are useful for many purposes:

* Filtering the documents in your database to find those relevant to a par-
ticular process.

* Extracting data from your documents and presenting it in a specific or-
der.

* Building efficient indexes to find documents by any value or structure
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 companyas finan-
cial transactions, a view can answer the question of what the spending
was in the last week, month, or year.

What Is a View?
Letas 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. Weall 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 a_ida,
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 fa-
miliar 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 defin-
ition.

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 donat run the JavaScript function yourself. Instead, when you query
your view, CouchDB takes the source code and runs it for you on every docu-
ment in the database your view was defined in. You query your view to re-
trieve 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 document in
the database. Our map function checks whether our document has a date and a
title attribute a luckily, all of our documents have them a 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 multiple times in
the map function to create multiple entries in the view results from a sin-
gle 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, aView resultsa 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 |
+-----------------------+----------------+
| a2009/01/15 15:52:20a | aHello Worlda |
+-----------------------+----------------+
| a2009/01/30 18:04:11a | aBikinga |
+-----------------------+----------------+
| a2009/02/17 21:13:39a | aBought a Cata |
+-----------------------+----------------+

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 horribly inef-
ficient 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 document.

The view result is stored in a B-tree, just like the structure that is re-
sponsible 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 sin-
gle view can answer all questions that involve time: aGive me all the blog
posts from last weeka or alast montha or athis year.a 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 result. 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 doesnat include any
superfluous whitespace or newlines, but this is better for you (and us!)
to read and understand. Where does that aida member in the result rows come
from? That wasnat there before. Thatas because we omitted it earlier to
avoid confusion. CouchDB automatically includes the document ID of the doc-
ument that created the entry in the view result. Weall 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 youare sure you know you want it. This stores an entire
additional copy of your document in the viewas 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 ?include_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
Letas move on to the second use case for views: abuilding efficient indexes
to find documents by any value or structure that resides in them.a We al-
ready explained the efficient indexing, but we skipped a few details. 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 executing 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, weare good a 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 resulting 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 efficient 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 docu-
ments are updated between view queries. The mechanism explained in the pre-
vious 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 resources.

Find One
On to more complex map functions. We said afind documents by any value or
structure that resides in them.a 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 viewas result is /data-
base/_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/_de-
sign/docs/_view/by_date?key="2009/01/30 18:04:11" to get the aBikinga 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 a and fast.

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

Find Many
We talked about agetting all posts for last month.a If itas 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] | aHello Worlda |
+---------------------------+----------------+
| [2009, 2, 17, 21, 13, 39] | aBikinga |
+---------------------------+----------------+
| [2009, 1, 30, 18, 4, 11] | aBought a Cata |
+---------------------------+----------------+

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 structures
as keys for your views. Say we tag our documents with a list of tags and
want to see all tags, but we donat 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 example
of how a map function calls emit() multiple times per document. And fi-
nally, you can pass null instead of a value to the value parameter. The
same is true for the key parameter. Weall 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. Whatas up with that?

Itas pretty easy to understand when you see how view query options work un-
der the hood. A view is stored in a tree structure for fast lookups. When-
ever you query a view, this is how CouchDB operates:

1. Starts reading at the top, or at the position that startkey specifies,
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 proce-
dure is followed.

Say you have a view result that looks like this:
+-----+-------+
| Key | Value |
+-----+-------+
| 0 | afooa |
+-----+-------+
| 1 | abara |
+-----+-------+
| 2 | abaza |
+-----+-------+

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 | abara |
+-----+-------+
| 0 | afooa |
+-----+-------+

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: end-
key=1&descending=true:
+-----+-------+
| Key | Value |
+-----+-------+
| 2 | abaza |
+-----+-------+
| 1 | abara |
+-----+-------+

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 parameter.
CouchDBas 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 arbi-
trary key ranges in logarithmic time. See Figure 1, aComments map func-
tiona.

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 youad 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 doesnat 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 CouchDBas incremental MapReduce system.

Anyway, with a group_level query, youare basically running a series of
reduce range queries: one for each group that shows up at the level you
query. Letas 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.
Weall explain whatas up with it in this section. By now, you should have
learned that your view result is stored in B-tree index structure for effi-
ciency. 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, aThe B-tree indexa 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 apre-ordera 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, weare 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.
Whatas important is that CouchDB runs all elements that are within a node
into the reduce function (setting the rereduce parameter to false) and
stores the result inside the parent node along with the edge to the subn-
ode. 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 com-
putes the result for all the elements in multiple iterations over the
elements in a single node, not all at once (which would be disastrous
for memory consumption).

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

CouchDB detects that all values in the subnode include the achinesea 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 itas 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 achinesea elementas value and the other nodeas
value and run them through the reduce function with the rereduce parame-
ter set to true.

The reduce function effectively calculates 3 + 1 at query time and re-
turns 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 donat reduce
your values. Consider the following map result and reduce function. 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 donat 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, aAn overflowing reduce indexa.

We hope you get the picture. The way the B-tree storage works means that if
you donat actually reduce your data in the reduce function, you end up hav-
ing CouchDB copy huge amounts of data around that grow linearly, 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 values.
[image: An overflowing reduce index] [image] Figure 4. An overflowing re-
duce index.UNINDENT

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

Each view you create corresponds to one B-tree. All views in a single de-
sign 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 docu-
ments 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
viewsa indexes when the design document is written, forcing them all to re-
build 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 functions
(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 aback refsa 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 (overloading the CPU
on your servers). The exact situation will depend on your deployment archi-
tecture.

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

Lessons Learned
* If you donat use the key field in the map function, you are probably do-
ing 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 donat 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 effectafree functions that take a document as argu-
ment and emit key/value pairs. CouchDB stores the emitted rows by con-
structing a sorted B-tree index, so row lookups by key, as well as stream-
ing operations across a range of rows, can be accomplished in a small mem-
ory and processing footprint, while writes avoid seeks. Generating 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 functions.
CouchDBas 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 calculate
the final reduce value. The end result is a reduce function that can be in-
crementally 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 func-
tionas third parameter, rereduce, is false. The arguments in this case are
the keys and values as output by the map function. The function has a sin-
gle returned reduction value, which is stored on the inner 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 func-
tion are intermediate reduction values as cached from previous calcula-
tions. When the tree is more than two levels deep, the rereduce phase is
repeated, consuming chunks of the previous levelas output until the final
reduce value is calculated at the root node.

A common mistake new CouchDB users make is attempting to construct complex
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
youall 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 in-
stance, to find the total, average, and standard deviation of a set of num-
bers in a single function.

If youare interested in pushing the edge of CouchDBas incremental reduce
functionality, have a look at Google^as paper on Sawzall, which gives exam-
ples 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 documents.
The key is composed of a customer _id and a sorting token. Because the key
for order documents begins with the _id of a customer document, all the or-
ders will be sorted by customer. Because the sorting token for customers is
lower than the token for orders, the customer 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 customeras or-
ders, limit the startkey and endkey ranges to cover only documents for that
customeras _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, request 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 fol-
lowing 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.created_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 Colla-
tion Algorithm, giving a dictionary sorting of keys. This can give sur-
prising results if you were expecting ASCII ordering. Note that:

* All symbols sort before numbers and letters (even the ahigha 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 aABCa and aabc1a, but not aabca. 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 afooa in the first element, such as ["foo","bar"] and
["foo",["bar","baz"]]. However it will not match ["foo",{"an":"object"}]

_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 ^aZ^a comes before ^aa^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 Erlang
collation, especially if you donat require UCA. This gives a different col-
lation sequence:

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

Beware that {} is no longer a suitable ahigha 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 document.
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 hasnat changed. To force a specific revision of a linked docu-
ment 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 youad go about modeling a
simple blogging system with aposta and acommenta entities, where any blog
post might have N comments. If youad be using an SQL database, youad obvi-
ously have two tables with foreign keys and youad be using joins. (At least
until you needed to add some denormalization).

But what would the aobviousa 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 a|",
"comments": [
{"author": "jack", "content": "a|"},
{"author": "jane", "content": "a|"}
]
}

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

The obvious advantage of this approach is that the data that belongs to-
gether 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 document
would not allow us to query for the comments themselves, but youad be
wrong. You could trivially write a CouchDB view that would return all com-
ments 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
(thatas optimistic concurrency in action). For some applications this makes
sense, but in many other apps, youad want to append new related data re-
gardless 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 youad have one document per blog post, and one document
per comment. The comment documents would have a abacklinka to the post they
belong to.

The blog post document would look similar to the above, minus the comments
property. Also, wead 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 a|"
}

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

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

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

To list all comments per blog post, youad 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 youad invoke that view passing it a ?key="post_id" query string parame-
ter.

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. Imagine
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 request 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: youad now need an additional fetch per comment. What
wead probably want then would be a way to join the blog post and the vari-
ous comments together to be able to retrieve them with a single HTTP re-
quest.

This was when Damien Katz, the author of CouchDB, chimed in to the discus-
sion 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: itas fairly
simple to make a view that includes both the content of the blog post docu-
ment, and the content of all the comments associated with that post. The
way you do that is by using complex keys. Until now weave been using simple
string values for the view keys, but in fact they can be arbitrary JSON
values, so letas 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. Letas 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 ain-
vokea a view, you can say that youare only interested in a subset of the
view rows by specifying a ?key=foo query string parameter. Or you can spec-
ify ?startkey=foo and/or ?endkey=bar query string parameters to fetch rows
over a range of keys. Finally, by adding ?include_docs=true to the query,
the result will include the full body of each emitted document.

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

SEE ALSO:

* Homebrew

FreeBSD
FreeBSD requires the use of GNU Make. Where make is specified in this docu-
mentation, 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 environment
variable. Likewise, options may be passed to the linker with the ERL_LD-
FLAGS 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 development, 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 Appleas 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, avail-
able 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 useras 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" ...

Donat 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 reliably.
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, contact
the CouchDB user mailing list or IRC-channel #couchdb in FreeNode network.

Letas 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 systemas 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 necessary.

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

1. Get the latest Windows binaries from the CouchDB web site. Old releases
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. Itas time to Relax!

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

NOTE:
Upgrading note

Itas recommended to uninstall previous CouchDB version before upgrading,
especially if the new one is built against different Erlang release.
The reason is simple: there may be leftover libraries with alternative
or incompatible versions from old Erlang release that may create con-
flicts, 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 com-
mands, supporting the new features of the 3.0 installer.

Install CouchDB without a service, but with an admin user:password of ad-
min: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 debug-
ging.

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 appli-
cation. 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

Thatas 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 Home-
brew and all formulae and install CouchDB with the following commands:

brew update
brew install couchdb

Installation from source
Installation on macOS is possible from source. Download the source tarball,
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 reliably.
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 Collection:

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 FreeBSDas -
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 upgrades
and re-installs without warning. Therefore administrators should use de-
fault.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 instal-
lation happened. Make note of these instructions, although they can be
found in the ports tree for later reference.

Installation via Docker
Apache CouchDB provides aconvenience binarya Docker images through Docker
Hub at apache/couchdb. This is our upstream release; it is usually mirrored
downstream at Dockeras 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 everything
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 aconvenience binarya 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 youave 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) con-
figuration files will be stored in /var/snap/couchdb/current/etc.

NOTE:
Your installation is not complete. Follow the Setup steps for a single
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 refreshed
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 re-
moves couchdb and purges any backups.

When troubleshooting couchdb snap, check the logs first. Youall likely need
to inspect /var/snap/couchdb/current/etc/local.ini to verify the data di-
rectory or modify admin settings, port, or address bindings. Also, anything
related to Erlang runtime check /var/snap/couchdb/current/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 Kubernetes.

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 installed on
the same host as CouchDB and communicates with it over the loopback net-
work.

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 ver-
sion 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 un-
packed into a directory on the Java classpath. If you do not have a class-
path 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 conventionally
called clouseau.ini and log4j.properties with the following content:

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 invocation
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 install 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 val-
ues.

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

The source code for the plugin and additional configuration documentation
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 21 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 directory 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 seg-
ment 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 com-
monly 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 identity
of client and server.

Configuring CouchDB to authenticate to Nouveau
You can configure CouchDB to connect to a secured Nouveau server as fol-
lows;

[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 pass-
word-protected and might need to set ssl_cacert_file if the Nouveau
serveras 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 youare 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 available
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 run-
ning.

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 ver-
sion provided by the new release. New defaults sometimes contain manda-
tory changes to enable default functionality. Always places your cus-
tomizations 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+ re-
quire an admin user to start (the admin party has ended).

7. Start CouchDB.

8. Relax! Youare done.

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

Weare 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 function-
ality 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! Youare 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 doesnat start after youave just installed, check the fol-
lowing things:

* On UNIX-like systems, this is usually this is a permissions issue. Ensure
that youave followed the User Registration and Security chown/chmod com-
mands. 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 youall just have to
work it out for yourself. For example, on recent versions of Ubuntu/De-
bian, 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 in-
stalled.

* 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, letas 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:hash_init(sha).

%% 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:hash_init(sha).
#Ref<0.3087268666.1613103106.180459>
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 systemas Unicode sup-
port 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 ex-
ample 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:

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

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

* If you receive an error including the string:

a| OS Process Error a| {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 sim-
ple procedure and report back to the user mailing list or IRC with the out-
put 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 proces-
sor architecture.

2. Note down the installed versions of CouchDBas dependencies.

3. Follow the checkout instructions to get a fresh copy of CouchDBas 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 systemas kernel trace tool and log the output of the above com-
mand.

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 directory.
CouchDBas directory layout has changed and may be confused by libraries
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. Youave probably exceeded this.

There are two settings that need changing to increase this value. Consult
your OS documentation for how to increase the limit for your process. Under
Linux and systemd, this setting can be adjusted via systemctl 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 Er-
lang 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. Itas 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 erlang-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 de-
fault ulimit max files to unlimited. In those cases itas also recommended
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 ^aundefined^a value as JSON)
If you see this in the CouchDB error logs, the JavaScript code you are us-
ing for either a map or reduce function is referencing an object member
that is not defined in at least one document in your database. Consider
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 ad-
dress 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, itas worth bearing
JavaScriptas understanding of afalsea 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 !== un-
defined) 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 upgrade
of the relevant CouchDB and then compact prior to replicating.

Alternatively, if the number of documents impacted is small, use filtered
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 purposes.
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 aFIPS
mode,a which, among other restrictions, does not allow the use of OpenSSLas
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 function calls
with equivalent calls to Erlangas built-in library erlang:md5. NOTE: there
may be a performance penalty associated with this workaround.

Because CouchDB does not make use of MD5 hashes for cryptographic purposes,
this workaround does not defeat the purpose of aFIPS mode,a provided that
the system owner is aware of and consents to its use.

Debugging startup
If youave 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 information
that CouchDB developers can use to help you.

Then, reach out to the CouchDB development team using the links provided 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 configu-
ration. 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 doesnat 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 aSingle-Node-Se-
tupa, 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 donat 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 databases 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 us-
ing 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 con-
figuration. Port 5986, previously used in CouchDB 2.x, has been removed 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 clustered
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 con-
figuration.

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 firewall, but
it is possible to force an Erlang application to use a specific port range.

This documentation will use the range TCP 9100-9200, but this range is un-
necessarily broad. If you only have a single Erlang application running 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 development 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 defines
the name of the node. Each node must have an identifier that allows remote
systems to talk to it. The node name is of the form <name>@<reach-
able-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 a either the nodeas fully qualified domain name
(FQDN) or the nodeas IP address. The FQDN is preferred so that you can
renumber the nodeas IP address without disruption to the cluster. (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 ad-
dress or FQDN.

* -setcookie 'brumbrum' the apassworda 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 pe-
riod (.):

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 firewalls
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 youare 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 listening 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 be-
fore 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 nodeas 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 evalu-
ating cookie and proxy authentication, and should be set consistently 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, Puppet,
etc., then you can place these settings in a .ini file and distribute 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 com-
mands 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 cluster is
3. For more explanation, see the Cluster Theory section of this documenta-
tion.

After installation and initial start-up of all nodes in your cluster, en-
suring 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 aSetup Clustera 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 nodeas 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 aSetupa 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 sec-
tion 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 sin-
gle CouchDB cluster.

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

The Cluster Setup API
If you would prefer to manually configure your CouchDB cluster, CouchDB ex-
poses the _cluster_setup endpoint for that purpose. After installation 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
asetup coordination nodea to run all these commands on. This asetup coor-
dination nodea 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 follow-
ing 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 donat
match, use curl to add nodes with PUT /_node/_local/_nodes/couchdb@<reach-
able-ip-address|fully-qualified-domain-name> and remove nodes with DELETE
/_node/_local/_nodes/couchdb@<reachable-ip-address|fully-qualified-do-
main-name>

You CouchDB cluster is now set up.

CONFIGURATION
Introduction To Configuring
Configuration files
By default, CouchDB reads configuration files from the following locations,
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: Applica-
tions/Apache CouchDB.app/Contents/Resources/couchdbx-core/etc for the de-
fault.ini and default.d directories, and one of /Users/<your-user>/Li-
brary/Application Support/CouchDB2/etc/couchdb or /Users/<your-user>/Li-
brary/Preferences/couchdb2-local.ini for the local.ini and local.d directo-
ries.

Settings in successive documents override the settings in earlier entries.
For example, setting the chttpd/bind_address parameter in local.ini would
override any setting in default.ini.

WARNING:
The default.ini file may be overwritten during an upgrade or re-instal-
lation, 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 envi-
ronment 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 op-
tion specified in the etc/vm.args file. And, BOTH of these options com-
pletely override CouchDB from searching in the default locations. Use
these options only when necessary, and be sure to track the contents 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 exam-
ple, in different locations to the ones provided by CouchDB, or you donat
want to edit the original files, the default locations may be changed by
setting the COUCHDB_ARGS_FILE or COUCHDB_SYSCONFIG_FILE environment vari-
ables:

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 Erlang
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 (loca-
tion 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 specific
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 optional to im-
prove configuration readability.

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

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 requiring a
server restart:

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

The old parameteras value is returned in the response:

"sequential"

You should be careful changing configuration via the HTTP API since itas
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 updates
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 effect.

Configuring the local node
While the HTTP API allows configuring all nodes in the cluster, as a conve-
nience, you can use the literal string _local in place of the node name, to
interact with the local nodeas 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. How-
ever, 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 default).

[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 ad-
mins.

[couchdb]
default_security = admin_only

enable_database_recovery
Enable this to only asoft-deletea 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 algo-
rithm.

Method used to compress everything that is appended to data-
base 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/decom-
pressor

* deflate_N: use zlibas 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 re-
sponse.

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

* false: The node responds normally, /_up returns a 200 re-
sponse.

It is expected that the administrator has configured a load
balancer in front of the CouchDB nodes in the cluster. 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 appropriate:

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

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

[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 after
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 sim-
ply checking http request body sizes. For individual docu-
ment updates via PUT that approximation was close enough,
however that is not the case for _bulk_docs endpoint. Af-
ter 2.1.0 a separate configuration 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 accordingly.

os_process_timeout
If an external process, such as a query server or external
process, runs for this amount of milliseconds without return-
ing 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, automatically
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 access
this instance of CouchDB. It is used to help discover the
port CouchDB is running on (if it was set to 0 (e.g. automat-
ically 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 object. Modi-
fication of this object is deprecated in 3.x and will be com-
pletely 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 remove
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 location
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 algorithm
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 spidermon-
key:

[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 partitions.

[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 cre-
ation time.

SEE ALSO:
Views Collation

Using Limits and Skipping Rows
By default, views return all results. Thatas ok when the number of results
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 mem-
ory.

But itas possible to reduce output result rows by specifying limit query
parameter. For example, retrieving the list of recipes using the by_title
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 pagina-
tion. Read pagination recipe why itas 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 function
from the specified design document.

Parameters

* db a Database name

* ddoc a Design document name

* view a View function name

Request Headers

* Content-Type a .INDENT 2.0

* application/json

* Accept a .INDENT 2.0

* application/json

Request JSON Object

Response Headers

* Content-Type a .INDENT 2.0

* application/json

* ETag a Response signature

* Transfer-Encoding a chunked

Response JSON Object

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

Status Codes

* 200 OK a Request completed successfully

* 400 Bad Request a Invalid request

* 401 Unauthorized a Read permission required

* 403 Forbidden a Insufficient permissions / Too many requests with
invalid credentials

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

* 500 Internal Server Error a 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 clus-
ter 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 specified
design document.

Parameters

* db a Database name

* ddoc a Design document name

* index a Search index name

Request Headers

* Accept a .INDENT 2.0

* application/json

* text/plain

Query Parameters

* bookmark (string) a 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) a 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) a 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) a 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) a This field defines the order of the groups in
a search that uses group_field. The default sort order is rele-
vance.

* highlight_fields (json) a 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 A string that is inserted before the
highlighted word in the highlights output.

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

* highlight_number (number) a Number of fragments that are returned
in highlights. If the search term occurs less often than the num-
ber of fragments that are specified, longer fragments are re-
turned.

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

* include_docs (boolean) a Include the full content of the documents
in the response.

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

* limit (number) a 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) a Alias for query.

* query (string) a Required. The Lucene query string.

* ranges (json) a 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 a[0 TO 10]a.

* sort (json) a Specifies the sort order of the results. In a
grouped search (when group_field is used), this parameter speci-
fies the sort order within a group. The default sort order is
relevance. A JSON string of the form "fieldname<type>" or -field-
name<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) a Set to ok to allow the use of an out-of-date in-
dex.

Response Headers

* Content-Type a .INDENT 2.0

* application/json

* text/plain; charset=utf-8

* ETag a Response signature

* Transfer-Encoding a chunked

Response JSON Object

* rows (array) a Array of view row objects. By default the informa-
tion returned contains only the document ID and revision.

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

* bookmark (string) a Opaque identifier to enable pagination.

Status Codes

* 200 OK a Request completed successfully

* 400 Bad Request a Invalid request

* 401 Unauthorized a Read permission required

* 403 Forbidden a Insufficient permissions / Too many requests with
invalid credentials

* 404 Not Found a 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 clus-
ter node. See Search Plugin Installation for details.

Added in version 3.0.

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

Parameters

* db a Database name

* ddoc a Design document name

* index a Search index name

Status Codes

* 200 OK a Request completed successfully

* 400 Bad Request a Request body is wrong (malformed or miss-
ing one of the mandatory fields)

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 specified
design document.

Parameters

* db a Database name

* ddoc a Design document name

* index a Nouveau index name

Request Headers

* Accept a .INDENT 2.0

* application/json

Query Parameters

* include_docs (boolean) a Include the full content of the documents
in the response.

* locale (string) a 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) a Limit the number of the returned documents to the
specified number.

* q (string) a Required. The Lucene query string.

* ranges (json) a This field defines ranges for numeric search
fields. The value is a JSON object where the fields names are nu-
meric 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 optional min_inclu-
sive and max_inclusive properties (defaulting to true if not spec-
ified). Example: {"bar":[{"label":"cheap","min":0,"max":100}]}

* sort (json) a Specifies the sort order of the results. The de-
fault sort order is relevance. A JSON string of the form "field-
name" or "-fieldname" for descending order, where fieldname 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) a Limit the number of facets returned by group, de-
faulting to 10 with a maximum of 1000.

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

Response Headers

* Content-Type a .INDENT 2.0

* application/json

* Transfer-Encoding a chunked

Response JSON Object

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

* total_hits (number) a Number of matches for the query.

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

* bookmark (string) a Opaque identifier to enable pagination.

Status Codes

* 200 OK a Request completed successfully

* 400 Bad Request a Invalid request

* 401 Unauthorized a Read permission required

* 403 Forbidden a Insufficient permissions / Too many requests with
invalid credentials

* 404 Not Found a 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 a Database name

* ddoc a Design document name

* index a Search index name

Status Codes

* 200 OK a Request completed successfully

* 400 Bad Request a Request body is wrong (malformed or miss-
ing one of the mandatory fields)

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 im-
plementation.

Parameters

* db a Database name

* ddoc a Design document name

* func a Show function name

Response Headers

* ETag a Response signature

Query Parameters

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

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 im-
plementation.

Parameters

* db a Database name

* ddoc a Design document name

* func a Show function name

* docid a Document ID

Response Headers

* ETag a Response signature

Query Parameters

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

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 im-
plementation.

Parameters

* db a Database name

* ddoc a Design document name

* func a List function name

* view a View function name

Response Headers

* ETag a Response signature

* Transfer-Encoding a chunked

Query Parameters

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

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 design
document.

The request and response parameters are depended upon function im-
plementation.

Parameters

* db a Database name

* ddoc a Design document name

* func a List function name

* other-ddoc a Other design document name that holds view
function

* view a View function name

Response Headers

* ETag a Response signature

* Transfer-Encoding a chunked

Query Parameters

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

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 a Database name

* ddoc a Design document name

* func a Update function name

Response Headers

* X-Couch-Id a Created/updated documentas ID

* X-Couch-Update-NewRev a Created/updated documentas revision

Status Codes

* 200 OK a No document was created or updated

* 201 Created a Document was created or updated

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 document.

Parameters

* db a Database name

* ddoc a Design document name

* func a Update function name

* docid a Document ID

Response Headers

* X-Couch-Id a Created/updated documentas ID

* X-Couch-Update-NewRev a Created/updated documentas revision

Status Codes

* 200 OK a No document was created or updated

* 201 Created a Document was created or updated

* 401 Unauthorized a Unauthorized request to a protected API

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

* 500 Internal Server Error a 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 contain-
ing the a rewrite function or an array of rule definitions.

Using a stringified function for rewrites
Added in version 2.0: When the rewrites field is a stringified function,
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 re-
quest to a new location or immediately return a response.

To rewrite the request, return an object containing the following proper-
ties:

* 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 original
request body is used.

To immediately respond to the request, return an object containing the fol-
lowing 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 define
dynamic variables.

* to (string): The path to rewrite the URL to. It can contain variables
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 con-
tain 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 request
is used to define the rewrite. To match the incoming request, the ruleas
method must match the requestas HTTP method and the ruleas from must
match the requestas path using the following pattern matching logic.

* The from pattern and URL are first split on / to get a list of tokens.
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 corresponding
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 dy-
namic 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 consid-
ered a match. In this example, somepath in the pattern matches
somepath in the URL and all tokens in the URL have matched, causing
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 * vari-
ables 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 | |
| {^afrom^a: | | | |
| ^a/a^a, | | | |
| atoa: | | | |
| a/somea} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b/c | /some/b/c | |
| {^afrom^a: | | | |
| ^a/a/*^a, | | | |
| atoa: | | | |
| a/some/*} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b?k=v | /some?k=v | k=v |
| {^afrom^a: | | | |
| ^a/a/b^a, | | | |
| atoa: | | | |
| a/somea} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b | /some/b?var=b | var=b |
| {^afrom^a: | | | |
| ^a/a/b^a, | | | |
| atoa: | | | |
| a/some/:vara} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b/c | /some/b/c?foo=b | foo=b |
| {^afrom^a: | | | |
| ^a/a/:foo/^a, | | | |
| atoa: | | | |
| a/some/:foo/a} | | | |
+-------------------------------+----------+------------------+--------+
| | /a/b | /some/?k=b&foo=b | foo=b |
| {^afrom^a: ^a/a/:foo^a, | | | |
| atoa: a/somea, | | | |
| aquerya: { | | | |
| aka: a:fooa }} | | | |
+-------------------------------+----------+------------------+--------+
| | /a?foo=b | /some/?b&foo=b | foo=b |
| {^afrom^a: ^a/a^a, | | | |
| atoa: | | | |
| a/some/:fooa} | | | |
+-------------------------------+----------+------------------+--------+

Request method, header, query parameters, request payload and response
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 pro-
vides 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 partition.
It includes document and deleted document counts along with external
and active data sizes.

Parameters

* db a Database name

* partition_id a Name of the partition to query

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

* 403 Forbidden a 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 setting
bounds on the provided partition range. Similar results can be had
by using the global /db/_all_docs endpoint with appropriately con-
figured values for start_key and end_key.

Refer to the view endpoint documentation for a complete description
of the available query parameters and the format of the returned
data.

Parameters

* db a Database name

* partition_id a Partition name

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

* 403 Forbidden a 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 specified par-
tition name.

Refer to the view endpoint documentation for a complete description
of the available query parameters and the format of the returned
data.

Parameters

* db a Database name

* partition_id a Partition name

* ddoc a Design document id

* view a View name

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

* 403 Forbidden a 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 speci-
fied partition id.

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

Parameters

* db a Database name

* partition_id a Name of the partition to query

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

* 403 Forbidden a 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 descrip-
tion of the available parameters and the format of the returned
data.

Parameters

* db a Database name

* partition_id a Name of the partition to query

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

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

Local (non-replicating) Documents
The local (non-replicating) document interface allows you to create local
documents that are not replicated to other databases. These documents can
be used to hold configuration or other information that is required specif-
ically 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-repli- |
| | | cated documents in |
| | | the database |
+-----------+----------------------+----------------------+
| GET | /{db}/_local/{docid} | Returns the latest |
| | | revision of the |
| | | non-replicated docu- |
| | | ment |
+-----------+----------------------+----------------------+
| PUT | /{db}/_local/{docid} | Inserts a new ver- |
| | | sion of the |
| | | non-replicated docu- |
| | | ment |
+-----------+----------------------+----------------------+
| DELETE | /{db}/_local/{docid} | Deletes the |
| | | non-replicated docu- |
| | | ment |
+-----------+----------------------+----------------------+
| COPY | /{db}/_local/{docid} | Copies the |
| | | non-replicated docu- |
| | | ment |
+-----------+----------------------+----------------------+

/{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, including a list of all
local documents and basic contents, consisting the ID, revision and
key. The key is the from the local documentas _id.

Parameters

* db a Database name

Request Headers

* Accept a .INDENT 2.0

* application/json

* text/plain

Query Parameters

* conflicts (boolean) a Includes conflicts information in response.
Ignored if include_docs isnat true. Default is false.

* descending (boolean) a Return the local documents in descending by
key order. Default is false.

* endkey (string) a Stop returning records when the specified key is
reached. Optional.

* end_key (string) a Alias for endkey param.

* endkey_docid (string) a Stop returning records when the specified
local document ID is reached. Optional.

* end_key_doc_id (string) a Alias for endkey_docid param.

* include_docs (boolean) a Include the full content of the local
documents in the return. Default is false.

* inclusive_end (boolean) a Specifies whether the specified end key
should be included in the result. Default is true.

* key (string) a Return only local documents that match the speci-
fied key. Optional.

* keys (string) a Return only local documents that match the speci-
fied keys. Optional.

* limit (number) a Limit the number of the returned local documents
to the specified number. Optional.

* skip (number) a Skip this number of records before starting to re-
turn the results. Default is 0.

* startkey (string) a Return records starting with the specified
key. Optional.

* start_key (string) a Alias for startkey param.

* startkey_docid (string) a Return records starting with the speci-
fied local document ID. Optional.

* start_key_doc_id (string) a Alias for startkey_docid param.

* update_seq (boolean) a Response includes an update_seq value indi-
cating which sequence id of the underlying database the view re-
flects. Default is false.

Response Headers

* Content-Type a .INDENT 2.0

* application/json

* text/plain; charset=utf-8

Response JSON Object

* offset (number) a Offset where the local document list started

* rows (array) a Array of view row objects. By default the informa-
tion returned contains only the local document ID and revision.

* total_rows (number) a Number of local documents in the database.
Note that this is not the number of rows returned in the actual
query.

* update_seq (number) a Current update sequence for the database

Status Codes

* 200 OK a Request completed successfully

* 401 Unauthorized a Unauthorized request to a protected API

* 403 Forbidden a 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 parameters
and behavior as specified in the GET /{db}/_local_docs API but al-
lows for the query string parameters to be supplied as keys in a
JSON object in the body of the POST request.

Parameters

* db a Database name

Status Codes

* 401 Unauthorized a Unauthorized request to a protected API

* 403 Forbidden a 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 a Database name

Request Headers

* Content-Type a .INDENT 2.0

* application/json

* Accept a .INDENT 2.0

* application/json

Request JSON Object

Response Headers

* Content-Type a .INDENT 2.0

* application/json

* text/plain; charset=utf-8

* Transfer-Encoding a chunked

Response JSON Object

* results (array) a An array of result objects - one for each query.
Each result object contains the same fields as the response to a
regular _local_docs request.

Status Codes

* 200 OK a Request completed successfully

* 400 Bad Request a Invalid request

* 401 Unauthorized a Unauthorized request to a protected API

* 403 Forbidden a Insufficient permissions / Too many requests with
invalid credentials

* 404 Not Found a Specified database is missing

* 500 Internal Server Error a 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 total_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, except that
the document is not replicated. See GET /{db}/{docid}.

Parameters

* db a Database name

* docid a 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 a Database name

* docid a Document ID

DELETE /{db}/_local/{docid}
Deletes the specified local document. The semantics are identical 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 struc-
tures that you can supply to CouchDB, or get in return to requests.

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 objects 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. Further-
more, 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 functions
calls, such as JavaScript views.

The default query server is written in JavaScript, running via Mozilla Spi-
derMonkey. 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 language 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, updates and vali-
date_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 read-
ability. 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 previous
input. If applicable, this is the point to run garbage collection.

CouchDB sends:

["reset"]

The Query Server answers:

true

To set up new Query Server state, the second argument is used with object
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 func-
tions.

CouchDB sends:

[
"add_lib",
{
"utils": "exports.MAGIC = 42;"
}
]

The Query Server answers:

true

NOTE:
This library shouldnat have any side effects nor track its own state or
youall have a lot of happy debugging time if something goes wrong. Re-
member 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, compile, 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 be-
fore 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 send-
ing 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 re-
turned 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 docu-
ment.

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 for-
mat [[key, id-of-doc], value]

Returns
Array with pair values: true and another array with reduced result

If the view has a reduce function defined, CouchDB will enter into the re-
duce 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 different
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 depending
on executed function

This command acts in two phases: ddoc registration and design function exe-
cution.

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 execu-
tion.

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>, <ar-
gument2>, ...]]

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 isnat specified in request

* 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 letas use
an example to illustrate.

Assume we have view a function that emits id-rev pairs:

function(doc) {
emit(doc._id, doc._rev);
}

And wead 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 di-
vided 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 function will be
complete and the client will receive a complete response.

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.

Letas 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 '}';
}

aWait, what?a - youad like to ask. Yes, wead build JSON response manually
by string chunks, but letas 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 re-
sponse 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 wasnat specified in request

* 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 sending a
special message in response to the received command.

Error messages prevent further command execution and return an error de-
scription to CouchDB. Errors are logically divided into two groups:

* Common errors. These errors only break the current Query Server command
and return the error info to the CouchDB instance without terminating the
Query Server process.

* Fatal errors. Fatal errors signal a condition that cannot be recovered.
For instance, if your a design function is unable to import a third party
module, itas better to count such error as fatal and terminate 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 itas
"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 pos-
sibly 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 Functions to
stop further function processing and prevent storage of the new document
revision. Since this is not actually an error, but an assertion against
user actions, CouchDB doesnat log it at ^aerror^a 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 under-
stand what they can do to solve the problem. Similar to forbidden, CouchDB
doesnat log it at ^aerror^a level, but returns a HTTP 401 Unauthorized re-
sponse 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 CouchDBas log file. This is done by sending a special log object 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 during Map Func-
tions.
+----------------+-----------------------------+
| JS Function | Reasonable to use in design |
| | 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 objects,
modules and functions:

emit(key, value)
Emits a key-value pair for further processing by CouchDB after the
map function is done.

Arguments

* key a The view key

* value a The keyas 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 a 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 a 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 a MIME key previously defined by registerType()

* func a MIME type handler

registerType(key, *mimes)
Registers list of MIME types by associated key.

Arguments

* key a MIME types

* mimes a 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 A CommonJS module path started from design document
root

Returns
Exported statements

send(chunk)
Sends a single string chunk in response.

Arguments

* chunk a Text chunk

function(head, req){
send('Hello,');
send(' ');
send('Couch');
return ;
}

start(init_resp)
Initiates chunked response. As an option, a custom response object
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 object
({}).

function(head, req){
start({
"code": 302,
"headers": {
"Location": "http://couchdb.apache.org"
}
});
return "Relax!";
}

sum(arr)
Sum arras items.

Arguments

* arr a Array of numbers

Return type
number

toJSON(obj)
Encodes obj to JSON string. This is an alias for the JSON.stringify
method.

Arguments

* obj a 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 func-
tionality.

Hereas 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 documentas views object, but mod-
ules can only be loaded from the object referenced via lib. The lib struc-
ture can still be used for view functions as well, by simply storing 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 a Function object.

* Acc a 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 a 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 a 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 docu-
ments are typically given the same partition key. The benefit of parti-
tioned databases is that secondary indices can be significantly more effi-
cient 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, weall consider a motivat-
ing use case to describe the benefits of this feature. For this example,
weall consider a database that stores readings from a large network 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 fol-
lowing 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 experiment.

So weave got a bunch of sensors, all grouped by the field they monitor
along with their readouts for a given day (or other appropriate time pe-
riod).

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 database 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 con-
tains sensor readings from an IoT field monitoring service. In this partic-
ular use case, itas quite logical to group all documents by their sensor_id
field. In this case, we would call the sensor_id the partition 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. Secondly, the
amount of data per partition should be asmalla. The general recommendation
is to limit individual partitions to less than ten gigabytes (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 accordingly.
Setting the value for this option to 0 disables the partition limit.

Why use partitions?
The primary benefit of using partitioned databases is for the performance
of partitioned queries. Large databases with lots of documents often have a
similar pattern where there are groups of related documents 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 executing 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 efficient and faster.

Partitions By Example
To create a partitioned database, we simply need to pass a query string pa-
rameter:

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 infor-
mation:

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..."
}

Youall now see that the "props" member contains "partitioned": true.

NOTE:
Every document in a partitioned database (except _design and _local doc-
uments) must have the format apartition:docida. 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 incompatible
requirements on document ids.

Now that weave created a partitioned database, itas time to add some docu-
ments. 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 document 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 parti-
tion 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 partitions. Both
query styles have the same performance.

Next, weall 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 weave 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 performance improvements,
itas actually a big deal. By knowing that the view results are all located
within the provided partition name, our partitioned queries now perform
nearly as fast as document lookups!

The last thing weall look at is how to query data across multiple parti-
tions. For that, weall 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, weall create a new design doc with this function. Be sure to notice
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 partitioned.
Design documents that contain views for queries across multiple parti-
tions must contain the "partitioned": false member in the "options" ob-
ject.

NOTE:
Design documents are either partitioned or global. They cannot contain a
mix of partitioned and global indexes.

And to see a request showing us all sensors in a field, we would use a re-
quest 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 weare not using the /dbname/_partition/... path for global
queries. This is because global queries, by definition, do not cover indi-
vidual partitions. Other than having the "partitioned": false parameter 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 par-
titioned database benefit from the performance improvements.

RELEASE NOTES
3.5.x Branch
* Version 3.5.2

* Version 3.5.1

* Version 3.5.0

Version 3.5.2
Features
* #5628, #5940: Nouveau Lucene 10 upgrade. Lucene is bumped to 10.4.0. New
Nouveau indexes use Lucene 10 by default. Existing Lucene 9 indexes con-
tinue to work via version negotiation, and an upgrade scanner (nou-
veau_index_upgrader) can rebuild them at a configurable rate.

* #5896: Nouveau bulk index updates. Replace doc-at-a-time updates to bulk
updates which should improve index building.

* #5942: Fix cluster index cleanup. Adds the [couchdb] index_cleanup_de-
lay_msec setting.

* #5624: Use SpiderMonkey 128 as the default version.

* #5754: Support safe secret rotation.

* #5811: Avoid updating password hash when request uses simple password
scheme.

Performance
* #5984: Update Jiffy to 2.0. Jiffy 2.0 has a number of performance opti-
mization which should speed up both encoding and decoding.

* #5908: Optimize replicator. Use gen_server casts to queue docs for
_bulk_docs in replication workers instead of synchronous calls.

* #5992: Do not run a full GC after each index doc update. Increase view
queue size from 100KB to 10MB. This should improve view index building
times.

* #5942: Pre-fetch design docs once per cleanup request and reuse signa-
tures across nodes (instead of fetching them on every worker).

Bugfixes
* #5776, #5704, #5701, #5708, #5707, #5702, #5694, #5691, #5731, #5867:
QuickJS updates. Memory leak fixes, use-after-free fixes in workers and
regex, regex memory blowup fix, Unicode 17 support, FP16 support, opti-
mized string operations, faster context creation, closure optimization,
iterator improvements.

* #5776: Fix purge mem3_rep client verification.

* #5830: Fix race condition during purge checkpoint creation.

* #5825: Fix handling shards dbs purge checkpoints in mem3_rep. Consider
previous-node replications for _dbs purge checkpoints.

* #5917: Fix signatures in mrview purge checkpoints. Avoid creating purge
checkpoints for invalid views. Do not reset dreyfus purge_seq back to 0.

* #5940: Initialise nouveau index purge_seq from db purge_seq, and commit
purge seq update before returning.

* #5939: Handle cases when dreyfus checkpoint is out-of-sync with the in-
dex. Fix view compaction duration logging.

* #5793: Fix replicator scheduler total jobs metric.

* #5793: Fix Prometheus metrics annotations.

* #5893: Improve replication since_seq parameter handling.

* #5865: Fix intermittent _scheduler/docs 500 error.

* #5853: Tolerate invalid typ claim when not required.

* #5846: Tolerate maintenance mode and a node down in partition info calls.

* #5628: Fix bulk_get error handling.

* #5978: Fix _find when over threshold. Use errstr() instead of toSource()
in nouveau JS wrapper.

* #5984: Fix ReferenceError in QuickJS dispatch.

* #5893: Send 404 for /_all_dbs and /_dbs_info with extra path parts.

Docs
* #5973: Fix Jenkins badge link in README.

* #5974: Update CI badge URL in README.rst.

* #5984: Add missing comment from docs.

* #5865: Fix docs about replication.

* #5925: Change CouchDB links to use HTTPS.

* #5924: Update URLs to use HTTPS in mac installation guide.

Tests/CI/Builds
* #5825, #5914, #5854, #5843: CI parallelism. Parallel make eunit (sub-tar-
gets / -j4 / Windows). Concat eunit test logs and remove tmp dirs in
Makefile. Speed up compiling and release building.

* #5971: Update Black to 26.3.1.

* #5967: Make creation of couch.uri independent of --auto-ports. Make file
path for couch.uri absolute.

* #5964: Use couchdb.uri only when auto-ports is enabled. Clean up the
couch.uri on make devclean.

* #5687: Write couch_uri files so ports are discoverable with --auto-ports
option.

* #5864: Enable EUnit/Elixir/Nouveau tests on Windows.

* #5894: Improve / fix Jenkins workspace cleanup.

* #5938: CI: enable xref checking for undefined functions.

* #5805: Donat run tests if we only change .github configuration.

* #5897: Temporarily disable freebsd-arm worker.

* #5908: Improve CI performance by combining some stages.

* #5908: Add Trixie to CI.

* #5805: Update Elixir tests and config files.

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 re-
moved 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 requests
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 instead of by
document IDs.

* #5707, #5706, #5706, #5694, #5691, #5669, #5629, #5574, #5573, #5566, -
#5553, #5550, #5534, #5730: QuickJS Updates. Optimized string operations,
faster context creation, a lot of bug fixes.

* #5719: Use aalla 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 se-
curity on http/2.

* #5614: Stop replication jobs to nodes which are not part of the cluster

* #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: Donat 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 er-
ror

* #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: Donat 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. Itas 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 functions

* #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 cluster

* #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 responses

* #5653: Document that _all_dbs endpoint supports inclusive_end query param

* #5575: Document how to mitigate high memory usage in docker

* #5600: Avoid amastera 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 aassert_on_statusa 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 hav-
ing to wait for all writes and fsync calls. This is enabled by default
and can be disabled with [couchdb] use_cfile = false in the configura-
tion.

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()ad file descriptors to be used for
reading and writing. Writes continue to be serialised at the database en-
gine layer, but reads now are no longer blocked by writes waiting to com-
mit.

Comes with an extensive test suite that includes property testing to en-
sure couch_cfile behaves exactly like Erlangas 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 cluster:
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 pro-
cessing of many concurrent TCP connections.

* #5347: Fix attachment size calculation. This could lead to shards not be-
ing 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 between 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 databases. It
can be configured to report individual revisions or aggregated statis-
tics.

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 fdatasync
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 ver-
sions 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, gracefully
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 feature
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 reliably
detect if a Clouseau node is ready to be used.

* #5416: Ensure we always map the documents in order in couch_mrview_up-
dater. While views still built correctly, this behaviour simplifies de-
bugging.

* #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 func-
tions.

* #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 replication.

* #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 in-
compatibilities, including SpiderMonkey 1.8.5 vs. newer SpiderMonkey 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
Thereas 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 be-
ing 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, gracefully
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 nouveau
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 reliably
detect if a Clouseau node is ready to be used.

* #5416: Ensure we always map the documents in order in couch_mrview_up-
dater. While views still built correctly, this behaviour simplifies de-
bugging.

* #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 func-
tions.

* #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 replication.

* #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 in-
compatibilities, including SpiderMonkey 1.8.5 vs. newer SpiderMonkey 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 Nouveau.

* #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 password
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 password
hashes to a newer algorithm and a configuration option that enables this
feature by default. As a consequence, if you are upgrading to CouchDB ver-
sion 3.4.0 from an earlier version and then have to roll back to the ear-
lier version, some of your _users documents might have already automati-
cally 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 restored manually by an adminstra-
tor.

As a result, the CouchDB team has decided to issue a 3.4.1 release setting
the configuration option to disable this new auto-upgrade feature.

The issue was found after the formal 3.4.0 release process has concluded,
so the source release is available normally, but the CouchDB team has not
made 3.4.0 convenience binaries available. The team recommends to upgrade
to 3.4.1 instead when it is available.

The CouchDB team also recommends enabling the feature by setting the up-
grade_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 ex-
pire. It is a surprise to some that this requires a change to the default
configuration. In the interest of security we will now require a valid
exp claim in tokens. Administrators can disable the check by changing re-
quired_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 sequences are
streamed back to the client.

Highlights
.-.
/ |
/\ | .-._.) ( ) .-..-. .-. ) (
/ \ |( )( )( / ./.-'_( | ( )
.-' / \| `-' `--': \_/ (__.' `-'-'`--':
(__.' `.

* #4291: Introducing Nouveau (beta) a modern, from-the-ground-up implemen-
tation 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. Weare 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 donat 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 run-
time:

./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 re-
port 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 check-
sums 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 iteration
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 during
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 authentication
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 clus-
tered port.

* #5136: Print log dir on dev/run startup.

* #5150: Ensure rexi_buffer metric includes the internal buffered messages.

* #5145: Add aggregate rexi_server and rexi_buffer message queue metrics.

* #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 /_session
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 Er-
lang/OTP primitives resulting in up to 19x faster histogram operations.

* #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 endpoints
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 moni-
toring _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 doesnat 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 oc-
currence 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 dependency.

* #5117, #5118: Validate target doc id for COPY method.

* #5111, #5114: Make sure config reload finds new .ini files in .d directo-
ries.

* #5110: Remove last remnant of snap install in ./configure. That happens
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 plugin.

* #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 inputs.

* #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 re-
sults.

* #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 index_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 fabric_doc_up-
date.

* #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 unused
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
Whatas 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 {pre-
fer_ipv6, true}.

* #4679: Fix multipart parser aattachment longer than expecteda error. Pre-
viously 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 pro-
cessing streaming requests.

* #4758: Remove sensitive headers from the mochiweb request in process dic-
tionary. 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 during
compact file flips could lead to crashes and a subsequent recompaction.

* #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 performance.

* #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 time-
outs 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 errors.

* #4348: Fix undef error in weatherreport.

* #4353: Allow starting of more than one replication job. (DaOH!)

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)] [im-
age]

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 operations and in-
crease 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 Erlang
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 writers
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 situa-
tions.

* #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_debug
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 apply-
ing 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 repli-
cates only the winning revisions from the source to the target, effec-
tively 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: Donat 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 persist 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. Previously,
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 com-
paction 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 _replicator
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 repli-
cation 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 aRelaxa welcome message to standard out on Windows.

Performance
* #3860: Add sharding to couch_index_server, similar to #3366, avoids pro-
cessing bottlenecks on servers with a lot of concurrent view indexing go-
ing 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 linear.
This speeds up working with heavily conflicted documents significantly.

* #4091: Optimise couch_util:to_hex/1, this speeds up all operations that
need to encode a revision id into JSON (this is most operations).

* #4106: Set io_priority in all IO paths. Introduces system io_priority.

* #4144, #4172: Implement _bulk_get support for the replicator. Backward
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 support.

* #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 ex-
pensive repeated AST-transformations on newer SpiderMonkey versions. 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 return
the detailed major.minor.patch as opposed to just the major version 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 temporar-
ily 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 cre-
ation.

* #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-condi-
tion 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 MINI-
MUM_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 sub-
sequent test flakiness.

* #3968: Ensure key tree rev stemming doesat take too much memory.

* #3980: Upgrade Mango test dependency nose to nose and fix flaky-on-Win-
dows 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 anywhere.

* #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. a 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 performance.

* #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 vul-
nerability.

* #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 collation
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 Erlang.

* #3787: Update sequences generated from DB info and
_changes?since=now&limit=0 now contain shard uuids as part of their in-
ternal, 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 data-
base 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-injected
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 differ-
ent 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] sec-
tion 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: CouchDBas replicator now implements a Fair Share replication
scheduler. Rather than using a round-robin scheduling mechanism, this up-
date 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.] [image]

* #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 cus-
todian, a diagnostic app forked from Bashoas riaknostic tool. More docu-
mentation 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 simi-
lar to any 5xx error (by retrying, as opposed to a permanent error).
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 infinity
to 1 GiB.

* #3361: Compaction process suspension now appears in the active_tasks out-
put, 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 possible. Fur-
ther, #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 estab-
lish 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 com-
ment all out in the default.ini.

* Config options moved from [httpd] to [chttpd]: allow_jsonp,
changes_timeout, config_whitelist, enable_cors, secure_rewrites, x_for-
warded_host, x_forwarded_proto, x_forwarded_ssl, enable_xframe_options,
max_http_request_size.

* Config options moved from [couch_httpd_auth] to [chttpd_auth]: authen-
tication_redirect, timeout, auth_cache_size, allow_persistent_cookies,
iterations, min_iterations, max_iterations, password_scheme,
proxy_use_secret, public_fields, secret, users_db_public, 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 passwords
using a list of regular expressions.

* #3506, #3416, #3377: CouchDB now provides a Prometheus compatible end-
point at GET /_node/{node-name}/_prometheus. A configuration option al-
lows for scraping via a different port (17986) that does not require au-
thentication, 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 en-
coding the plus sign + in non-query parts of URLs, in compliance with the
original CouchDB standards. The opt-in is via the [chttpd] de-
code_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. Documentation is in the de-
fault.ini file.

* #3734, #3733: Users with databases that have low q and n values would of-
ten receive the No DB shards could be opened error when the cluster is
overloaded, due to a hard-coded 100ms timeout. CouchDB now calculates 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 perfor-
mance. Previously, as a single gen_server, the process would have a fi-
nite throughput that, in busy clusters, is easily breached a causing 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 replica-
tor.

* #3600, #3047, #3019: The default slack channel for smoosh auto-compaction
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-com-
paction 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 ex-
isting nodeas 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 replica-
tor 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 consis-
tent 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 sup-
port maps instead of the default data structure.

* #3255, #2558: View files that have incorrect db_headers now reset the in-
dex 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 re-
turn the field without parsing.

* #3279: Some default headers were missing from some responses in replica-
tion, 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 Trans-
fer-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 ensures
that each new couch_server_X property receives 1/num_servers() of it.

* #3373: Requests to {db}/_changes with a custom filter no longer result in
a fabric request timeout if the request body is not available to addi-
tional 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 unexpectedly.

* #3491: libicu tests no longer fail on older OS releases such as CentOS 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 conflicting
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:multicall
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_error.

* #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 coor-
dinator.

Other
* Donuts for everyone! Er, not really - thank you for reading the 3.2 re-
lease 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 anormal : unknowna 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 specified
as a list of lists, to avoid having to define this redundantly in a sin-
gle query. (Some languages donat have this facility.)

* #3132: The new [chttpd] buffer_response option can be enabled to delay
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 terminated 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 resched-
uling, where previously with high load it may have failed to try to
restart crashed jobs.

* #2981: When handling extremely large documents (aY50MB), 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 operates
correctly with newer browsers.

* #3061, #3080: The couch_index server wonat crash and log errors if a de-
sign 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 para-
meters 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 partitioned
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 result
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_com-
paction, 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 current
Mozilla SpiderMonkey ESR release. This provides direct support for pack-
aging on the latest operating system variants, including Ubuntu 20.04
aFocal Fossa.a

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 improve-
ment when document revisions approach the revs_limit. The fixes also in-
clude 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 fara|thank 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 re-
laxed via the [couchdb] max_document_size config 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 anode-locala 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 interface
(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

a|and so on. Documentation has been updated to reflect this change.

WARNING:
The _node endpoint is for adminstrative purposes it is NOT intended as
an alternative to the regular endpoints (aGET /dbnamea, aPUT /db-
name/docida 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 end-
point.

* #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 transparently
from CouchDB 1.x to 3.x. In addition, the couchup utility has been re-
moved 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 in-
dexes, 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 - asofta 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 in-
valid)

* 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 partition_query_limit val-
ues in the ini file [query_server_config] section.

* 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 re-
placed in CouchDB 3.0:

* #2089, #2128, #2251: Local endpoints for replication targets, which never
functioned as expected in CouchDB 2.x, have been completely removed. When
replicating databases, always specify a full URL for the source and tar-
get. In addition, the node local _replicator database is no longer auto-
matically 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 improved
file, active and external size metrics. Fauxton has been updated to
match.

* #2173: The ability to submit multiple queries against a view using the -
POST to /{db}/_design/{ddoc}/_view/{view} with the ?queries= option 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 ob-
ject 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 con-
figuration file. All writes are now full commits. The /_ensure_full_com-
mit API endpoint has been retained (as a no-op) for backwards compatibil-
ity with old CouchDB replicators.

* #2395: The security object in the _users database cannot be edited by de-
fault. A setting exists in the configuration file to revert this behav-
iour. The ability to override the disable setting is expected to be re-
moved in CouchDB 4.0.

Deprecated feature warnings
The following features are deprecated in CouchDB 3.0 and will be removed 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 sec-
tion 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 op-
erator-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 correctly handle
creating local replicas of that database.

* #2805: Mango operators more correctly handle being passed empty arrays.

* #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 module.

* #2818: Mango now uses a safer method of bookmark creation that prevents
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 sub-
system ensures secondary indexes (such as JavaScript, Mango, and text
search) are kept up to date, without requiring an external query to trig-
ger building them. Many configuration parameters are available.

* #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 con-
figurable and well-documented.

* #2436, #2455: CouchDB now regression tests against, and officially sup-
ports, running on the arm64v8 (aarch64) and ppc64le (ppc64el) machine ar-
chitectures. Convenience binaries are generated on these architectures
for Debian 10.x (abustera) packages, and for the Docker containers.

* #1875, #2437, #2423: CouchDB now supports linking against SpiderMonkey 60
or SpiderMonkey 1.8.5. SpiderMonkey 60 provides enhanced support for ES5,
ES6, and ES2016+. Full compatibility information is available at the -
ECMAScript compatibility table. Click on aShow obsolete platformsa, then
look for aFF 60 ESRa 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, CouchDBas 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 binary
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 De-
bian, 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 installed.

* #2037: Dreyfus, the CouchDB side of the Lucene-powered search solution,
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 re-
quire_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}/_system end-
points.

* #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
CouchDBas microsecond-accurate timestamps, and uses the sd-daemon(3) log-
ging levels.

* #2296, #1977: If the configuration file setting [couchdb] single_node is
set to true, CouchDB will automatically create the system databases 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 ob-
ject, rather than in the URL when using POST.

* #2292: The _scheduler/docs and _scheduler/info endpoints now return de-
tailed 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 tar-
get_proxy keys. The API documentation has been updated.

* #2240: Headers are now returned from the /{db}/_changes feed immediately,
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 parti-
tioned view requests can all be specified separately in the ini file un-
der 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 cookieas SameSite at-
tribute. It may be necessary to set this to strict for compatibility
with future versions of Google Chrome. If CouchDB CORS support is en-
abled, 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 interfaceas 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 ^a=Y 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 thousands of un-
necessary 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 func-
tionality. This reduces overall CouchDB load.

Bugfixes
* #1752, #2398, #1803: The cluster setup wizard now ensures a consistent
UUID and http secret across all nodes in a cluster. CouchDB admin pass-
words are also synced when the cluster setup wizard is used. This pre-
vents 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 re-
sponse, 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 databaseas shard map will not corrupt
additional database properties, such as partitioning values.

* #1877: The _purge and _purged_infos_limit endpoints are now correctly re-
stricted to server admin only.

* #1794: The minimum purge sequence value for a database is now gathered
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 Request error.

* #2321: CouchDB no longer requires Basic auth credentials to reach the
/_session endpoint for login, even when require_valid_user is enabled.

* #2295: CouchDB no longer marks a job as failed permanently if the inter-
nal 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 data-
base 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 in-
valid 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 handles the case when a view
file lacks a proper header.

* #1983: Improve database aexternala size calcuation to be more precise.

* #1971: Correctly compare ETags using weak comparison methods to support
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
werenat followed by a match within a given shard.

* #2393, #2143: It is now possible to override the query server environment
variables COUCHDB_QUERY_SERVER_JAVASCRIPT and COUCHDB_QUERY_SERVER_COF-
FEESCRIPT without overwriting the couchdb/couchdb.cmd startup scripts.

* #2426, #2415: The replicator now better handles the situation where de-
sign document writes to the target fail when replicating with non-admin
credentials.

* #2444, #2413: Replicator error messages are now significantly improved,
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 selector or
operators with empty arrays.

* #2466: Mango text indexes no longer error if the indexed document revi-
sion 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 specified
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 donat 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 Re-
quest.

* #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 creden-
tials 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 child-
specs 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 before_doc_up-
date.

* #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 dreyfus_fab-
ric_search.

* #2506: CouchDBas release candidates no longer propagate the RC tags into
each Erlang applicationas version string.

* #2511: recon, the Erlang diagnostic toolkit, has been added to CouchDBas
build process and ships in the release + convenience binaries.

* 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 failures.

* #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 aw:3a for lots of doc tests.

* #1939, #1931: Multiple fixes to improve support in constrained CI envi-
ronments.

* #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 vari-
ables.

* #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 optional
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 fara|thank you for reading.

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 configu-
ration 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 enabled
by default. Setup differences have been moved from default.ini to the
couchdb and couchdb.cmd start scripts respectively.

Additional query servers can now be configured using environment vari-
ables:

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 command-
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 Erlang
query server continues to be disabled by default. This change adds a
[native_query_servers] enable_erlang_query_server = BOOL setting (de-
faults to false) to enable the Erlang query server.

If the legacy configuration for enabling the query server is detected,
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 re-
placed 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 up-
dated 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 char-
acters. 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 isnat 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 de-
tails, 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 nodeas _nodes database automatically, triggering a distrib-
uted Erlang connection and replication of the internal system 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 dependency.

* #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 re-
set on job restart.

* #1195, #1742: CouchDBas _bulk_get implementation now supports the multi-
part/mixed and multipart/related content types if requested, extending
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 performance when
transferring large attachments.

* #1423: Mango selector matching now occurs at the shard level, reducing
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 intermit-
tently.

* #1550: Replicator _session support was incompatible with CouchDB instal-
lations 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 itas 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. Previ-
ously, 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/_en-
sure_full_commit call to restore database validation checks.

* #1591: CouchDB now creates missing shard files when accessing a database
if necessary. This handles the situation when, on database creation, no
nodes were capable of creating any of the shard files required 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 spe-
cific 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 operations.

* #1636: A memory leak when replicating over HTTPS and a problem occurs has
been squashed.

* #1635: /_replicate jobs are no longer restarted if parameters havenat
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 invalid
VDU function into one of the _replicator databases.

* #1644, #1647: It is no longer possible to create illegally-named data-
bases 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, additional
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 allocation
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 possible 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 databaseas _security object on migration.

* #1672: When checking the status of a view compaction immediately after
starting it, the total_changes and changes_done fields are now immedi-
ately 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 re-
sponse.

* #1603: CouchDB now returns the correct total_rows result when querying
/{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 sta-
tistics.

* #1607: The replicator no longer fails to re-authenticate to open a remote
database when its session cookie times out due to a VDU function forbid-
ding 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 intended to
replace the aging, unmaintainable JavaScript test suite, and help re-
duce 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 dis-
abled per module if desired.

* #1682: A new [feature_flags] config section exists for the purpose of en-
abling or disabling experimental features by CouchDB developers.

* A narwhal! OK, no, not really. If you got this fara|thank 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. Support
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 performance
since re-authorization does not have to be performed with every request.
Because of this performance improvement, it is recommended 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] it-
erations = 10000.

Do not do this if an older version of CouchDB is replicating TO this in-
stance or cluster regularly, since CouchDB < 2.2.0 must perform authenti-
cation on every request and replication performance will suffer.

A future version will make this increased number of iterations a default.

* #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}/_de-
sign/{ddoc}/_view/{view}/queries has been introduced to replace 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 up-
dated on database write, not read. This has lead to significant perfor-
mance enhancements on very busy clusters. To restore the previous behav-
iour, your local ini file can contain the block [couchdb] up-
date_lru_on_read = true.

* #1153: The CouchDB replicator can now make use of the /_session endpoint
rather than relying entirely on HTTP basic authentication headers. This
can greatly improve replication performance. We encourage you to upgrade
any nodes or clusters that regularly act as replication 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 docu-
mented in default.ini.

* #1330: CouchDB externals and OS daemons are now officially deprecated and
no longer documented. Support for these features will be completely re-
moved 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 back-
ward- compatible breaking change, it is best to update your local ini
files to reference the new {chttpd_auth, proxy_authentication_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 re-
moved. 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 mechanisms

* Fixes for IE10, IE11, and Edge (we hopea|)

* 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 dif-
ferent backends for storing the base database file itself. The refactor
included a full migration of the existing alegacya storage engine 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 for-
mer 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 respond.
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 discussion
about the path forward for future releases is available in #1200 and -
#1253.

* An update to the replicator http client that improves active socket ac-
counting, without which CouchDB can cease to be responsive over the
main http interface (#1117)

* The replicatoras http client no longer performs unconditional retries
on failure (#1177)

* A path by which CouchDB could lose track of their RPC workers during
multipart attachment processing was removed. (#1178)

* When CouchDB transmits a 413 Payload Too Large response on attachment
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 replicator http client cor-
rectly closes its own socket after processing any 413 response. (#1234)

* A fabric process to receive unchunked attachments can no longer orphan
processes that leave unprocessed binaries in memory until all available
memory is exhausted. (#1264).

* When using CouchDBas native SSL responder (port 6984 by default), ses-
sions 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 li-
braries. (#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 clus-
teras q value. Set this in your local ini file, under [couch_peruser] 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 authenticataion
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_pe-
ruser) 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 seconds.

* A notice-level log about closing view indexes has been demoted to
the debug level. In a sceario with many design docs, this would cre-
atesignficant load on the logging subsystem every [compaction_dae-
mon] 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 run-
ning on any given machine.

* COUCHDB-2971, #1346: CouchDB now includes a new builtin reduce function
_approx_count_distinct, that uses a HyperLogLog algorithm to estimate the
number of distinct keys in the view index. The precision is currently
fixed to 2^11 observables, and therefore uses approximately 1.5KB of mem-
ory.

* #1377: CouchDB finalization of view reduces now occurs at the coordinator
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 Erlang
processes that can have huge number of messages in their mailbox, 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_options ini file set-
ting.

* #1440: CouchDB can now be configured to prevent non-admins from accessing
the GET /_all_dbs method by specifying [chttpd] admin_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 Erlang
MD5 hash function when not available in the external environment (e.g.
FIPS enabled CentOS) at compile time with the configure flag --en-
able-md5. Because this implementation is slower, it is not recommended 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 algorithm
can be disabled by setting the option [couchdb] stem_interactive_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 pro-
vided to the GET or POST /{db}/_all_docs?update_seq=true endpoints. This
was affecting PouchDB compatibility.

* #984, #1434: CouchDB views now retain their update_seq after compaction,
preventing potentially expensive client-side view rewinds after com-
paction.

* #1012: Address a theoretical race condition the replication scheduler
could encounter when trying to determine if the cluster is astablea
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 correctly.
The syntax now also supports shard-level custom compaction configuration
if desired (which it probably isnat.)

* #1097: Compaction daemon will not crash out when trying to check specific
file system mounts that are not areala 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 administra-
tive 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 implemented
directly in Erlang (after enabling the optional Erlang view server).

* #1223: The couch_config application now correctly handles non-persistent
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 en-
cryption 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 response)
no longer is incorrectly calculated in such a way that it could occasion-
ally 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 configura-
tion flag enable_database_recovery when set when compacting databases,
rather than always retaining the old, renamed, uncompacted database file.

* #1439: The CouchDB setup wizard now correctly validates bind_addresses.
It also no longer logs credentials by moving logging of internal 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 warning 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 re-
turned. 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-specified
name already starts with _design/.

* #988, #989: When specifying a use_index value with an invalid index, cor-
rectly return a 400 Bad Request showing that the requested index is in-
valid for the request specified.

* #998: The fix for CVE 2017-12635 presented a breaking change to Mangoas
/{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 in-
stance of a field, silently ignoring those that appear before 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 se-
lector 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 in-
dex, and Mango now correctly ignores their presence in any index that ex-
plicitly 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 queryas
sort field list.

* Multiple fixes related to using Mango as a front-end for full text index-
ing (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 Fauxton
and documentation builds by specifying the new --dev option to the con-
figure script.

* The mochiweb dependency was bumped to version 2.17.0, in part to address
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 improved
long-term project maintenance and automatability.

* Related improvements to the CouchDB deb/rpm packaging and Docker reposi-
tories to make deployment even easier.

* #1007: Move etc/default.ini entries back into [replicator] section (in-
correctly moved to [couch_peruser] section)

* #1245: Increased debug-level logging for shard open errors is now avail-
able.

* #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 fara|thank 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 de-
fault node name has changed from couchdb@localhost to couchdb@127.0.0.1,
which can prevent CouchDB from accessing existing databases on the sys-
tem. 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 fu-
ture.

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

* If user code reads or manipulates replicator document states, consider
using the [replicator] update_docs = true compatibility parameter. In
that case the replicator will continue updating documents with transient
replication states. However, that will incur a performance 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=update_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 configu-
ration parameter, which had been unfortunately 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 modi-
fied 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 de-
fault. To restore the original behaviour, add the --eval flag to the def-
inition 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 authen-
tication 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 itself will cor-
rectly perform free space checks in version 21.0.

* #824: The current nodeas local interface can now be accessed at
/_node/_local/{endpoint} as well as at /_node/<nodename>@<hostname>/{end-
point}.

* The Dockerfile in the source repository has been retired. For a current
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 between
10-40% in both CPU and wall-clock time for database compaction.

* The design document cache (ddoc_cache) has been rewritten to improve per-
formance.

Mango
* #808: Mango now supports partial indexes. Partial indexes allow documents
to be filtered at indexing time, potentially offering significant perfor-
mance improvements for query selectors that donat map cleanly to a range
query on an index.

* #740: Mango queries can now be paginated. Each query response includes 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 include_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 candidate
index must exist in a queryas selector. Previously, this check was incor-
rect, 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 results 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 sup-
port)

* #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 data-
baseas q, n, and default w and r values. This supplements the exist-
ing /{db}/_shards and /{db}/_shards/{id} detailed information on
sharding and quorum.

* #810: The replicator scheduler crashed counter gauge more reliably de-
tects replication crashes by reducing the default number of retries
from 10 to 5 (reducing the duration from 4 mins to 8 secs).

* COUCHDB-3288: Tolerate mixed clusters for the upcoming pluggable stor-
age 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 debug-
ging 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, allowing
views with a single bad reduce to build while not exhausting the
serveras 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 ex-
plicitly depend on a full index scan (such as $exists) would not re-
turn a complete result set.

* #883: Erlang time module compatibility has been improved for releases
of Erlang newer than 18.0.

* #933: 410 is now returned when attempting to make a temporary view re-
quest.

* #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, $allMatch,
which matches and returns all documents that contain an array field with
all its elements matching all the specified query criteria.

* New scheduling replicator. The core of the new replicator is a scheduler
which allows running a large number of replication jobs by switching be-
tween them, stopping some and starting others periodically. Jobs which
fail are backed off exponentially. There is also an improved inspection
and querying API: _scheduler/jobs and _scheduler/docs:

* _scheduler/jobs : This endpoint shows active replication jobs. These
are jobs managed by the scheduler. Some of them might be running, some
might be waiting to run, or backed off (penalized) because they crashed
too many times. Semantically this is somewhat equivalent to _ac-
tive_tasks but focuses only on replications. Jobs which have completed
or which were never created because of malformed 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 represents 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 tran-
sient states like triggered or error anymore, instead _scheduler/docs API
should be used to query replication document states.

Other scheduling replicator improvements
* Network resource usage and performance was improved by implementing 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 control
algorithm.

* Improved performance by having exponential backoff for all replication
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. Currently
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 eventually recovers,
replications reach their retry limit, stop retrying 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 automatically.

* 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 ex-
ponentially. 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% re-
duction in memory usage during replication of DBs with large attach-
ments)

* COUCHDB-2964: Investigate switching replicator manager change feeds to
using anormala instead of alongpolla

* COUCHDB-2988: (mango) Allow query selector as changes and replication
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. aOn a modern linux system with SSD, we see improvements
up to 15x.a

* COUCHDB-3063: astale=oka option replaced with new astablea and aup-
datea 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 log-
ging

* COUCHDB-3242: Make get view group info timeout in couch_indexer con-
figurable

* COUCHDB-3249: Add config to disable index all fields (text indexes)

* COUCHDB-3251: Remove hot loop usage of filename:rootname/1

* COUCHDB-3284: 8Kb read-ahead in couch_file causes extra IO and binary
memory usage

* COUCHDB-3298: Optimize writing btree nodes

* COUCHDB-3302: (Improve) Attachment replication over low bandwidth net-
work 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 doesnat 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 config-
urable

* #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 clickjacking

* #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 atruea

* (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 headers
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 aAccess-Control-Request-Headersa
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&heart-
beat=30000

* COUCHDB-3168: Replicator doesnat handle well writing documents to a tar-
get 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 multi-
part/related requests

* COUCHDB-3178: Fabric does not send message when filtering lots of docu-
ments

* COUCHDB-3181: function_clause error when adding attachment to doc in
_users db

* COUCHDB-3184: couch_mrview_compactor:recompact/1 does not handle errors
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 doesnat account for an already mal-
formed 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 during
document creation

* COUCHDB-3231: Allow fixing usersa 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 Coffee-
Script view server)

* COUCHDB-3255: Conflicts introduced by recreating docs with attachments

* COUCHDB-3259: Donat trap exits in couch_file

* COUCHDB-3264: POST to _all_docs does not respect conflicts=true

* COUCHDB-3269: view response can ahanga with filter and limit specified

* COUCHDB-3271: Replications crash with akabooma 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 mak-
ing progress

* COUCHDB-3293: Allow limiting length of document ID (for CouchDB proper)

* COUCHDB-3305: (mango) donat crash with invalid input to built in reducer
function

* COUCHDB-3362: DELETE attachment on non-existing document creates the doc-
ument, rather than returning 404

* COUCHDB-3364: Donat 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 up-
dated

* 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 fabricas 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 aBad Requesta 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 replication
between multiple, distinct CouchDB servers, configure a cluster of
CouchDB nodes. These nodes will use an optimized Erlang-driven ainternal
replicationa to ensure data durability and accessibility. Combine a clus-
tered CouchDB with a load balancer (such as haproxy) to scale CouchDB out
horizontally. More details of the clustering feature are available in the
Cluster Management.

* Futon replaced by brand-new, completely re-engineered Fauxton interface.
URL remains the same.

* The new Mango Query Server provides a simple JSON-based way to perform
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, _index 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 magni-
tude (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 per-
formance boost.

* The global changes feed has been enhanced. It is now resumable and per-
sistent.

* New endpoints added (documentation forthcoming):

* /_membership shows all nodes in a cluster

* /_bulk_get speeds up the replication protocol over low-latency connec-
tions

* /_node/ api to access individual nodesa 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.

* aBackenda 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 Microsoft
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 con-
fig 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 intro-
duction of the clustering feature. Specifically, make note of the differ-
ence 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 defin-
ition. This is due to design document caching, which may take a few sec-
onds 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 of-
ficial 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 docu-
ment 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 aremotea source or
target

2. A database name (e.g., db1), called a alocala 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 alocala 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 multiple
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 pur-
poses 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 clustered
interface.

* #656: The OAuth 1.0 support is broken and deprecated. It will be removed
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 compli-
ance 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 specified.

* 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 system.

* 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 aTest Suitea 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 issues.

HTTP Server
* COUCHDB-2430: Disable Nagleas algorithm by default.

* COUCHDB-2583: Donat drop connection by the endpoints which doesnat 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_authentication_han-
dler to follow the *_authentication_handler form of all other handlers. The
old proxy_authentification_handler name is marked as deprecated and will be
removed in future releases. Itas strongly recommended to update httpd/au-
thentication_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, in-
cluding switching the code editor from CodeMirror to Ace as well as bet-
ter 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 sin-
gle 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 settings
are well-formed. #dbe769c6

* COUCHDB-1922: fix CORS exposed headers. #4f619833

* Rename proxy_authentification_handler to proxy_authentication_handler. -
#c66ac4a8

* COUCHDB-1795: ensure the startup script clears the pid file on termina-
tion. #818ef4f9

* COUCHDB-1962: replication can now be performed without having write ac-
cess to the source database (#1d5fe2aa), the replication checkpoint in-
terval 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 docu-
ment with a different ID than the one suggested by Futon. #4906b591

* COUCHDB-1923: add support for attachments and att_encoding_info options
(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 releases
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 sin-
gle 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 ex-
perimental 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 community 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. Up-
grading 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: itas 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 creation,
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 vali-
date_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. Upgrad-
ing to a more recent release is strongly recommended.

Upgrade Notes
You can upgrade your existing CouchDB 1.0.x installation to 1.3.0 without
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 version 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 mi-
grated 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 _replicator
docs. #869f42e2

Log System
* COUCHDB-1794: Fix bug in WARN level logging from 1.3.0.

* Donat 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 duplica-
tion.

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 wonat allow you to save original view af-
ter 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
doesnat 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 resource
(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 charac-
ters 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 updated
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 re-
cursive 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 documents
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 sys-
tem dbs, #41667642f7

Replicator
* COUCHDB-1248: HTTP 500 error now doesnat 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 already
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 embed-
ded /as, 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 validate_doc_up-
date functions.

* COUCHDB-1372: _stats built-in reduce function no longer produces error
for empty view result.

* COUCHDB-1444: Fix missed_named_view error that occurs on existed design
documents and views. #b59ac98b

* COUCHDB-1445: CouchDB tries no more to delete view file if it couldnat
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 Windows.
#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 introduced
in version 0.9.0. Compact your older databases (that have not been com-
pacted for a long time) before upgrading, or they will become inaccessi-
ble.

WARNING:
Version 1.2.1 contains important security fixes. Previous 1.2.x releases
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 authen-
ticated user that created them.

* Non-owner users will not see confidential information like passwords 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 creation
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 local.ini
[couchdb] section, but the on-disk format will still be upgraded.

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 fail-
ures due to bogus rewrite limit reports.

Version 1.2.1
Build System
* Fix couchdb start script.

* Win: fix linker invocations.

Futon
* Disable buttons that arenat 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 alter-
native 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 pub-
licly readable.

* Password hashes are now calculated by CouchDB. Clients are no longer re-
quired 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 awith-js-include and awith-js-lib options.

* Added awith-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 continuous 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 configu-
ration 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 al-
lows 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 instead
of the original replication object/document.

Storage System
* Added optional database and view index file compression (using Googleas
snappy or zlibas deflate). This feature is enabled by default, but it can
be disabled by adapting local.ini accordingly. The on-disk format is up-
graded 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 sup-
porting metadata, both for database and view index files. This informa-
tion 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 con-
figurable.

* Added support for automatic database and view compaction. This feature is
disabled by default, but it can be enabled via the .ini configuration.

* 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 parameters.

* 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 releases
are not recommended for regular usage.

Version 1.1.2
Build System
* Donat 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 doc-
ument.

* Fix retrieval of headers larger than 4k.

* Allow OPTIONS HTTP method for list requests.

* Donat 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 afiltera 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 atext/javascripta 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 ainfinitya.

* 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 achange passworda-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 aNaglea.

* 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 aQ valuesa and media parameters in HTTP Ac-
cept 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 attachments.

* 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 after
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 a backporting so that 0.10.x
can replicate to 1.0 wouldnat be that hard. All that is required is patch-
ing 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 application/json.

* JSONP is disabled by default. An .ini option was added to selectively en-
able it.

* The key, startkey and endkey properties of the request object passed to
list and show functions now contain JSON objects representing the URL en-
coded string values in the query string. Previously, these properties
contained strings which needed to be converted to JSON before using.

WARNING:
Version 1.0.4 contains important security fixes. Previous 1.0.x releases
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 randomly
selected port so they wonat 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 in-
clude_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 lo-
cal-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 con-
fig.

* Fix error when the ibrowse connection closes unexpectedly.

* Fix authenticated replication (with HTTP basic auth) of design documents
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 data-
bases.

* Fix occasional error when writing to a database that has just been com-
pacted.

* 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 parame-
ters.

* 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 du-
plicated 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
* Donat 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 prevent
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 re-
leases 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 application/json.

* JSONP is disabled by default. An .ini option was added to selectively en-
able 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 con-
tains the member method with the specified HTTP method of the current re-
quest. Previously, this member was called verb. method is following 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 admins 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 en-
tire 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 excep-
tion, 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 E4Xas XML objects will not automatically be stringi-
fied. 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 pop-
ups which result from sending the WWW-Authenticate header. To enable ba-
sic-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 performance for common
operations. It also gives more flexibility to query server implementers and
shouldnat 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, instead
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 ^ahelp 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 aexpando linksa 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() wasnat 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
* Donat require a revpos for attachment stubs.

* Added checking to ensure when a revpos is sent with an attachment stub,
itas correct.

* Make file deletions async to avoid pauses during compaction and db dele-
tion.

* 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 amake dista.

* Bug fix for building couch.appas 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 position.

* 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-overlap-
ping 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 validation
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 arawa 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. Example
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 re-
leases are not recommended for regular usage.

Modular Configuration Directories
CouchDB now loads configuration from the following places (glob(7) syntax)
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 sequence.

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 extra
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 provide
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 ^acount^a to ^alimit^a
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 up-
date 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 Precondition 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 configura-
tion files. Old .ini files wonat work. Also note that CouchDB now ships
with two .ini files where 0.8 used couch.ini there are now default.ini and
local.ini. default.ini contains CouchDBas standard configuration values.
local.ini is meant for local changes. local.ini is not overwritten on
CouchDB updates, so your edits are safe. In addition, the new runtime con-
figuration system persists changes to the configuration in local.ini.

Version 0.9.2
Build and System Integration
* Remove branch callbacks to allow building couchjs against newer versions
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 security.

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 considered
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 areva 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 Mul-
tilingual 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 modification
of option values.

* Added a JSON asource viewa for document display.

* JSON data in view rows is now syntax highlighted.

* Removed the use of an iframe for better integration with browser history
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 developer
controlled content-types.

* Attachment names may use slashes to allow uploading of nested directories
(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 problems
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 arenat 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 Explorer
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 mul-
tiple TCP packets, which caused problems with the test suite under Sa-
fari, 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 request.
(COUCHDB-55)

* CouchDB can now be bound to IPv6 addresses.

* The HTTP Server header now contains the versions of CouchDB and Erlang.

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 engine.
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 docu-
ments 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) instead
of by media type.

* Automatically generated document IDs are now based on proper UUID genera-
tion 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 dialog. The
name is automatically put into edit mode so that it can be changed imme-
diately.

* 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 descending
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 com-
paction. (COUCHDB-38)

* Fixed portential double encoding of document IDs and other URI segments
in many instances. (COUCHDB-39)

* Improved display of attachments.

* The JavaScript Shell has been removed due to unresolved licensing issues.

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 in-
terpreter embedding API.

* View functions using the default JavaScript view server can now do log-
ging using the global log(message) function. Log messages are directed
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 implemen-
tation. Among other things, this means that the extra configuration 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 with-
out 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 persistent
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 un-
derscore) now return a unknown_private_path error instead of the confus-
ing 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 lan-
guage 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 timing
attacks, also known as side-channel information leakage, due to using sim-
ple break-on-inequality string comparisons when verifying hashes and pass-
words.

Mitigation
All users should upgrade to CouchDB 0.11.0. Upgrades from the 0.10.x se-
ries 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 development
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 CouchD-
Bas 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 anonymous.

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 Fu-
ton, CouchDBas web-based administration UI, a malicious site can execute
arbitrary code in the context of a useras browsing session.

Credit
This XSS issue was discovered by a source that wishes to stay anonymous.

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 including
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 mechanisms. 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 included 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 compo-
nent.

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_handlers/fav-
icon.ico and httpd_global_handlers/_utils lines within httpd_global_han-
dlers:

[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 Adobeas 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 vulnerable,
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 donat enable it since itas 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 execute
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 Founda-
tion 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 resourceas count query parameter is able to take unreasonable
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 restart-
ing 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 CouchDBas 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 database,
including the special case _admin role, that denotes administrative users.
In combination with CVE-2017-12636 (Remote Code Execution), this can be
used to give non-admin users access to arbitrary shell commands 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 con-
sult 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 doc-
ument write, but the first roles key is used for subsequent authorisation
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 Erlang,
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, includ-
ing downloading and executing scripts from the public 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 con-
sult with upgrade notes.

Credit
This issue was discovered by Joan Touzet of the CouchDB Security team dur-
ing the investigation of CVE-2017-12635.

CVE-2018-11769: Apache CouchDB Remote Code Execution
Date 08.08.2018

Affected
Apache CouchDB 1.x and ax2.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 configuration set-
tings via the HTTP API, it is possible for a CouchDB administrator user to
escalate their privileges to that of the operating systemas 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 seamless.

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 possible
by removing the _config route from the default.ini file, as follows:

[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-configuration
of key components of the database. In some cases, this led to vulnerabili-
ties where CouchDB admin users could access the underlying operating system
as the CouchDB user. Together with other vulnerabilities, 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 fixing
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 components
at runtime. While some flexibility is needed for speciality configurations
of CouchDB, the configuration was changed from being available 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 seamless.

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 configuration set-
tings via the HTTP API, it is possible for a CouchDB administrator user to
escalate their privileges to that of the operating systemas user that
CouchDB runs under, by bypassing the backlist 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 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 con-
sult 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 require_valid_user_ex-
cept_for_up. It was meant as an extension to the long-standing setting re-
quire_valid_user, which in turn requires that any and all requests to
CouchDB will have to be made with valid credentials, 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 enforcing
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 interface 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 at-
tachment, _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 configuration
options to turn Content-Security-Policy headers on for all affected re-
quests.

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 without
authenticating and gain admin privileges.

1. CouchDB opens a random network port, bound to all available interfaces
in anticipation of clustered operation and/or runtime introspection. 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 authenticates
any communication between Erlang nodes.

The CouchDB documentation has always made recommendations for properly se-
curing 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 vul-
nerable.

Mitigation
CouchDB 3.2.2 and onwards will refuse to start with the former default er-
lang cookie value of monster. Installations that upgrade to this versions
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 doesnat 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 ex-
pose 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, in-
sert the session as an external resource (such as an image), or store the
credential in a _local document with an aupdatea function.

For the attack to succeed the attacker has to be able to insert the design
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;
}
a
+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 objectas 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 eliminating
security problems and denial of service attacks against Apache CouchDB.

We strongly encourage folks to report such problems to our private security
mailing list first, before disclosing them in a public forum.

Please note that the security mailing list should only be used for report-
ing undisclosed security vulnerabilities in Apache CouchDB and managing the
process of fixing such vulnerabilities. We cannot accept regular bug re-
ports 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 isnat an undisclosed security vulnerabil-
ity, 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 attacks,
and we cannot promise magic workarounds to generic problems (such as a
client streaming lots of data to your server, or re-requesting 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. Weall 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 donat have a GitHub account yet, it is a good time to get one, they
are free. If you donat want to use GitHub, there are alternate ways to con-
tributing back, that weall cover next time.

Go to https://github.com/apache/couchdb and click the aforka button in the
top right. This will create a fork of CouchDB in your GitHub account. If
your account is username, your fork lives at -
https://github.com/username/couchdb. In the header, it tells me my aGitHub
Clone URLa. We need to copy that and start a terminal:

$ git clone https://github.com/username/couchdb.git
$ cd couchdb/src/docs
$ subl .

Iam opening the whole CouchDB documentation source tree in my favourite ed-
itor. 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 docu-
mentation. We can look through http://docs.couchdb.org/en/latest/ for in-
spiration. The JSON Structure Reference looks like a fine place to write
this up.

The current state includes mostly tables describing the JSON structure (af-
ter all, thatas the title of this chapter), but some prose about the number
representation canat hurt. For future reference, since the topic in the
thread includes views and different encoding in views (as opposed to the
storage engine), we should remember to make a note in the views documenta-
tion as well, but weall leave this for later.

Letas try and find the source file that builds the file -
http://docs.couchdb.org/en/latest/json-structure.html a we are in luck, un-
der share/doc/src we find the file json-structure.rst. That looks promis-
ing. .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, documentation
in this case. Letas 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, letas 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. Letas mark them up. Weall 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 documenta-
tion entry as opposed to a post on a mailing list.

The next step would be to validate that we got all the markup right. Iall
leave this for later. For now weall 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 aPull Requesta button. Fill in the description with something
useful and hit the aSend Pull Requesta button.

And weare 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 com-
pliance 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 exceptions.
The best style is the one that is followed because it seems to be the nat-
ural way of doing it.

The guidelines
The guidelines are in descending priority.

1. Syntax

* Correct syntax is always more important than style. This includes con-
figuration 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 de-
scending 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 May 11, 2026 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.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation