sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ aws/ data/ rds.mdx

Aurora is AWS's managed Postgres/MySQL. Bringing it up by hand means a secret, a subnet group, a cluster, instances, and optionally a proxy — alchemy wraps all of that in the Aurora helper, one call that returns every underlying DB* resource so you can drop down to the canonical surface (DBCluster, DBInstance, DBProxy, …) whenever you outgrow the defaults.

At runtime there are two ways in: the Connect binding, which resolves host, port, and credentials from Secrets Manager so you can query it with Effect SQL, and the Data API (AWS.RDSData.*), which executes SQL over an HTTPS endpoint with no database connection at all.

Network prerequisite

Aurora lives inside a VPC. If you don't have one, the Network helper builds the standard public/private layout in one call; two security groups let the function reach the database on the Postgres port and nothing else:

const network = yield* AWS.EC2.Network("Network", {
  cidrBlock: "10.0.0.0/16",
  availabilityZones: 2,
  nat: "single",
});

const functionSecurityGroup = yield* AWS.EC2.SecurityGroup(
  "FunctionSecurityGroup",
  {
    vpcId: network.vpcId,
    description: "Security group for the service function",
  },
);

const databaseSecurityGroup = yield* AWS.EC2.SecurityGroup(
  "DatabaseSecurityGroup",
  {
    vpcId: network.vpcId,
    description: "Security group for the Aurora cluster",
    ingress: [
      {
        ipProtocol: "tcp",
        fromPort: 5432,
        toPort: 5432,
        referencedGroupId: functionSecurityGroup.groupId,
        description: "Allow the function to reach Aurora PostgreSQL",
      },
    ],
  },
);

See VPC & networking for what Network creates and how to build the same layout by hand.

The Aurora helper

Aurora needs only the subnets and security groups the database should live in:

const db = yield* AWS.RDS.Aurora("Database", {
  subnetIds: network.privateSubnetIds,
  securityGroupIds: [databaseSecurityGroup.groupId],
});

That one call creates:

  • a Secrets Manager secret with a generated 32-character password for the admin user (app by default),
  • a DB subnet group over the subnets you passed,
  • an Aurora PostgreSQL cluster (aurora-postgresql) with a database named app, storage snapshots tagged, and the Data API enabled (dataApi: false to turn it off),
  • one Serverless v2 writer instance scaling between 0.5 and 1 ACU.

The result exposes every underlying resource — db.secret, db.subnetGroup, db.cluster, db.writer, db.readers, and db.proxy when enabled — so expanding into the low-level AWS.RDS.DB* surface never means rewriting the stack.

Readers, scaling, and a proxy

Grow the same call as needs grow:

const db = yield* AWS.RDS.Aurora("Database", {
  subnetIds: network.privateSubnetIds,
  securityGroupIds: [databaseSecurityGroup.groupId],
  readers: 2,
  proxy: true,
  scaling: { minCapacity: 0.5, maxCapacity: 4 },
});
  • readers adds read replicas alongside the writer, with promotion tiers set so failover order is deterministic.
  • proxy: true wires up an RDS Proxy — the IAM role that reads the secret, the proxy itself (TLS required by default), and a target group pointed at the cluster. Pass an object instead of true to tune auth, the target group, or add an extra endpoint.
  • scaling sets the Serverless v2 ACU range; for provisioned instances set instanceClass: "db.r6g.large" instead of the default db.serverless.

Connect from Lambda with Effect SQL

The Connect binding resolves connection settings — host, port, database, username, password — for a cluster, proxy, or proxy endpoint. Credentials are read from Secrets Manager at request time, so they never land in environment variables, and the binding attaches the secretsmanager:GetSecretValue IAM statement to the function automatically.

Wrap it in an Effect service so the rest of your code depends on query, not on Aurora:

// src/database.ts
import * as AWS from "@alchemy.run/aws";
import * as SQL from "@alchemy.run/sql/Postgres";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import type { SqlError } from "effect/sql/SqlError";
import { Network } from "./network.ts";

export class Database extends Context.Service<
  Database,
  {
    query(
      statement: string,
    ): Effect.Effect<ReadonlyArray<Record<string, unknown>>, SqlError>;
  }
>()("Database") {}

export const DatabaseAurora = Layer.effect(
  Database,
  Effect.gen(function* () {
    const { vpc, databaseSecurityGroup } = yield* Network;

    const db = yield* AWS.RDS.Aurora("Database", {
      subnetIds: vpc.privateSubnetIds,
      securityGroupIds: [databaseSecurityGroup.groupId],
    });

    const connect = yield* AWS.RDS.Connect(db.cluster, {
      secret: db.secret,
      database: "app",
    });

    const sql = yield* SQL.Postgres({
      url: connect.pipe(Effect.map((connection) => connection.url)),
    });

    return Database.of({
      query: (statement) => sql.unsafe(statement),
    });
  }),
);

yield* AWS.RDS.Connect(db.cluster, ...) runs in the function's Construction phase and returns an inner Effect; each yield* of that inner Effect at runtime resolves fresh ConnectionInfo from the secret. SQL.Postgres resolves its url on the first query of each invocation and closes the pool when the invocation settles. Network here is the same network from the prerequisite section, wrapped in its own layer (see the examples/aws-rds for the full three-file layout).

The Lambda function provides both layers plus the AWS.RDS.ConnectHttp implementation and serves queries over HTTP:

// src/api.ts
import * as AWS from "@alchemy.run/aws";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import { Database, DatabaseAurora } from "./database.ts";
import { NetworkLive } from "./network.ts";

export default class Api extends AWS.Lambda.Function<Api>()(
  "Api",
  { main: import.meta.url, runtime: "nodejs24.x" },
  Effect.gen(function* () {
    const db = yield* Database;

    return {
      fetch: db.query("select now()::text as now").pipe(
        Effect.flatMap((rows) => HttpServerResponse.json(rows[0] ?? null)),
        Effect.catchTag("SqlError", (error) =>
          HttpServerResponse.json({ error: error.message }, { status: 500 }),
        ),
      ),
    };
  }).pipe(
    Effect.provide(
      Layer.provideMerge(
        Layer.mergeAll(DatabaseAurora),
        Layer.mergeAll(NetworkLive, AWS.RDS.ConnectHttp),
      ),
    ),
  ),
) {}

The handler only sees Database — swap DatabaseAurora for a layer backed by Neon or a local Postgres and nothing above it changes.

Yield the function in your Stack as usual:

// alchemy.run.ts
import * as Alchemy from "alchemy";
import * as AWS from "@alchemy.run/aws";
import * as Effect from "effect/Effect";
import Api from "./src/api.ts";

export default Alchemy.Stack(
  "MyApp",
  { providers: AWS.providers(), state: AWS.state() },
  Effect.gen(function* () {
    const api = yield* Api;
    return { url: api.functionUrl };
  }),
);

To reach a private cluster over a direct connection, the Lambda function also accepts a vpc prop (vpc: { subnetIds, securityGroupIds }) that attaches it to the VPC and adds the AWSLambdaVPCAccessExecutionRole managed policy for you.

The Data API

Aurora's Data API executes SQL over an HTTPS endpoint — no connection pool, no driver. The Aurora helper enables it by default, and the AWS.RDSData bindings expose it the same way as any other capability:

// Construction
const execute = yield* AWS.RDSData.ExecuteStatement(db.cluster, {
  secret: db.secret,
  database: "app",
});

// runtime
const result = yield* execute({ sql: "select now()" });

Provide AWS.RDSData.ExecuteStatementHttp as a layer on the function. The binding attaches both the rds-data:ExecuteStatement and secret-read IAM statements — no policy JSON to write.

Transactions and batches follow the same shape: BatchExecuteStatement, BeginTransaction, CommitTransaction, and RollbackTransaction, each with a matching *Http layer.

Where next

  • Drizzle + Aurora PostgreSQL — a standalone Lambda application with IAM database authentication, verified TLS, and controlled schema setup.

  • Drizzle + Aurora DSQL — a different database with a public IAM-authenticated endpoint, no Aurora PostgreSQL cluster or VPC required.

  • SQL databases — database engines, connection paths, and client choices.

  • VPC & networking — the Network helper and the primitives underneath it.

  • Lambda — the runtime this page binds Aurora into.

  • Secrets & env — how the generated secret and GetSecretValue binding this page relies on actually work.

  • Neon — serverless Postgres with branching, no VPC required.

  • PlanetScale — horizontally sharded MySQL and Postgres.

Reference: