# Using Amazon DocumentDB serverless
Amazon DocumentDB serverless is an on-demand, auto scaling configuration that automates the processes of dynamically adjusting the capacity of your Amazon DocumentDB database based on application demand. You're charged only for the resources that your clusters consume. Thus, DocumentDB serverless can help you to stay within budget and avoid paying for computer resources that you don't use.
This type of automation is especially valuable for environments with highly variable and unpredictable workloads, such as multitenant databases, distributed databases, and development and test systems.
**Topics**
+ [Serverless use cases](#docdb-serverless-use-cases)
+ [Advantages of Amazon DocumentDB serverless](#docdb-serverless-advantages)
+ [How serverless works](docdb-serverless-how-it-works.md)
+ [Serverless requirements and limitations](docdb-serverless-limitations.md)
+ [Creating a cluster that uses serverless](docdb-serverless-create-cluster.md)
+ [Migrating to serverless](docdb-serverless-migrating.md)
+ [Managing serverless](docdb-serverless-managing.md)
+ [Serverless instance limits](docdb-serverless-instance-limits.md)
+ [Serverless scaling configuration](docdb-serverless-scaling-config.md)
+ [Monitoring serverless](docdb-serverless-monitoring.md)
## DocumentDB serverless use cases
Both Amazon DocumentDB provisioned clusters and DocumentDB serverless support many types of database workloads, from development and testing environments to the most demanding, business-critical applications that require high scale and availability. But DocumentDB serverless adds another dimension to customer workloads, namely the ability to support websites and applications that have unpredictable workloads.
DocumentDB serverless is especially useful for the following use cases:
+ **Variable workloads** — You're running workloads that have sudden and unpredictable increases in activity. An example is a traffic site that sees a surge of activity when it starts raining. Another is an e-commerce site with increased traffic when you offer sales or special promotions. With DocumentDB serverless, your database automatically scales capacity to meet the needs of the application's peak load and scales back down when the surge of activity is over. With DocumentDB serverless, you no longer need to provision for peak or average capacity. You can specify an upper capacity limit to handle the worst-case situation, and that capacity isn't used unless it's needed.
+ The granularity of scaling in DocumentDB serverless helps you to match capacity closely to your database's needs. For a provisioned cluster, scaling up requires adding a whole new instance. DocumentDB serverless can add half a DCU when only a little more capacity is needed. It can add 0.5, 1, 1.5, 2, or additional half-DCUs based on the additional capacity needed to handle an increase in workload. And it can remove 0.5, 1, 1.5, 2, or additional half-DCUs when the workload decreases and that capacity is no longer needed.
+ **Multi-tenant applications** — With DocumentDB serverless, you don't have to individually manage database capacity for each application in your fleet. DocumentDB serverless manages individual database capacity for you.
+ You can create a cluster for each tenant. That way, you can use features such as cloning and snapshot restore to enhance high availability and disaster recovery as appropriate for each tenant.
+ Each tenant might have specific busy and idle periods depending on the time of day, time of year, promotional events, and so on. Each cluster can have a wide capacity range. That way, clusters with low activity incur minimal instance charges. Any cluster can quickly scale up to handle periods of high activity.
+ **New applications** — You're deploying a new application and you're unsure about the instance size you need. By using DocumentDB serverless, you can set up a cluster with one or many instances and have the database autoscale to the capacity requirements of your application.
+ **Mixed-use applications** — Suppose that you have an online transaction processing (OLTP) application, but you periodically experience spikes in query traffic. By specifying promotion tiers for the DocumentDB serverless instances in a cluster, you can configure your cluster so that the reader instances can scale independently of the writer instance to handle the additional load. When the usage spike subsides, the reader instances scale back down to match the capacity of the writer instance.
+ **Capacity planning** — Suppose that you usually adjust your database capacity, or verify the optimal database capacity for your workload, by modifying the instance classes of all the instances in a cluster. With DocumentDB serverless, you can avoid this administrative overhead. You can determine the appropriate minimum and maximum capacity by running the workload and checking how much the instances actually scale.
+ You can modify existing instances from provisioned to DocumentDB serverless or from DocumentDB serverless to provisioned. You don't need to create a new cluster or a new instance in such cases.
+ **Development and testing** — In addition to running your most demanding applications, you can also use DocumentDB serverless for development and testing environments. With DocumentDB serverless, you can create instances with a low minimum capacity instead of using burstable db.t\$1 instance classes. You can set the maximum capacity high enough that those instances can still run substantial workloads without running low on memory. When the database isn't in use, all of the instances scale down to avoid unnecessary charges.
### Using Amazon DocumentDB serverless for existing provisioned workloads
Suppose that you already have an DocumentDB application running on a provisioned cluster. You can check how the application would work with DocumentDB serverless by adding one or more DocumentDB serverless instances to the existing cluster as reader instances. You can check how often the reader instances scale up and down. You can use the DocumentDB failover mechanism to promote an DocumentDB serverless instance to be the writer and check how it handles the read/write workload. That way, you can switch over with minimal downtime and without changing the endpoint that your client applications use. For details on the procedure to convert existing clusters to DocumentDB serverless, see [Migrating to Amazon DocumentDB serverless](docdb-serverless-migrating.md).
## Advantages of Amazon DocumentDB serverless
DocumentDB serverless is intended for variable or "spiky" workloads. With such unpredictable workloads, you might have difficulty planning when to change your database capacity. You might also have trouble making capacity changes quickly enough using the familiar mechanisms such as adding instances or changing instance classes. DocumentDB serverless provides the following advantages to help with such use cases:
+ **Simpler capacity management than provisioned** — DocumentDB serverless reduces the effort for planning instance sizes and resizing instances as the workload changes. It also reduces the effort for maintaining consistent capacity for all the instances in a cluster.
+ **Faster and easier scaling during periods of high activity** — DocumentDB serverless scales compute and memory capacity as needed, with no disruption to client transactions or your overall workload. The ability to use reader instances with DocumentDB serverless helps you to take advantage of horizontal scaling in addition to vertical scaling. The ability to use DocumentDB global clusters means that you can spread your DocumentDB serverless read workload across multiple AWS Regions. This capability is more convenient than the scaling mechanisms for provisioned clusters.
+ **Cost-effective during periods of low activity** — DocumentDB serverless helps you to avoid overprovisioning your instances. DocumentDB serverless adds resources in granular increments when instances scale up. You pay only for the database resources that you consume. DocumentDB serverless resource usage is measured on a per-second basis. That way, when a instance scales down, the reduced resource usage is registered right away.
+ **Feature parity with provisioned** — You can use all DocumentDB features with DocumentDB serverless. For example, with DocumentDB serverless you can use reader instances, AWS Identity and Access Management (IAM) database authentication, and Performance Insights.
In particular, with DocumentDB serverless you can take advantage of the following features from provisioned clusters:
+ **Reader instances** — DocumentDB serverless can take advantage of reader instances to scale horizontally. When a cluster contains one or more reader instances, the cluster can fail over immediately in case of problems with the writer instance.
+ **Multi-AZ clusters** — You can distribute the DocumentDB serverless instances of a cluster across multiple Availability Zones (AZs). Setting up a Multi-AZ cluster helps to ensure business continuity even in the rare case of issues that affect an entire AZ.
+ **Global clusters** — You can use DocumentDB serverless in combination with DocumentDB global clusters to create additional read-only copies of your cluster in other AWS Regions for disaster recovery purposes.
# How Amazon DocumentDB serverless works
**Topics**
+ [Overview](#docdb-serverlerss-overviewn)
+ [Configurations for Amazon DocumentDB clusters](#docdb-serverlerss-configuration)
+ [Amazon DocumentDB serverless scaling capacity](#docdb-serverless-scaling-capacity)
+ [Amazon DocumentDB serverless scaling](#docdb-serverless-scaling)
+ [Idle state (0.5 DCUs)](#docdb-serverlerss-idle-state)
## Overview
Amazon DocumentDB serverless is suitable for the most demanding, highly variable workloads. For example, your database usage might be heavy for a short period of time, followed by long periods of light activity or no activity at all. Some examples are retail, gaming, or sports websites with periodic promotional events, and databases that produce reports when needed. Others are development and testing environments, and new applications where usage might ramp up quickly. For cases such as these and many others, configuring capacity correctly in advance isn't always possible with the provisioned model. It can also result in higher costs if you overprovision and have capacity that you don't use.
In contrast, DocumentDB provisioned clusters are suitable for steady workloads. With provisioned clusters, you choose a instance class that has a predefined amount of memory, CPU power, I/O bandwidth, and so on. If your workload changes, you manually modify the instance class of your writer and readers. The provisioned model works well when you can adjust capacity in advance of expected consumption patterns and it's acceptable to have brief outages while you change the instance class of the writer and readers in your cluster.
DocumentDB serverless is architected from the ground up to support serverless clusters that are instantly scalable. DocumentDB serverless is engineered to provide the same degree of security and isolation as with provisioned writers and readers. These aspects are crucial in multitenant serverless cloud environments. The dynamic scaling mechanism has very little overhead so that it can respond quickly to changes in the database workload. It's also powerful enough to meet dramatic increases in processing demand.
By using DocumentDB serverless, you can create an DocumentDB cluster without being locked into a specific database capacity for each writer and reader. You specify the minimum and maximum capacity range. DocumentDB scales each DocumentDB serverless writer or reader in the cluster within that capacity range. By using a Multi-AZ cluster where each writer or reader can scale dynamically, you can take advantage of dynamic scaling and high availability.
DocumentDB serverless scales the database resources automatically based on your minimum and maximum capacity specifications. Scaling is fast because most scaling events operations keep the writer or reader on the same host. In the rare cases that an DocumentDB serverless writer or reader is moved from one host to another, DocumentDB serverless manages the connections automatically. You don't need to change your database client application code or your database connection strings.
With DocumentDB serverless, as with provisioned clusters, storage capacity and compute capacity are separate. When we refer to DocumentDB serverless capacity and scaling, it's always compute capacity that's increasing or decreasing. Thus, your cluster can contain many terabytes of data even when the CPU and memory capacity scale down to low levels.
Instead of provisioning and managing database servers, you specify database capacity. The actual capacity of each DocumentDB serverless writer or reader varies over time, depending on your workload. For details about that mechanism, see [Amazon DocumentDB serverless scaling](#docdb-serverless-scaling).
## Configurations for Amazon DocumentDB clusters
For each of your Amazon DocumentDB clusters, you can choose any combination of DocumentDB serverless capacity, provisioned capacity, or both.
You can set up a cluster that contains both DocumentDB serverless and provisioned capacity, called a mixed-configuration cluster. For example, suppose that you need more read/write capacity than is available for an DocumentDB serverless writer. In this case, you can set up the cluster with a very large provisioned writer. Then you can still use DocumentDB serverless for the readers. Or suppose that the write workload for your cluster varies but the read workload is steady. In this case, you can set up your cluster with an DocumentDB serverless writer and one or more provisioned readers.
You can also set up a cluster where all the capacity is managed by DocumentDB serverless. To do this, you can create a new cluster and use DocumentDB serverless from the start. Or you can replace all the provisioned capacity in an existing cluster with DocumentDB serverless. For the procedures to create a new cluster with DocumentDB serverless or to switch an existing cluster to DocumentDB serverless, see [Creating a cluster that uses Amazon DocumentDB serverless](docdb-serverless-create-cluster.md) and [Migrating to Amazon DocumentDB serverless](docdb-serverless-migrating.md).
If you don't use DocumentDB serverless at all in a cluster, all the writers and readers in the cluster are provisioned. This is the most common kind of cluster that most users are familiar with. Provisioned capacity is constant. The charges are relatively easy to forecast. However, you have to predict in advance how much capacity you need. In some cases, your predictions might be inaccurate or your capacity needs might change. In these cases, your cluster can become underprovisioned (slower than you want) or overprovisioned (more expensive than you want).
## Amazon DocumentDB serverless scaling capacity
The unit of measure for Amazon DocumentDB serverless is the DocumentDB Capacity Unit (DCU). DocumentDB serverless scaling capacity isn't tied to the instance classes that you use for provisioned clusters.
Each DCU is a combination of approximately 2 gibibytes (GiB) of memory, corresponding CPU, and networking. You specify the database capacity range using this unit of measure. The `ServerlessDatabaseCapacity` and `DCUUtilization` CloudWatch metrics help you to determine how much capacity your database is actually using and where that capacity falls within the specified range.
At any moment in time, each DocumentDB serverless writer or reader has a capacity. The capacity is a floating-point number representing DCUs. The capacity increases or decreases whenever the writer or reader scales. This value is measured every second. For each cluster where you intend to use DocumentDB serverless, you define a capacity range: the minimum and maximum capacity values that each DocumentDB serverless writer or reader can scale between. The capacity range is the same for each DocumentDB serverless writer or reader in a cluster. Each DocumentDB serverless writer or reader has its own capacity, falling somewhere in that range.
DocumentDB serverless is supported on DocumentDB 5.0.0 only (not supported on 8.0) with a capacity range of 0.5 - 256 DCUs.
The smallest DocumentDB serverless capacity that you can define is 0.5 DCUs. You can specify a higher number if it's less than or equal to the maximum supported capacity value. Setting the minimum capacity to a small number lets lightly loaded clusters consume minimal compute resources. At the same time, they stay ready to accept connections immediately and scale up when they become busy.
We recommend setting the minimum to a value that allows each writer or reader to hold the working set of the application in the buffer pool. That way, the contents of the buffer pool aren't discarded during idle periods. For all the considerations when choosing the scaling capacity range, see [Choosing the scaling capacity range for a DocumentDB serverless cluster](docdb-serverless-scaling-config.md#docdb-serverless-scaling-capacity-choosing).
Depending on how you configure the readers in a Multi-AZ deployment, their capacities can be tied to the capacity of the writer or independently. For details about how to do that, see [Viewing and modifying the promotion tier of serverless readers](docdb-serverless-managing.md#docdb-serverless-promo-tier).
Monitoring DocumentDB serverless involves measuring the capacity values for the writer and readers in your cluster over time. If your database doesn't scale down to the minimum capacity, you can take actions such as adjusting the minimum and optimizing your database application. If your database consistently reaches its maximum capacity, you can take actions such as increasing the maximum. You can also optimize your database application and spread the query load across more readers.
The charges for DocumentDB serverless capacity are measured in terms of DCU-hours. For information about how DocumentDB serverless charges are calculated, see [Amazon DocumentDB pricing](https://aws.amazon.com//documentdb/pricing). Suppose that the total number of writers and readers in your cluster is n. In that case, the cluster consumes approximately n x minimum DCUs when you aren't running any database operations. Amazon DocumentDB itself might run monitoring or maintenance operations that cause some small amount of load. That cluster consumes no more than n x maximum DCUs when the database is running at full capacity.
For more details about choosing appropriate minimum and maximum DCU values, see [Choosing the scaling capacity range for a DocumentDB serverless cluster](docdb-serverless-scaling-config.md#docdb-serverless-scaling-capacity-choosing). The minimum and maximum DCU values that you specify also affect some Amazon DocumentDB instance limits. For details about the interaction between the capacity range and instance limits, see [Amazon DocumentDB serverless instance limits](docdb-serverless-instance-limits.md).
## Amazon DocumentDB serverless scaling
For each DocumentDB serverless writer or reader, Amazon DocumentDB continuously tracks utilization of resources such as CPU, memory, and network. These measurements collectively are called the load. The load includes the database operations performed by your application. It also includes background processing for the database server and Amazon DocumentDB administrative tasks. When capacity is constrained by any of these, DocumentDB serverless scales up. DocumentDB serverless also scales up when it detects performance issues that it can resolve by doing so. You can monitor resource utilization and how it affects DocumentDB serverless scaling by using the procedures in [Monitoring Amazon DocumentDB serverless](docdb-serverless-monitoring.md).
The load can vary across the writer and readers in your cluster. The writer handles write operations, and performs all the data modifications to the cluster volume. Readers can process read-only requests.
Scaling is the operation that increases or decreases DocumentDB serverless capacity for your database. With DocumentDB serverless, each writer and reader has its own current capacity value, measured in DCUs. DocumentDB serverless scales a writer or reader up to a higher capacity when its current capacity is too low to handle the load. It scales the writer or reader down to a lower capacity when its current capacity is higher than needed.
DocumentDB serverless can increase capacity incrementally. When your workload demand begins to reach the current database capacity of a writer or reader, DocumentDB serverless increases the number of DCUs for that writer or reader. DocumentDB serverless scales capacity in the increments required to provide the best performance for the resources consumed. Scaling happens in increments as small as 0.5 DCUs. The larger the current capacity, the larger the scaling increment and thus the faster scaling can happen.
Because DocumentDB serverless scaling is so frequent, granular, and nondisruptive, it doesn't cause discrete events in the AWS Management Console. Instead, you can measure the Amazon CloudWatch metrics such as `serverlessDatabaseCapacity` and `DCUUtilization`, and track their minimum, maximum, and average values over time. To learn more about monitoring DocumentDB serverless, see [Monitoring Amazon DocumentDB serverless](docdb-serverless-monitoring.md).
Scaling up or down can be caused by the following:
+ Memory utilization
+ CPU utilization
+ Network utilization
+ Storage utilization
You can monitor these causes of scaling up/down on DocumentDB serverless instances. For more information, see [Monitoring Amazon DocumentDB serverless](docdb-serverless-monitoring.md).
You can choose to make a reader scale at the same time as the associated writer, or independently from the writer. You do so by specifying the promotion tier for that reader.
+ DocumentDB serverless readers, in promotion tiers 0 and 1, scale at the same time as the writer. That scaling behavior makes readers in priority tiers 0 and 1 ideal for availability. That's because they are always sized to the right capacity to take over the workload from the writer in case of failover.
+ Readers in promotion tiers 2–15 scale independently from the writer. Each reader remains within the minimum and maximum DCU values that you specified for your cluster. When a reader scales independently of the associated writer DB, it can become idle and scale down while the writer continues to process a high volume of transactions. It's still available as a failover target, if no other readers are available in lower promotion tiers. However, if it's promoted to be the writer, it might need to scale up to handle the full workload of the writer.
For details about viewing and changing promotion tiers of serverless instances, see [Viewing and modifying the promotion tier of serverless readers](docdb-serverless-managing.md#docdb-serverless-promo-tier).
DocumentDB serverless scaling can happen while database connections are open, while transactions are in process, etc. DocumentDB serverless doesn't wait for a quiet point to begin scaling. Scaling doesn't disrupt any database operations that are underway.
If your workload requires more read capacity than is available with a single writer and a single reader, you can add multiple DocumentDB serverless readers to the cluster. Each DocumentDB serverless reader can scale within the range of minimum and maximum capacity values that you specified for your cluster. You can use the cluster's reader endpoint to direct read-only sessions to the readers and reduce the load on the writer.
Whether DocumentDB serverless performs scaling, and how fast scaling occurs once it starts, also depends on the minimum and maximum DCU settings for the cluster. In addition, it depends on whether a reader is configured to scale along with the writer or independently from it. For details about the scaling configuration, see [Amazon DocumentDB serverless scaling configuration](docdb-serverless-scaling-config.md).
## Idle state (0.5 DCUs)
When Amazon DocumentDB serverless writers or readers are idle, DocumentDB serverless instances support scaling down to an idle state of 0.5 DCUs if the cluster’s MinCapacity is configured to be 0.5.
In the idle state, the DocumentDB serverless instances do not have sufficient CPU compute capacity to support most production workloads, but are ready to quickly scale up to support a new workload. In a non-idle state, DocumentDB serverless instances typically require at least 1.0 - 2.5 DCUs. Therefore, when DocumentDB serverless instances scale up from an idle state to a non-idle state, they will scale up directly to 1.0 - 2.5 DCUs (or the value of MaxCapacity if it is lower).
In order to support scaling down to 0.5 DCUs when idle, instance limits are capped if the MinCapacity is configured to be less than or equal to 1.0 DCUs. For more information on how the limits are affected by the MinCapacity configuration, see [Amazon DocumentDB serverless instance limits](docdb-serverless-instance-limits.md).
# Requirements and limitations for DocumentDB serverless
## Feature requirements
### Region availability
The Amazon DocumentDB serverless instance type is available in the following regions:
The following AWS CLI command can be used to verify the exact DocumentDB serverless instance options offered in a particular region:
```
aws docdb describe-orderable-db-instance-options \
--region my_region \
--db-instance-class db.serverless \
--engine docdb
```
### Engine version availability
DocumentDB serverless is supported by Amazon DocumentDB 5.0.0 engine version only. It is not available on engine versions 3.6, 4.0, or 8.0.
**Note**
DocumentDB serverless is supported only on newer patch versions of 5.0.0. Please ensure that your cluster is updated to a recent engine patch version. For more information on maintaining Amazon DocumentDB clusters, see [Maintaining Amazon DocumentDB](db-instance-maintain.md)
### Cluster configuration
Before adding any Amazon DocumentDB serverless instances to an Amazon DocumentDB cluster, the cluster must also have the `ServerlessV2ScalingConfiguration` parameter set. This defines the capacity range of DocumentDB serverless instances in the cluster. For more information on scaling configuration, see [Amazon DocumentDB serverless scaling configuration](docdb-serverless-scaling-config.md).
### Minimum scaling capacity range settings for certain Amazon DocumentDB features
Some Amazon DocumentDB features work with DocumentDB serverless, but might cause issues if your capacity range is lower than needed for the memory requirements for those features with your specific workload. In that case, your database might not perform as well as usual, or might encounter out-of-memory errors.
The following features require configuration of a higher `MinCapacity` and/or `MaxCapacity` value for best operation:
+ Performance Insights
+ Global clusters (applies only to the primary AWS Region)
+ Serverless instance creation on a cluster with a large data volume
This includes serverless instance creation as part of a cluster restore.
For recommendations about setting the appropriate capacity range (if you are using this feature), see [Choosing the scaling capacity range for a DocumentDB serverless cluster](docdb-serverless-scaling-config.md#docdb-serverless-scaling-capacity-choosing). For troubleshooting information if your database encounters out-of-memory errors due to a misconfigured capacity range, see [Avoiding out-of-memory errors](docdb-serverless-scaling-config.md#docdb-serverless-scaling-mem-errors).
# Creating a cluster that uses Amazon DocumentDB serverless
## Creating an Amazon DocumentDB serverless cluster
With Amazon DocumentDB serverless, your clusters are interchangeable with provisioned clusters. You can have clusters where some instances use serverless and some instances are provisioned.
Verify that your desired region and engine version support DocumentDB serverless. See [Requirements and limitations for DocumentDB serverless](docdb-serverless-limitations.md).
To create an Amazon DocumentDB cluster where you can add serverless instances, follow the same procedure as in [Creating an Amazon DocumentDB cluster](db-cluster-create.md). The only difference is that the `ServerlessV2ScalingConfiguration` argument must also be provided.
The `ServerlessV2ScalingConfiguration` argument specifies the scaling capacity range of your DocumentDB serverless instances. It consists of the minimum and maximum DocumentDB capacity unit (DCU) values that apply to all the DocumentDB serverless instances in the cluster:
+ The `MinCapacity` value specifies the minimum scaling capacity.
+ The `MaxCapacity` value specifies the maximum scaling capacity.
For more information on scaling, see [Amazon DocumentDB serverless scaling configuration](docdb-serverless-scaling-config.md).
------
#### [ Using the AWS Management Console ]
The following AWS Management Console configuration example shows how to create a DocumentDB serverless cluster.
1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console.
1. In the navigation pane, choose **Clusters**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
The **Clusters** table appears.
1. Choose **Create**.
The **Create Amazon DocumentDB cluster** page appears.
1. On the Create Amazon DocumentDB cluster page, in the **Cluster type** section, choose **Instance-based cluster** (this is the default option).
1. In the **Cluster configuration** section:
1. For **Cluster identifier**, enter a unique name, such as **myserverlesscluster**. Note that the console will change all cluster names into lower-case regardless of how they are entered.
1. For **Engine version**, choose **5.0.0** (this is the default option).
1. In the **Cluster storage configuration** section, choose **Amazon DocumentDB Standard** (this is the default option).
**Note**
The other option in this category is **Amazon DocumentDB I/O-Optimized**. To learn more about either option, see [Amazon DocumentDB cluster storage configurations](db-cluster-storage-configs.md)
1. In the **Instance configuration** section:
1. For **DB instance class**, choose **Serverless**.
1. For **Number of regular replica instances**, choose **3** (this is the default option).
1. In the **Capacity range** section, leave the default values for **Minimum DCUs** and **Maximum DCUs**. For information on setting these parameters, see [Amazon DocumentDB serverless instance limits](docdb-serverless-instance-limits.md).
![\[Configuration form for a serverless database cluster with fields for instance class, replica instances and capacity range.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/instance-config-serverless.png)
1. In the **Connectivity** section, leave the default setting of **Don't connect to an EC2 compute resource**.
1. In the **Authentication** section, enter a username for the primary user, and then choose **Self managed**. Enter a password, then confirm it.
If you instead chose **Managed in AWS Secrets Manager**, see [Password management with Amazon DocumentDB and AWS Secrets Manager](docdb-secrets-manager.md) for more information.
1. Leave all other options as default and choose **Create cluster**.
------
#### [ Using the AWS CLI ]
In the following example, replace each *user input placeholder* with your own information or configuration parameters.
To create a cluster compatible with DocumentDB serverless instances using the AWS CLI, see [Creating a cluster using the AWS CLI](db-cluster-create.md#db-cluster-create-cli).
Include the following additional parameters in your `create-db-cluster` command:
```
--serverless-v2-scaling-configuration
MinCapacity=minimum_capacity,MaxCapacity=maximum_capacity
```
Example:
```
aws docdb create-db-cluster \
--db-cluster-identifier sample-cluster \
--engine docdb \
--engine-version 5.0.0 \
--serverless-v2-scaling-configuration MinCapacity=0.5,MaxCapacity=16 \
--master-username user-name \
--master-user-password password
```
------
## Adding an Amazon DocumentDB serverless instance
To add an DocumentDB serverless instance, follow the same procedure in [Adding an Amazon DocumentDB instance to a cluster](db-instance-add.md), making sure to specify db.serverless as the instance class.
### Adding a serverless instance using the AWS Management Console.
To add an DocumentDB serverless instances using the console, see [Adding an Amazon DocumentDB instance to a cluster](db-instance-add.md) and choose the **Using the AWS Management Console** tab.
### Adding a serverless instance using the AWS CLI
To add an DocumentDB serverless instances using the AWS CLI, see [Adding an Amazon DocumentDB instance to a cluster](db-instance-add.md) and choose the **Using the AWS CLI** tab.
Use the following instance class CLI argument:
```
--db-instance-class db.serverless
```
Example:
```
aws docdb create-db-instance \
--db-cluster-identifier sample-cluster \
--db-instance-identifier sample-instance \
--db-instance-class db.serverless \
--engine docdb
```
# Migrating to Amazon DocumentDB serverless
**Topics**
+ [Migrating existing DocumentDB clusters to serverless](#w2aac43c19b5)
+ [Migrating from MongoDB to DocumentDB serverless](#w2aac43c19b7)
## Migrating existing DocumentDB clusters to serverless
### Upgrading a cluster’s engine version
If your provisioned cluster is running a lower engine version that does not support DocumentDB serverless, you need to first upgrade the cluster to a supported engine version. For more information, see [Amazon DocumentDB in-place major version upgrade](docdb-mvu.md).
### Migrating a provisioned cluster to DocumentDB serverless
To switch a provisioned cluster to use DocumentDB serverless, follow these steps:
1. Check if the provisioned cluster’s engine version needs to be upgraded to be used with DocumentDB serverless. See [Requirements and limitations for DocumentDB serverless](docdb-serverless-limitations.md).
**Note**
If the provisioned cluster is running an engine version that isn't available for DocumentDB serverless, upgrade the engine version of the cluster. See [Amazon DocumentDB in-place major version upgrade](docdb-mvu.md).
1. Configure the scaling configuration for the cluster. For details on choosing the scaling configuration, see [Choosing the scaling capacity range for a DocumentDB serverless cluster](docdb-serverless-scaling-config.md#docdb-serverless-scaling-capacity-choosing). To modify the scaling configuration for a cluster, see [Viewing and modifying a cluster’s scaling capacity range configuration](docdb-serverless-managing.md#docdb-serverless-range-config).
1. Configure any other cluster properties to account for the DocumentDB serverless requirements and limitations from [Requirements and limitations for DocumentDB serverless](docdb-serverless-limitations.md).
1. Add one or more DocumentDB serverless instances to the cluster. Follow the procedure in [Adding an Amazon DocumentDB serverless instance](docdb-serverless-create-cluster.md#docdb-serverless-adding-instance).
**Note**
In some cases, you might already have one or more provisioned reader instances in the cluster. If so, you can choose to convert one of the readers to a DocumentDB serverless instance instead of creating a new instance. To do so, follow the procedure in [Changing an instance's class](db-instance-classes.md#db-instance-class-changing).
1. (Optional) Perform a failover operation to make a DocumentDB serverless instance the cluster writer. See [Amazon DocumentDB Failover](failover.md).
1. (Optional) Convert any remaining provisioned Amazon DocumentDB instances to DocumentDB serverless instances (see [Changing an instance's class](db-instance-classes.md#db-instance-class-changing)) or remove them from the cluster (see [Deleting an Amazon DocumentDB instance](db-instance-delete.md)).
------
#### [ Using the AWS Management Console ]
The following AWS Management Console configuration example shows the migration process using an Amazon DocumentDB provisioned cluster that is running Amazon DocumentDB 5.0.0, which does not require an engine version upgrade to start using DocumentDB serverless. The cluster is named `sample`, and starts with three provisioned instances named `sample`, `sample2`, and `sample3`. In this example, these three instances will be replaced by three serverless instances.
1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console.
1. In the navigation pane, choose **Clusters**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
The **Clusters** table appears.
1. In the **Clusters** table, select the checkbox of the cluster to which you want to add a serverless instance.
1. Choose **Actions**, and then choose **Add instances**.
1. In the **Add instances** dialog box, select **Serverless** in the **DB instance class** section for each new serverless instance you want to create.
1. For **Serverless capacity settings**, set the scaling configuration based on the capacity description in the dialog box.
1. (Optional) To add another instance, choose **Add instance**. Continue adding instances until you have reached the desired number of new instances.
In this example, three new serverless instances are created.
1. Choose **Create**.
It takes several minutes to create an instance. You can use the console or the AWS CLI to view the instance's status. For more information, see [Monitoring an Amazon DocumentDB Cluster's Status](https://docs.aws.amazon.com//documentdb/latest/developerguide/monitoring_docdb-cluster_status.html).
1. Returning to the **Clusters** table, select the checkboxes of all three of the original provisioned instances.
1. Choose **Actions**, and then choose **Delete**.
During the deletion, a failover is automatically performed to promote one of the remaining instances to be the writer. After a few minutes, the delete process is completed. The existing cluster now contains three DocumentDB serverless instances (as defined in the **Size** column).
------
#### [ Using the AWS CLI ]
The following AWS CLI configuration example shows the migration process using an Amazon DocumentDB provisioned cluster that is running Amazon DocumentDB 5.0.0, which does not require an engine version upgrade to start using DocumentDB serverless. The cluster is named `sample`, and starts with three provisioned instances named `sample`, `sample2`, and `sample3`. In this example, these three instances will be replaced by three serverless instances. The cluster is named `sample-cluster`, and starts with two provisioned instances named `sample-provisioned-instance-1` and `sample-provisioned-instance-2`, a writer instance and a reader instance.
In the following example, replace each *user input placeholder* with your own information or configuration parameters.
Use the `aws docdb describe-db-clusters` operation to determine the status of a cluster. The following code finds the status of the cluster `sample-cluster` and outputs the results in a table:
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].DBClusterMembers' \
--output table
```
```
--------------------------------------------------------------------------------------------------------
| DescribeDBClusters |
+--------------------------------+---------------------------------+------------------+----------------+
| DBClusterParameterGroupStatus | DBInstanceIdentifier | IsClusterWriter | PromotionTier |
+--------------------------------+---------------------------------+------------------+----------------+
| in-sync | sample-provisioned-instance-2 | False | 1 |
| in-sync | sample-provisioned-instance-1 | True | 1 |
+--------------------------------+---------------------------------+------------------+----------------+
```
Add the scaling configuration for the cluster:
```
aws docdb modify-db-cluster \
--db-cluster-identifier sample-cluster \
--serverless-v2-scaling-configuration MinCapacity=0.5,MaxCapacity=16
```
Add the serverless instances. In this example, new serverless instances named `sample-serverless-instance-1` and `sample-serverless-instance-2` are added:
```
aws docdb create-db-instance \
--db-cluster-identifier sample-cluster \
--db-instance-identifier sample-serverless-instance-1 \
--db-instance-class db.serverless \
--engine docdb
aws docdb create-db-instance \
--db-cluster-identifier sample-cluster \
--db-instance-identifier sample-serverless-instance-2 \
--db-instance-class db.serverless \
--engine docdb
```
Enter the following to wait for the serverless instances to be available before proceeding:
```
aws docdb wait db-instance-available \
--db-instance-identifier sample-serverless-instance-1
aws docdb wait db-instance-available \
--db-instance-identifier sample-serverless-instance-2
```
Perform a failover to make the new `sample-serverless-instance-1` instance the cluster writer:
```
aws docdb failover-db-cluster \
--db-cluster-identifier sample-cluster \
--target-db-instance-identifier sample-serverless-instance-1
```
The failover takes a few seconds to complete, after which sample-serverless-instance-1 becomes the cluster writer. Verify this with the following input:
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].DBClusterMembers' \
--output table
```
```
--------------------------------------------------------------------------------------------------------
| DescribeDBClusters |
+--------------------------------+---------------------------------+------------------+----------------+
| DBClusterParameterGroupStatus | DBInstanceIdentifier | IsClusterWriter | PromotionTier |
+--------------------------------+---------------------------------+------------------+----------------+
| in-sync | sample-provisioned-instance-2 | False | 1 |
| in-sync | sample-provisioned-instance-1 | False | 1 |
| in-sync | sample-serverless-instance-2 | False | 1 |
| in-sync | sample-serverless-instance-1 | True | 1 |
+--------------------------------+---------------------------------+------------------+----------------+
```
Finally, delete the original provisioned instances:
```
aws docdb delete-db-instance \
--db-instance-identifier sample-provisioned-instance-1
aws docdb delete-db-instance \
--db-instance-identifier sample-provisioned-instance-2
```
------
## Migrating from MongoDB to DocumentDB serverless
You can migrate your MongoDB databases to DocumentDB serverless, just as with provisioned Amazon DocumentDB. For more information, see [Migrating to Amazon DocumentDB](docdb-migration.md).
# Managing Amazon DocumentDB serverless
## Viewing and modifying a cluster’s scaling capacity range configuration
The `ServerlessV2ScalingConfiguration` argument specifies the scaling capacity range of your DocumentDB serverless instances. It consists of the minimum and maximum DocumentDB capacity unit (DCU) values that apply to all the DocumentDB serverless instances in the cluster.
+ **`MinCapacity`** — The minimum scaling capacity of any DocumentDB serverless instances in the cluster.
+ **`MaxCapacity`** — The maximum scaling capacity of any DocumentDB serverless instances in the cluster.
**Note**
The following scaling configuration modifications require an instance restart to reflect the new `MinCapacity` and `MaxCapacity` values:
Any changes to the `MaxCapacity` value
Changing the `MinCapacity` value to 1.0 or lower from a higher value
Changing the `MinCapacity` value to greater than 1.0 from a lower value
For more information on scaling configuration and how to select appropriate scaling capacity limits, see [Amazon DocumentDB serverless scaling configuration](docdb-serverless-scaling-config.md).
------
#### [ Using the AWS Management Console ]
The following AWS Management Console configuration example shows how to view and edit a DocumentDB serverless cluster's scaling configuration settings.
1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console.
1. In the navigation pane, choose **Clusters**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
The **Clusters** table appears.
1. In the **Clusters** table, select the checkbox of the cluster to which you want to modify the scaling capacity.
1. Choose **Actions**, and then choose **Modify**.
The **Modify cluster** dialog box appears.
1. Locate the **Serverless capacity setting** section and set the scaling configuration (**Capacity range**) based on the capacity description in the dialog box.
For more information about scaling and capacity ranges, see [Amazon DocumentDB serverless scaling configuration](docdb-serverless-scaling-config.md).
1. Choose **Continue**.
1. For **Scheduling of modifications**, choose **Apply immediately**.
1. Choose **Modify cluster**.
1. Once the modification has completed, each serverless instance should be rebooted. To minimize writer unavailability, perform the following sequence of operations:
1. Reboot each serverless reader instance.
1. Select the reader instance, choose **Actions**, and then **Reboot**.
1. Wait for the instance status to return to **Available**.
1. Perform a failover to a rebooted serverless instance.
1. Select the cluster, choose **Actions**, and then **Failover**.
1. Wait for the failover operation to complete.
1. Reboot the remaining serverless instance.
1. Select the remaining instance, choose **Actions**, and then **Reboot**.
1. Wait for the instance status to return to **Available**.
------
#### [ Using the AWS CLI ]
The following AWS CLI configuration example shows the current scaling configuration.
In the following example, replace each *user input placeholder* with your own information or configuration parameters.
The cluster’s current scaling configuration can be viewed using the `describe-db-clusters` AWS CLI command:
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[0].ServerlessV2ScalingConfiguration'
```
The following is the output of this command:
```
{
"MinCapacity": 0.5,
"MaxCapacity": 16.0
}
```
The cluster’s scaling configuration can be modified using the `modify-db-cluster` command:
```
aws docdb modify-db-cluster \
--db-cluster-identifier sample-cluster \
--serverless-v2-scaling-configuration MinCapacity=0.5,MaxCapacity=32
```
Once complete, each serverless instance should be rebooted. To minimize writer unavailability, we can perform the following sequence of operations:
```
aws docdb reboot-db-instance \
--db-instance-identifier sample-serverless-instance-reader
aws docdb wait db-instance-available \
--db-instance-identifier sample-serverless-instance-reader
aws docdb failover-db-cluster \
--db-cluster-identifier sample-cluster \
--target-db-instance-identifier sample-serverless-instance-reader
aws docdb reboot-db-instance \
--db-instance-identifier sample-serverless-instance-writer
aws docdb wait db-instance-available \
--db-instance-identifier sample-serverless-instance-writer
aws docdb failover-db-cluster \
--db-cluster-identifier sample-cluster \
--target-db-instance-identifier sample-serverless-instance-writer
```
------
## Viewing and modifying the promotion tier of serverless readers
For clusters containing multiple DocumentDB serverless instances or a mixture of provisioned and serverless instances, pay attention to the promotion tier setting for each serverless instance. This setting controls more behavior for serverless instances than for provisioned instances.
For provisioned instances, the choice of tier 0–15 determines only the order in which Amazon DocumentDB chooses which reader instance to promote to the writer during a failover operation. However, for serverless instances, the tier number also determines whether the instance scales up to match the capacity of the writer instance or scales independently based on its own workload. Serverless reader instances in tier 0 or 1 are kept at a minimum capacity at least as high as the writer instance. That way, they are ready to take over from the writer instance in case of a failover. If the writer instance is a provisioned instance, Amazon DocumentDB estimates the equivalent DocumentDB serverless capacity. It uses that estimate as the minimum capacity for the serverless reader instance.
DocumentDB serverless reader instances in tiers 2–15 don't have the same constraint on their minimum capacity. When they are idle, they can scale down to the minimum DocumentDB capacity unit (DCU) value specified in the cluster's capacity range.
------
#### [ Using the AWS Management Console ]
The following AWS Management Console configuration example shows how to view and modify a DocumentDB serverless instance reader's promotional tier settings.
1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console.
The promotion tiers of each instance is displayed in the **Promotion tier** column in the AWS Management Console.
1. In the navigation pane, choose **Clusters**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
The **Clusters** table appears.
1. In the **Clusters** table, select the checkbox of the instance to which you want to modify the promotion tier.
1. Choose **Actions**, and then choose **Modify**.
The **Modify instance** dialog box appears.
1. Locate the **Failover** section and set the **Promotion tier** to the desired level.
1. Choose **Continue**.
1. For **Scheduling of modifications**, choose **Apply immediately**.
1. Choose **Modify instance**.
------
#### [ Using the AWS CLI ]
The following AWS CLI configuration example shows the current scaling configuration.
In the following example, replace each *user input placeholder* with your own information or configuration parameters.
The promotion tiers of all instances in a cluster can be viewed using the `describe-db-clusters` AWS CLI command:
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[0].DBClusterMembers' \
--output table
```
The following is the output of this command:
```
--------------------------------------------------------------------------------------------------------
| DescribeDBClusters |
+--------------------------------+---------------------------------+------------------+----------------+
| DBClusterParameterGroupStatus | DBInstanceIdentifier | IsClusterWriter | PromotionTier |
+--------------------------------+---------------------------------+------------------+----------------+
| in-sync | sample-serverless-instance-2 | False | 1 |
| in-sync | sample-serverless-instance-1 | True | 1 |
+--------------------------------+---------------------------------+------------------+----------------+
```
The promotion tier of a specific instance can be modified using the `modify-db-instance` command:
```
aws docdb modify-db-instance \
--db-instance-identifier sample-serverless-instance-2 \
--promotion-tier 3
```
------
# Amazon DocumentDB serverless instance limits
For DocumentDB serverless instances, the following limits per instance are dependent upon the instance’s current scaling capacity:
+ Instance Memory (GiB)
+ Connections (all)
+ Cursor Limit
+ Open Transactions
+ Connections (active)
The following tables describe how the per-instance limits of serverless instances scale in relation to the instance’s current scaling capacity.
Note that the limit values are different depending on whether the cluster’s `MinCapacity` scaling configuration has been set to greater than two (2). If `MinCapacity` is set to less than or equal to 2, then the limit values for cursor limit, open transactions, and connections (active) are capped to a lower maximum value. (The technical reason for the cap is to support scaling down to an “idle” state. For more information, see [Idle state (0.5 DCUs)](docdb-serverless-how-it-works.md#docdb-serverlerss-idle-state).
**db.serverless instance limits if MinCapacity ≤1**
| Current Capacity (DCU) | Instance Memory (GiB) | Connections (all) | Cursor Limit | Open Transactions | Connections (active) |
| --- | --- | --- | --- | --- | --- |
| 0.5 | 1 | 250 | 6 | 12 | 39 |
| 1 | 2 | 500 | 12 | 24 | 79 |
| 2 | 4 | 1000 | 24 | 48 | 173 |
| 4 | 8 | 2000 | 48 | 96 | 416 |
| 8 | 16 | 4000 | 96 | 192 | 1071 |
| 16 | 32 | 8000 | 132 | 264 | 1550 |
| 32 | 64 | 16000 | 132 | 264 | 1550 |
| 64 | 128 | 32000 | 132 | 264 | 1550 |
| 128 | 256 | 60000 | 132 | 264 | 1550 |
| 256 | 512 | 60000 | 132 | 264 | 1550 |
**db.serverless instance limits if MinCapacity >1**
| Current Capacity (DCU) | Instance Memory (GiB) | Connections (all) | Cursor Limit | Open Transactions | Connections (active) |
| --- | --- | --- | --- | --- | --- |
| 1.5 | 3 | 7250 | 18 | 36 | 124 |
| 2 | 4 | 1000 | 24 | 48 | 173 |
| 4 | 8 | 2000 | 48 | 96 | 416 |
| 8 | 16 | 4000 | 96 | 192 | 1071 |
| 16 | 32 | 8000 | 192 | 384 | 2709 |
| 32 | 64 | 16000 | 384 | 768 | 4500 |
| 64 | 128 | 32000 | 768 | 1536 | 4500 |
| 128 | 256 | 60000 | 1536 | 3072 | 4500 |
| 256 | 512 | 60000 | 3072 | 6144 | 4500 |
You can monitor and alarm on the per instance limits using the following CloudWatch metrics. For more on Amazon DocumentDB CloudWatch metrics, see [Monitoring Amazon DocumentDB with CloudWatch](cloud_watch.md).
| Resource | CloudWatch limit metric | CloudWatch usage metric (1-min. max) | CloudWatch usage metric |
| --- | --- | --- | --- |
| Instance Memory | - | - | FreeableMemory |
| Connections (all) | DatabaseConnectionsLimit | DatabaseConnectionsMax | DatabaseConnections |
| Cursors | DatabaseCursorsLimit | DatabaseCursorsMax | DatabaseCursors |
| Transactions | TransactionsOpenLimit | TransactionsOpenMax | TransactionsOpen |
# Amazon DocumentDB serverless scaling configuration
**Topics**
+ [Choosing the scaling capacity range for a DocumentDB serverless cluster](#docdb-serverless-scaling-capacity-choosing)
+ [Choosing the `MinCapacity` setting for a DocumentDB serverless cluster](#docdb-serverless-scaling-mincapacity-choosing)
+ [Choosing the `MaxCapacity` setting for a DocumentDB serverless cluster](#docdb-serverless-scaling-maxcapacity-choosing)
+ [Avoiding out-of-memory errors](#docdb-serverless-scaling-mem-errors)
+ [Why is my serverless instance not scaling down?](#docdb-serverless-scaling-down)
## Choosing the scaling capacity range for a DocumentDB serverless cluster
Before adding any DocumentDB serverless instances to an Amazon DocumentDB cluster, the cluster must also have the `ServerlessV2ScalingConfiguration` parameter set.
The `ServerlessV2ScalingConfiguration` parameter consists of two values which define the serverless scaling capacity range of any serverless instance in the cluster:
+ **`MinCapacity`** — The minimum scaling capacity of any DocumentDB serverless instances in the cluster.
+ **`MaxCapacity`** — The maximum scaling capacity of any DocumentDB serverless instances in the cluster.
## Choosing the `MinCapacity` setting for a DocumentDB serverless cluster
It's tempting to always choose 0.5 for `MinCapacity`. That value allows the instance to scale down to the smallest capacity when it's completely idle, while remaining active. However, depending on how you use that cluster and the other settings that you configure, a different minimum capacity might be the most effective. Consider the following factors when choosing the minimum capacity setting:
+ The scaling rate for a DocumentDB serverless instance depends on its current capacity. The higher the current capacity, the faster it can scale up. If you need the instance to quickly scale up to a very high capacity, consider setting the minimum capacity to a value where the scaling rate meets your requirement.
+ If you typically modify the instance class of your instances in anticipation of especially high or low workload, you can use that experience to make a rough estimate of the equivalent DocumentDB serverless capacity range. To determine the memory size of a provisioned Amazon DocumentDB instance type, see [Instance limits](limits.md#limits.instance).
For example, suppose that you use the `db.r6g.xlarge` instance class when your cluster has a low workload. That instance class has 32 GiB of memory. Thus, you can specify a `MinCapacity` of 16 to set up a serverless instance that can scale down to approximately that same capacity. That's because each DCU corresponds to approximately 2 GiB of memory. You might specify a somewhat lower value to let the instance scale down further in case your `db.r6g.xlarge` instance was sometimes underutilized.
+ If your application works most efficiently when the instances have a certain amount of data in the buffer cache, consider specifying a minimum DCU setting where the memory is large enough to hold the frequently accessed data. Otherwise, some data is evicted from the buffer cache when the serverless instances scale down to a lower memory size. Then when the instances scale back up, the information is read back into the buffer cache over time. If the amount of I/O to bring the data back into the buffer cache is substantial, it might be more effective to choose a higher minimum DCU value. For more information, see [Instance sizing](best_practices.md#best_practices-instance_sizing).
+ If your DocumentDB serverless instances run most of the time at a particular capacity, consider specifying a minimum capacity setting that's lower than that baseline, but not too much lower. Serverless instances can most effectively estimate how much and how fast to scale up when the current capacity isn't drastically lower than the required capacity.
+ If your provisioned workload has memory requirements that are too high for small instance classes such as T3 or T4g, choose a minimum DCU setting that provides memory comparable to an R5 or R6g instance.
+ In particular, we recommend the following minimum `MinCapacity` for use with the specified features (these recommendations are subject to change):
+ Performance Insights — 2 DCUs
+ Global clusters — 8 DCUs (applies only to the primary AWS Region)
+ In Amazon DocumentDB, replication occurs at the storage layer, so reader capacity doesn't directly affect replication. However, for DocumentDB serverless reader instances that scale independently, make sure that the minimum capacity is sufficient to handle workloads during write-intensive periods to avoid query latency. If reader instances in promotion tiers 2–15 experience performance issues, consider increasing the cluster's minimum capacity. For details on changing whether reader instances scale along with the writer or independently, see [Viewing and modifying the promotion tier of serverless readers](docdb-serverless-managing.md#docdb-serverless-promo-tier).
If you have a cluster with DocumentDB serverless reader instances, the readers don't scale along with the writer instance when the promotion tier of the readers isn't 0 or 1. In that case, setting a low minimum capacity can result in excessive replication lag. That's because the readers might not have enough capacity to apply changes from the writer when the database is busy. We recommend that you set the minimum capacity to a value that represents a comparable amount of memory and CPU to the writer instance.
+ The time it takes for a DocumentDB serverless instance to scale from its minimum capacity to its maximum capacity depends on the difference between its minimum and maximum DCU values. When the current capacity of the instance is large, DocumentDB serverless scales up in larger increments than when the instance starts from a small capacity. Thus, if you specify a relatively large maximum capacity and the instance spends most of its time near that capacity, consider increasing the minimum DCU setting. That way, an idle instance can scale back up to maximum capacity more quickly.
+ Certain instance limits are determined by the serverless instance’s current capacity, such as connections limit, cursor limit, and open transactions limit. If the instance’s current capacity is small, then the limits will correspondingly also be small. If these limits are an issue when your serverless instance is scaled down to its `MinCapacity` value, then consider increasing `MinCapacity` to a higher value. For more information, see [Amazon DocumentDB serverless instance limits](docdb-serverless-instance-limits.md).
+ Furthermore, certain instance limits are capped at a lower maximum value if the `MinCapacity` is set to less than or equal to 1.0 DCUs, such as active connections limit, cursor limit, and open transactions limit. If these capped limits are insufficient for your workload, please use a `MinCapacity` value of at least 1.5 DCUs. For more information, see [Amazon DocumentDB serverless instance limits](docdb-serverless-instance-limits.md).
For instructions on how to modify a cluster’s scaling configuration, see [Managing Amazon DocumentDB serverless](docdb-serverless-managing.md).
## Choosing the `MaxCapacity` setting for a DocumentDB serverless cluster
It's tempting to always choose some high value for the maximum DocumentDB serverless capacity setting. A large maximum capacity allows the instance to scale up the most when it's running an intensive workload. A low value avoids the possibility of unexpected charges. Depending on how you use that cluster and the other settings that you configure, the most effective value might be higher or lower than you originally thought. Consider the following factors when choosing the maximum capacity setting:
+ The maximum capacity must be at least as high as the minimum capacity. You can set the minimum and maximum capacity to be identical. However, in that case the capacity never scales up or down. Thus, using identical values for minimum and maximum capacity isn't appropriate outside of testing situations.
+ The maximum capacity must be at least 1.0 DCUs and must be at most 256 DCUs.
+ We recommend monitoring the scaling and resource usage of your serverless instances. If your serverless instance is frequently scaling to maximum capacity and hitting resource constraints (e.g. when `DCUUtilization` metric is at 100.0), we recommend selecting a higher `MaxCapacity` value. For more information, see [Monitoring Amazon DocumentDB serverless](docdb-serverless-monitoring.md).
+ If you typically modify the instance class of your provisioned instances in anticipation of especially high or low workload, you can use that experience to estimate the equivalent DocumentDB serverless capacity range. To determine the memory size of provisioned Amazon DocumentDB instances, see [Instance limits](limits.md#limits.instance).
For example, suppose that you use the `db.r6g.4xlarge` instance class when your cluster has a high workload. That instance class has 128 GiB of memory. Thus, you can specify a maximum DCU setting of 64 to set up a serverless instance that can scale up to approximately that same capacity. That's because each DCU corresponds to approximately 2 GiB of memory. You might specify a somewhat higher value to let the instance scale up farther in case your `db.r6g.4xlarge` instance sometimes doesn't have enough capacity to handle the workload effectively.
+ If you have a budgetary cap on your database usage, choose a value that stays within that cap even if all your serverless instances run at maximum capacity all the time. Remember that when you have n serverless instances in your cluster, the theoretical maximum serverless capacity that the cluster can consume at any moment is n times the maximum DCU setting for the cluster. (The actual amount consumed might be less, for example if some readers scale independently from the writer.)
+ If you make use of serverless reader instances to offload some of the read-only workload from the writer instance, you might be able to choose a lower maximum capacity setting. You do this to reflect that each reader instance doesn't need to scale as high as if the cluster contains only a single instance.
+ Suppose that you want to protect against excessive usage due to misconfigured database parameters or inefficient queries in your application. In that case, you might avoid accidental overuse by choosing a maximum capacity setting that's lower than the absolute highest that you could set.
+ If spikes due to real user activity are rare but do happen, you can take those occasions into account when choosing the maximum capacity setting. If the priority is for the application to keep running with full performance and scalability, you can specify a maximum capacity setting that's higher than you observe in normal usage. If it's OK for the application to run with reduced throughput during very extreme spikes in activity, you can choose a slightly lower maximum capacity setting. Make sure that you choose a setting that still has enough memory and CPU resources to keep the application running.
+ If you turn on settings in your cluster that increase the memory usage for each instance, take that memory into account when deciding on the maximum DCU value. Such settings include those for Performance Insights and global clusters. Make sure that the maximum DCU value allows the serverless instances to scale up enough to handle the workload when those feature are being used. For information about troubleshooting problems caused by the combination of a low maximum DCU setting and Amazon DocumentDB features that impose memory overhead, see [Avoiding out-of-memory errors](#docdb-serverless-scaling-mem-errors) (below).
+ In particular, we recommend the following minimum `MaxCapacity` for use with the specified features (these recommendations are subject to change):
+ Serverless instance creation on a cluster with a large data volume – 2 DCUs (this includes serverless instance creation as part of a cluster restore.)
+ Certain instance limits are determined by the instance’s current capacity, such as connections limit, cursor limit, and open transactions limit. When choosing the `MaxCapacity` value for your workload, make sure to keep these instance limits in mind in order to avoid being bottlenecked by one of these limits. For more information, see [Amazon DocumentDB serverless instance limits](docdb-serverless-instance-limits.md).
For instructions on how to modify a cluster’s scaling configuration, see [Managing Amazon DocumentDB serverless](docdb-serverless-managing.md).
## Avoiding out-of-memory errors
If one of your DocumentDB serverless instances consistently reaches the limit of its maximum capacity, Amazon DocumentDB indicates this condition by setting the instance to a status of **incompatible-parameters**. While the instance has the **incompatible-parameters** status, some operations are blocked. For example, you can't upgrade the engine version. For more information on the status of an Amazon DocumentDB instance, see [Monitoring an Amazon DocumentDB instance's status](https://docs.aws.amazon.com//documentdb/latest/developerguide/monitoring_docdb-instance_status.html).
Typically, your instance goes into this status when it restarts frequently due to out-of-memory errors. Amazon DocumentDB records an event when this type of restart happens. To view resource events, see [Viewing Amazon DocumentDB events](managing-events.md#viewing-events). Unusually high memory usage can happen because of overhead from turning on settings such as Performance Insights. It can also come from a heavy workload on your instance or from managing the metadata associated with a large number of schema objects.
If the memory pressure becomes lower so that the instance doesn't reach its maximum capacity very often, Amazon DocumentDB automatically changes the instance status back to available.
To recover from this condition, you can take some or all of the following actions:
+ Increase the lower limit on capacity for serverless instances by changing the minimum DocumentDB capacity unit (DCU) value for the cluster. Doing so avoids issues where an idle database scales down to a capacity with less memory than is needed for the features that are turned on in your cluster. After changing the DCU settings for the cluster, reboot the serverless instance. Doing so evaluates whether Amazon DocumentDB can reset the status back to available.
+ Increase the upper limit on capacity for serverless instances by changing the maximum DCU value for the cluster. Doing so avoids issues where a busy database can't scale up to a capacity with enough memory for the features that are turned on in your cluster and the database workload. After changing the DCU settings for the cluster, reboot the serverless instance. Doing so evaluates whether Amazon DocumentDB can reset the status back to available.
+ Turn off configuration settings that require memory overhead. For example, suppose that you have a feature such as Performance Insights turned on but don't use it. If so, you can turn it off. Or you can adjust the minimum and maximum capacity values for the cluster higher to account for the memory used by those types of features. For guidelines about choosing minimum and maximum capacity settings, see [Choosing the scaling capacity range for a DocumentDB serverless cluster](#docdb-serverless-scaling-capacity-choosing).
+ Reduce the workload on the instance. For example, you can add reader instances to the cluster to spread the load from read-only queries across more instances.
## Why is my serverless instance not scaling down?
In some cases, DocumentDB serverless doesn't scale down to the minimum capacity, even with no load on the database. This can happen for the following reasons:
+ Performance Insights can increase resource usage and prevent the database from scaling down to minimum capacity. These features include the following:
+ If a reader instance isn't scaling down to the minimum and stays at the same or higher capacity than the writer instance, then check the priority tier of the reader instance. DocumentDB serverless reader instances in tier 0 or 1 are kept at a minimum capacity at least as high as the writer instance. Change the priority tier of the reader to 2 or higher so that it scales up and down independently of the writer. For more information, see [Amazon DocumentDB serverless scaling](docdb-serverless-how-it-works.md#docdb-serverless-scaling).
+ Heavy database workloads can increase resource usage.
+ Large database volumes can increase resource usage. Amazon DocumentDB uses memory and CPU resources for cluster management. Amazon DocumentDB requires more CPU and memory to manage clusters with larger database volumes. If your cluster’s minimum capacity is less than the minimum required for cluster management, your cluster won't scale down to the minimum capacity.
+ Background maintenance activity can periodically increase resource usage.
If the database still doesn't scale down to the minimum capacity configured, then stop and restart the database to reclaim any memory fragments that might have built up over time. Stopping and starting a database results in downtime, so we recommend doing this sparingly.
# Monitoring Amazon DocumentDB serverless
To learn more about monitoring in Amazon DocumentDB, see [Monitoring Amazon DocumentDB](monitoring_docdb.md).
**Topics**
+ [Out of Memory: incompatible-parameters status](#w2aac43c27b7)
+ [Amazon CloudWatch metrics for DocumentDB serverless](#w2aac43c27b9)
+ [Monitoring DocumentDB serverless performance with Performance Insights](#w2aac43c27c11)
## Out of Memory: incompatible-parameters status
If one of your serverless instances consistently reaches the limit of its maximum capacity, Amazon DocumentDB indicates this condition by setting the instance to a status of incompatible-parameters. For more information, see [Avoiding out-of-memory errors](docdb-serverless-scaling-config.md#docdb-serverless-scaling-mem-errors).
## Amazon CloudWatch metrics for DocumentDB serverless
To learn more about using CloudWatch with Amazon DocumentDB, see [Monitoring Amazon DocumentDB with CloudWatch](cloud_watch.md).
You can view your serverless instances in CloudWatch to monitor the capacity consumed by each instance with the `ServerlessDatabaseCapacity` metric. You can also monitor all of the standard DocumentDB CloudWatch metrics, such as `DatabaseConnections` and Queries. For the full list of CloudWatch metrics that you can monitor for Amazon DocumentDB, see [Monitoring Amazon DocumentDB with CloudWatch](cloud_watch.md). The following CloudWatch instance-level metrics are important to monitor for you to understand how your DocumentDB serverless instances are scaling up and down. All of these metrics are calculated every second. That way, you can monitor the current status of your serverless instances. You can set alarms to notify you if any serverless instance approaches a threshold for metrics related to capacity. You can determine if the minimum and maximum capacity settings are appropriate, or if you need to adjust them. You can determine where to focus your efforts for optimizing the efficiency of your database.
+ **`ServerlessDatabaseCapacity`** — As an instance-level metric, it reports the number of DCUs represented by the current instance capacity. As a cluster-level metric, it represents the average of the `ServerlessDatabaseCapacity` values of all the DocumentDB serverless instances in the cluster.
+ **`DCUUtilization.`** — This metric is new in DocumentDB serverless. This value is represented as a percentage. It's calculated as the value of the `ServerlessDatabaseCapacity` metric divided by the maximum DCU value of the cluster. Consider the following guidelines to interpret this metric and take action:
+ If this metric approaches a value of `100.0`, the instance has scaled up as high as it can. Consider increasing the maximum DCU setting for the cluster. That way, both writer and reader instances can scale to a higher capacity.
+ Suppose that a read-only workload causes a reader instance to approach a `DCUUtilization` of `100.0`, while the writer instance isn't close to its maximum capacity. In this case, consider adding additional reader instances to the cluster. That way, you can spread the read-only part of the workload across more instances, reducing the load on each reader instance.
+ Suppose that you are running a production application, where performance and scalability are the primary considerations. In this case, you can set the maximum DCU value for the cluster to a high number. Your goal is for the `DCUUtilization` metric to always be below 100.0. With a high maximum DCU value, you can be confident that there's enough room in case there are unexpected spikes in database activity. You are only charged for the database capacity that's actually consumed.
+ **`CPUUtilization`** — This metric is interpreted differently in DocumentDB serverless than in provisioned instances. For DocumentDB serverless, this value is a percentage that's calculated as the amount of CPU currently being used, divided by the CPU capacity that's available under the maximum DCU value of the cluster. Amazon DocumentDB monitors this value automatically and scales up your serverless instance when the instance consistently uses a high proportion of its CPU capacity.
If this metric approaches a value of `100.0`, the instance has reached its maximum CPU capacity. Consider increasing the maximum DCU setting for the cluster. If this metric approaches a value of `100.0` on a reader instance, consider adding additional reader instances to the cluster. That way, you can spread the read-only part of the workload spread across more instances, reducing the load on each reader instance.
+ **`FreeableMemory`** — This value represents the amount of unused memory that is available when the DocumentDB serverless instance is scaled to its maximum capacity. For every DCU that the current capacity is below the maximum capacity, this value increases by approximately 2 GiB. Thus, this metric doesn't approach zero until the instance is scaled up as high as it can.
If this metric approaches a value of zero, the instance has scaled up as much as it can and is nearing the limit of its available memory. Consider increasing the maximum DCU setting for the cluster. If this metric approaches a value of zero on a reader instance, consider adding additional reader instances to the cluster. That way, the read-only part of the workload can be spread across more instances, reducing the memory usage on each reader instance.
+ **`TempStorageIops`** — The number of IOPS done on local storage attached to the instance. It includes the IOPS for both reads and writes. This metric represents a count and is measured once per second. This is a new metric for DocumentDB serverless. For details, see [Monitoring Amazon DocumentDB with CloudWatch](cloud_watch.md).
+ **`TempStorageThroughput`** — The amount of data transferred to and from local storage associated with the instance. This metric represents bytes and is measured once per second. This is a new metric for DocumentDB serverless. For details, see [Monitoring Amazon DocumentDB with CloudWatch](cloud_watch.md).
Typically, most scaling up for DocumentDB serverless instances is caused by memory usage and CPU activity. The `TempStorageIops` and `TempStorageThroughput` metrics can help you to diagnose the rare cases where network activity for transfers between your instance and local storage devices is responsible for unexpected capacity increases. To monitor other network activity, you can use these existing metrics:
+ `NetworkReceiveThroughput`
+ `NetworkThroughput`
+ `NetworkTransmitThroughput`
+ `StorageNetworkReceiveThroughput`
+ `StorageNetworkThroughput`
+ `StorageNetworkTransmitThroughput`
### How DocumentDB serverless CloudWatch metrics apply to your AWS bill
The DocumentDB serverless charges on your AWS bill are calculated based on the same `ServerlessDatabaseCapacity` metric that you can monitor. The billing mechanism can differ from the computed CloudWatch average for this metric in cases where you use DocumentDB serverless capacity for only part of an hour. It can also differ if system issues make the CloudWatch metric unavailable for brief periods. Thus, you might see a slightly different value of DCU-hours on your bill than if you compute the number yourself from the `ServerlessDatabaseCapacity` average value.
### Examples of Amazon CloudWatch CLI commands for DocumentDB serverless metrics
The following AWS CLI examples demonstrate how you can monitor the most important CloudWatch metrics related to DocumentDB serverless. In each case, replace the `Value=` string for the `--dimensions` parameter with the identifier of your own DocumentDB serverless instance.
The following Linux example displays the minimum, maximum, and average capacity values for an instance, measured every 10 minutes over one hour. The Linux date commands specifies the start and end times relative to the current date and time. The `sort_by` function in the `--query` parameter sorts the results chronologically based on the `Timestamp` field.
```
aws cloudwatch get-metric-statistics \
--metric-name "ServerlessDatabaseCapacity" \
--start-time "$(date -d '1 hour ago')" \
--end-time "$(date -d 'now')" \
--period 600 \
--namespace "AWS/DocDB" \
--statistics Minimum Maximum Average \
--dimensions Name=DBInstanceIdentifier,Value=my_instance \
--query 'sort_by(Datapoints[*].{min:Minimum,max:Maximum,avg:Average,ts:Timestamp},&ts)' \
--output table
```
The following Linux example demonstrates monitoring the capacity of an instance in a cluster. It measures the minimum, maximum, and average capacity utilization of an instance. The measurements are taken once each hour over a three-hour period. These examples use the `DCUUtilization` metric representing a percentage of the upper limit on DCUs, instead of `ServerlessDatabaseCapacity` representing a fixed number of DCUs. That way, you don't need to know the actual numbers for the minimum and maximum DCU values in the capacity range. You can see percentages ranging from 0 to 100.
```
aws cloudwatch get-metric-statistics \
--metric-name "DCUUtilization" \
--start-time "$(date -d '3 hours ago')" \
--end-time "$(date -d 'now')" \
--period 3600 \
--namespace "AWS/DocDB" \
--statistics Minimum Maximum Average \
--dimensions Name=DBInstanceIdentifier,Value=my_instance \
--query 'sort_by(Datapoints[*].{min:Minimum,max:Maximum,avg:Average,ts:Timestamp},&ts)' \
--output table
```
The following Linux example does similar measurements as the previous ones. In this case, the measurements are for the `CPUUtilization` metric. The measurements are taken every 10 minutes over a 1-hour period. The numbers represent the percentage of available CPU used, based on the CPU resources available to the maximum capacity setting for the instance.
```
aws cloudwatch get-metric-statistics \
--metric-name "CPUUtilization" \
--start-time "$(date -d '1 hour ago')" \
--end-time "$(date -d 'now')" \
--period 600 \
--namespace "AWS/DocDB" \
--statistics Minimum Maximum Average \
--dimensions Name=DBInstanceIdentifier,Value=my_instance \
--query 'sort_by(Datapoints[*].{min:Minimum,max:Maximum,avg:Average,ts:Timestamp},&ts)' \
--output table
```
The following Linux example does similar measurements as the previous ones. In this case, the measurements are for the `FreeableMemory` metric. The measurements are taken every 10 minutes over a 1-hour period.
```
aws cloudwatch get-metric-statistics \
--metric-name "FreeableMemory" \
--start-time "$(date -d '1 hour ago')" \
--end-time "$(date -d 'now')" \
--period 600 \
--namespace "AWS/DocDB" \
--statistics Minimum Maximum Average \
--dimensions Name=DBInstanceIdentifier,Value=my_instance \
--query 'sort_by(Datapoints[*].{min:Minimum,max:Maximum,avg:Average,ts:Timestamp},&ts)' \
--output table
```
## Monitoring DocumentDB serverless performance with Performance Insights
You can use Performance Insights to monitor the performance of DocumentDB serverless instances. For Performance Insights procedures, see [Monitoring with Performance Insights](performance-insights.md).
The following new Performance Insights counters apply to DocumentDB serverless instances:
+ **`os.general.serverlessDBCapacity`** — The current capacity of the instance in DCUs. The value corresponds to the `ServerlessDatabaseCapacity` CloudWatch metric for the instance.
+ **`os.general.dcuUtilization`** — The percentage of current capacity out of the maximum configured capacity. The value corresponds to the `DCUUtilization` CloudWatch metric for the instance.
+ **`os.general.maxConfiguredDcu`** — The maximum capacity that you configured for this DocumentDB serverless instance. It's measured in DCUs.
+ **`os.general.minConfiguredDcu`** — The minimum capacity that you configured for this DocumentDB serverless instance. It's measured in DCUs.
For the full list of Performance Insights counters, see [Performance Insights for counter metrics](performance-insights-counter-metrics.md).
When vCPU values are shown for a DocumentDB serverless instance in Performance Insights, those values represent estimates based on the DCU value for the instance. At the default interval of one minute, any fractional vCPU values are rounded up to the nearest whole number. For longer intervals, the vCPU value shown is the average of the integer vCPU values for each minute.