Skip to content

Commit b1543d7

Browse files
mhartingtoncoderabbitai[bot]
authored and
aidankmcalister
committed
docs(): add v7 migration guide (#7249)
* docs(): add v7 migration guide * docs(): update based on feedback * Update content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * docs(): update based on feedback * docs(): update based on feedback * docs(): update based on feedback --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent 7cf2b32 commit b1543d7

4 files changed

Lines changed: 623 additions & 1 deletion

File tree

‎content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
title: 'Upgrade to Prisma ORM 7'
3+
metaTitle: 'Upgrade to Prisma ORM 7'
4+
metaDescription: 'Guide on how to upgrade to Prisma ORM 7'
5+
tocDepth: 3
6+
toc: true
7+
---
8+
9+
Prisma ORM v7 introduces **breaking changes** when you upgrade from an earlier Prisma ORM version. This guide explains how this upgrade might affect your application and gives instructions on how to handle any changes.
10+
11+
<details>
12+
<summary>Questions answered in this page</summary>
13+
14+
- What changed in Prisma 7?
15+
- How do I upgrade safely?
16+
- Which breaking changes affect my app?
17+
18+
</details>
19+
20+
For developers using AI Agents, we have a [migration prompt](/docs/ai/prompts/prisma-7) that you can
21+
add to your project for automatic migrations.
22+
23+
## Upgrade the `prisma` and `@prisma/client` packages to v7
24+
25+
To upgrade to Prisma ORM v7 from an earlier version, you need to update both the `prisma` and `@prisma/client` packages:
26+
27+
<TabbedContent code>
28+
29+
<TabItem value="npm">
30+
31+
```terminal
32+
npm install @prisma/client@7
33+
npm install -D prisma@7
34+
```
35+
36+
</TabItem>
37+
38+
<TabItem value="yarn">
39+
40+
```terminal
41+
yarn up prisma@7 @prisma/client@7
42+
```
43+
44+
</TabItem>
45+
46+
<TabItem value="pnpm">
47+
48+
```terminal
49+
pnpm upgrade prisma@7 @prisma/client@7
50+
```
51+
52+
</TabItem>
53+
54+
<TabItem value="bun">
55+
56+
```terminal
57+
bun add @prisma/client@7
58+
bun add prisma@7 --dev
59+
```
60+
61+
</TabItem>
62+
63+
</TabbedContent>
64+
65+
:::danger
66+
67+
Before you upgrade, check each breaking change below to see how the upgrade might affect your application.
68+
69+
:::
70+
71+
## Breaking changes
72+
73+
This section gives an overview of breaking changes in Prisma ORM v7.
74+
75+
### Minimum supported Node.js & TypeScript versions
76+
77+
| | Minimum Version | Recommended |
78+
|------------|-----------------|-------------|
79+
| Node | 20.19.0 | 22.x |
80+
| TypeScript | 5.4.0 | 5.9.x |
81+
82+
### ESM support
83+
Prisma ORM now ships as an ES module, the module format supported in Bun, Deno, and Node. Set the
84+
`type` field in your `package.json` to `module`
85+
86+
```json
87+
{
88+
"type": "module",
89+
"scripts": {...},
90+
}
91+
```
92+
93+
If you are using TypeScript, you need to configure your `tsconfig.json` to be able to consume ES modules
94+
95+
```json
96+
{
97+
"compilerOptions": {
98+
"module": "ESNext",
99+
"moduleResolution": "node",
100+
"target": "ES2023",
101+
"strict": true,
102+
"esModuleInterop": true
103+
}
104+
}
105+
```
106+
107+
108+
### Prisma schema changes
109+
110+
The older `prisma-client-js` provider will be removed in future releases of Prisma ORM. Upgrade to
111+
the new `prisma-client` provider which uses the new Rust-free client. This will give you faster
112+
queries, smaller bundle size, and require less system resources when deployed to your server.
113+
114+
115+
#### Before
116+
```prisma
117+
generator client {
118+
provider = "prisma-client-js"
119+
engineType = "binary"
120+
}
121+
```
122+
123+
#### After
124+
```prisma
125+
generator client {
126+
provider = "prisma-client"
127+
}
128+
```
129+
130+
Additionally other fields such as `url`, `directUrl`, and `shadowDatabaseUrl` in the `datasource` block are deprecated and now part of the [Prisma Config](/orm/reference/prisma-config-reference)
131+
132+
```ts
133+
import 'dotenv/config'
134+
import { defineConfig, env } from 'prisma/config'
135+
136+
export default defineConfig({
137+
datasource: {
138+
url: env('DATABASE_URL'),
139+
directUrl: env('DIRECT_URL'),
140+
shadowDatabaseUrl: env('SHADOW_DATABASE_URL')
141+
},
142+
})
143+
```
144+
145+
146+
### Driver adapters and client instantiation
147+
The way to create a new Prisma Client has changed to require a driver adapter for all databases.
148+
This change aligns with the move to make the main Prisma Client as lean and open as possible. For
149+
instance, if you are using Prisma Postgres, you now need the `@prisma/adapter-pg` adapter. This also
150+
means the signature for creating a new Prisma Client has changed slightly:
151+
152+
#### Before
153+
154+
```ts
155+
import { PrismaClient } from '@prisma/client';
156+
const prisma = new PrismaClient({
157+
datasources: {
158+
db: { url: process.env.DATABASE_URL },
159+
},
160+
datasourceUrl: process.env.DATABASE_URL,
161+
});
162+
```
163+
164+
#### After
165+
166+
```ts
167+
import { PrismaClient } from './generated/prisma/client';
168+
import { PrismaPg } from '@prisma/adapter-pg';
169+
170+
const adapter = new PrismaPg({
171+
connectionString: process.env.DATABASE_URL
172+
});
173+
const prisma = new PrismaClient({ adapter });
174+
```
175+
176+
If you are using SQLite, you can use the `@prisma/adapter-better-sqlite3`:
177+
178+
```ts
179+
import { PrismaClient } from './generated/prisma/client';
180+
import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3';
181+
182+
const adapter = new PrismaBetterSQLite3({
183+
url: process.env.DATABASE_URL || 'file:./dev.db'
184+
})
185+
186+
export const prisma = new PrismaClient({ adapter })
187+
```
188+
189+
### Explicit loading of environment variables
190+
In Prisma ORM 7.0.0, environment variables are not loaded by default. Instead developers need to
191+
explicitly load the variables when calling the `prisma` CLI. Libraries like [`dotenv`](https://github.com/motdotla/dotenv) can be used to manage loading environment variables by reading the appropriate `.env` file.
192+
193+
194+
<TabbedContent code>
195+
196+
<TabItem value="npm">
197+
198+
```terminal
199+
npm install dotenv
200+
```
201+
202+
</TabItem>
203+
204+
<TabItem value="yarn">
205+
206+
```terminal
207+
yarn add dotenv
208+
```
209+
210+
</TabItem>
211+
212+
<TabItem value="pnpm">
213+
214+
```terminal
215+
pnpm add dotenv
216+
```
217+
218+
</TabItem>
219+
220+
</TabbedContent>
221+
222+
For bun users, no action is required as bun will automatically load `.env` files.
223+
224+
### Prisma config is now used to configure the Prisma CLI
225+
226+
Prisma Config is now the default place for configuring how the Prisma CLI interacts with your
227+
database. You now configure your database URL, schema location, migration output, and custom seed
228+
scripts.
229+
230+
```ts
231+
import 'dotenv/config'
232+
import { defineConfig, env } from 'prisma/config'
233+
234+
export default defineConfig({
235+
// the main entry for your schema
236+
schema: 'prisma/schema.prisma',
237+
// where migrations should be generated
238+
// what script to run for "prisma db seed"
239+
migrations: {
240+
path: 'prisma/migrations',
241+
seed: 'tsx prisma/seed.ts',
242+
},
243+
// The database URL
244+
datasource: {
245+
// Type Safe env() helper
246+
// Does not replace the need for dotenv
247+
url: env('DATABASE_URL'),
248+
},
249+
})
250+
```
251+
252+
253+
254+
### Metrics has been removed from the Client extensions
255+
256+
The Metrics preview feature was deprecated in [Prisma ORM 6.14.0](https://github.com/prisma/prisma/releases/tag/6.14.0) and has been removed for Prisma ORM 7.0.0.
257+
If you need this feature, you can use the underlying driver adapter for your database, or Client Extensions to make this information available.
258+
259+
For example, a basic `totalQueries` counter:
260+
261+
```ts
262+
const total = 0
263+
const prisma = new PrismaClient().$extends({
264+
client: {
265+
$log: (s: string) => console.log(s),
266+
async $totalQueries() { return total; },
267+
},
268+
query: {
269+
$allModels: {
270+
async $allOperations({ query, args }) {
271+
total += 1;
272+
return query(args);
273+
},
274+
},
275+
},
276+
})
277+
278+
async function main() {
279+
prisma.$log('Hello world')
280+
const totalQueries = await prisma.$totalQueries()
281+
console.log(totalQueries)
282+
}
283+
```
284+
285+
### Client middleware has been removed
286+
287+
The client middleware API has been removed. If possible, use [Client Extensions](orm/prisma-client/client-extensions).
288+
289+
```ts
290+
// ❌ Old (removed)
291+
prisma.$use(async (params, next) => {
292+
// middleware logic
293+
return next(params)
294+
})
295+
// ✅ New (use extensions)
296+
const prisma = new PrismaClient().$extends({
297+
query: {
298+
user: {
299+
async findMany({ args, query }) {
300+
// extension logic
301+
return query(args)
302+
}
303+
}
304+
}
305+
})
306+
```
307+
308+
### Various environment variables have been removed
309+
310+
We've removed a small selection of Prisma-specific environment variables.
311+
312+
- `PRISMA_CLI_QUERY_ENGINE_TYPE`
313+
- `PRISMA_CLIENT_ENGINE_TYPE`
314+
- `PRISMA_QUERY_ENGINE_BINARY`
315+
- `PRISMA_QUERY_ENGINE_LIBRARY`
316+
- `PRISMA_GENERATE_SKIP_AUTOINSTALL`
317+
- `PRISMA_SKIP_POSTINSTALL_GENERATE`
318+
- `PRISMA_GENERATE_IN_POSTINSTALL`
319+
- `PRISMA_GENERATE_DATAPROXY`
320+
- `PRISMA_GENERATE_NO_ENGINE`
321+
- `PRISMA_CLIENT_NO_RETRY`
322+
- `PRISMA_MIGRATE_SKIP_GENERATE`
323+
- `PRISMA_MIGRATE_SKIP_SEED`

‎content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ To upgrade to the latest version of Prisma ORM:
2424

2525
### Prisma ORM 2 and onwards
2626

27+
- [Upgrade to Prisma ORM 7](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-7)
2728
- [Upgrade to Prisma ORM 6](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-6)
2829
- [Upgrade to Prisma ORM 5](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-5)
2930
- [Upgrade to Prisma ORM 4](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-4)

0 commit comments

Comments
 (0)