The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | --- |
| 2 | title: RDS & Aurora |
| 3 | description: Stand up an Aurora cluster in one call with the Aurora helper, connect from Lambda over the Connect binding with Effect SQL, or skip connections entirely with the Data API. |
| 4 | --- |
| 5 | |
| 6 | Aurora is AWS's managed Postgres/MySQL. Bringing it up by hand |
| 7 | means a secret, a subnet group, a cluster, instances, and |
| 8 | optionally a proxy — alchemy wraps all of that in the |
| 9 | **`Aurora` helper**, one call that returns every underlying |
| 10 | `DB*` resource so you can drop down to the canonical surface |
| 11 | (`DBCluster`, `DBInstance`, `DBProxy`, …) whenever you outgrow |
| 12 | the defaults. |
| 13 | |
| 14 | At runtime there are two ways in: the **`Connect` binding**, |
| 15 | which resolves host, port, and credentials from Secrets Manager |
| 16 | so you can query it with [Effect SQL](/sql/effect-sql/postgres), and the |
| 17 | **Data API** (`AWS.RDSData.*`), which executes SQL over an HTTPS |
| 18 | endpoint with no database connection at all. |
| 19 | |
| 20 | ## Network prerequisite |
| 21 | |
| 22 | Aurora lives inside a VPC. If you don't have one, the |
| 23 | [`Network` helper](/aws/networking) builds the standard |
| 24 | public/private layout in one call; two security groups let the |
| 25 | function reach the database on the Postgres port and nothing |
| 26 | else: |
| 27 | |
| 28 | ```typescript |
| 29 | const network = yield* AWS.EC2.Network("Network", { |
| 30 | cidrBlock: "10.0.0.0/16", |
| 31 | availabilityZones: 2, |
| 32 | nat: "single", |
| 33 | }); |
| 34 | |
| 35 | const functionSecurityGroup = yield* AWS.EC2.SecurityGroup( |
| 36 | "FunctionSecurityGroup", |
| 37 | { |
| 38 | vpcId: network.vpcId, |
| 39 | description: "Security group for the service function", |
| 40 | }, |
| 41 | ); |
| 42 | |
| 43 | const databaseSecurityGroup = yield* AWS.EC2.SecurityGroup( |
| 44 | "DatabaseSecurityGroup", |
| 45 | { |
| 46 | vpcId: network.vpcId, |
| 47 | description: "Security group for the Aurora cluster", |
| 48 | ingress: [ |
| 49 | { |
| 50 | ipProtocol: "tcp", |
| 51 | fromPort: 5432, |
| 52 | toPort: 5432, |
| 53 | referencedGroupId: functionSecurityGroup.groupId, |
| 54 | description: "Allow the function to reach Aurora PostgreSQL", |
| 55 | }, |
| 56 | ], |
| 57 | }, |
| 58 | ); |
| 59 | ``` |
| 60 | |
| 61 | See [VPC & networking](/aws/networking) for what `Network` |
| 62 | creates and how to build the same layout by hand. |
| 63 | |
| 64 | ## The Aurora helper |
| 65 | |
| 66 | [`Aurora`](/providers/aws/rds/aurora) needs only the subnets and |
| 67 | security groups the database should live in: |
| 68 | |
| 69 | ```typescript |
| 70 | const db = yield* AWS.RDS.Aurora("Database", { |
| 71 | subnetIds: network.privateSubnetIds, |
| 72 | securityGroupIds: [databaseSecurityGroup.groupId], |
| 73 | }); |
| 74 | ``` |
| 75 | |
| 76 | That one call creates: |
| 77 | |
| 78 | - a **Secrets Manager secret** with a generated 32-character |
| 79 | password for the admin user (`app` by default), |
| 80 | - a **DB subnet group** over the subnets you passed, |
| 81 | - an **Aurora PostgreSQL cluster** (`aurora-postgresql`) with a |
| 82 | database named `app`, storage snapshots tagged, and the |
| 83 | **Data API enabled** (`dataApi: false` to turn it off), |
| 84 | - one **Serverless v2 writer** instance scaling between 0.5 and |
| 85 | 1 ACU. |
| 86 | |
| 87 | The result exposes every underlying resource — `db.secret`, |
| 88 | `db.subnetGroup`, `db.cluster`, `db.writer`, `db.readers`, |
| 89 | and `db.proxy` when enabled — so expanding into the low-level |
| 90 | `AWS.RDS.DB*` surface never means rewriting the stack. |
| 91 | |
| 92 | ## Readers, scaling, and a proxy |
| 93 | |
| 94 | Grow the same call as needs grow: |
| 95 | |
| 96 | ```typescript |
| 97 | const db = yield* AWS.RDS.Aurora("Database", { |
| 98 | subnetIds: network.privateSubnetIds, |
| 99 | securityGroupIds: [databaseSecurityGroup.groupId], |
| 100 | readers: 2, |
| 101 | proxy: true, |
| 102 | scaling: { minCapacity: 0.5, maxCapacity: 4 }, |
| 103 | }); |
| 104 | ``` |
| 105 | |
| 106 | - `readers` adds read replicas alongside the writer, with |
| 107 | promotion tiers set so failover order is deterministic. |
| 108 | - `proxy: true` wires up an RDS Proxy — the IAM role that reads |
| 109 | the secret, the proxy itself (TLS required by default), and a |
| 110 | target group pointed at the cluster. Pass an object instead of |
| 111 | `true` to tune auth, the target group, or add an extra |
| 112 | endpoint. |
| 113 | - `scaling` sets the Serverless v2 ACU range; for provisioned |
| 114 | instances set `instanceClass: "db.r6g.large"` instead of the |
| 115 | default `db.serverless`. |
| 116 | |
| 117 | ## Connect from Lambda with Effect SQL |
| 118 | |
| 119 | The [`Connect`](/providers/aws/rds/connect) binding resolves |
| 120 | connection settings — host, port, database, username, password — |
| 121 | for a cluster, proxy, or proxy endpoint. Credentials are read |
| 122 | from Secrets Manager **at request time**, so they never land in |
| 123 | environment variables, and the binding attaches the |
| 124 | `secretsmanager:GetSecretValue` IAM statement to the function |
| 125 | automatically. |
| 126 | |
| 127 | Wrap it in an Effect service so the rest of your code depends on |
| 128 | `query`, not on Aurora: |
| 129 | |
| 130 | ```typescript |
| 131 | // src/database.ts |
| 132 | import * as AWS from "@alchemy.run/aws"; |
| 133 | import * as SQL from "@alchemy.run/sql/Postgres"; |
| 134 | import * as Context from "effect/Context"; |
| 135 | import * as Effect from "effect/Effect"; |
| 136 | import * as Layer from "effect/Layer"; |
| 137 | import type { SqlError } from "effect/sql/SqlError"; |
| 138 | import { Network } from "./network.ts"; |
| 139 | |
| 140 | export class Database extends Context.Service< |
| 141 | Database, |
| 142 | { |
| 143 | query( |
| 144 | statement: string, |
| 145 | ): Effect.Effect<ReadonlyArray<Record<string, unknown>>, SqlError>; |
| 146 | } |
| 147 | >()("Database") {} |
| 148 | |
| 149 | export const DatabaseAurora = Layer.effect( |
| 150 | Database, |
| 151 | Effect.gen(function* () { |
| 152 | const { vpc, databaseSecurityGroup } = yield* Network; |
| 153 | |
| 154 | const db = yield* AWS.RDS.Aurora("Database", { |
| 155 | subnetIds: vpc.privateSubnetIds, |
| 156 | securityGroupIds: [databaseSecurityGroup.groupId], |
| 157 | }); |
| 158 | |
| 159 | const connect = yield* AWS.RDS.Connect(db.cluster, { |
| 160 | secret: db.secret, |
| 161 | database: "app", |
| 162 | }); |
| 163 | |
| 164 | const sql = yield* SQL.Postgres({ |
| 165 | url: connect.pipe(Effect.map((connection) => connection.url)), |
| 166 | }); |
| 167 | |
| 168 | return Database.of({ |
| 169 | query: (statement) => sql.unsafe(statement), |
| 170 | }); |
| 171 | }), |
| 172 | ); |
| 173 | ``` |
| 174 | |
| 175 | `yield* AWS.RDS.Connect(db.cluster, ...)` runs in the function's |
| 176 | Construction phase and returns an inner Effect; each `yield*` of that |
| 177 | inner Effect at runtime resolves fresh `ConnectionInfo` from the |
| 178 | secret. `SQL.Postgres` resolves its `url` on the first query of each |
| 179 | invocation and closes the pool when the invocation settles. `Network` here is the same network from the prerequisite |
| 180 | section, wrapped in its own layer (see the |
| 181 | [`examples/aws-rds`](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-rds) |
| 182 | for the full three-file layout). |
| 183 | |
| 184 | The Lambda function provides both layers plus the |
| 185 | `AWS.RDS.ConnectHttp` implementation and serves queries over |
| 186 | HTTP: |
| 187 | |
| 188 | ```typescript |
| 189 | // src/api.ts |
| 190 | import * as AWS from "@alchemy.run/aws"; |
| 191 | import * as Effect from "effect/Effect"; |
| 192 | import * as Layer from "effect/Layer"; |
| 193 | import * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 194 | import { Database, DatabaseAurora } from "./database.ts"; |
| 195 | import { NetworkLive } from "./network.ts"; |
| 196 | |
| 197 | export default class Api extends AWS.Lambda.Function<Api>()( |
| 198 | "Api", |
| 199 | { main: import.meta.url, runtime: "nodejs24.x" }, |
| 200 | Effect.gen(function* () { |
| 201 | const db = yield* Database; |
| 202 | |
| 203 | return { |
| 204 | fetch: db.query("select now()::text as now").pipe( |
| 205 | Effect.flatMap((rows) => HttpServerResponse.json(rows[0] ?? null)), |
| 206 | Effect.catchTag("SqlError", (error) => |
| 207 | HttpServerResponse.json({ error: error.message }, { status: 500 }), |
| 208 | ), |
| 209 | ), |
| 210 | }; |
| 211 | }).pipe( |
| 212 | Effect.provide( |
| 213 | Layer.provideMerge( |
| 214 | Layer.mergeAll(DatabaseAurora), |
| 215 | Layer.mergeAll(NetworkLive, AWS.RDS.ConnectHttp), |
| 216 | ), |
| 217 | ), |
| 218 | ), |
| 219 | ) {} |
| 220 | ``` |
| 221 | |
| 222 | The handler only sees `Database` — swap `DatabaseAurora` for a |
| 223 | layer backed by [Neon](/neon) or a local Postgres and nothing |
| 224 | above it changes. |
| 225 | |
| 226 | Yield the function in your Stack as usual: |
| 227 | |
| 228 | ```typescript |
| 229 | // alchemy.run.ts |
| 230 | import * as Alchemy from "alchemy"; |
| 231 | import * as AWS from "@alchemy.run/aws"; |
| 232 | import * as Effect from "effect/Effect"; |
| 233 | import Api from "./src/api.ts"; |
| 234 | |
| 235 | export default Alchemy.Stack( |
| 236 | "MyApp", |
| 237 | { providers: AWS.providers(), state: AWS.state() }, |
| 238 | Effect.gen(function* () { |
| 239 | const api = yield* Api; |
| 240 | return { url: api.functionUrl }; |
| 241 | }), |
| 242 | ); |
| 243 | ``` |
| 244 | |
| 245 | To reach a private cluster over a direct connection, the Lambda |
| 246 | function also accepts a `vpc` prop |
| 247 | (`vpc: { subnetIds, securityGroupIds }`) that attaches it to the |
| 248 | VPC and adds the `AWSLambdaVPCAccessExecutionRole` managed |
| 249 | policy for you. |
| 250 | |
| 251 | ## The Data API |
| 252 | |
| 253 | Aurora's Data API executes SQL over an HTTPS endpoint — no |
| 254 | connection pool, no driver. The `Aurora` helper enables it by |
| 255 | default, and the `AWS.RDSData` bindings expose it the same way |
| 256 | as any other capability: |
| 257 | |
| 258 | ```typescript |
| 259 | // Construction |
| 260 | const execute = yield* AWS.RDSData.ExecuteStatement(db.cluster, { |
| 261 | secret: db.secret, |
| 262 | database: "app", |
| 263 | }); |
| 264 | |
| 265 | // runtime |
| 266 | const result = yield* execute({ sql: "select now()" }); |
| 267 | ``` |
| 268 | |
| 269 | Provide `AWS.RDSData.ExecuteStatementHttp` as a layer on the |
| 270 | function. The binding attaches both the |
| 271 | `rds-data:ExecuteStatement` and secret-read IAM statements — |
| 272 | no policy JSON to write. |
| 273 | |
| 274 | Transactions and batches follow the same shape: |
| 275 | `BatchExecuteStatement`, `BeginTransaction`, `CommitTransaction`, |
| 276 | and `RollbackTransaction`, each with a matching `*Http` layer. |
| 277 | |
| 278 | ## Where next |
| 279 | |
| 280 | - [Drizzle + Aurora PostgreSQL](/aws/data/drizzle-aurora) — a standalone Lambda |
| 281 | application with IAM database authentication, verified TLS, and controlled schema setup. |
| 282 | - [Drizzle + Aurora DSQL](/aws/data/drizzle-dsql) — a different database with a |
| 283 | public IAM-authenticated endpoint, no Aurora PostgreSQL cluster or VPC required. |
| 284 | |
| 285 | - [SQL databases](/sql/databases) — database engines, connection paths, and client choices. |
| 286 | |
| 287 | |
| 288 | - [VPC & networking](/aws/networking) — the `Network` helper and |
| 289 | the primitives underneath it. |
| 290 | - [Lambda](/aws/compute/lambda) — the runtime this page binds Aurora |
| 291 | into. |
| 292 | - [Secrets & env](/aws/security/secrets-env) — how the generated secret |
| 293 | and GetSecretValue binding this page relies on actually work. |
| 294 | - [Neon](/neon) — serverless Postgres with branching, no VPC |
| 295 | required. |
| 296 | - [PlanetScale](/planetscale) — horizontally sharded MySQL and |
| 297 | Postgres. |
| 298 | |
| 299 | Reference: |
| 300 | |
| 301 | - [`Aurora` reference](/providers/aws/rds/aurora) — every prop |
| 302 | on the helper. |
| 303 | - [`Connect` reference](/providers/aws/rds/connect) |
| 304 | - [`ExecuteStatement` reference](/providers/aws/rdsdata/executestatement) |