clover's git

the-knife

1	---
2	title: Postgres
3	description: Prisma Postgres as Stack resources — projects, databases, branch attachment, and a zero-config local database under alchemy dev.
4	---
5
6	A `Prisma.Project` owns everything; a `Prisma.Postgres` database
7	lives inside it. Declare both and alchemy converges them like any
8	other resource.
9
10	## Project
11
12	```typescript
13	import * as Prisma from "alchemy/Prisma";
14
15	const project = yield* Prisma.Project("app", {
16	createDatabase: false,
17	region: "us-east-1",
18	});
19	```
20
21	By default, creating a project also provisions a default Prisma
22	Postgres database in the chosen region. Prisma Compute deployments
23	under that project receive system-managed `DATABASE_URL` and
24	`DATABASE_URL_POOLED` variables automatically. Pass
25	`createDatabase: false` (as above) when you'd rather declare
26	databases explicitly with their own lifecycle and connection outputs.
27
28	:::caution[Projects own their data]
29	Destroying a `Prisma.Project` deletes the project and its contained
30	databases and apps. Use a durable state backend and review the destroy
31	plan before removing a project from a Stack.
32	:::
33
34	## Database
35
36	`Prisma.Postgres` and `Prisma.Database` are the same resource under
37	two names — use whichever reads better. Standalone database resources
38	cannot be the project's default database; let `Prisma.Project` own the
39	default database when you need one:
40
41	```typescript
42	const postgres = yield* Prisma.Postgres("db", {
43	project,
44	region: "us-east-1",
45	});
46	```
47
48	Omit `name` and alchemy generates a stable physical name, so an
49	interrupted create recovers instead of duplicating the database.
50
51	## Branches
52
53	A `Prisma.Branch` groups databases under a git-style name, and a
54	database attaches to one by `branchId` (or `branchGitName`):
55
56	```typescript
57	const branch = yield* Prisma.Branch("preview", { project });
58
59	const previewDb = yield* Prisma.Postgres("preview-db", {
60	project,
61	branchId: branch.branchId,
62	});
63	```
64
65	See [Branches](/prisma/data/branches) for preview-per-stage
66	patterns and default-branch promotion.
67
68	## Local dev
69
70	Under `bun alchemy dev`, the database resolves to a local
71	`@prisma/dev` Postgres instead of the cloud — same outputs, zero
72	provisioning. The `dev` prop tunes it:
73
74	```typescript
75	const postgres = yield* Prisma.Postgres("db", {
76	project,
77	dev: {
78	// run migrations once the local server is ready, with
79	// DATABASE_URL pointing at it
80	migrate: "bun run db:setup",
81	},
82	});
83	```
84
85	`persistenceMode: "stateless"` gives you a fresh database on every
86	dev session; the default (`"stateful"`) keeps data across restarts.
87
88	## Where next
89
90	- [Connections](/prisma/data/connections) — credentials, connection
91	strings, and origins for Hyperdrive.
92	- [Compute](/prisma/compute/apps) — deploy an app next to the database.
93
94	Reference:
95
96	- [Project API reference](/providers/prisma/project)
97	- [Database API reference](/providers/prisma/database)
98	- [Branch API reference](/providers/prisma/branch)