The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 139 lines 4.54 KB
Raw
1 ---
2 title: Connections
3 description: Prisma Connections materialize database credentials — a conventional databaseUrl, direct and pooled connection strings, parsed origins for Hyperdrive, and the Connect runtime binding.
4 ---
5
6 A `Prisma.Connection` is a credential (an API key) for one
7 database. The `name` prop is optional — alchemy derives one from the
8 logical ID and appends the resource's instance identity so
9 connections stay unambiguous — and every secret output is `Redacted`
10 so nothing prints in logs or plan output.
11
12 ```typescript
13 import * as Prisma from "@alchemy.run/prisma";
14
15 const connection = yield* Prisma.Connection("api", {
16 database: postgres,
17 });
18 ```
19
20 ## Connection outputs
21
22 ```typescript
23 connection.databaseUrl; // conventional app URL (pooled → direct → Accelerate)
24 connection.directConnectionString; // direct Postgres URL
25 connection.pooledConnectionString; // pooled Postgres URL
26 connection.accelerateConnectionString; // Accelerate URL, when the database has one
27 connection.origin; // parsed direct connection components
28 connection.pooledOrigin; // parsed pooled connection components
29 ```
30
31 `databaseUrl` is the serverless-safe default for application
32 traffic: it prefers the pooled endpoint, then direct, then
33 Accelerate. For a standalone database under a project created with
34 `createDatabase: false`, pass it (and the direct URL for migration
35 tooling) straight into an app's env:
36
37 ```typescript
38 const app = yield* Prisma.Compute("api", {
39 project,
40 path: "./app",
41 env: {
42 DATABASE_URL: connection.databaseUrl,
43 DIRECT_URL: connection.directConnectionString,
44 },
45 });
46 ```
47
48 If `Prisma.Project` created the project's default database, omit
49 these env entries. Prisma injects system-managed `DATABASE_URL` and
50 `DATABASE_URL_POOLED` values into Compute deployments automatically.
51
52 ## The origin shape
53
54 `origin` and `pooledOrigin` are the same connections parsed into the
55 structured shape Postgres consumers like `Cloudflare.Hyperdrive`
56 accept — the same shape Neon branches and PlanetScale roles
57 materialize:
58
59 ```typescript
60 type PostgresOrigin = {
61 scheme: "postgres" | "postgresql";
62 host: string;
63 port: number;
64 database: string;
65 user: string;
66 password: Redacted.Redacted<string>;
67 };
68 ```
69
70 Hyperdrive is itself a pooler, so hand it the **direct** origin:
71
72 ```typescript
73 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("api-hd", {
74 origin: connection.origin.as<Prisma.PostgresOrigin>(),
75 });
76 ```
77
78 (The `.as<...>()` narrows the output: a connection to a legacy
79 Accelerate-only database has no direct Postgres endpoint, so
80 `origin` is typed optional.)
81
82 ## The Connect binding
83
84 Inside a Prisma Compute app, AWS Lambda function, Cloudflare Worker,
85 or Cloudflare Container, `Prisma.Connect` resolves the bound
86 connection at runtime as a typed client:
87
88 ```typescript
89 Effect.gen(function* () {
90 const db = yield* Prisma.Connect(connection);
91 const sql = yield* SQL.Postgres({ url: db.databaseUrl });
92
93 return {
94 fetch: Effect.gen(function* () {
95 const users = yield* sql`SELECT * FROM users`;
96 return yield* HttpServerResponse.json(users);
97 }),
98 };
99 }).pipe(Effect.provide(Prisma.ConnectBinding));
100 ```
101
102 At deploy time the binding carries the connection's outputs into the
103 host's environment (env vars on Compute, Lambda, and Containers;
104 secret text bindings on Workers); at runtime `db.databaseUrl` and
105 friends read them back as `Redacted` values.
106
107 A container is a real process with no workerd bindings, so env vars
108 are its only channel — which is exactly why `Prisma.Connect` reaches
109 it and `Cloudflare.Hyperdrive.Connect` does not. Start the container
110 with `api.start({ enableInternet: true })` so it can reach the database. See
111 [Which capabilities reach a container](/cloudflare/compute/containers#which-capabilities-reach-a-container).
112
113 ## Rotation
114
115 Change `rotate` from `false` to `true` to mint fresh credentials on
116 the next deploy while keeping the connection's identity:
117
118 ```typescript
119 const connection = yield* Prisma.Connection("api", {
120 database: postgres,
121 rotate: true,
122 });
123 ```
124
125 Prisma attempts to revoke the previous credentials on a best-effort
126 basis. Downstream consumers receive the new secret on the same deploy
127 through their bindings. To rotate again, deploy once with
128 `rotate: false`, then change it back to `true`.
129
130 ## Where next
131
132 - [Connect from Workers](/prisma/guides/cloudflare-workers) — both
133 wiring styles for Cloudflare, side by side.
134 - [Hyperdrive](/cloudflare/data/hyperdrive) — the full pooling
135 walkthrough.
136
137 Reference:
138
139 - [Connection API reference](/providers/prisma/connection)