Database Scaling

      Databases can be multi-dimensionally scaled by adding or removing service instances and whole services, and by adjusting service instance sizes.

      This page will walk you through multi-dimensional database scaling. It includes information about database services, rebalancing, statuses, events, and jobs.

      The dimensions of multi-dimensional scaling are:

      1. Adding and removing service instances

      2. Increasing and decreasing the size of service instances

      3. Adding and removing whole services

      Database Services

      Couchbase databases comprise multiple independent services. Database capacity is determined by the capacity of each service running on the database. Scaling a database means scaling the capacities of each service. Capella sets up services on a per-node basis. Each node runs one instance of a service.

      You can determine the capacity of an individual service by multiplying these factors:

      • The number of instances, or nodes, that make up a service

      • The size of those instances, including VM instance type and storage.

      Each of these factors can be independently scaled. Adding additional instances to a service is scaling out. Increasing the size of a service’s instances is scaling up. Removing instances is scaling in. Reducing the size of instances is scaling down. These scaling techniques, together with the ability to add and remove whole services within a database, enable multi-dimensional scaling.


      Many of the scaling actions result in the addition or removal of nodes from a database. Even changing a service instance size adds new nodes to the database, since Capella swaps out the underlying virtual machines for new ones. After performing any of these procedures, the database rebalances to accommodate the new number of active member nodes.

      Database rebalance is a process that’s required for redistributing data and indexes among available nodes whenever nodes are added or removed. During rebalance, the database continues to service requests for data while the database map is correspondingly updated and distributed to clients.

      Capella maintains consistent availability and performance during rebalancing. See the rebalance documentation to learn about how each service behaves during a rebalance. It can help you assess the impacts of this process on your deployments.

      Storage Auto-Expansion

      Storage Auto-Expansion is available on AWS and GCP only.

      Couchbase Capella’s Storage Auto-Expansion automatically expands your storage capacity. When your usage exceeds 75%, the system triggers a 50% increase in storage capacity. At the same time, Capella also adjusts the IOPS to match the recommended default IOPS for the new storage capacity. When the existing IOPS value is already above the recommended default IOPS value for the new storage capacity, the IOPS value remains unchanged. Use Auto-Expansion to prevent downtime and service interruptions from running out of storage capacity.

      Storage Auto-Expansion manages the entire scaling process and underlying infrastructure changes without manual intervention.

      When creating a new database, the Auto-Expansion toggle is on by default, and you can’t turn it off. With Storage Auto-Expansion turned on, Couchbase bills you only for the additional storage capacity when the limit increase triggers.

      • Couchbase recommends turning on Storage Auto-Expansion for existing production databases.

      • If you have questions about Storage Auto-Expansion for your database, contact Support.

      To minimize the risk of disruptions to your database, it’s critical to carefully review all cloud provider limitations and plan accordingly before making any changes to your storage configuration. Additionally, monitor your systems closely after making adjustments to ensure they function as expected.

      AWS Storage Scaling Limitations

      If you’re hosting your database on AWS, you must be aware of the storage scaling limitations. You can only change your IOPS or increase storage capacity once every 6 hours. For more information about storage scaling limitations, see the AWS Limitations Documentation.

      If you need to scale your storage during these 6 hours, Capella replaces and rebalances the nodes. Rebalancing can result in data movement and slower performance depending on the size of your data and available computing resources.

      auto expansion toggle off
      AWS and GCP do not allow a decrease in storage capacity. However, Couchbase Capella allows for manual decreases in storage capacity by replacing and rebalancing nodes. While this approach provides greater flexibility, it can result in data movement and a slower process depending on the size of your data and available computing resources. As such, it’s essential to carefully consider the impact of decreasing storage capacity before making any changes to ensure the stability and performance of your systems are not compromised.

      IOPS Defaults

      The following tables contain recommended default IOPS values for AWS gp3, AWS io2, and Azure Ultra Disk. These defaults are based on disk utilization for typical enterprise workloads. When creating or modifying a database and choosing a storage option, Capella uses these defaults for the IOPS field. You can replace the default IOPS value with one higher than the default but not lower.

      Couchbase recommends that you review your current IOPS values for your existing databases against these default values.
      Table 1. AWS gp3 and io2
      Storage Size Range (GB) IOPS





















      1000 & Up


      Table 2. Azure Ultra Disk
      Storage Size Range (GB) IOPS









      1024 & Up


      Database Scaling Statuses

      When you create, delete, or modify a database, you can see its status when you open its project.

      Check the database statuses
      Figure 1. List of databases in a project

      A database satus can be:

      • Deploying

      • Deployment Failed

      • Healthy

      • Unhealthy

      • Scaling

      • Scaling Failed

      • Rebalance Failed

      • Destroying

      • Destroy Failed

      Database Events

      You can find a list of all your database events by opening the Activity Log:

      1. With the Projects tab in your organization open, select the project with the database you’re working with.

      2. With the Databases tab open, select your database.

      3. Click the Settings tab.

      4. In the navigation menu, click Activity Log.

      database activity log
      Figure 2. Database Activity Log

      When scaling your database, you’ll see these events:

      • A Cluster Configuration Updated event when you first request any changes.

      • A Cluster Scaling Complete event when Capella has finished applying the new configuration.

      See Also