CouchDB - Attaching Files

CouchDB - Attaching Files to Documents

A powerful feature of CouchDB is the ability to attach binary files (like images, PDFs, or any other file type) directly to a document. This is conceptually similar to adding an attachment to an email. Each attachment has its own metadata, including its name, content type (MIME type), and size.

Method 1: Attaching Files using cURL

To attach a file, you send an HTTP PUT request to a special attachment URL. A crucial prerequisite is that you must provide the document’s current revision ID (_rev). This is part of CouchDB’s concurrency control to prevent data conflicts.

The syntax for attaching a file is:

curl -u USER:PASS -X PUT http://127.0.0.1:5984/db_name/doc_id/attachment_name?rev=doc_rev_id \
--data-binary @/path/to/your/file -H "Content-Type: mime/type"

Key components of this command:

• /db_name/doc_id/attachment_name: This path specifies where the attachment will be stored. attachment_name is the name the file will have inside the document (e.g., profile.jpg).
• ?rev=doc_rev_id: The document’s current revision ID is a mandatory query parameter.
• --data-binary @/path/to/your/file: This tells cURL to read the file’s content and send it as the request body.
• -H "Content-Type: mime/type": This HTTP header specifies the file’s MIME type, which is essential for browsers and applications to handle it correctly (e.g., image/jpeg).

Example: Step-by-Step

Let’s attach a file named avatar.png to a document with _id user001 in the users database.

Step 1: Get the document’s current revision (_rev).

$ curl -u admin:password -X GET http://127.0.0.1:5984/users/user001

{
    "_id": "user001",
    "_rev": "1-a9a4c9c1b9b7e7e8a9f6b4d3a0c5e7b1",
    "name": "John Doe",
    "email": "john.doe@example.com"
}

The current _rev is 1-a9a4c9c1b9b7e7e8a9f6b4d3a0c5e7b1.

Step 2: Upload the attachment using the fetched _rev.

$ curl -u admin:password -X PUT http://127.0.0.1:5984/users/user001/avatar.png?rev=1-a9a4c9c1b9b7e7e8a9f6b4d3a0c5e7b1 \
--data-binary @avatar.png -H "Content-Type: image/png"

{"ok":true,"id":"user001","rev":"2-c3f2b7b5f0d8a9e8e7c6b5a4d9f8e6a5"}

A successful response returns {"ok": true} and provides the new revision ID for the document.

Verification

To verify the attachment, fetch the document again. You will see a new _attachments object containing metadata about the uploaded file.

$ curl -u admin:password -X GET http://127.0.0.1:5984/users/user001

{
   "_id": "user001",
   "_rev": "2-c3f2b7b5f0d8a9e8e7c6b5a4d9f8e6a5",
   "name": "John Doe",
   "email": "john.doe@example.com",
   "_attachments": {
      "avatar.png": {
         "content_type": "image/png",
         "revpos": 2,
         "digest": "md5-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6==",
         "length": 18240,
         "stub": true
      }
   }
}

Method 2: Attaching Files using Fauxton

Fauxton provides an intuitive interface for managing attachments.

• 1. Navigate to your database and open the document to which you want to add an attachment.
• 2. In the document view, look for a paperclip icon in the header bar with the tooltip ‘Upload Attachment’. Click on it.
• 3. A dialog box will appear. Click ‘Choose File’ to browse your local system and select the file you want to upload.
• 4. Once a file is selected, click the ‘Upload’ button in the dialog.
• 5. The page will refresh, and you will see the file listed under the ‘_attachments’ section of your document.

Best Practices

While convenient, storing large binary files (many megabytes) directly in CouchDB can significantly increase the database size and impact replication performance. For systems that handle very large files, a common architectural pattern is to store the files in a dedicated object storage service (like AWS S3, Google Cloud Storage, or MinIO) and only store the URL or a reference to the file in the CouchDB document. This keeps your database lean and fast.