CouchDB - Deleting a Document

CouchDB - Deleting a Document

In CouchDB, documents are not physically removed from the database file immediately upon deletion. Instead, a new revision of the document is created with a "_deleted": true flag. This is known as a ‘tombstone’. This approach is essential for replication, allowing deletions to be synced correctly across database copies. The tombstoned documents are permanently removed later during database compaction.

The Importance of the _rev Token

To delete a document, you MUST provide its current revision ID (_rev). This is a fundamental part of CouchDB’s Multi-Version Concurrency Control (MVCC). It prevents the ‘lost update’ problem by ensuring you are deleting the version of the document you think you are. If someone else updated the document between the time you fetched it and the time you tried to delete it, your _rev will be outdated, and the operation will fail.

Method 1: Using the cURL Utility

Deleting a document involves sending an HTTP DELETE request to the document’s URL, including the current ?rev= as a query parameter.

Example: Step-by-Step

Let’s delete a document with _id of product:101 from a database named inventory.

Step 1: Fetch the document to get its current _rev.

$ curl -u admin:password -X GET http://127.0.0.1:5984/inventory/product:101

{
    "_id": "product:101",
    "_rev": "1-b8f65b4f8b9f9b5c2a6f2b3e4d5e6f7a",
    "item": "Laptop Stand",
    "quantity": 25
}

The current revision is 1-b8f65b4f8b9f9b5c2a6f2b3e4d5e6f7a.

Step 2: Send the DELETE request with the correct _rev.

$ curl -u admin:password -X DELETE http://127.0.0.1:5984/inventory/product:101?rev=1-b8f65b4f8b9f9b5c2a6f2b3e4d5e6f7a

{
    "ok": true,
    "id": "product:101",
    "rev": "2-c9a8b7f6e5d4c3b2a1f0e9d8c7b6a5b4"
}

The response indicates success ("ok": true) and provides the new revision ID of the tombstone document.

Verification

If you now try to fetch the document, CouchDB will inform you that it has been deleted.

$ curl -u admin:password -X GET http://127.0.0.1:5984/inventory/product:101

{"error":"not_found","reason":"deleted"}

Common Errors

The most common error is providing an incorrect or outdated _rev. In this case, CouchDB will reject the request with a 409 Conflict error, protecting you from accidentally deleting the wrong version of a document.

// Attempting to delete with a wrong 'rev' value
$ curl -u admin:password -X DELETE http://127.0.0.1:5984/inventory/product:101?rev=1-WRONG-REV-ID

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

Method 2: Using Fauxton (The Web UI)

Fauxton provides a safe and easy way to delete documents visually.

• 1. In Fauxton, navigate to the database containing the document you wish to delete.
• 2. Click on the document’s _id in the list to open the document view.
• 3. In the header bar above the document’s content, you will see several icons. Click the trash can icon.
• 4. A confirmation dialog will pop up, asking ‘Are you sure you want to delete this document?’.
• 5. Click the ‘Delete’ button to confirm. The document will be deleted, and you will be returned to the database view.