Postgres.v1

The Postgres component lets you add a Postgres database to your app using Amazon Aurora Serverless v2.

For existing usage, rename sst.aws.Postgres to sst.aws.Postgres.v1. For new Postgres, use the latest Postgres component instead.

Caution

This component has been deprecated.

What changed:

• In this version, the database used AWS RDS Aurora Serverless v2, which supported RDS Data API. This allowed your machine to connect to the database during “sst dev” without the need for a VPN.
• In the new version, the database now uses AWS RDS Postgres. The “sst.aws.Vpc” component has been enhanced to set up a secure tunnel, enabling seamlessly connections to the database. Postgres provides greater flexibility and wider feature support while being cheaper to run.

Note

Data API for Aurora Postgres Serverless v2 is still being rolled out in all regions.

To connect to your database from your Lambda functions, you can use the AWS Data API. It does not need a persistent connection, and works over HTTP. You also don’t need a VPN to connect to it locally.

Create the database

sst.config.ts

const vpc = new sst.aws.Vpc("MyVpc");
const database = new sst.aws.Postgres.v1("MyDatabase", { vpc });

Change the scaling config

sst.config.ts

new sst.aws.Postgres.v1("MyDatabase", {
  scaling: {
    min: "2 ACU",
    max: "128 ACU"
  },
  vpc
});

Link to a resource

You can link your database to other resources, like a function or your Next.js app.

sst.config.ts

new sst.aws.Nextjs("MyWeb", {
  link: [database],
  vpc
});

Once linked, you can connect to it from your function code.

app/page.tsx

import { Resource } from "sst";
import { drizzle } from "drizzle-orm/aws-data-api/pg";
import { RDSDataClient } from "@aws-sdk/client-rds-data";

drizzle(new RDSDataClient({}), {
  database: Resource.MyDatabase.database,
  secretArn: Resource.MyDatabase.secretArn,
  resourceArn: Resource.MyDatabase.clusterArn
});

---

Constructor

new Postgres.v1(name, args, opts?)

Parameters

• name string

• args PostgresArgs

• opts? ComponentResourceOptions

PostgresArgs

databaseName?

Type Input<string>

Default Based on the name of the current app

Name of a database that is automatically created inside the cluster.

The name must begin with a letter and contain only lowercase letters, numbers, or underscores. By default, it takes the name of the app, and replaces the hyphens with underscores.

{
  databaseName: "acme"
}

scaling?

Type Input<Object>

• max?

• min?

Default {min: “0.5 ACU”, max: “4 ACU”}

The Aurora Serverless v2 scaling config. By default, the cluster has one DB instance that is used for both writes and reads. The instance can scale from the minimum number of ACUs to the maximum number of ACUs.

Caution

Aurora Serverless v2 does not scale down to 0. The minimum cost of a Postgres cluster per month is roughly 0.5 * $0.12 per ACU hour * 24 hrs * 30 days = $43.20.

An ACU or Aurora Capacity Unit is a combination of CPU and RAM. The cost of an Aurora Serverless v2 cluster is based on the ACU hours used. Additionally, you are billed for I/O and storage used by the cluster. Read more here.

Each ACU is roughly equivalent to 2 GB of memory. So pick the minimum and maximum based on the baseline and peak memory usage of your app.

scaling.max?

Type Input<“${number} ACU”>

Default 4 ACU

The maximum number of ACUs, ranges from 1 to 128, in increments of 0.5.

{
  scaling: {
    max: "128 ACU"
  }
}

scaling.min?

Type Input<“${number} ACU”>

Default 0.5 ACU

The minimum number of ACUs, ranges from 0.5 to 128, in increments of 0.5.

For your production workloads, setting a minimum of 0.5 ACUs might not be a great idea due to the following reasons, you can also read more here.

• It takes longer to scale from a low number of ACUs to a much higher number.
• Query performance depends on the buffer cache. So if frequently accessed data cannot fit into the buffer cache, you might see uneven performance.
• The max connections for a 0.5 ACU Postgres instance is capped at 2000.

{
  scaling: {
    min: "2 ACU"
  }
}

transform?

Type Object

• cluster?

• instance?

• subnetGroup?

Transform how this component creates its underlying resources.

transform.cluster?

Type ClusterArgs | (args: ClusterArgs, opts: ComponentResourceOptions, name: string) => void

Transform the RDS Cluster.

transform.instance?

Type ClusterInstanceArgs | (args: ClusterInstanceArgs, opts: ComponentResourceOptions, name: string) => void

Transform the database instance in the RDS Cluster.

transform.subnetGroup?

Type SubnetGroupArgs | (args: SubnetGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the RDS subnet group.

version?

Type Input<string>

Default “15.5”

The Postgres engine version. Check out the available versions in your region.

{
  version: "13.9"
}

vpc

Type “default” | Input<Object>

• privateSubnets

• securityGroups

The VPC to use for the database cluster.

Each AWS account has a default VPC. If default is specified, the default VPC is used.

Note

The default VPC does not have private subnets and is not recommended for production use.

{
  vpc: {
    privateSubnets: ["subnet-0db7376a7ad4db5fd ", "subnet-06fc7ee8319b2c0ce"],
    securityGroups: ["sg-0399348378a4c256c"],
  }
}

Or create a Vpc component.

const myVpc = new sst.aws.Vpc("MyVpc");

And pass it in.

{
  vpc: myVpc
}

vpc.privateSubnets

Type Input<Input<string>[]>

A list of private subnet IDs in the VPC. The database will be placed in the private subnets.

vpc.securityGroups

Type Input<Input<string>[]>

A list of VPC security group IDs.

Properties

clusterArn

Type Output<string>

The ARN of the RDS Cluster.

clusterID

Type Output<string>

The ID of the RDS Cluster.

database

Type Output<string>

The name of the database.

host

Type Output<string>

The host of the database.

nodes

Type Object

• cluster

• instance

nodes.cluster

Type Cluster

nodes.instance

Type ClusterInstance

password

Type Output<string>

The password of the master user.

port

Type Output<number>

The port of the database.

secretArn

Type Output<string>

The ARN of the master user secret.

username

Type Output<string>

The username of the master user.

SDK

Use the SDK in your runtime to interact with your infrastructure.

---

Links

This is accessible through the Resource object in the SDK.

• clusterArn string

  The ARN of the RDS Cluster.

• database string

  The name of the database.

• host string

  The host of the database.

• password string

  The password of the master user.

• port number

  The port of the database.

• secretArn string

  The ARN of the master user secret.

• username string

  The username of the master user.

Methods

static get

Postgres.get(name, clusterID)

Parameters

• name string

  The name of the component.

• clusterID Input<string>

  The id of the existing Postgres cluster.

Returns Postgres

Reference an existing Postgres cluster with the given cluster name. This is useful when you create a Postgres cluster in one stage and want to share it in another. It avoids having to create a new Postgres cluster in the other stage.

Tip

You can use the static get method to share Postgres clusters across stages.

Imagine you create a cluster in the dev stage. And in your personal stage frank, instead of creating a new cluster, you want to share the same cluster from dev.

sst.config.ts

const database = $app.stage === "frank"
  ? sst.aws.Postgres.v1.get("MyDatabase", "app-dev-mydatabase")
  : new sst.aws.Postgres.v1("MyDatabase");

Here app-dev-mydatabase is the ID of the cluster created in the dev stage. You can find this by outputting the cluster ID in the dev stage.

sst.config.ts

return {
  cluster: database.clusterID
};