Postgres

The Postgres component lets you add a Postgres database to your app using Amazon RDS Postgres.

Create the database

sst.config.ts

const vpc = new sst.aws.Vpc("MyVpc");
const database = new sst.aws.Postgres("MyDatabase", { 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 { Pool } from "pg";

const client = new Pool({
  user: Resource.MyDatabase.username,
  password: Resource.MyDatabase.password,
  database: Resource.MyDatabase.database,
  host: Resource.MyDatabase.host,
  port: Resource.MyDatabase.port,
});
await client.connect();

Running locally

By default, your RDS Postgres database is deployed in sst dev. But let’s say you are running Postgres locally.

docker run \
  --rm \
  -p 5432:5432 \
  -v $(pwd)/.sst/storage/postgres:/var/lib/postgresql/data \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=local \
  postgres:16.4

You can connect to it in sst dev by configuring the dev prop.

sst.config.ts

const postgres = new sst.aws.Postgres("MyPostgres", {
  vpc,
  dev: {
    username: "postgres",
    password: "password",
    database: "local",
    port: 5432
  }
});

This will skip deploying an RDS database and link to the locally running Postgres database instead. Check out the full example.

---

Cost

By default this component uses a Single-AZ Deployment, On-Demand DB Instances of a db.t4g.micro at $0.016 per hour. And 20GB of General Purpose gp3 Storage at $0.115 per GB per month.

That works out to $0.016 x 24 x 30 + $0.115 x 20 or $14 per month. Adjust this for the instance type and the storage you are using.

The above are rough estimates for us-east-1, check out the RDS for PostgreSQL pricing for more details.

RDS Proxy

If you enable the proxy, it uses Provisioned instances with 2 vCPUs at $0.015 per hour.

That works out to an additional $0.015 x 2 x 24 x 30 or $22 per month.

The above are rough estimates for us-east-1, check out the RDS Proxy pricing for more details.

---

Constructor

new Postgres(name, args, opts?)

Parameters

• name string

• args PostgresArgs

• opts? ComponentResourceOptions

PostgresArgs

database?

Type Input<string>

Default Based on the name of the current app

Name of a database that is automatically created.

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.

{
  database: "acme"
}

dev?

Type Object

• database?

• host?

• password?

• port?

• username?

Configure how this component works in sst dev.

By default, your Postgres database is deployed in sst dev. But if you want to instead connect to a locally running Postgres database, you can configure the dev prop.

Note

By default, this creates a new RDS database even in sst dev.

This will skip deploying an RDS database and link to the locally running Postgres database instead.

Setting the dev prop also means that any linked resources will connect to the right database both in sst dev and sst deploy.

{
  dev: {
    username: "postgres",
    password: "password",
    database: "postgres",
    host: "localhost",
    port: 5432
  }
}

dev.database?

Type Input<string>

Default Inherit from the top-level database.

The database of the local Postgres to connect to when running in dev.

dev.host?

Type Input<string>

Default “localhost”

The host of the local Postgres to connect to when running in dev.

dev.password?

Type Input<string>

Default Inherit from the top-level password.

The password of the local Postgres to connect to when running in dev.

dev.port?

Type Input<number>

Default 5432

The port of the local Postgres to connect to when running in dev.

dev.username?

Type Input<string>

Default Inherit from the top-level username.

The username of the local Postgres to connect to when running in dev.

instance?

Type Input<string>

Default “t4g.micro”

The type of instance to use for the database. Check out the supported instance types.

{
  instance: "m7g.xlarge"
}

multiAz?

Type Input<boolean>

Default false

Enable Multi-AZ deployment for the database.

This creates a standby replica for the database in another availability zone (AZ). The standby database provides automatic failover in case the primary database fails. However, when the primary database is healthy, the standby database is not used for serving read traffic.

Caution

Using Multi-AZ will approximately double the cost of the database since it will be deployed in two AZs.

{
  multiAz: true
}

password?

Type Input<string>

Default A random password is generated.

The password of the master user.

{
  password: "Passw0rd!"
}

Use Secrets to manage the password.

{
  password: new sst.Secret("MyDBPassword").value
}

proxy?

Type Input<boolean | Object>

• credentials? Input<Input<Object>[]>

  • password

  • username

Default false

Enable RDS Proxy for the database.

{
  proxy: true
}

proxy.credentials?

Type Input<Input<Object>[]>

Additional credentials the proxy can use to connect to the database. You don’t need to specify the master user credentials as they are always added by default.

Note

This component will not create the Postgres users listed here. You need to create them manually in the database.

{
  credentials: [
    {
      username: "metabase",
      password: "Passw0rd!",
    }
  ]
}

Use Secrets to manage the password.

{
  credentials: [
    {
      username: "metabase",
      password: new sst.Secret("MyDBPassword").value,
    }
  ]
}

proxy.credentials[].password

Type Input<string>

The password of the user.

proxy.credentials[].username

Type Input<string>

The username of the user.

storage?

Type Input<“${number} GB” | “${number} TB”>

Default “20 GB”

The maximum storage limit for the database.

RDS will autoscale your storage to match your usage up to the given limit. You are not billed for the maximum storage limit, You are only billed for the storage you use.

Note

You are only billed for the storage you use, not the maximum limit.

By default, gp3 storage volumes are used without additional provisioned IOPS. This provides a good baseline performance for most use cases.

The minimum storage size is 20 GB. And the maximum storage size is 64 TB.

{
  storage: "100 GB"
}

transform?

Type Object

• instance?

• parameterGroup?

• proxy?

• subnetGroup?

Transform how this component creates its underlying resources.

transform.instance?

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

Transform the database instance in the RDS Cluster.

transform.parameterGroup?

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

Transform the RDS parameter group.

transform.proxy?

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

Transform the RDS Proxy.

transform.subnetGroup?

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

Transform the RDS subnet group.

username?

Type Input<string>

Default “postgres”

The username of the master user.

Caution

Changing the username will cause the database to be destroyed and recreated.

{
  username: "admin"
}

version?

Type Input<string>

Default “16.4”

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

{
  version: "17.2"
}

vpc

Type Vpc | Input<Object>

• subnets

The VPC subnets to use for the database.

{
  vpc: {
    subnets: ["subnet-0db7376a7ad4db5fd ", "subnet-06fc7ee8319b2c0ce"],
  }
}

Or create a Vpc component.

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

And pass it in. The database will be placed in the private subnets.

{
  vpc: myVpc
}

vpc.subnets

Type Input<Input<string>[]>

A list of subnet IDs in the VPC.

Properties

database

Type Output<string>

The name of the database.

host

Type Output<string>

The host of the database.

id

Type Output<string>

The identifier of the Postgres instance.

nodes

Type Object

• instance

nodes.instance

Type undefined | Instance

password

Type undefined | Output<string>

The password of the master user.

port

Type Output<number>

The port of the database.

proxyId

Type Output<string>

The name of the Postgres proxy.

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.

• database string

  The name of the database.

• host string

  The host of the database.

• password undefined | string

  The password of the master user.

• port number

  The port of the database.

• username string

  The username of the master user.

Methods

static get

Postgres.get(name, args, opts?)

Parameters

• name string

  The name of the component.

• args PostgresGetArgs

  The arguments to get the Postgres database.

• opts? ComponentResourceOptions

Returns Postgres

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

Tip

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

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

sst.config.ts

const database = $app.stage === "frank"
  ? sst.aws.Postgres.get("MyDatabase", {
      id: "app-dev-mydatabase",
      proxyId: "app-dev-mydatabase-proxy",
    })
  : new sst.aws.Postgres("MyDatabase", {
      proxy: true,
    });

Here app-dev-mydatabase is the ID of the database, and app-dev-mydatabase-proxy is the ID of the proxy created in the dev stage. You can find these by outputting the database ID and proxy ID in the dev stage.

sst.config.ts

return {
  id: database.id,
  proxyId: database.proxyId,
};

PostgresGetArgs

id

Type Input<string>

The ID of the database.

proxyId?

Type Input<string>

The ID of the proxy.