What are CouchDB attachments and when would you use them?

Attachments in CouchDB are binary blobs stored directly alongside a document under the reserved _attachments key. Each attachment has a filename, a MIME content type, byte length, and an MD5 digest. They are stored in the same database file as the document but transferred separately — a GET on the document returns only metadata stubs by default, not the binary payload.

# Attach a PDF to an existing document (must supply current _rev)
curl -X PUT \
  "http://admin:pass@localhost:5984/contracts/contract:1001/agreement.pdf?rev=2-abc" \
  -H "Content-Type: application/pdf" \
  --data-binary @agreement.pdf
# {"ok":true,"id":"contract:1001","rev":"3-xyz"}

# Fetch just the raw binary
curl http://admin:pass@localhost:5984/contracts/contract:1001/agreement.pdf

# Inline all attachment data in the document response
curl "http://admin:pass@localhost:5984/contracts/contract:1001?attachments=true"

Good use cases for attachments:

• Small binary files that must replicate alongside their parent document — thumbnails, QR codes, small PDFs.
• Offline-first mobile apps using PouchDB where images must sync alongside document metadata.

When to avoid them: Each attachment write bumps the document's _rev, making concurrent updates prone to 409 conflicts. Large attachments (over ~1 MB) bloat the database file and increase compaction time significantly. For large media, store the file in an object store (S3, MinIO, Cloudflare R2) and keep only the URL in the CouchDB document.