Storage Engines

      Couchbase supports two different backend storage mechanisms: Couchstore and Magma. It is important to understand which backend storage is best suited to your requirements.


      Couchstore is the default bucket storage engine. It is optimized for high performance with large data sets, while using fewer system resources (the minimum bucket size for the Couchstore backend is 100 MB). If you have a small data set that can fit in memory, then you should consider using Couchstore.


      Magma is designed for high performance with very large datasets that do not fit in memory. It is ideal for use cases that rely primarily on disk access. The performance of disk access will be as good as the underlying disk sub-systems — for example, using NVMe SSDs will give higher performance.

      In order to get maximum performance from Magma for disk-oriented workloads, it is recommended to set the Writer Threads to Disk i/o optimized. This setting will ensure there are enough threads to sustain high write rates.

      To learn more about Writer Thread settings, see Data Settings

      Magma can work with very low amounts of memory for large datasets: a minimum memory-to-data ratio of 1% is required. For example, if a node is holding 5 TB of data, Magma can be used with only 64 GB RAM.

      Table 1. Magma Supported Services
      Couchbase Version Services Supported

      Version 7.1

      Query, Index, XDCR, Backup

      Version 7.1.2 and Higher

      Search, Eventing, Analytics[1]


      If these services are required in versions prior to 7.1.2, Couchstore should be used.

      Couchstore and Magma at a Glance

      Couchstore Magma

      Minimum bucket memory quota

      100 MB

      1 GB[1]

      Minimum memory to data ratio



      Maximum data per node

      3 TB

      10 TB


      Magma’s minimum memory requirement is higher at 1GB per node due to the more complex data structures it has to maintain.

      When should you use Couchstore?

      The choice of Couchstore or Magma is set at the bucket level when the bucket is created. A single Couchbase cluster can have a mix of Couchstore and Magma buckets.

      You should use the Couchstore backend if:

      • You have a dataset with a working set that will fit into available memory (and the working set is > 20%).

      • You are running the Couchbase server on low-end hardware.

      • You are running a version prior to 7.1.2, and your bucket needs to support the Search, Eventing, or Analytics Service.

      • You are running the legacy MapReduce Views Service, which will not run on Magma storage.

      When should you use Magma?

      You should use the Magma backend if:

      • Your working set is much larger than the available memory, and you need high disk-access speed.

      • You need to store and access large amounts of data (several terabytes) using a small amount of memory.

      • Your applications make heavy use of transactions with persistence-based durability.

      Migrating Between Storage Engines

      You can migrate a bucket to use a different storage engine. Consider migrating a bucket if it no longer meets the criteria explained in the previous sections. For example, suppose you have a bucket using the Couchstore backend that has grown to the point where it no longer fits in memory. In this case, you should migrate the bucket to use Magma as a storage backend.

      To learn how to migrate a bucket’s storage backend, see Migrate a Bucket’s Storage Backend.