Aurora Serverless automatically adjusts compute capacity based on application demand. Two generations are available:
- Serverless v1 — uses
engine_mode = "serverless" and a scaling_configuration block. Supports MySQL 5.6/5.7 and PostgreSQL 10/11 (all end-of-life). Suitable only for existing v1 workloads.
- Serverless v2 — uses
engine_mode = "provisioned" (the default) with a serverlessv2_scaling_configuration block and cluster_instance_class = "db.serverless". Supports current Aurora MySQL and PostgreSQL engine versions.
For new clusters, use Serverless v2. It supports more engine versions, has faster scaling, supports Multi-AZ and global databases, and can be mixed with provisioned instances in the same cluster.
Serverless v1 vs v2 comparison
| Feature | Serverless v1 | Serverless v2 |
|---|
engine_mode | "serverless" | "provisioned" |
| Capacity unit | ACU (Aurora Capacity Unit) | ACU |
| Scaling speed | Minutes | Seconds |
| Multi-AZ | No | Yes |
| Global database | No | Yes |
| Mixed provisioned instances | No | Yes |
| HTTP Data API | Yes (enable_http_endpoint) | Yes (PostgreSQL, enable_http_endpoint) |
scaling_configuration block | Yes | No |
serverlessv2_scaling_configuration block | No | Yes |
| Supported engines | aurora (MySQL 5.6), aurora-mysql (5.7), aurora-postgresql (10/11) | aurora-mysql 8.0+, aurora-postgresql 13+ |
Serverless v2 examples
The following examples are taken from examples/serverless/.
MySQL Serverless v2
PostgreSQL Serverless v2
module "aurora_mysql" {
source = "terraform-aws-modules/rds-aurora/aws"
name = "my-mysql-serverlessv2"
engine = "aurora-mysql"
engine_mode = "provisioned"
engine_version = "8.0"
storage_encrypted = true
master_username = "root"
vpc_id = module.vpc.vpc_id
db_subnet_group_name = module.vpc.database_subnet_group_name
security_group_ingress_rules = {
private-az1 = {
cidr_ipv4 = element(module.vpc.private_subnets_cidr_blocks, 0)
}
private-az2 = {
cidr_ipv4 = element(module.vpc.private_subnets_cidr_blocks, 1)
}
private-az3 = {
cidr_ipv4 = element(module.vpc.private_subnets_cidr_blocks, 2)
}
}
cluster_monitoring_interval = 60
apply_immediately = true
skip_final_snapshot = true
serverlessv2_scaling_configuration = {
min_capacity = 2
max_capacity = 10
}
cluster_instance_class = "db.serverless"
instances = {
one = {}
two = {}
}
tags = local.tags
}
This example also enables the HTTP endpoint (Data API) and configures auto-pause via seconds_until_auto_pause.data "aws_rds_engine_version" "postgresql" {
engine = "aurora-postgresql"
version = "17.5"
}
module "aurora_postgresql" {
source = "terraform-aws-modules/rds-aurora/aws"
name = "my-postgresql-serverlessv2"
engine = data.aws_rds_engine_version.postgresql.engine
engine_mode = "provisioned"
engine_version = data.aws_rds_engine_version.postgresql.version
storage_encrypted = true
master_username = "root"
vpc_id = module.vpc.vpc_id
db_subnet_group_name = module.vpc.database_subnet_group_name
security_group_ingress_rules = {
private-az1 = {
cidr_ipv4 = element(module.vpc.private_subnets_cidr_blocks, 0)
}
private-az2 = {
cidr_ipv4 = element(module.vpc.private_subnets_cidr_blocks, 1)
}
private-az3 = {
cidr_ipv4 = element(module.vpc.private_subnets_cidr_blocks, 2)
}
}
cluster_monitoring_interval = 60
apply_immediately = true
skip_final_snapshot = true
enable_http_endpoint = true
serverlessv2_scaling_configuration = {
min_capacity = 0
max_capacity = 10
seconds_until_auto_pause = 3600
}
cluster_instance_class = "db.serverless"
cluster_timeouts = {
delete = "30m"
}
instances = {
one = {}
two = {}
}
instance_timeouts = {
delete = "30m"
}
tags = local.tags
}
Serverless v2 configuration reference
Set cluster_instance_class = "db.serverless" for every instance in the cluster. Capacity is controlled by the serverlessv2_scaling_configuration block:
serverlessv2_scaling_configuration = {
min_capacity = 0 # Minimum ACUs. 0 enables auto-pause.
max_capacity = 10 # Maximum ACUs.
seconds_until_auto_pause = 3600 # Idle seconds before pausing (optional).
}
| Attribute | Required | Description |
|---|
max_capacity | Yes | Maximum Aurora Capacity Units (ACUs). Valid range: 0.5–256. |
min_capacity | No | Minimum ACUs. Set to 0 to enable auto-pause. |
seconds_until_auto_pause | No | Seconds of inactivity before the cluster pauses. Only applies when min_capacity = 0. |
seconds_until_auto_pause in Serverless v2 requires min_capacity = 0. The cluster scales to zero ACUs and pauses. The first connection after a pause incurs a cold-start delay of a few seconds.
Serverless v1 configuration reference
Serverless v1 is in maintenance mode. AWS recommends migrating to Serverless v2. Use Serverless v1 only if you have an existing cluster that cannot be migrated yet.
engine_mode = "serverless". The scaling_configuration block controls capacity:
module "aurora_serverless_v1" {
source = "terraform-aws-modules/rds-aurora/aws"
name = "my-serverless-v1"
engine = "aurora-postgresql"
engine_version = "11.21"
engine_mode = "serverless"
vpc_id = module.vpc.vpc_id
db_subnet_group_name = module.vpc.database_subnet_group_name
scaling_configuration = {
auto_pause = true
min_capacity = 2
max_capacity = 16
seconds_until_auto_pause = 300
timeout_action = "ForceApplyCapacityChange"
}
# Serverless v1 clusters do not use the `instances` map
# or cluster_instance_class
enable_http_endpoint = true # HTTP Data API
tags = local.tags
}
scaling_configuration attributes
| Attribute | Type | Description |
|---|
auto_pause | bool | Whether to automatically pause the cluster when idle. Default: true. |
min_capacity | number | Minimum ACUs. Valid values depend on engine: 1, 2, 4, 8, 16, 32, 64, 128, 256. |
max_capacity | number | Maximum ACUs. Same valid values as min_capacity. |
seconds_until_auto_pause | number | Seconds of inactivity before auto-pause. Default: 300. Range: 300–86400. |
seconds_before_timeout | number | Seconds before scaling times out. Range: 60–600. |
timeout_action | string | Action when a scaling point is not found: "ForceApplyCapacityChange" or "RollbackCapacityChange". |
HTTP endpoint (Data API)
The HTTP Data API lets you execute SQL statements against an Aurora Serverless v1 cluster over HTTPS without a persistent database connection. Enable it with:
enable_http_endpoint = true
enable_http_endpoint enables the Data API for Serverless v1 clusters (engine_mode = "serverless"). It is also used in the Serverless v2 PostgreSQL example with engine_mode = "provisioned". The variable description in the module states it is “Only valid when engine_mode is set to serverless” — consult the current AWS provider documentation for the latest supported configurations.
Supporting infrastructure
Both v1 and v2 require a VPC with database subnets:
provider "aws" {
region = "eu-west-1"
}
data "aws_availability_zones" "available" {
filter {
name = "opt-in-status"
values = ["opt-in-not-required"]
}
}
locals {
vpc_cidr = "10.0.0.0/16"
azs = slice(data.aws_availability_zones.available.names, 0, 3)
}
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 6.0"
name = "my-serverless-vpc"
cidr = local.vpc_cidr
azs = local.azs
private_subnets = [for k, v in local.azs : cidrsubnet(local.vpc_cidr, 8, k + 3)]
database_subnets = [for k, v in local.azs : cidrsubnet(local.vpc_cidr, 8, k + 6)]
}
