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

main
mdx 340 lines 12.3 KB
Raw
1 ---
2 title: Contracts
3 description: Author Prisma ORM v8 contracts in Prisma Schema Language or TypeScript, generate optional Effect bindings and row schemas, and connect them to migrations.
4 ---
5
6 A Prisma ORM v8 **contract** defines your models, fields, relations, and
7 storage mappings. It supplies the types for application queries and the
8 schema that Prisma uses to plan migrations.
9
10 Choose one authoritative source: **Prisma Schema Language (PSL)** or
11 **TypeScript**. Both use the same Effect-native Postgres runtime and
12 [Alchemy migration resources](/sql/prisma/migrations).
13
14 :::caution
15 This guide targets Prisma ORM v8 release candidates and PostgreSQL 17+.
16 The contract toolchain is different from earlier Prisma versions; expect
17 breaking changes between release candidates. See [Postgres](/sql/prisma/postgres)
18 for dependencies and the client API, or the [Cloudflare integration](/cloudflare/data/prisma)
19 for a complete deployment example.
20 :::
21
22 ## Choose an authoring form
23
24 | | PSL-first | TypeScript-first |
25 | --- | --- | --- |
26 | Source of truth | `contract.psl` (or `.prisma`) | `contract.ts` |
27 | Model definitions | Prisma Schema Language | Prisma's native builders |
28 | Application import | Generated `makeDatabase` | The authored `contract` |
29 | Generate before compiling queries | Required | Not required |
30 | Optional Effect row schemas | Generated standalone module | `makeSchemas(contract)` or generation |
31
32 The generated contract files are outputs, not a second schema to edit.
33 TypeScript-first applications can infer query types directly from their
34 source contract; migration tooling still emits contract artifacts.
35
36 ## Define a PSL contract
37
38 Create `src/prisma/contract.psl`:
39
40 ```prisma
41 model User {
42 id id.uuidv7Native()
43 email String @unique
44 name String
45 createdAt temporal.createdAtString()
46 posts Post[]
47 }
48
49 model Post {
50 id id.uuidv7Native()
51 title String
52 authorId Uuid
53 author User @relation(fields: [authorId], references: [id])
54 }
55 ```
56
57 `User` has many posts, and each `Post` belongs to a user through `authorId`.
58 Prisma's built-in field presets provide the ID and creation-time defaults.
59
60 ### Configure PSL generation
61
62 Point Prisma at the source and register Alchemy's Effect outputs in
63 `prisma.config.ts`:
64
65 ```typescript
66 import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";
67 import { definePrismaConfig } from "prisma/config";
68 import { withEffect } from "@alchemy.run/prisma/ORM/generator";
69
70 export default definePrismaConfig({
71 orm: withEffect(
72 ormConfig({
73 contract: "./src/prisma/contract.psl",
74 output: "./src/prisma/generated",
75 }),
76 { client: true, schemas: true },
77 ),
78 });
79 ```
80
81 Paths resolve relative to the configuration file. `withEffect` selects the
82 additional outputs; it does not generate files when the config is imported.
83 Run:
84
85 ```sh
86 pnpm exec alchemy provider prisma generate
87 ```
88
89 This runs offline and emits Prisma's contract artifacts plus the selected
90 Effect bindings. Registration belongs in `prisma.config.ts`, rather than a
91 legacy `generator` block in PSL. Native `prisma contract emit` does not invoke
92 Alchemy's Effect generator.
93
94 ### Query a PSL contract
95
96 Import the generated factory in application code:
97
98 ```typescript
99 import { makeDatabase } from "./prisma/generated/client.ts";
100
101 const db = yield* makeDatabase(connectionString);
102 const users = yield* db.orm.public.User.select("id", "email").all();
103 ```
104
105 These calls run inside an Effect. `connectionString` is an Effect producing a
106 redacted connection string, as returned by Alchemy's database connection bindings.
107 The [Cloudflare integration](/cloudflare/data/prisma) shows Hyperdrive wiring.
108 The generated factory binds your contract to the
109 shared Effect runtime, rather than generating another ORM implementation.
110
111 ## Define a TypeScript contract
112
113 Create `src/prisma/contract.ts` with the equivalent native Prisma builders:
114
115 ```typescript
116 import { defineContract } from "@alchemy.run/prisma/ORM";
117
118 export const contract = defineContract({}, ({ field, model, rel }) => ({
119 models: {
120 User: model("User", {
121 fields: {
122 id: field.id.uuidv7Native(),
123 email: field.text().unique(),
124 name: field.text(),
125 createdAt: field.temporal.createdAtString(),
126 },
127 relations: {
128 posts: rel.hasMany("Post", { by: "authorId" }),
129 },
130 }),
131 Post: model("Post", {
132 fields: {
133 id: field.id.uuidv7Native(),
134 title: field.text(),
135 authorId: field.uuidNative(),
136 },
137 relations: {
138 author: rel.belongsTo("User", { from: "authorId", to: "id" }),
139 },
140 }),
141 },
142 }));
143 ```
144
145 Alchemy's `defineContract` export uses Prisma's original runtime function and
146 builders. It adds compatibility types for metadata lost in Prisma rc.11's
147 published declarations; it is not a separate model language. The adapter
148 supports explicit storage names through `.sql({ table: "users" })` and
149 `.column("created_at")`, but rejects global `snake_case` naming. Defaults on
150 `field.namedType(...)` retain upstream inference limitations. The declaration
151 gaps are tracked in [Prisma #30341](https://github.com/prisma/orm/issues/30341).
152
153 :::note[Cloudflare Workers]
154 Before importing the native contract builder, configure Arktype with
155 `jitless: true` in a separate, first-imported module and preserve that module
156 from tree-shaking. Follow [Configure validation for Workers](/cloudflare/data/prisma#configure-validation-for-workers).
157 Ordinary Node and Bun applications do not need this setup. PSL-first Workers
158 use the emitted contract and do not import the authoring builder.
159 :::
160
161 ### Configure TypeScript emission
162
163 The Prisma CLI and Alchemy's migration resources read the same
164 `prisma.config.ts`:
165
166 ```typescript
167 import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";
168 import { definePrismaConfig } from "prisma/config";
169
170 export default definePrismaConfig({
171 orm: ormConfig({
172 contract: "./src/prisma/contract.ts",
173 output: "./src/prisma/generated",
174 }),
175 });
176 ```
177
178 This config is enough for native contract emission and migration planning.
179 Wrap `ormConfig(...)` with `withEffect` only when you also want generated
180 Effect clients or standalone schemas.
181
182 ### Query the authored contract
183
184 Pass the source contract directly to `Postgres` inside an Effect:
185
186 ```typescript
187 import { Postgres } from "@alchemy.run/prisma/ORM/Postgres";
188 import { contract } from "./prisma/contract.ts";
189
190 const db = yield* Postgres(connectionString, { contract });
191 const users = yield* db.orm.public.User.select("id", "email").all();
192 ```
193
194 No generated application import or explicit contract type parameter is
195 required. Queries, transactions, streaming, errors, and connection cleanup
196 behave the same as the PSL-first factory.
197
198 ## Choose generated outputs
199
200 `alchemy provider prisma generate` supports both authoring forms. The second argument
201 to `withEffect` controls which Effect modules it emits:
202
203 | Options | Effect outputs |
204 | --- | --- |
205 | `{ client: true, schemas: true }` | Client factory and standalone row schemas |
206 | `{ client: true, schemas: false }` | Client factory only |
207 | `{ client: false, schemas: true }` | Standalone row schemas only |
208
209 Both options default to `true`. Prisma's canonical `contract.json` and
210 `contract.d.ts` are emitted in every mode. With both options enabled, the
211 output directory contains:
212
213 ```text
214 src/prisma/generated/
215 ├── contract.json # Runtime contract data
216 ├── contract.d.ts # Contract type declaration
217 ├── runtime.ts # Runtime contract data export
218 ├── client.ts # makeDatabase factory
219 ├── schemas.ts # Standalone Effect row schemas
220 └── index.ts # Selected Effect exports
221 ```
222
223 Schema-only generation also works with a TypeScript source when a frontend
224 needs validators without importing the contract builder.
225
226 ## Validate rows without a database
227
228 TypeScript-first applications can derive schemas directly:
229
230 ```typescript
231 import { makeSchemas } from "@alchemy.run/prisma/ORM/Schema";
232 import * as Schema from "effect/Schema";
233 import { contract } from "./prisma/contract.ts";
234
235 const schemas = makeSchemas(contract);
236 const user = yield* Schema.decodeUnknownEffect(schemas.public.User)(input);
237 ```
238
239 PSL-first applications import the standalone generated module:
240
241 ```typescript
242 import * as Schema from "effect/Schema";
243 import { schemas } from "./prisma/generated/schemas.ts";
244
245 const user = yield* Schema.decodeUnknownEffect(schemas.public.User)(input);
246 ```
247
248 The generated schema module imports Effect, not Alchemy, Prisma, a connection
249 URL, or the generated client.
250
251 These validate **scalar database rows**, not create/update inputs, relation
252 includes, or public API responses. Nullable fields accept `null` but remain
253 required. Defaults do not make row fields optional. Define separate public
254 response schemas when database rows contain private fields.
255
256 Built-in mappings preserve enums, scalar lists, nullable fields, numbers,
257 lossless `bigint`, decimal strings, bytes, and recursive JSON. Prisma's
258 `*-string` temporal codecs remain strings; generation does not convert them
259 to JavaScript `Date`. Unsupported codecs, including Temporal-object codecs,
260 fail with the field path and codec ID rather than accepting unknown values.
261 Value objects, unions, and inherited or variant model schemas are outside this
262 scalar-row generator; use client-only generation and define application schemas
263 for those models.
264
265 ### Map custom scalar codecs
266
267 Provide an explicit codec mapping for additional scalar types:
268
269 ```typescript
270 const options = {
271 codecs: {
272 "custom/date@1": {
273 schema: Schema.Date,
274 expression: "Schema.Date",
275 },
276 },
277 };
278
279 const schemas = makeSchemas(contract, options);
280 ```
281
282 The same mapping belongs in the second argument to `withEffect` for standalone
283 generation. An expression can reference `Schema` or names introduced through
284 its `imports` array. Custom import paths resolve from the generated module.
285 Mappings must describe the codec's actual row representation.
286
287 ## Regenerate during development
288
289 Watch your source while developing:
290
291 ```sh
292 pnpm exec alchemy provider prisma generate --watch
293 ```
294
295 Use `--config ./path/to/prisma.config.ts` to choose another configuration.
296 The watcher observes the configuration directory, excluding generated output
297 and dependencies. Each generation uses a fresh process so imported TypeScript
298 changes are picked up. Keep shared contract modules under that directory.
299 Invalid source reports an error; the watcher remains available for the next edit.
300
301 In a PSL-first project, run generation before type checking or bundling:
302
303 ```sh
304 pnpm exec alchemy provider prisma generate
305 pnpm exec tsc --noEmit
306 ```
307
308 Generation preserves unchanged file contents, removes Effect outputs disabled
309 by configuration, and refuses to overwrite handwritten Effect modules. Commit
310 the generated files used by your application, including `contract.d.ts` if your
311 repository normally ignores declaration files.
312
313 ## Connect the contract to migrations
314
315 The source contract, emitted artifacts, and database each have a separate role:
316
317 | Step | What it does |
318 | --- | --- |
319 | Author | Edit `contract.psl` or `contract.ts` |
320 | Generate | Emit contract artifacts and optional Effect bindings, without a database |
321 | Plan | Compare contracts and write reviewable migration packages |
322 | Apply | Run pending migration packages against the database |
323
324 `Prisma.Contract` uses `prisma.config.ts` to emit the contract and plan missing
325 migration packages during deployment. `Prisma.Migrate` applies those packages.
326 Neither resource runs the optional Effect generator: PSL-first applications
327 must generate their client before compiling or bundling it.
328
329 Changing a source file or running `alchemy provider prisma generate` does not change
330 the database. Follow [Migrations](/sql/prisma/migrations) to review and apply
331 schema changes, including changes that need an explicit data backfill.
332
333 ## Where next
334
335 - [Postgres](/sql/prisma/postgres) — queries, prepared statements, and transactions.
336 - [Cloudflare integration](/cloudflare/data/prisma) — provision a database and query it from a Worker.
337 - [SQL databases](/sql/databases) — database choices and canonical deployment guides.
338 - [Migrations](/sql/prisma/migrations) — plan and apply contract changes on deployment.
339 - [TypeScript-first example](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-neon-prisma) — authored contract with optional standalone schema generation.
340 - [PSL-first example](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-neon-prisma-psl) — PSL source with generated client and schemas.