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.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.