CouchDB – Update Document

To update an existing document in a CouchDB database, send an HTTP PUT request containing the document’s current _rev value. You can also edit and save the document through the CouchDB Fauxton web interface.

CouchDB uses revisions to prevent one client from accidentally overwriting changes made by another client. For this reason, an update normally requires the latest revision value returned by CouchDB.

CouchDB Update Document REST API Syntax

Send a HTTP PUT request with the following URL.

http://hostname/database_name/new_document_id/

For an update, the final path segment is the ID of the existing document. The general HTTP request format is:

</>
Copy
PUT /database_name/document_id

The request body must be valid JSON and must include the current _rev value. Set the Content-Type request header to application/json.

Update Document 0005 in the tutorialkart Database

We have our CouchDB running in our localhost. Hence, we shall use 127.0.0.1:5984 as hostname.

We will use an existing database named tutorialkart.

Let us update document with id 0005.

The resulting request URL that we have to use for PUT request will become,

http://127.0.0.1:5984/tutorialkart/0005/

Send all the fields with the updated values or original values along with _rev field.

 {
   "_rev": "1-8a00a24fcd8e1fbf9922c489df210f38",
   "topic": "PostgreSQL Tutorial",
   "category": "RDBMS",
   "topics": 22
 }

A document update replaces the stored JSON body with the JSON body supplied in the PUT request. Therefore, include every existing application field that you want to keep. Any existing field omitted from the request body will no longer be present in the updated document.

You can get the current _rev field value by sending a GET request for the document. For details, refer to CouchDB – GET Document.

We will use Postman to trigger a PUT request with the URL and JSON body. In Postman, select PUT, set the body type to raw JSON, add the current revision, and send the request. You can use another REST client or a command-line tool instead.

CouchDB - Update Document

CouchDB Successful Update Response

When CouchDB accepts the update, it returns a success response containing the document ID and a new revision value. A typical response has the following structure:

{
  "ok": true,
  "id": "0005",
  "rev": "2-new-revision-value"
}

The exact revision string is generated by CouchDB. Store or retrieve the new revision before sending another update to the same document.

Update a CouchDB Document with curl

The following command updates document 0005 from a terminal. Replace the example revision with the current _rev value returned by your CouchDB server.

</>
Copy
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "_rev": "1-8a00a24fcd8e1fbf9922c489df210f38",
    "topic": "PostgreSQL Tutorial",
    "category": "RDBMS",
    "topics": 22
  }' \
  http://127.0.0.1:5984/tutorialkart/0005

If authentication is enabled, supply valid credentials using the authentication method configured for the server. Avoid placing production passwords directly in reusable scripts or shell history.

Verify the Updated CouchDB Document

Let us check if the document is updated.

Send a HTTP GET Request with the same URL as above.

CouchDB - Updated Document

The document has been updated. CouchDB returns the document as JSON, including its latest _rev value. Every accepted update creates a new document revision, so the previous revision value cannot be reused for a later update.

CouchDB Revision Conflict During an Update

If the request contains a missing or outdated revision, CouchDB rejects the update with an HTTP 409 Conflict response. The error commonly resembles:

{
  "error": "conflict",
  "reason": "Document update conflict."
}

To resolve the conflict, retrieve the latest version of the document, review any changes made by another request, apply your intended changes to that version, and send the update again with the latest _rev.

CouchDB Update Document Response Codes

  • 201 Created: CouchDB accepted the update and created a new document revision.
  • 202 Accepted: The update was accepted under a configuration where the write was not immediately committed to disk.
  • 400 Bad Request: The request body is invalid JSON or the request is otherwise malformed.
  • 401 Unauthorized: Authentication is required or the supplied credentials are invalid.
  • 403 Forbidden: The user is not permitted to update the document.
  • 404 Not Found: The database does not exist.
  • 409 Conflict: The supplied revision is missing, outdated, or does not match the current document revision.
  • 415 Unsupported Media Type: The request body was sent without a supported JSON content type.

Update a CouchDB Document in Fauxton

You can also update document in CouchDB database using Web Interface.

Open URL http://hostname/_utils/ in your browser. In this example, the URL will be http://127.0.0.1:5984/_utils/.

Click on Databases tab present in the left panel. Click on the database in which you would like to update the document. To view the document, open Table view and click on the document.

When you click on the document, an editor will be opened with the JSON document.

Change the required field values without removing fields that should remain in the document. In this example, change the topics field and select Save Changes.

CouchDB - Update Document - CouchDB Web Interface

You would see an information popup at the top saying ‘Saving Document.‘

CouchDB - Saved Document

The document details are updated. Fauxton also displays the new _rev value created by CouchDB for the saved revision.

CouchDB Update Document FAQs

Why is _rev required when updating a CouchDB document?

The _rev value tells CouchDB which document revision the client intends to replace. CouchDB compares it with the current revision and rejects stale updates to prevent silent overwrites.

Does CouchDB PUT update only the fields included in the request?

No. A document-level PUT replaces the stored document body. Include all application fields that must remain after the update, together with the current _rev.

What causes a CouchDB document update conflict?

A conflict occurs when the supplied revision does not match the current revision, usually because another request updated the document after it was read. Fetch the latest document and retry after reconciling the changes.

Can the document ID be changed during an update?

No. The document ID identifies the resource in the URL. To use a different ID, create a new document under the new ID and, when appropriate, delete the old document separately.

CouchDB Update Document Summary

In this CouchDB Tutorial, we learned how to update a CouchDB document through the HTTP REST API and the Fauxton web interface. A REST update uses PUT /database/document_id, includes the complete document body and current _rev, and returns a new revision after a successful write.