clover's git

the-knife

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/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 `Cloudflare.Containers.layer(Api, { enableInternet: true })` so
111	it can reach the database. See
112	[Which capabilities reach a container](/cloudflare/compute/containers#which-capabilities-reach-a-container).
113
114	## Rotation
115
116	Change `rotate` from `false` to `true` to mint fresh credentials on
117	the next deploy while keeping the connection's identity:
118
119	```typescript
120	const connection = yield* Prisma.Connection("api", {
121	database: postgres,
122	rotate: true,
123	});
124	```
125
126	Prisma attempts to revoke the previous credentials on a best-effort
127	basis. Downstream consumers receive the new secret on the same deploy
128	through their bindings. To rotate again, deploy once with
129	`rotate: false`, then change it back to `true`.
130
131	## Where next
132
133	- [Connect from Workers](/prisma/guides/cloudflare-workers) — both
134	wiring styles for Cloudflare, side by side.
135	- [Hyperdrive](/cloudflare/data/hyperdrive) — the full pooling
136	walkthrough.
137
138	Reference:
139
140	- [Connection API reference](/providers/prisma/connection)