RDS

caution

This is the SST v0.x Constructs doc. SST v1 is now released. If you are using v1, see the v1 Constructs doc. If you are looking to upgrade to v1, check out the migration steps.

The RDS construct is a higher level CDK construct that makes it easy to create an RDS Serverless Cluster. It uses the following defaults:

• Defaults to using the Serverless v1 On-Demand autoscaling configuration to make it serverless.
• Provides a built-in interface for running schema migrations using Kysely.
• Enables Data API to allow your Lambda functions to access the database cluster without needing to deploy the functions in a VPC (virtual private cloud).
• Enables Backup Snapshot to make sure that you don't lose your data.

Initializer

new RDS(scope: Construct, id: string, props: RDSProps)

Parameters

• scope Construct
• id string
• props RDSProps

Examples

Using the minimal config

import { RDS } from "@serverless-stack/resources";

new RDS(this, "Database", {
  engine: "postgresql13.9",
  defaultDatabaseName: "my_database",
});

Configuring auto-scaling

RDS automatically scales the cluster size based on CPU utilization, connections, and available memory. An RDS with the MySQL engine can scale from 1 to 256 ACU (Aurora capacity unit). And an RDS with the PostgreSQL engine can scale from 2 to 384 ACU. You can specify the minimum and maximum range for the cluster. The default minimum and maximum capacity are 2 and 16 ACU.

You can also choose to pause your RDS cluster after a given amount of time with no activity. When the cluster is paused, you are charged only for the storage. If database connections are requested when a cluster is paused, the cluster automatically resumes. By default, the cluster auto-pauses after 5 minutes of inactivity.

For dev stages, it makes sense to pick a low capacity and auto-pause time. And disable it for production stages.

import * as cdk from "aws-cdk-lib";
import * as rds from "aws-cdk-lib/aws-rds";

const prodConfig = {
  autoPause: false,
  minCapacity: "ACU_8",
  maxCapacity: "ACU_64",
};
const devConfig = {
  autoPause: true,
  minCapacity: "ACU_2",
  maxCapacity: "ACU_2",
};

new RDS(this, "Database", {
  engine: "postgresql13.9",
  defaultDatabaseName: "acme",
  scaling: app.stage === "prod" ? prodConfig : devConfig,
});

Read more over on the RDS docs.

Configuring migrations

new RDS(this, "Database", {
  engine: "postgresql13.9",
  defaultDatabaseName: "acme",
  migrations: "path/to/migration/scripts",
});

The RDS construct uses Kysely to run and manage schema migrations. The migrations prop should point to the folder where your migration files are.

On sst deploy, all migrations that have not yet been run will be run as a part of the deploy process. The migrations are executed in alphabetical order by their name.

On sst start, migrations are not automatically run. You can manually run them via the SST Console.

note

New migrations must always have a name that comes alphabetically after the last executed migration.

Migration files should have the following format.

async function up(db) {
  // Migration code
}

async function down(db) {
  // Migration code
}

module.exports = { up, down };

For example:

PostgreSQL migration example

async function up(db) {
  await db.schema
    .createTable("person")
    .addColumn("id", "serial", (col) => col.primaryKey())
    .addColumn("first_name", "varchar", (col) => col.notNull())
    .addColumn("last_name", "varchar")
    .addColumn("gender", "varchar(50)", (col) => col.notNull())
    .execute()
}

async function down(db) {
  await db.schema.dropTable("person").execute()
}

module.exports = { up, down };

MySQL migration example

async function up(db) {
  await db.schema
    .createTable("person")
    .addColumn("id", "integer", (col) => col.autoIncrement().primaryKey())
    .addColumn("first_name", "varchar(255)", (col) => col.notNull())
    .addColumn("last_name", "varchar(255)")
    .addColumn("gender", "varchar(50)", (col) => col.notNull())
    .execute()
}

async function down(db) {
  await db.schema.dropTable("person").execute()
}

module.exports = { up, down };

Read more about writing migrations over on the Kysely docs.

Configuring the RDS cluster

You can configure the internally created CDK ServerlessCluster instance.

import * as cdk from "aws-cdk-lib";

new RDS(this, "Database", {
  engine: "postgresql13.9",
  defaultDatabaseName: "acme",
  rdsServerlessCluster: {
    backupRetention: cdk.Duration.days(7),
  },
});

Import an existing VPC

The RDS construct automatically creates a VPC to deploy the cluster. This VPC contains only PRIVATE and ISOLATED subnets, without NAT Gateways.

note

Since we are using the Data API, you don't need to deploy your Lambda functions into the RDS's VPC.

You can override the internally created VPC instance.

import * as ec2 from "aws-cdk-lib/aws-ec2";

new RDS(this, "Database", {
  engine: "postgresql13.9",
  defaultDatabaseName: "acme",
  rdsServerlessCluster: {  
    vpc: ec2.Vpc.fromLookup(this, "VPC", {
      vpcId: "vpc-xxxxxxxxxx",
    }),
    vpcSubnets: {
      subnetType: ec2.SubnetType.PRIVATE,
    },
  },
});

Properties

An instance of RDS contains the following properties.

clusterArn

Type: string

The ARN of the internally created CDK ServerlessCluster instance.

clusterIdentifier

Type: string

The identifier of the internally created CDK ServerlessCluster instance.

clusterEndpoint

Type: string

The endpoint of the internally created CDK ServerlessCluster instance.

secretArn

Type: string

The ARN of the internally created CDK Secret instance.

migratorFunction

Type : Function

The internally created schema migration Function instance.

rdsServerlessCluster

Type : cdk.aws-rds.ServerlessCluster

The internally created CDK ServerlessCluster instance.

RDSProps

engine

Type : string

Supported engine are mysql5.6, mysql5.7, postgresql11.13, postgresql11.16 and postgresql13.9

defaultDatabaseName

Type : string

Name of a database that's automatically created inside the cluster.

scaling?

Type : RDSScalingProps

Scaling configuration of the cluster.

migrations?

Type : string, defaults to migrations not automatically run on deploy

Path to the directory that contains the migration scripts.

rdsServerlessCluster?

Type : cdk.aws-rds.ServerlessCluster | RDSCdkServerlessClusterProps, defaults to undefined

Optionally pass in a CDK cdk.aws-rds.ServerlessCluster instance or RDSCdkServerlessClusterProps. This allows you to override the default settings this construct uses internally to create the cluster.

RDSScalingProps

autoPause?

Type : boolean | number, defaults to true

The time before an RDS cluster is paused. Pass in true to pause after 5 minutes of inactivity. And pass in false to disable auto-pausing.

Or pass in the number of minutes to wait before the cluster is paused.

minCapacity?

Type : string, defaults to ACU_2

The minimum capacity for an RDS cluster. Supported capacity are ACU_1, ACU_2, ACU_4, ACU_8, ACU_16, ACU_32, ACU_64, ACU_128, ACU_192, ACU_256, and ACU_384

maxCapacity?

Type : string, defaults to ACU_16

The maximum capacity for an RDS cluster. Supported capacity are ACU_1, ACU_2, ACU_4, ACU_8, ACU_16, ACU_32, ACU_64, ACU_128, ACU_192, ACU_256, and ACU_384

RDSCdkServerlessClusterProps

RDSCdkServerlessClusterProps extends cdk.aws-rds.ServerlessClusterProps with the exception that the vpc field is optional, in which case a default VPC will be created. And the engine, defaultDatabaseName, and scaling fields are not accepted. The engine, the default database name, and the scaling options should be configured using the engine, the defaultDatabaseName, and the scaling properties.

You can use RDSCdkServerlessClusterProps to configure all the other table properties.