@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
mdx 304 lines 9.72 KB
Raw
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)