neighbourhoodie-nnh-logo

Binary Attachments in CouchDB posted Thursday, October 30, 2025 by The Neighbourhoodie Team CouchDBDataTip

CouchDB is known for JSON documents and distributed syncing. But it also handles binary attachments like images, PDFs and other files, directly in the database. This means you don’t really need an external file storage to keep your documents and relevant files together, simplifying the document management process.

Storing Files in CouchDB

Usually you would need to store the user uploads in an object store like S3 or on a separate file server. This adds additional complexity of permissions, synchronisation, maintenance and so on. With CouchDB, you can embed files directly in the document as attachments. No need to maintain parallel or extra dependencies.

Think of CouchDB attachments as email attachments: arbitrary binary data identified by a name, a content-type and data size. This is mainly meant for small binary data, like user avatars or small to medium-sized images, rather than full-fledged arbitrarily sized binary storage like a file-system.

Limits

Binary attachments in CouchDB are practical but not limitless. Here are a few things to keep in mind:

  • Document size: Even though attachments are affected by the max_document_size limit, performance and replication speed can be slowed down with larger document sizes. That’s why we recommend smaller documents.
  • Replication: As mentioned in the point earlier, larger attachments — typically more than 10MB — can slow the replication process. We recommend you keep attachments small too.
  • General: Attachments are great for small to medium content (profile pictures, documents) but are not optimal for large media (DVD images, video libraries).

Use Cases

  • Profile pictures: small images that belong to the user document.
  • Documents: reports, invoices, receipts, PDFs or similar records.
  • Logos, icons: logos and icons used in apps.

Adding Attachments

Attachments can be added and fetched through cURL or Fauxton:

Using cURL

To upload an attachment you can run the following command. You can get the rev value by running curl -X GET http://127.0.0.1:5984/testdb/doc1

This will store the photo.jpg as an attachment of document doc1.

Using Fauxton

In Fauxton you can open the specific document you want to make the edits to. Then select Upload Attachment to add the required content.

This screenshot snippet shows the “Upload Attachment” button visible on the horizontal navigation in Fauxton when viewing a single document.

In this screenshot the “Upload Attachment” dialog is shown, with a “Choose File” button and a field to show the selected file. It’s also informs users that “Uploading a file saves the document as a new revision.”

Once saved CouchDB automatically serves the attachment via a URL like so http://localhost:5984/testdb/doc1/myphoto.jpg. This can be used directly in an application image tag or download link.

Base64 vs Binary Blobs

When it comes to attachments, it’s helpful to familiarise ourselves with the attachment encoding types: binary blobs and base64. Binary blobs are the raw data itself whereas base64 is a way of encoding binary data into a long text string limited to a set of 64 unique characters.

In CouchDB attachments are always stored in binary format on disk. However a base64 option is available if you wish to upload or retrieve an attachment. To do so simply pass attachments=true with your request. For example to retrieve a document with attachments as base64 run

Note that using base64 encoding increases data size by roughly 33%. This increases the amount of data transferred and load on the network and also requires ability to encode/decode on the client. However it has no effect on the data that is stored, as data is base64-decoded before writing to disk.

Here are a few use cases where you would use base64 inline attachments:

  • When you want to update the document and the attachments in a single request. This saves time and it means the document is never in an ‘intermediate’ state where its fields are updated but not its attachments. This is important for consistency.
  • When your client or API requires binary data and it is safe to transmit in text-based base64 formats.

For other purposes it is easier to use binary data for efficiency.

Tips From Experience

Here are some practical tips on using attachments in CouchDB:

  • Client-side rendering: If an user uploads images, resize or compress them client-side in the browser or mobile app before saving. This reduces bandwidth, storage, and replication time.
  • Leverage URLs: Since CouchDB serves attachments over HTTP you can access attachments via an easily composable URL. This can be directly used in href, src attributes etc. without the need for any extra API.
  • PouchDB support: Attachments work seamlessly with PouchDB without any need for additional setup.
  • Storage: In smaller projects, internal tools and prototypes, you can use attachments instead of AWS Buckets or similar storage offerings and, as we saw above, enjoy the benefit of leveraging URLs to fetch them.

Binary attachments on CouchDB is a powerful feature that helps to maintain documents and their related files together in a consistent system that makes syncing a breeze. For user-facing apps requiring simple attachments, binary attachments are a perfect fit. By understanding the trade-offs and using the tips mentioned you can make the most out of attachments.

« Back to the blog post overview
og-image-preview