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

      Couchbase Capella’s storage auto-expansion can prevent downtime and service interruptions by automatically expanding your storage when it starts to get full. Capella manages the entire scaling process and underlying infrastructure changes without manual intervention.

      Auto-expansion behaves differently depending on the chosen cloud provider:

      • When your usage exceeds 75% on AWS and GCP databases, Capella triggers a 50% increase in the current storage capacity. Storage increases are in place without any data movement or performance impact. To learn more about how Capella handles AWS storage change limitations, see AWS Storage Scaling Limitations.

      • When your usage exceeds 75% on Azure databases, Capella doubles the current storage capacity. Storage increases for Azure use the replacement and rebalancing of nodes, which can affect performance until the process completes. To learn more about how Capella handles Azure storage change limitations, see Azure Storage Scaling Limitations.

      When auto-expansion occurs, Capella adjusts the IOPS to match the recommended default IOPS for the new storage capacity. If an existing IOPS value is above the recommended default IOPS value for the new storage capacity, the IOPS value remains unchanged.

      When deploying a new database with AWS or GCP, storage auto-expansion is always on, and you cannot turn it off. Databases deploying with Azure have auto-expansion off by default with the option to turn it on. Before turning auto-expansion on for Azure databases, you need to consider possible performance impacts during an auto-expansion. For more information, see Azure Storage Scaling Limitations.

      With storage auto-expansion turned on, Couchbase bills you only for the additional storage capacity when the limit increase triggers.

      To minimize the risk of disruptions to your database, review all cloud provider limitations before making any storage configuration changes. Monitor your systems after making adjustments to make sure they function as expected.

      If you have questions about storage auto-expansion for your database, contact Support.

      AWS Storage Scaling Limitations

      If you’re hosting your database on AWS, you must be aware of the storage scaling limitations. AWS allows you to 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. Depending on the size of your data and available computing resources, this can affect performance until the process completes.

      Couchbase Capella does not automatically decrease storage capacity. However, 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. It’s essential to consider the effects of decreasing storage capacity before making any changes to make sure the stability and performance of your systems are not compromised.

      Azure Storage Scaling Limitations

      Auto-expansion for Azure requires replacing and rebalancing nodes, which results in data movement. Depending on the amount of your data and available computing, this may affect performance until the auto-scaling process completes.

      All Azure databases have auto-expansion turned off by default. You can turn on Azure storage auto-expansion during database creation or after you create a database. To change the storage auto-expansion settings for an existing database in the Capella UI, open the database page and click Settings  Services. Each Service Group has its own Auto-Expansion toggle.

      When a database hosted with Azure auto expands, Capella doubles the current storage up to the maximum available per node. For the maximum storage that’s available for databases hosted with Azure, see Microsoft Azure — Storage.

      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