docs(): add v7 migration guide

Author: mhartington

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

@@ -0,0 +1,266 @@
+---
+title: 'Upgrade to Prisma ORM 7'
+metaTitle: 'Upgrade to Prisma ORM 7'
+metaDescription: 'Guides on how to upgrade to Prisma ORM 7'
+tocDepth: 3
+toc: true
+---
+
+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.
+
+<details>
+<summary>Questions answered in this page</summary>
+
+- What changed in Prisma 7?
+- How do I upgrade safely?
+- Which breaking changes affect my app?
+
+</details>
+
+## Upgrade the `prisma` and `@prisma/client` packages to v7
+
+To upgrade to Prisma ORM v7 from an earlier version, you need to update both the `prisma` and `@prisma/client` packages:
+
+<TabbedContent code>
+
+<TabItem value="npm">
+
+```terminal
+npm install @prisma/client@7
+npm install -D prisma@7
+```
+
+</TabItem>
+
+<TabItem value="yarn">
+
+```terminal
+yarn up prisma@7 @prisma/client@7
+```
+
+</TabItem>
+
+<TabItem value="pnpm">
+
+```terminal
+pnpm upgrade prisma@7 @prisma/client@7
+```
+
+</TabItem>
+
+<TabItem value="bun">
+
+```terminal
+bun add @prisma/client@7
+bun add prisma@7 --dev
+```
+
+</TabItem>
+
+</TabbedContent>
+
+:::danger
+
+Before you upgrade, check each breaking change below to see how the upgrade might affect your application.
+
+:::
+
+## Breaking changes
+
+This section gives an overview of breaking changes in Prisma ORM v7.
+
+### Minimum supported Node.js & TypeScript versions
+
+|            | Minimum Version | Recommended |
+|------------|-----------------|-------------|
+| Node       | 20.19.0         | 22.x        |
+| TypeScript | 5.4.0           | 5.9.x       |
+
+### ESM Support 
+Prisma ORM now ships as an ES module, module format supported in Bun, Deno, and Node. Set the
+`type` field in your `package.json` to `module`
+
+```json
+{
+  "type": "module",
+  "scripts": {...},
+}
+```
+
+If you are using TypeScript, you need to configure your `tsconfig.json` to be able to consume ES modules
+
+```json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "target": "ES2023",
+    "strict": true,
+    "esModuleInterop": true
+  }
+}
+```
+
+
+### Prisma Schema Changes
+
+The older `prisma-client-js` provider will be removed in future releases of Prisma ORM. Upgrade to
+the new `prisma-client` provider which uses the new Rust-free client. This will give you faster
+queries, smaller bundle size, and require less system resources when deployed to your server.
+
+
+#### Before
+```prisma
+generator client {
+  provider = "prisma-client-js"
+  engineType = "binary"
+}
+```
+
+#### After
+```prisma
+generator client {
+  provider = "prisma-client"
+}
+```
+
+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)
+
+
+### Driver Adapters and Client Instantiation
+The way to create a new Prisma Client has changed to require a driver adapter for all databases.
+This change aligns with the move to make the main Prisma Clinet as lean and open as possible. For
+instance, if you are using Prisma Postgres, you now need the `@prisma/adapter-pg` adapter. This also
+means the signature for creating a new Prisma Client has changed slightly:
+
+#### Before
+
+```ts
+import { PrismaClient } from '@prisma/client';
+const prisma = new PrismaClient({
+  datasources: {
+    db: { url: process.env.DATABASE_URL },
+  },
+  datasourceUrl: process.env.DATABASE_URL,
+});
+```
+
+#### After
+
+```ts
+import { PrismaClient } from './generated/prisma/client.js';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+const adapter = new PrismaPg({ 
+  connectionString: process.env.DATABASE_URL 
+});
+const prisma = new PrismaClient({ adapter });
+```
+
+If you are using SQLite, you can use the `@prisma/adapter-better-sqlite3`:
+
+```ts
+import { PrismaClient } from './generated/prisma/client.js';
+import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3';
+
+const adapter = new PrismaBetterSQLite3({
+  url: process.env.DATABASE_URL || 'file:./dev.db'
+})
+
+export const prisma = new PrismaClient({ adapter })
+```
+
+### Explicit loading of Environment Variables
+In Prisma ORM 7.0.0, environment variables are not loaded by default. Instead developers need to
+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.
+
+
+<TabbedContent code>
+
+<TabItem value="npm">
+
+```terminal
+npm install dotenv
+```
+
+</TabItem>
+
+<TabItem value="yarn">
+
+```terminal
+yarn add dotenv
+```
+
+</TabItem>
+
+<TabItem value="pnpm">
+
+```terminal
+pnpm add dotenv
+```
+
+</TabItem>
+
+</TabbedContent>
+
+For bun users, no action is required as bun will automatically load `.env` files. 
+
+### Prisma Config is now used to configure the Prisma CLI
+
+Prisma Config is now the default place for configuring how the Prisma CLI interacts with your
+database. You now configure your database URL, schema location, migration output, and custom seed
+scripts. 
+
+```ts
+import 'dotenv/config'
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  // the main entry for your scheam
+  schema: 'prisma/schema.prisma',
+  // where migrations should be generated
+  // what script to run for "prisma db seed"
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',
+  },
+  // The database URL 
+  datasource: {
+    // Type Safe env() helper 
+    // Does not replace the need for dotenv
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+
+
+### Metrics has been removed from the Client extensions
+
+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. 
+If you need this feature, use the underlying driver adapter for the database you are using and
+incorporate Client extensions to expose that information.
+
+### Client Middleware has been removed
+
+The client middleware API has been removed in favor of using
+[Extensions](orm/prisma-client/client-extensions). 
+
+```ts
+// ❌ Old (removed)
+prisma.$use(async (params, next) => {
+  // middleware logic
+  return next(params)
+})
+// ✅ New (use extensions)
+const prisma = new PrismaClient().$extends({
+  query: {
+    user: {
+      async findMany({ args, query }) {
+        // extension logic
+        return query(args)
+      }
+    }
+  }
+})
+```

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

@@ -24,6 +24,7 @@ To upgrade to the latest version of Prisma ORM:
 
 ### Prisma ORM 2 and onwards
 
+- [Upgrade to Prisma ORM 7](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-7)
 - [Upgrade to Prisma ORM 6](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-6)
 - [Upgrade to Prisma ORM 5](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-5)
 - [Upgrade to Prisma ORM 4](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-4)