# Amazon Neptune Serverless
Amazon Neptune Serverless is an on-demand autoscaling configuration that is architected to scale your DB cluster as needed to meet even very large increases in processing demand, and then scale down again when the demand decreases. It helps to automate the processes of monitoring workload and adjusting capacity for your Neptune database. Because capacity is adjusted automatically based on application demand, you're charged only for the resources that your application actually needs.
## Use cases for Neptune Serverless
Neptune Serverless supports many types of workloads. It is suitable for demanding, highly variable workloads and can be very helpful if your database usage is typically heavy for short periods of time, followed by long periods of light activity or no activity at all. Neptune Serverless is especially useful for the following use cases:
+ **Variable workloads** – Workloads that have sudden and unpredictable increases in CPU activity. With Neptune Serverless, your graph database automatically scales capacity to meet the needs of the workload and scales back down when the surge of activity is over. You no longer have to provision for peak or average capacity. You can specify an upper capacity limit to handle peak workloads, and that capacity isn't used unless it's needed.
The granularity of scaling provided by Neptune Serverless helps you match capacity closely to your workload's needs. Neptune Serverless can add or remove capacity in fine grained increments based on what is needed. It can add as little as half a [Neptune Capacity Unit (NCU)](neptune-serverless-capacity-scaling.md) when only a little more capacity is required.
+ **Multi-tenant applications** – By taking advantage of Neptune Serverless, you can create a separate DB cluster for each of the applications you need to run without having to manage those tenant clusters individually. Each of the tenant clusters may have different busy and idle periods depending on multiple factors, but Neptune Serverless can scale them efficiently without your intervention.
+ **New applications** – When you deploy a new application, you're often unsure how much database capacity it will need. Using Neptune Serverless, you can set up a DB cluster that can scale automatically to meet the new application's capacity requirements as they develop.
+ **Capacity planning** – Suppose you usually adjust your database capacity, or verify the optimal database capacity for your workload, by modifying the DB instance classes of all the DB instances in a cluster. With Neptune Serverless, you can avoid this administrative overhead. Instead, you can modify existing DB instances from provisioned to serverless or from serverless to provisioned without having to create a new DB cluster or instance.
+ **Development and testing** – Neptune Serverless is also perfect for development and testing environments. With Neptune Serverless you can create DB instances with a high enough maximum capacity to test your most demanding application, and a low minimum capacity for all the other times when the system may be idle between tests.
Neptune Serverless only scales compute capacity. Your storage volume remains the same, and is not affected by serverless scaling.
**Note**
You can also [use Neptune auto-scaling with Neptune Serverless](manage-console-autoscaling.md#autoscaling-with-serverless) to handle different kinds of workload variations.
## Amazon Neptune Serverless constraints
+ Neptune Serverless is only available in the following regions:
+ US East (N. Virginia): `us-east-1`
+ US East (Ohio): `us-east-2`
+ US West (N. California): `us-west-1`
+ US West (Oregon): `us-west-2`
+ Canada (Central): `ca-central-1`
+ Europe (Stockholm): `eu-north-1`
+ Europe (Spain): `eu-south-2`
+ Europe (Ireland): `eu-west-1`
+ Europe (London): `eu-west-2`
+ Europe (Paris): `eu-west-3`
+ Europe (Frankfurt): `eu-central-1`
+ Asia Pacific (Tokyo): `ap-northeast-1`
+ Asia Pacific (Seoul): `ap-northeast-2`
+ Asia Pacific (Singapore): `ap-southeast-1`
+ Asia Pacific (Sydney): `ap-southeast-2`
+ Asia Pacific (Jakarta): `ap-southeast-3`
+ Asia Pacific (Hong Kong): `ap-east-1`
+ Asia Pacific (Mumbai): `ap-south-1`
+ South America (São Paulo): `sa-east-1`
+ **Not available in early engine versions** – Neptune Serverless is only available in engine releases 1.2.0.1 or later.
+ **Not compatible with the Neptune lookup cache** – The [lookup cache](feature-overview-lookup-cache.md) does not work with serverless DB instances.
+ **Maximum memory in a serverless instance is 256 GB** – Setting `MaxCapacity` to 128 NCUs (the highest supported setting) allows a Neptune Serverless instance to scale to 256 GB of memory, which is equivalent to that of an `R6g.8XL` provisioned instance type.
# Capacity scaling in a Neptune Serverless DB cluster
Setting up a Neptune Serverless DB cluster is similar to setting up a normal provisioned cluster, with additional configuration for minimum and maximum units for scaling, and with the instance type set to `db.serverless`. The scaling configuration is defined in Neptune Capacity Units (NCUs), each of which consists of 2 GiB (gibibyte) of memory (RAM) along with associated virtual processor capacity (vCPU) and networking. It is set as a part of a `ServerlessV2ScalingConfiguration` object, represented in JSON like this:
```
"ServerlessV2ScalingConfiguration": {
"MinCapacity": (minimum NCUs, a floating-point number such as 1.0),
"MaxCapacity": (maximum NCUs, a floating-point number such as 128.0)
}
```
At any moment in time, each Neptune writer or reader instance has a capacity measured by a floating-point number that represents the number of NCUs currently being used by that instance. You can use the CloudWatch [ServerlessDatabaseCapacity](neptune-serverless-using.md#neptune-serverless-monitoring) metric at an instance level to find out you how many NCUs a given DB instance is currently using, and the [NCUUtilization](neptune-serverless-using.md#neptune-serverless-monitoring) metric to find out what percentage of its maximum capacity the instance is using. Both of these metrics are also available at a DB cluster level to show average resource utilization for the DB cluster as a whole.
When you create a Neptune Serverless DB cluster, you set both the minimum and the maximum number of **Neptune capacity units** (NCUs) for all the serverless instances.
The minimum NCU value that you specify sets the smallest size to which a serverless instance in your DB cluster can shrink, and likewise, the maximum NCU value establishes the largest size to which a serverless instance can grow. The highest maximum NCU value you can set is 128.0 NCUs, and the lowest minimum is 1.0 NCUs.
Neptune continuously tracks the load on each Neptune Serverless instance by monitoring its utilization of resources such as CPU, memory, and network. The load is generated by your application's database operations, by background processing for the server, and by other administrative tasks.
When the load on a serverless instance reaches the limit of current capacity, or when Neptune detects any other performance issues, the instance scales up automatically. When the load on the instance declines, the capacity scales down towards the configured minimum capacity units, with CPU capacity being released before memory. This architecture allows releasing of resources in a controlled step-down manner and handles demand fluctuations effectively.
You can make a reader instance scale together with the writer instance or scale independently by setting its promotion tier. Reader instances in promotion tiers 0 and 1 scale at the same time as the writer, which keeps them sized at the right capacity to take over the workload from the writer rapidly in case of failover. Readers in promotion tiers 2 through 15 scale independently of the writer instance, and of each other.
If you've created your Neptune DB cluster as a Multi-AZ cluster to ensure high availability, Neptune Serverless scales instances in all AZs up and down with your database load. You can set the promotion tier of a reader instance in a secondary AZ to 0 or 1 so that it scales up and down along with the capacity of the writer instance in the primary AZ so that it's ready to take over the current workload at any time.
**Note**
Storage for a Neptune DB cluster consists of six copies of all your data, spread across three AZs, regardless of whether you created the cluster as a Multi-AZ cluster or not. Storage replication is handled by the storage subsystem and is not affected by Neptune Serverless.
## Choosing a minimum capacity value for a Neptune Serverless DB cluster
The smallest value you can set for the minimum capacity is `1.0` NCUs.
Be sure not to set the minimum value lower than what your application requires to operate efficiently. Setting it too low can result in a higher rate of timeouts in certain memory-intensive workloads.
Setting the minimum value as low as possible can save money, since your cluster will use minimal resources when demand is low. However, if your workload tends to fluctuate dramatically, from very low to very high, you may want to set the minimum higher, because a higher minimum lets your Neptune Serverless instances scale up faster.
The reason for this is that Neptune chooses scaling increments based on current capacity. If current capacity is low, Neptune will initially scale up slowly. If the minimum is higher, Neptune starts with a larger scaling increment, and can therefore scale up faster to meet a large sudden increase in workload.
## Choosing a maximum capacity value for a Neptune Serverless DB cluster
The largest value you can set for the maximum capacity is `128.0` NCUs, and the smallest value you can set for the maximum capacity is `2.5` NCUs. Whatever maximum capacity value you set must be at least as large as the minimum capacity value you set.
As a general rule, set the maximum value high enough to handle the peak load that your application is likely to encounter. Setting it too low can result in a higher rate of timeouts in certain memory-intensive workloads.
Setting the maximum value as high as possible has the advantage that your application is likely to be able to handle even the most unexpected workloads. The disadvantage is that you lose some ability to predict and control resource costs. An unexpected spike in demand can end up costing much more than your budget has anticipated.
The benefit of a carefully targeted maximum value is that it lets you meet peak demand while also putting a cap on Neptune compute costs.
**Note**
Changing the capacity range of a Neptune Serverless DB cluster causes changes to the default values of some configuration parameters. Neptune can apply some of those new defaults immediately, but some of the dynamic parameter changes take effect only after a reboot. A `pending-reboot` status indicates that you need a reboot to apply some parameter changes.
## Use your existing configuration to estimate serverless requirements
If you typically modify the DB instance class of your provisioned DB instances to meet exceptionally high or low workload, you can use that experience to make a rough estimate of the equivalent Neptune Serverless capacity range.
### Estimate the best minimum capacity setting
You can apply what you know about your existing Neptune DB cluster to estimate the serverless minimum capacity setting that will work best.
For example, if your provisioned workload has memory requirements that are too high for small DB instance classes such as `T3` or `T4g`, choose a minimum NCU setting that provides memory comparable to an `R5` or `R6g` DB instance class.
Or, suppose that you use the `db.r6g.xlarge` DB instance class when your cluster has a low workload. That DB instance class has 32 GiB of memory, so you can specify a minimum NCU setting of 16 to create serverless instances that can scale down to approximately that same capacity (each NCU corresponds to about 2 GiB of memory). If your `db.r6g.xlarge` instance is sometimes underutilized, you might be able to specify a lower value.
If your application works most efficiently when your DB instances can hold a given amount of data in memory or the buffer cache, consider specifying a minimum NCU setting large enough to provide enough memory for that. Otherwise, data may be evicted from the buffer cache when the serverless instances scale down, and will have to be read back into the buffer cache over time when instances scale back up. If the amount of I/O to bring data back into the buffer cache is substantial, choosing a higher minimum NCU value could be worthwhile.
If you find that your serverless instances are running most of the time at a particular capacity, it works well to set the minimum capacity just a little lower than that. Neptune Serverless can efficiently estimate how much and how fast to scale up when the current capacity isn't drastically lower than the required capacity.
In a [mixed configuration](neptune-serverless-configuration.md#neptune-serverless-mixed-configuration), with a provisioned writer and Neptune Serverless readers, the readers don't scale along with the writer. Because they scale independently, setting a low minimum capacity for them can result in excessive replication lag. They may not have sufficient capacity to keep up with changes the writer is making when there is a highly write-intensive workload. In this situation, set a minimum capacity that's comparable to the writer capacity. In particular, if you observe replica lag in readers that are in promotion tiers 2–15, increase the minimum capacity setting for your cluster.
### Estimate the best maximum capacity setting
You can also apply what you know about your existing Neptune DB cluster to estimate the serverless maximum capacity setting that will work best.
For example, suppose that you use the `db.r6g.4xlarge` DB instance class when your cluster has a high workload. That DB instance class has 128 GiB of memory, so you can specify a maximum NCU setting of 64 to set up equivalent Neptune Serverless instances (each NCU corresponds to about 2 GiB of memory). You could specify a higher value to let the DB instance scale up further in case your `db.r6g.4xlarge` instance can't always handle the workload.
If unexpected spikes in your workload are rare, it may make sense to set your maximum capacity high enough to maintain application performance even during those spikes. On the other hand, you may want to set a lower maximum capacity that can reduce throughput during unusual spikes but that allows Neptune to handle your expected workloads without problem, and that limits costs.
# Additional configuration for Neptune Serverless DB clusters and instances
In addition to [setting minimum and maximum capacity](neptune-serverless-capacity-scaling.md) for your Neptune Serverless DB cluster, there are a few other configuration choices to consider.
## Combining serverless and provisioned instances in a DB cluster
A DB cluster doesn't have to be serverless only— you can create a combination of serverless and provisioned instances (a mixed configuration).
For example, suppose that you need more write capacity than is available in a serverless instance. In that case, you can set up the cluster with a very large provisioned writer and still use serverless instances for the readers.
Or, suppose that the write workload on your cluster varies but the read workload is steady. In that case, you could set up your cluster with a serverless writer and one or more provisioned readers.
See [Using Amazon Neptune Serverless](neptune-serverless-using.md) for information about how to create a mixed-configuration DB cluster.
## Setting the promotion tiers for Neptune Serverless instances
For clusters containing multiple 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 DB instances.
In the AWS Management Console, you specify this setting using the **Failover priority** under **Additional configuration** on the **Create database**, **Modify instance**, and **Add reader** pages. You see this property for existing instances in the optional **Priority tier** column on the **Databases** page. You can also see this property on the details page for a DB cluster or instance.
For provisioned instances, the choice of tier 0–15 determines only the order in which Neptune chooses which reader instance to promote to the writer during a failover operation. For Neptune Serverless reader instances, the tier number also determines whether the instance scales up to match the capacity of the writer instance or scales independently of it based only on its own workload.
Neptune Serverless reader instances in tier 0 or 1 are kept at a minimum capacity at least as high as the writer instance so that they are ready to take over from the writer in case of failover. If the writer is a provisioned instance, Neptune estimates the equivalent serverless capacity and uses that estimate as the minimum capacity for the serverless reader instance.
Neptune Serverless reader instances in tiers 2–15 don't have the same constraint on their minimum capacity, and scale independently of the writer. When they are idle, they scale down to the minimum NCU value specified in the cluster's [capacity range](neptune-serverless-capacity-scaling.md). This can cause problems, however, if the read workload spikes rapidly.
## Keeping reader capacity aligned to writer capacity
One important thing to keep in mind is that you want to make sure your reader instances can keep up with your writer instance, to prevent excessive replication lag. This is particularly a concern in two situations, where serverless reader instances do not automatically scale in sync with the writer instance:
+ When your writer is provisioned, and your readers are serverless.
+ When your writer is serverless, and your serverless readers are in promotion tiers 2-15.
In both of those cases, set the minimum serverless capacity to match that of the expected writer capacity, to ensure that reader operations don't time out and potentially cause restarts. In the case of a provisioned writer instance, set the minimum capacity to match that of the provisioned instance. In the case of a serverless writer, the optimal setting may be harder to predict.
Because the instance capacity range is set at the cluster level, all serverless instances are controlled by the same minimum and maximum capacity settings. Reader instances in tiers 0 and 1 scale in sync with the writer instance, but instances in promotion tiers 2-15 scale independently of each other and of the writer instance, depending on their workload. If you set the minimum capacity too low, idle instances in tiers 2 to 15 can scale down too low to scale back up fast enough to handle a sudden burst in writer activity.
## Avoid setting the timeout value too high
It is possible to incur unexpected costs if you set the query timeout value too high on a serverless instance.
Without a reasonable timeout setting, you may inadvertently issue a query that requires a powerful, expensive instance type and that keeps running for a very long time, incurring costs you never anticipated. You can avoid that situation by using a query timeout value which accomodates most of your queries and only causes unexpectedly long-running ones to time out.
This is true both for general query timeout values set using parameters and for per-query timeout values set using query hints.
## Optimizing your Neptune Serverless configuration
If your Neptune Serverless DB cluster is not tuned to the workload it is running, you may notice that it doesn't run optimally. You can adjust the minimum and/or maximum capacity setting so that it can scale without encountering memory problems.
+ Increase the minimum capacity setting for the cluster. This can correct the situation where an idle instance scales back to a capacity that has less memory than your application and enabled features need.
+ Increase the maximum capacity setting for the cluster. This can correct the situation where a busy database can't scale up to a capacity with enough memory to handle the workload and any memory-intensive features that are enabled.
+ Change the workload on the instance in question. For example, you can add reader instances to the cluster to spread the read load across more instances.
+ Tune your application's queries so that they use fewer resources.
+ Try using a provisioned instance that is larger than the maximum NCUs available within Neptune Serverless, to see if it is a better fit for the memory and CPU requirements of the workload.
# Using Amazon Neptune Serverless
You can create a new Neptune DB cluster as a serverless one, or in some cases you can convert an existing DB cluster to use serverless. You can also convert DB instances in a serverless DB cluster to and from serverless instances. You can only use Neptune Serverless in one of the AWS Regions where it's supported, with a few other limitations (see [Amazon Neptune Serverless constraints](neptune-serverless.md#neptune-serverless-limitations)).
You can also use the [Neptune CloudFormation stack](get-started-cfn-create.md) to create a Neptune Serverless DB cluster.
## Creating a new DB cluster that uses Serverless
To create a Neptune DB cluster that uses serverless, you can do so [using the AWS Management Console](manage-console-launch-console.md) the same way you do to create a provisioned cluster. The difference is that under **DB instance size**, you need to set the **DB instance class** to **serverless**. When you do that, you then need to [set the serverless capacity range](neptune-serverless-capacity-scaling.md) for the cluster.
You can also create a serverless DB cluster using the AWS CLI with commands like this (on Windows, replace '\$1' with '^'):
```
aws neptune create-db-cluster \
--region (an AWS Region region that supports serverless) \
--db-cluster-identifier (ID for the new serverless DB cluster) \
--engine neptune \
--engine-version (optional: 1.2.0.1 or above) \
--serverless-v2-scaling-configuration "MinCapacity=1.0, MaxCapacity=128.0"
```
You could also specify the `serverless-v2-scaling-configuration` parameter like this:
```
--serverless-v2-scaling-configuration '{"MinCapacity":1.0, "MaxCapacity":128.0}'
```
You can then run the `describe-db-clusters` command for the `ServerlessV2ScalingConfiguration` attribute, which should return the capacity range settings you specified:
```
"ServerlessV2ScalingConfiguration": {
"MinCapacity": (the specified minimum number of NCUs),
"MaxCapacity": (the specified maximum number of NCUs)
}
```
## Converting an existing DB cluster or instance to Serverless
If you have a Neptune DB cluster that is using engine version 1.2.0.1 or above, you can convert it to be serverless. This process does incur some downtime.
The first step is to add a capacity range to the existing cluster. You can do so using the AWS Management Console, or by using a AWS CLI command like this (on Windows, replace '\$1' with '^'):
```
aws neptune modify-db-cluster \
--db-cluster-identifier (your DB cluster ID) \
--serverless-v2-scaling-configuration \
MinCapacity=(minimum number of NCUs, such as 2.0), \
MaxCapacity=(maximum number of NCUs, such as 24.0)
```
The next step is to create a new serverless DB instance to replace the existing primary instance (the writer) in the cluster. Again, you can do this and all the subsequent steps using either the AWS Management Console or the AWS CLI. In either case, specify the DB instance class as serverless. The AWS CLI command would look like this (on Windows, replace '\$1' with '^'):
```
aws neptune create-db-instance \
--db-instance-identifier (an instance ID for the new writer instance) \
--db-cluster-identifier (ID of the DB cluster) \
--db-instance-class db.serverless \
--engine neptune
```
When the new writer instance has become available, perform a failover to make it the writer instance for the cluster:
```
aws neptune failover-db-cluster \
--db-cluster-identifier (ID of the DB cluster) \
--target-db-instance-identifier (instance ID of the new serverless instance)
```
Next, delete the old writer instance:
```
aws neptune delete-db-instance \
--db-instance-identifier (instance ID of the old writer instance) \
--skip-final-snapshot
```
Finally, do the same thing to create a new serverless instance to take the place of each existing provisioned reader instance that you would like to turn into a serverless instance, and delete the existing provisioned instances (no failover is needed for reader instances).
## Modifying the capacity range of an existing serverless DB cluster
You can change the capacity range of a Neptune Serverless DB cluster using the AWS CLI like this (on Windows, replace '\$1' with '^'):
```
aws neptune modify-db-cluster \
--region (an AWS region that supports serverless) \
--db-cluster-identifier (ID of the serverless DB cluster) \
--apply-immediately \
--serverless-v2-scaling-configuration MinCapacity=4.0, MaxCapacity=32
```
Changing the capacity range causes changes to the default values of some configuration parameters. Neptune can apply some of those new defaults immediately, but some of the dynamic parameter changes take effect only after a reboot. A status of `pending-reboot` indicates that you need a reboot to apply some parameter changes.
## Changing a Serverless DB instance to provisioned
All you need to do to convert a Neptune Serverless instance to a provisioned one is to change its instance class to one of the provisioned instance classes. See [Modifying a Neptune DB Instance (and Applying Immediately)](manage-console-instances-modify.md).
## Configuring Gremlin clients for Serverless
When using Gremlin WebSocket clients with Neptune Serverless, you need to configure the client's heartbeat interval appropriately to maintain stable connections during scaling events. For detailed configuration instructions for Java, Go, JavaScript/Node.js, and Python clients, see [Heartbeat Configuration for Neptune Serverless](best-practices-gremlin-heartbeat-serverless.md).
## Monitoring serverless capacity with Amazon CloudWatch
You can use CloudWatch to to monitor the capacity and utilization of the Neptune serverless instances in your DB cluster. There are two CloudWatch metrics that let you track current serverless capacity both at the cluster level and at the instance level:
+ **`ServerlessDatabaseCapacity`** – As an instance-level metric, `ServerlessDatabaseCapacity` reports the current instance capacity, in NCUs. As a cluster-level metric, it reports the average of all the `ServerlessDatabaseCapacity` values of all the DB instances in the cluster.
+ **`NCUUtilization`** – This metric reports the percentage of possible capacity being used. It is calculated as the current `ServerlessDatabaseCapacity` (either at the instance level or at the cluster level) divided by the maximum capacity setting for the DB cluster.
If this metric approaches 100% at a cluster level, meaning that the cluster has scaled as high as it can, consider increasing the maximum capacity setting.
If it approaches 100% for a reader instance while the writer instance is not near maximum capacity, consider adding more reader instances to distribute the read workload.
Note that the `CPUUtilization` and `FreeableMemory` metrics have slightly different meanings for serverless instances than for provisioned instances. In a serverless context, `CPUUtilization` is a percentage that's calculated as the amount of CPU currently being used divided by the amount of CPU that would be available at maximum capacity. Similarly, `FreeableMemory` reports the amount of freeable memory that would be available if an instance was at maximum capacity.
The following example shows how to use the AWS CLI on Linux to retrieve the minimum, maximum, and average capacity values for a given DB instance, measured every 10 minutes over one hour. The Linux `date` command 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/Neptune"
--statistics Minimum Maximum Average \
--dimensions Name=DBInstanceIdentifier,Value=(instance ID) \
--query 'sort_by(Datapoints[*].{min:Minimum,max:Maximum,avg:Average,ts:Timestamp},&ts)' \
--output table
```