diff --git a/apps/blog/content/blog/is-prisma-8-ready-for-long-lived-production-apps/index.mdx b/apps/blog/content/blog/is-prisma-8-ready-for-long-lived-production-apps/index.mdx index 4c662384b96..f8265a4172a 100644 --- a/apps/blog/content/blog/is-prisma-8-ready-for-long-lived-production-apps/index.mdx +++ b/apps/blog/content/blog/is-prisma-8-ready-for-long-lived-production-apps/index.mdx @@ -105,7 +105,7 @@ The risk teams are taking today is gaps in the implementation. This is a bigger Our own cloud platform API already runs on Prisma 8, so I can say from experience that it's worth it. -For teams already using Prisma 7 on PostgreSQL, I recommend migrating incrementally. Unlike previous versions of Prisma, Prisma 8 and earlier versions can run in parallel against the same database. Queries or execution paths can be switched over one by one and checked to ensure they behave as expected. See the [PostgreSQL upgrade guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql) for more details. +For teams already using Prisma 7 on PostgreSQL, I recommend migrating incrementally. Unlike previous versions of Prisma, Prisma 8 and earlier versions can run in parallel against the same database. Queries or execution paths can be switched over one by one and checked to ensure they behave as expected. See the [PostgreSQL upgrade guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql-incremental) for more details. Prisma 7 will receive bug fixes and security updates for the next 12 months, so teams that want to wait until they have more confidence can do that too. diff --git a/apps/blog/content/blog/prisma-orm-8-closes-330-most-requested-issues/index.mdx b/apps/blog/content/blog/prisma-orm-8-closes-330-most-requested-issues/index.mdx index 24d003ffb6a..eeba258a7f4 100644 --- a/apps/blog/content/blog/prisma-orm-8-closes-330-most-requested-issues/index.mdx +++ b/apps/blog/content/blog/prisma-orm-8-closes-330-most-requested-issues/index.mdx @@ -37,7 +37,7 @@ _Every issue on this list started with a developer taking the time to share a pr Many of the changes in Prisma ORM 8, from TypeScript migrations to the new contract artifact, were shaped by your feedback and discussions on GitHub. -If you tried Prisma before and moved on because of one of these issues, [give Prisma 8 another try](https://www.prisma.io/docs/orm). If you're already on Prisma 7, our [upgrade guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql) will help you make the move. +If you tried Prisma before and moved on because of one of these issues, [give Prisma 8 another try](https://www.prisma.io/docs/orm). If you're already on Prisma 7, our [upgrade guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm) will help you make the move. And if something still doesn't work the way you'd like, [join us on Discord](https://pris.ly/discord), [open a GitHub issue](https://github.com/prisma/orm/issues/new/choose), or upvote an existing one. We use those votes to help prioritize what to build next, and this list shows why your feedback matters. diff --git a/apps/blog/content/blog/prisma-orm-8-nestjs/index.mdx b/apps/blog/content/blog/prisma-orm-8-nestjs/index.mdx index 50ff5e28ef1..b32e426f954 100644 --- a/apps/blog/content/blog/prisma-orm-8-nestjs/index.mdx +++ b/apps/blog/content/blog/prisma-orm-8-nestjs/index.mdx @@ -230,7 +230,7 @@ export class PrismaService implements OnModuleDestroy { } ``` -If you are coming from Prisma ORM 7, the [Prisma ORM 7 to 8 upgrade guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql) shows how contracts and the new query APIs fit together, one route at a time. +If you are coming from Prisma ORM 7, the [Prisma ORM 7 to 8 upgrade guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql-incremental) shows how contracts and the new query APIs fit together, one route at a time. ## Deploy the API to Prisma Compute @@ -297,7 +297,7 @@ The starter annotates each constructor parameter with `@Inject(PrismaService)` o Yes, in early access. Scaffold with `npm create prisma@latest -- my-app --template nest --provider mongodb --package-manager pnpm --yes` (plain npm hits an `ERESOLVE` error in the current `create-prisma` release). The scaffold gives you document models in the contract, and the ORM adds a pipeline builder for aggregations and migration plans that create collections and indexes. The Prisma CLI reads `MONGODB_URL` while the dev server reads `DATABASE_URL`, so export both with the same value. Prisma ORM 8 does not run MongoDB transactions yet. -The [Prisma ORM 7 to 8 upgrade guide for PostgreSQL](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql) has you install Prisma ORM 8 next to Prisma ORM 7, infer a contract from the existing database, and move queries over one route at a time, with `findMany` and `findFirst` becoming `.all()` and `.first()`. In a NestJS app, replace the service that extends `PrismaClient` with an `@Injectable()` class that holds the shared `db` object and calls query functions from `src/prisma/`. +The [Prisma ORM 7 to 8 upgrade guide for PostgreSQL](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql-incremental) has you install Prisma ORM 8 next to Prisma ORM 7, infer a contract from the existing database, and move queries over one route at a time, with `findMany` and `findFirst` becoming `.all()` and `.first()`. In a NestJS app, replace the service that extends `PrismaClient` with an `@Injectable()` class that holds the shared `db` object and calls query functions from `src/prisma/`. diff --git a/apps/docs/content/docs/(index)/index.mdx b/apps/docs/content/docs/(index)/index.mdx index 53fdec0eece..fa76179abd2 100644 --- a/apps/docs/content/docs/(index)/index.mdx +++ b/apps/docs/content/docs/(index)/index.mdx @@ -50,7 +50,7 @@ Prisma is a complete TypeScript stack with one workflow: **build** your app and } /> } /> } /> - } /> + } /> diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx index 9ce0cc28e6a..0ede7bdb4c2 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx @@ -12,7 +12,7 @@ On this page you add Prisma ORM to an app whose PostgreSQL database already has Your app must reach its PostgreSQL database and run on Node.js 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer ([Supported versions](/orm/supported-versions)). Work against a development copy of your database, not production. [Step 9](#9-make-your-first-change-to-the-tables) shows how to apply your changes to production afterwards. -If your database has no tables yet, follow [Add Prisma ORM and PostgreSQL to an existing app](/prisma-orm/quickstart/existing-app/postgresql) instead, which creates the tables for you. If you want Prisma ORM to create a new app for you, follow [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). If your app uses Prisma ORM 7 today, follow [Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql). +If your database has no tables yet, follow [Add Prisma ORM and PostgreSQL to an existing app](/prisma-orm/quickstart/existing-app/postgresql) instead, which creates the tables for you. If you want Prisma ORM to create a new app for you, follow [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). If your app uses Prisma ORM 6 or 7 today, follow [Upgrade to Prisma 8](/guides/upgrade-prisma-orm). :::note[Using Prisma ORM 7?] diff --git a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx index 106061ea139..217d9082ec6 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx @@ -47,7 +47,7 @@ npm install --save-dev prisma tsx typescript `temporal-polyfill` is a peer dependency of `@prisma/orm-postgres` too. It adds `Temporal`, the newer JavaScript date and time API, to runtimes such as Node.js 24 that do not have it built in. npm installs it for you, but with Yarn you add it yourself. -The two Prisma packages have different version numbers, for example `prisma` 8.0.0-rc.32 and `@prisma/orm-postgres` 8.0.0-rc.23. That is normal, and any two `latest` versions work together. +The two Prisma packages have different version numbers, for example `prisma` 8.0.0-rc.33 and `@prisma/orm-postgres` 8.0.0-rc.23. That is normal, and any two `latest` versions work together. ## 2. Create the config file and `.env` diff --git a/apps/docs/content/docs/(index)/prisma-orm/index.mdx b/apps/docs/content/docs/(index)/prisma-orm/index.mdx index fa67ad5ee13..197a9573b41 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/index.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/index.mdx @@ -20,8 +20,8 @@ Pick the page that matches where you are starting from: }> Generate the file that holds your models from the tables you have, then make your next schema change. - }> - Run Prisma ORM 8 next to Prisma ORM 7 in the same app, and move your code over in steps. + }> + Upgrade in one pass, or run Prisma ORM 7 and Prisma 8 side by side and move one route at a time. diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/postgresql.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/postgresql.mdx index 3b3412889f8..b3e9554a09c 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/postgresql.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/postgresql.mdx @@ -8,7 +8,7 @@ metaDescription: 'Add Prisma ORM to an app you already have: run orm init, write This page uses PostgreSQL. [Use MongoDB instead](/prisma-orm/quickstart/existing-app/mongodb). -Use this page when you already have an app and its database has no tables yet. By the end, your app has one model, the database has a table for it, and a script writes and reads a row. You also change the model once and apply the change to the database with a migration. If your database already has tables, follow [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql) instead. If your app uses Prisma ORM 7 today, follow [Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql). +Use this page when you already have an app and its database has no tables yet. By the end, your app has one model, the database has a table for it, and a script writes and reads a row. You also change the model once and apply the change to the database with a migration. If your database already has tables, follow [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql) instead. If your app uses Prisma ORM 6 or 7 today, follow [Upgrade to Prisma 8](/guides/upgrade-prisma-orm). :::note[Using Prisma ORM 7?] diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json b/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json index 50ff6c8d9d0..71600b3f6e2 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json @@ -5,7 +5,7 @@ "[I'm creating a new app](/prisma-orm/quickstart/postgresql)", "[I have an app, but no database yet](/prisma-orm/quickstart/existing-app/postgresql)", "[I have a database already](/prisma-orm/add-to-existing-project/postgresql)", - "[I have a Prisma 7 app](/guides/upgrade-prisma-orm/postgresql)" + "[I have a Prisma 6 or 7 app](/guides/upgrade-prisma-orm)" ], "hiddenPages": [ "mongodb", diff --git a/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx b/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx index b5fff73cd82..104f2b2a77c 100644 --- a/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx +++ b/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx @@ -312,7 +312,7 @@ rm postgres-to-prisma-postgres.dump postgres-restore.list row-counts.sql source- ## Recommended next step: adopt Prisma ORM -Your database migration is complete, and upgrading Prisma ORM is a separate application change. Prisma ORM 8 is a [release candidate](/orm/release-status); to adopt it, follow the [incremental Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql) after the application is stable on Prisma Postgres. +Your database migration is complete, and upgrading Prisma ORM is a separate application change. Prisma ORM 8 is a [release candidate](/orm/release-status); to adopt it, follow the [incremental Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql-incremental) after the application is stable on Prisma Postgres. If you want to complete both changes on the same day, deploy and verify the Prisma Postgres connection first. Upgrade Prisma ORM in a separate commit or deployment so failures have one clear cause. diff --git a/apps/docs/content/docs/cli/orm-init.mdx b/apps/docs/content/docs/cli/orm-init.mdx index ae5e823658f..59acd1a7ebf 100644 --- a/apps/docs/content/docs/cli/orm-init.mdx +++ b/apps/docs/content/docs/cli/orm-init.mdx @@ -127,7 +127,7 @@ After you confirm, `orm init`: It does not write a starter contract, and it changes nothing in `prisma/` or in the database. Prisma ORM 7 keeps owning the schema and its migrations. From now on, `prisma` runs Prisma ORM 8 and `prisma7` runs Prisma ORM 7, so a Prisma ORM 7 command such as `migrate dev` becomes `npx prisma7 migrate dev`. Your application keeps using the Prisma ORM 7 client until you move its routes, one at a time, to the Prisma ORM 8 client in `src/prisma/db.ts`. If the project still uses a Prisma ORM version before 7, so that your `package.json` lists `@prisma/client` below version 7, `orm init` upgrades `@prisma/client` to version 7, because the Prisma ORM 7 CLI it installs needs a client of the same major version. Run `npx prisma7 generate` afterwards to generate the upgraded client. -To finish, set `DATABASE_URL` and run `npx prisma db sign` once. [`db sign`](/cli/db-sign) checks that the database matches the contract and then writes the marker, a row that records which contract the database matches. The row goes in the table `prisma_contract.marker`, which the first `db sign` creates in a PostgreSQL schema of its own named `prisma_contract`, so your own tables do not change. After each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign` again. [Configuration](/cli/configuration#use-a-prisma-orm-7-schema) explains `prisma7Schema`, and [the upgrade guide](/guides/upgrade-prisma-orm/postgresql) covers the rest of the move. +To finish, set `DATABASE_URL` and run `npx prisma db sign` once. [`db sign`](/cli/db-sign) checks that the database matches the contract and then writes the marker, a row that records which contract the database matches. The row goes in the table `prisma_contract.marker`, which the first `db sign` creates in a PostgreSQL schema of its own named `prisma_contract`, so your own tables do not change. After each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign` again. [Configuration](/cli/configuration#use-a-prisma-orm-7-schema) explains `prisma7Schema`, and [the upgrade guide](/guides/upgrade-prisma-orm) covers the rest of the move. ## On a Prisma ORM 6 MongoDB project diff --git a/apps/docs/content/docs/compute/getting-started.mdx b/apps/docs/content/docs/compute/getting-started.mdx index 48ee8631585..cf3cd053a4a 100644 --- a/apps/docs/content/docs/compute/getting-started.mdx +++ b/apps/docs/content/docs/compute/getting-started.mdx @@ -149,3 +149,4 @@ To browse and manage the same resources without the CLI, open the [Console](http - [Deployments](/compute/deployments): inspect, promote, roll back, start, stop. - [Environment variables](/compute/environment-variables): production, preview, and per-branch overrides. - [Environments](/compute/branching): how branches isolate work and map to Git. +- [Deploy an existing app](/guides/compute/deploy-existing-app): move a Node.js server already on Prisma 8 onto Compute. diff --git a/apps/docs/content/docs/compute/github.mdx b/apps/docs/content/docs/compute/github.mdx index 9fdef76d7f3..b079190234a 100644 --- a/apps/docs/content/docs/compute/github.mdx +++ b/apps/docs/content/docs/compute/github.mdx @@ -91,3 +91,4 @@ Uninstalling the app disconnects every repository that was connected through it, - [Deploy on push](/compute/deploy-on-push): the full walkthrough, from connection to a preview for every pushed branch other than the default one. - [Environments](/compute/branching): how platform branches map to Git. - [Environment variables](/compute/environment-variables): per-branch config for previews. +- [Deploy an existing app](/guides/compute/deploy-existing-app): move a Node.js server already on Prisma 8 onto Compute. diff --git a/apps/docs/content/docs/guides/compute/deploy-existing-app.mdx b/apps/docs/content/docs/guides/compute/deploy-existing-app.mdx new file mode 100644 index 00000000000..91c241dafdf --- /dev/null +++ b/apps/docs/content/docs/guides/compute/deploy-existing-app.mdx @@ -0,0 +1,277 @@ +--- +title: Deploy an existing app on Prisma Compute +description: 'Use when a Node.js server already on Prisma 8 with PostgreSQL should deploy on Prisma Compute from GitHub, with a Prisma Postgres database for each branch' +url: /guides/compute/deploy-existing-app +metaTitle: How to deploy an existing Prisma 8 app on Prisma Compute +metaDescription: 'Step-by-step guide to deploying an existing Prisma 8 PostgreSQL app on Prisma Compute: connect the repository in the Console, finish the setup pull request, take the client from the service, ship runtime files, set environment variables, and check the preview.' +--- + +{/* lint-versions-ignore-file: this page pins the Prisma 8 and Composer versions that the Console's Compute setup installs, not npm latest. They are PRISMA_CLI_VERSION and ORM_POSTGRES_VERSION in planComposerSetup.ts in prisma/pdp-control-plane, and the Composer version that matches them; update them together. */} + +{/* cspell:ignore feedbackboard */} + +:::note[Not for an app on Prisma ORM 6 or 7, or for a new app] + +Prisma Compute runs only Prisma 8. To upgrade an app on Prisma ORM 6 or 7 first, start at [Upgrade to Prisma 8](/guides/upgrade-prisma-orm). To start a new app on Compute, follow [Getting started](/compute/getting-started). + +::: + +This guide takes an Express, Fastify, Hono or other Node.js server that already runs Prisma 8 on PostgreSQL and deploys it on [Prisma Compute](/compute) from its GitHub repository. At the end, every push deploys the app: the default branch to production, and every other branch to a preview with its own Prisma Postgres database. + +The examples continue the feedback board from [Prisma ORM 6 or 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql): Express 4, EJS views, compiled with `tsc` to `dist/` and started with `node dist/server.js`. + +If you use a coding agent, the `prisma-compute` skill follows this guide: + +```npm +npx skills add prisma/skills --skill prisma-compute +``` + +## Prerequisites + +- **Node.js 24.11 or newer.** `prisma dev`, which runs the app locally the way Compute runs it, refuses older versions. +- **A Prisma 8 app on PostgreSQL** at `prisma@8.0.0-rc.27` and `@prisma/orm-postgres@8.0.0-rc.20`, with its client created by `postgres({ contract, url })`, the emitted contract in `src/prisma/`, and its migrations in `migrations/app/`. These are the versions the Console's setup works with today; newer ones do not yet deploy. +- **The app in a GitHub repository**, with a committed lockfile, and a [Prisma Console](https://console.prisma.io) workspace you can connect it to. + +## How the app changes on Compute + +On Prisma Compute, the app does not read `DATABASE_URL`. The deploy creates a Prisma Postgres database for each branch, applies `migrations/app/` to it, and hands the app a client connected to it. `DATABASE_URL` is a reserved variable that holds the placeholder `-`, so an app that keeps reading it deploys and then fails every query with `P1001` and `host: "base"`. + +Two more changes follow from that. Compute ships only what your build writes to `dist/`, so the files the server reads at runtime have to be in it. And because the client comes from [Prisma Composer](/composer), the part of Compute that runs your app, `npm start` stops working: locally, the app runs under `prisma dev` instead. + +## 1. Connect the repository in the Console + +Push your work, then in the [Console](https://console.prisma.io) create a project and connect the repository to it. [GitHub](/compute/github) describes the connection. The project's region is set when it is created and cannot change later, so pick the one nearest your users. To set up deploys without the Console, skip to [Without the Console](#without-the-console). + +The Console opens a pull request, **Set up Prisma Cloud deploys**, on a branch named `prisma-cloud/setup`. It adds: + +- `.github/workflows/prisma-deploy.yml`, which deploys every push: the default branch to production, and every other branch to its own preview. +- `module.mjs`, which declares the app and its Prisma Postgres database for Composer. +- `service.mjs`, which declares your server as a service with `deps: { db: postgres(dataContract(contractJson)) }`, the database it needs. +- A `composer` section in `prisma.config.ts`, and the Composer packages in `package.json`. The setup keeps the `prisma` and `@prisma/orm-postgres` versions your `package.json` declares. + +Because the workflow runs on every push, the setup branch deploys as a preview. Make the changes below on that branch, and merge the pull request only after its preview works, because merging deploys production. + +## 2. Move the service declaration into your build + +A Compute service runs the files your build produces, here `dist/`, and nothing outside them. Your server code imports the service declaration to get its database, so the declaration has to be part of the build. Check out the setup branch, then move `service.mjs` into `src/` as a TypeScript ES module: + +```bash +git switch prisma-cloud/setup +git rm service.mjs +``` + +```typescript title="src/service.mts" +import node from "@prisma/composer/node"; +import { compute } from "@prisma/composer-prisma-cloud"; +import { postgres, dataContract } from "@prisma/composer-prisma-cloud/orm"; +import type { Contract } from "./prisma/contract.js"; +import contractJson from "./prisma/contract.json" with { type: "json" }; + +export const data = dataContract(contractJson); + +export default compute({ + name: "feedback-board", + deps: { db: postgres(data) }, + build: node({ module: import.meta.url, dir: ".", entry: "server.js", dependencies: "external" }), +}); +``` + +Keep the `name` the setup wrote. `tsc` compiles this file to `dist/service.mjs`, so `dir: "."` is `dist/` and `entry` is the file in it that starts your server, the one `npm start` runs. Check it, because the setup guesses the entry from your repository and can get it wrong. `dependencies: "external"` ships the packages in `node_modules` that the entry imports, since `tsc` does not bundle them. `dataContract(...)` gives the client the types from `contract.d.ts`. + +In `module.mjs`, import the compiled service instead of the deleted file: + +```javascript title="module.mjs" +import feedbackBoardService from "./service.mjs"; // [!code --] +import feedbackBoardService from "./dist/service.mjs"; // [!code ++] +``` + +The deploy workflow runs `npm run build` before it reads `module.mjs`, so `dist/service.mjs` exists by then. + +## 3. Take the client from the service + +Change `src/db.ts` to use the client Composer connects to the branch's database: + +```typescript title="src/db.ts" tab="Prisma Compute" +import service from "./service.mjs"; + +export const db = service.load().db.client; +``` + +```typescript title="src/db.ts" tab="Before" +import "dotenv/config"; +import postgres from "@prisma/orm-postgres/runtime"; +import { contractFromJson } from "@prisma/orm-postgres/static"; +import type { Contract } from "./prisma/contract.d"; +import contractJson from "./prisma/contract.json"; + +export const db = postgres({ + contract: contractFromJson(contractJson), + url: process.env["DATABASE_URL"]!, +}); +``` + +`db.client` has the same type as the client you had, so the rest of your code does not change. `service.load().db` also has `url`, the raw connection string, for a library that needs one. `src/db.ts` stays CommonJS and loads the ES module through `require`, which Node.js 22.12 and newer support. Have the server listen on `service.port()` and `"0.0.0.0"` instead of `process.env.PORT`. + +Outside a Composer run, `service.load()` throws `missing required config param "url"`, so `npm start`, a `tsx` dev script and a `Procfile` stop working. Run the app locally under `prisma dev`, which starts a local Prisma Postgres, applies `migrations/app/` to it, and runs the service the way Compute does: + +```npm +npm run build +npx prisma dev module.mjs +``` + +**Expected result:** `dev: ready` and the service's local URL, such as `feedbackboard: http://localhost:3000`. The local database starts empty. Make `npm run build && npx prisma dev module.mjs` your `dev` script. A seed script must not import `src/db.ts`: keep its own `postgres({ contract, url })` client, and run it against the local database with `DATABASE_URL="$(npx prisma dev url database)" npx tsx prisma/seed.ts`. + +## 4. Ship files the server reads at runtime + +Only `dist/` reaches Compute, so if your server reads other files at runtime, such as EJS views in `views/` or static files in `public/`, copy them into `dist/` in the build, and read them from next to the compiled code: + +```json title="package.json (excerpt)" +{ + "scripts": { + "build": "tsc", // [!code --] + "build": "tsc && cp -R views public dist/" // [!code ++] + } +} +``` + +```typescript title="src/server.ts (excerpt)" +app.set("views", path.join(__dirname, "..", "views")); // [!code --] +app.set("views", path.join(__dirname, "views")); // [!code ++] +app.use(express.static(path.join(__dirname, "..", "public"))); // [!code --] +app.use(express.static(path.join(__dirname, "public"))); // [!code ++] +``` + +Without this, the app starts and every page it renders fails with `Failed to lookup view`. + +## 5. Set your other environment variables + +Compute sets the database and the port. Pass every other variable your app reads to the service as a [service input](/composer/service-input), which reads the same value on Compute and under `prisma dev`. Declare the input in the service: + +```typescript title="src/service.mts (excerpt)" +import { type } from "arktype"; +import { secretString } from "@prisma/composer/arktype"; + +export default compute({ + name: "feedback-board", + deps: { db: postgres(data) }, + input: type({ sessionSecret: secretString() }), // [!code ++] + build: node({ module: import.meta.url, dir: ".", entry: "server.js", dependencies: "external" }), +}); +``` + +Add `arktype` as a direct dependency, at the version `@prisma/composer` already uses, which `npm ls arktype` prints. Then fill the input from a project environment variable where `module.mjs` provisions the service, and read it in the server: + +```javascript title="module.mjs (excerpt)" +import { envSecret } from "@prisma/composer-prisma-cloud"; + +provision(feedbackBoardService, { + deps: { db: database }, + input: { sessionSecret: envSecret("SESSION_SECRET") }, // [!code ++] +}); +``` + +```typescript title="src/server.ts (excerpt)" +const SESSION_SECRET = process.env.SESSION_SECRET!; // [!code --] +const SESSION_SECRET = service.input().sessionSecret.expose(); // [!code ++] +``` + +Set each value for production and for previews. `read -rs` asks for the value without showing it, and given only the variable's name, `project env add` reads the value from your environment, so the secret stays off the command line and out of your shell history: + +```bash +read -rs SESSION_SECRET && export SESSION_SECRET # type the production value, then press Enter +npx prisma project env add SESSION_SECRET --role production +read -rs SESSION_SECRET && export SESSION_SECRET # type the preview value, then press Enter +npx prisma project env add SESSION_SECRET --role preview +unset SESSION_SECRET +``` + +Run these from a directory linked to the project, or add `--project `. Set them before you push, and redeploy after you change one. [Environment variables](/compute/environment-variables) covers scopes and branch overrides. + +## 6. Push and check the preview + +```bash +git add -A +git commit -m "Deploy on Prisma Compute" +git push +``` + +The push runs the deploy workflow for the setup branch. Find the preview's URL: + +```npm +npx prisma service list --branch prisma-cloud/setup +``` + +**Expected result:** the request you use as a health check succeeds against that URL, for example `curl https:///healthz` returns `{"ok":true}`, and pages that read and write the database work. The preview database starts empty, with your schema from `migrations/app/` and no data. + +When the preview works, merge the pull request. The merge deploys production the same way, with its own database. + +## Without the Console + +To set up deploys yourself, write the files the setup pull request adds, make the changes from steps 2 to 5, deploy once from your machine, and then connect the repository. Start with the Composer packages, at the version that matches `@prisma/orm-postgres@8.0.0-rc.20`, because the latest Composer release does not work with it: + +```npm +npm install --save-exact @prisma/composer@0.34.0 @prisma/composer-prisma-cloud@0.34.0 +``` + +Add a `composer` section to `prisma.config.ts`, with the region for the project the first deploy creates. Keep the `orm` section you have; the one below is from the upgrade guide: + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { definePrismaConfig } from "prisma/config"; +import { defineConfig, prisma7Schema } from "@prisma/orm-postgres/config"; +import { defineConfig as composer } from "@prisma/composer/config"; // [!code ++] +import { nodeBuild } from "@prisma/composer/node/control"; // [!code ++] +import { prismaCloud, prismaState } from "@prisma/composer-prisma-cloud/control"; // [!code ++] + +export default definePrismaConfig({ + orm: defineConfig({ + contract: prisma7Schema("prisma/schema.prisma"), + output: "src/prisma", + db: { + connection: process.env["DATABASE_URL"], + }, + }), + composer: composer({ // [!code ++] + extensions: [prismaCloud({ region: "eu-central-1" }), nodeBuild()], // [!code ++] + state: prismaState(), // [!code ++] + }), // [!code ++] +}); +``` + +The region cannot change after the first deploy creates the project. [Limitations](/compute/limitations#runtime) lists the ones you can choose. Declare the app and its database in `module.mjs`, from the same contract the service in step 2 exports: + +```javascript title="module.mjs" +import { module } from "@prisma/composer"; +import { postgres } from "@prisma/composer-prisma-cloud/orm"; +import feedbackBoardService, { data } from "./dist/service.mjs"; + +export default module("feedback-board", ({ provision }) => { + const database = provision(postgres({ name: "database", contract: data, config: "prisma.config.ts" })); + provision(feedbackBoardService, { deps: { db: database } }); +}); +``` + +Composer writes local state to `.prisma/`, `.prisma-composer/` and `.alchemy/`, so add those folders to `.gitignore`. Then make the changes from steps 2 to 5, and deploy production once from your machine. The deploy creates the project, and the commands after it link this directory to the project and connect the repository: + +```npm +npm run build +npx prisma deploy --entry module.mjs +npx prisma project link feedback-board +npx prisma git connect +``` + +`git connect` opens the browser so you can install the Prisma GitHub app, and it does not add a deploy workflow. Add the workflow from [Deploy on push](/compute/deploy-on-push#4-add-the-deploy-workflow), with `module: module.mjs` in the action's inputs, because the action looks for `module.ts` by default: + +```yaml title=".github/workflows/prisma-deploy.yml (excerpt)" + - uses: prisma/cloud-deploy-action@v1 + with: + build-command: npm run build + module: module.mjs +``` + +Push a branch other than the default one, and check its preview as in step 6. + +## Next steps + +- [Deploy on push](/compute/deploy-on-push): how previews, production and branch cleanup work once the workflow is in place. +- [Databases in Prisma Composer](/composer/databases): the `postgres()` database, its client, and how the deploy migrates it. diff --git a/apps/docs/content/docs/guides/compute/meta.json b/apps/docs/content/docs/guides/compute/meta.json index 5d6cbe6f38c..b27f6197180 100644 --- a/apps/docs/content/docs/guides/compute/meta.json +++ b/apps/docs/content/docs/guides/compute/meta.json @@ -1 +1 @@ -{ "title": "Build on Compute", "pages": ["astro-marketing-site"] } +{ "title": "Build on Compute", "pages": ["deploy-existing-app", "astro-marketing-site"] } diff --git a/apps/docs/content/docs/guides/deployment/vercel.mdx b/apps/docs/content/docs/guides/deployment/vercel.mdx index 85376c5639a..356467b2fdc 100644 --- a/apps/docs/content/docs/guides/deployment/vercel.mdx +++ b/apps/docs/content/docs/guides/deployment/vercel.mdx @@ -22,7 +22,7 @@ The [Vercel Marketplace integration](/guides/postgres/vercel) creates a [Prisma ## Prerequisites -- A Next.js app that uses the App Router and Prisma ORM 8, in a Git repository. This guide shows a contract written in `src/prisma/contract.prisma`, the default. If yours is a TypeScript contract, `contract.ts`, `contract emit` writes its files to `src/prisma/generated/`: use that folder in the `git ls-files` command in step 1 and in the imports in step 5. To start one, follow [Next.js](/guides/frameworks/nextjs) up to its deploy step. That guide's template, from `npm create prisma@latest -- my-app --template next --provider postgres --no-deploy`, is the app this guide refers to as the template; `--no-deploy` skips its offer to deploy to Prisma's own hosting. To move a Prisma ORM 7 app first, follow [Upgrade to Prisma ORM 8](/guides/upgrade-prisma-orm/postgresql). +- A Next.js app that uses the App Router and Prisma ORM 8, in a Git repository. This guide shows a contract written in `src/prisma/contract.prisma`, the default. If yours is a TypeScript contract, `contract.ts`, `contract emit` writes its files to `src/prisma/generated/`: use that folder in the `git ls-files` command in step 1 and in the imports in step 5. To start one, follow [Next.js](/guides/frameworks/nextjs) up to its deploy step. That guide's template, from `npm create prisma@latest -- my-app --template next --provider postgres --no-deploy`, is the app this guide refers to as the template; `--no-deploy` skips its offer to deploy to Prisma's own hosting. To move a Prisma ORM 7 app first, follow [Upgrade to Prisma ORM 8](/guides/upgrade-prisma-orm). - A [Vercel account](https://vercel.com/signup). - A PostgreSQL database for production that Vercel can reach over the internet, such as [Prisma Postgres](/postgres). diff --git a/apps/docs/content/docs/guides/frameworks/solid-start.mdx b/apps/docs/content/docs/guides/frameworks/solid-start.mdx index 474aa078b26..ab73cb99180 100644 --- a/apps/docs/content/docs/guides/frameworks/solid-start.mdx +++ b/apps/docs/content/docs/guides/frameworks/solid-start.mdx @@ -400,7 +400,7 @@ check: enabled Skill Package Version Installed into prisma-8 @prisma/orm-postgres 8.0.0-rc.23 .claude/skills, .cursor/skills, .agents/skills, .devin/skills prisma-composer-core-concepts @prisma/composer 0.29.1 .claude/skills, .cursor/skills, .agents/skills, .devin/skills -prisma-platform-core-concepts prisma 8.0.0-rc.32 .claude/skills, .cursor/skills, .agents/skills, .devin/skills +prisma-platform-core-concepts prisma 8.0.0-rc.33 .claude/skills, .cursor/skills, .agents/skills, .devin/skills ⚠ [INIT.CONFIG_KEPT] prisma.config.ts already exists, so init left it alone instead of writing the skills section. → Add skills: { agents: ["claude", "cursor", "agents", "devin"] } to the object passed to definePrismaConfig in prisma.config.ts. diff --git a/apps/docs/content/docs/guides/index.mdx b/apps/docs/content/docs/guides/index.mdx index 40c055c62a8..93bb4afada3 100644 --- a/apps/docs/content/docs/guides/index.mdx +++ b/apps/docs/content/docs/guides/index.mdx @@ -83,7 +83,7 @@ Guides that build a complete app and deploy it to [Prisma Compute](/compute), wi ## Upgrading - + diff --git a/apps/docs/content/docs/guides/making-guides.mdx b/apps/docs/content/docs/guides/making-guides.mdx index d3b9abae1c7..f3ae9e45cab 100644 --- a/apps/docs/content/docs/guides/making-guides.mdx +++ b/apps/docs/content/docs/guides/making-guides.mdx @@ -210,7 +210,7 @@ If a topic cannot be ported because Prisma ORM 8 does not support it yet (for ex | **Authentication** | `guides/authentication/` | Authentication patterns | [Clerk with Next.js](/guides/authentication/clerk/nextjs) | | **Prisma Postgres** | `guides/postgres/` | Prisma Postgres features | [Vercel](/guides/postgres/vercel), [Netlify](/guides/postgres/netlify), [Viewing data](/guides/postgres/viewing-data) | | **Migration** | `guides/switch-to-prisma-orm/` | Switch from other ORMs | [From Drizzle](/guides/switch-to-prisma-orm/from-drizzle), [From Mongoose](/guides/switch-to-prisma-orm/from-mongoose) | -| **Upgrade** | `guides/upgrade-prisma-orm/` | Move between Prisma versions | [Prisma ORM 7 to 8 on PostgreSQL](/guides/upgrade-prisma-orm/postgresql) | +| **Upgrade** | `guides/upgrade-prisma-orm/` | Move between Prisma versions | [Prisma ORM 7 to 8, route by route](/guides/upgrade-prisma-orm/postgresql-incremental) | ## Guide template diff --git a/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-neon.mdx b/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-neon.mdx index 0128afdaedd..4b18c79c3c2 100644 --- a/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-neon.mdx +++ b/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-neon.mdx @@ -302,7 +302,7 @@ rm neon-to-prisma-postgres.dump neon-restore.list row-counts.sql source-row-coun ## Recommended next step: adopt Prisma ORM -Your database migration is complete, and upgrading Prisma ORM is a separate application change. Prisma ORM 8 is a [release candidate](/orm/release-status); to adopt it, follow the [incremental Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql) after the application is stable on Prisma Postgres. +Your database migration is complete, and upgrading Prisma ORM is a separate application change. Prisma ORM 8 is a [release candidate](/orm/release-status); to adopt it, follow the [incremental Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql-incremental) after the application is stable on Prisma Postgres. If you want to complete both changes on the same day, deploy and verify the Prisma Postgres connection first. Upgrade Prisma ORM in a separate commit or deployment so failures have one clear cause. diff --git a/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-supabase.mdx b/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-supabase.mdx index f6329e74959..22700991858 100644 --- a/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-supabase.mdx +++ b/apps/docs/content/docs/guides/switch-to-prisma-postgres/from-supabase.mdx @@ -323,7 +323,7 @@ rm supabase-to-prisma-postgres.dump supabase-restore.list row-counts.sql source- ## Recommended next step: adopt Prisma ORM -Your database migration is complete, and upgrading Prisma ORM is a separate application change. Prisma ORM 8 is a [release candidate](/orm/release-status); to adopt it, follow the [incremental Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql) after the application is stable on Prisma Postgres. +Your database migration is complete, and upgrading Prisma ORM is a separate application change. Prisma ORM 8 is a [release candidate](/orm/release-status); to adopt it, follow the [incremental Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql-incremental) after the application is stable on Prisma Postgres. If you want to complete both changes on the same day, deploy and verify the Prisma Postgres connection first. Upgrade Prisma ORM in a separate commit or deployment so failures have one clear cause. diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/index.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/index.mdx new file mode 100644 index 00000000000..6806f3cf5a4 --- /dev/null +++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/index.mdx @@ -0,0 +1,26 @@ +--- +title: Upgrade to Prisma 8 +description: 'Use when choosing how to upgrade an app from Prisma ORM 6 or 7 to Prisma 8: pick the guide for your database, your current version, and whether to move in one pass or route by route' +url: /guides/upgrade-prisma-orm +metaTitle: How to upgrade from Prisma ORM 6 or 7 to Prisma 8 +metaDescription: 'Pick the Prisma 8 upgrade guide for your app: PostgreSQL from Prisma ORM 6 or 7 in one pass, PostgreSQL from Prisma ORM 7 route by route, or MongoDB from Prisma ORM 6.' +--- + +Prisma 8 is a [release candidate](/orm/release-status). Each guide below keeps your database and its data, and ends with the app running only on Prisma 8. Pick the one that matches your database, the version you run today, and how you want to move: + +| Database | You run | Strategy | Guide | +| --- | --- | --- | --- | +| PostgreSQL | Prisma ORM 6 or 7 | All at once: keep your `schema.prisma` and rewrite every query in one pass | [Prisma ORM 6 or 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql) | +| PostgreSQL | Prisma ORM 7 | Route by route: run Prisma ORM 7 and Prisma 8 side by side and move one route at a time | [Prisma ORM 7 to 8, route by route (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql-incremental) | +| MongoDB | Prisma ORM 6 | All at once (Prisma ORM 7 has no MongoDB connector) | [Prisma ORM 6 to 8 (MongoDB)](/guides/upgrade-prisma-orm/mongodb) | +| Any but MongoDB | Prisma ORM 6 | Staying on Prisma ORM 7 for now | [Upgrade to Prisma ORM 7](/guides/upgrade-prisma-orm/v7) | + +On Prisma ORM 5 or earlier, upgrade one major version at a time first, because each release has breaking changes of its own: [to 6](/guides/upgrade-prisma-orm/v6), [to 5](/guides/upgrade-prisma-orm/v5), [to 4](/guides/upgrade-prisma-orm/v4), [to 3](/guides/upgrade-prisma-orm/v3), or [from Prisma 1](/guides/upgrade-prisma-orm/v1). + +The two PostgreSQL guides also differ in where the [contract](/orm/contract-authoring/the-data-contract) comes from. The all-at-once guide reads your existing `schema.prisma` through `prisma7Schema(...)`, so you keep editing that file. The route-by-route guide infers a new `contract.prisma` from the live database. + +## Deploying on Prisma Compute + +Prisma Compute runs only Prisma 8, so finish the upgrade before you deploy there. An app in the middle of the route-by-route guide still runs Prisma ORM 7 and cannot deploy on Compute until that guide's last step removes it. + +[Deploy an existing app on Prisma Compute](/guides/compute/deploy-existing-app) covers PostgreSQL apps, which get a Prisma Postgres database for each branch. Today it needs the Prisma 8 versions the all-at-once guide installs. The route-by-route guide installs the latest Prisma 8 releases, which Compute does not deploy yet, so check the deploy guide's [prerequisites](/guides/compute/deploy-existing-app#prerequisites) before you start. diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/meta.json b/apps/docs/content/docs/guides/upgrade-prisma-orm/meta.json index 3fd2bc0049e..a1eba2d2325 100644 --- a/apps/docs/content/docs/guides/upgrade-prisma-orm/meta.json +++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/meta.json @@ -1,4 +1,4 @@ { "title": "Upgrade Prisma ORM", - "pages": ["postgresql", "mongodb", "v7", "v6", "v5", "v4", "v3", "v1"] + "pages": ["index", "postgresql", "postgresql-incremental", "mongodb", "v7", "v6", "v5", "v4", "v3", "v1"] } diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql-incremental.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql-incremental.mdx new file mode 100644 index 00000000000..4b1ac853677 --- /dev/null +++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql-incremental.mdx @@ -0,0 +1,583 @@ +--- +title: Prisma ORM 7 to 8, route by route (PostgreSQL) +description: 'Use when a PostgreSQL app on Prisma ORM 7 should move to Prisma 8 gradually, with both versions running side by side and one route moving at a time' +url: /guides/upgrade-prisma-orm/postgresql-incremental +metaTitle: How to migrate a PostgreSQL project from Prisma ORM 7 to 8 route by route +metaDescription: 'Step-by-step guide to migrating a Prisma ORM 7 PostgreSQL project to Prisma ORM 8 incrementally. Run both clients side by side, migrate routes one at a time, then move migrations to Prisma ORM 8.' +--- + +:::note[Not for a Prisma ORM 6 app, or for an upgrade in one pass] + +To move a Prisma ORM 6 or 7 app in one pass, keeping your `schema.prisma`, follow [Prisma ORM 6 or 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql). [Upgrade to Prisma 8](/guides/upgrade-prisma-orm) compares the two. Prisma Compute runs only Prisma 8, so an app in the middle of this guide cannot deploy there until step 5 removes Prisma ORM 7. This guide installs the latest Prisma 8 releases, which Compute does not deploy yet; [Deploy an existing app on Prisma Compute](/guides/compute/deploy-existing-app#prerequisites) lists the versions it needs. + +::: + +This guide is for teams running a Prisma ORM 7 application on PostgreSQL who want to move to **Prisma ORM 8** without a rewrite. You will install Prisma ORM 8 next to Prisma ORM 7 in the same application, move routes over one at a time, hand migration ownership to Prisma ORM 8, and remove Prisma ORM 7 once nothing depends on it. + +Both versions run against the same PostgreSQL database the whole time. The database, its data, and its connection string do not change; only application code and tooling do. Because each route stays on Prisma ORM 7 until you deliberately move it, the application remains shippable at every point in the migration. + +This guide covers **PostgreSQL only**, and guidance for other databases will follow. If you are coming from v6 on MongoDB, see the [MongoDB guide](/guides/upgrade-prisma-orm/mongodb). + +:::info + +Step 2.1 installs the latest Prisma ORM 8 packages. This guide was written for the Prisma ORM 8 CLI as of `8.0.0-rc.26` and `@prisma/orm-postgres` as of `8.0.0-rc.23`. The two packages have separate version numbers. The Prisma ORM 7 side of the app stays at `7.10.1` throughout. + +::: + +## How the incremental migration works + +The migration runs in five phases. The application works at the end of each one. + +1. **Prepare Prisma ORM 7 for side-by-side operation.** Move Prisma ORM 7 onto its own package name, binary, and config file. No behavior changes. +2. **Add Prisma ORM 8.** Install the Prisma ORM 8 CLI and runtime with their own config, schema contract, and generated client. No application code uses them yet. +3. **Migrate one route.** One route runs on Prisma ORM 8 while the rest stay on Prisma ORM 7, all against the same database. +4. **Transfer migration ownership.** Prisma ORM 8 takes over planning and applying schema changes. +5. **Remove Prisma ORM 7** once nothing imports it. + +The ownership timeline matters more than the code timeline. Prisma ORM 7 owns schema migrations through phases 1 to 3, and routes move to Prisma ORM 8 independently of that. Prisma ORM 8 takes over migrations only in phase 4, after a database signature and a `db` ref are in place; the first `migration plan` then writes the baseline migration itself. You can pause between phases for as long as you need. + +The [prisma8-and-7-example](https://github.com/prisma/prisma8-and-7-example) repository shows the finished result of each phase (tags `step-0` through `step-3`). + +## Prerequisites + +- **Node.js 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer**; Node.js 24 recommended +- A working **Prisma ORM 7** application on PostgreSQL: `prisma.config.ts`, the `prisma-client` generator, and a driver adapter +- **TypeScript 5.9 or newer** with `"strict": true`. [Step 2.6](#26-set-up-tsconfigjson-for-the-prisma-orm-8-client) tells you whether to change the `module` setting in `tsconfig.json` + +## 1. Prepare Prisma ORM 7 for side-by-side operation + +Prisma ORM 8 expects the `prisma` package name, the `prisma` binary, and the `prisma.config.ts` file name. In this phase you move Prisma ORM 7 off those three names so Prisma ORM 8 can take them without ambiguity. Nothing migrates yet. + +### 1.1. Confirm the application works + +The guide follows a small Hono API with two routes. Map the file names to your own project. The Prisma ORM 7 pieces that matter: + +```json title="package.json (excerpt)" +{ + "scripts": { + "prisma:generate": "prisma generate", + "db:migrate": "prisma migrate dev" + }, + "dependencies": { + "@prisma/adapter-pg": "^7.10.0", + "@prisma/client": "^7.10.0" + }, + "devDependencies": { + "prisma": "^7.10.0" + } +} +``` + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "postgresql" +} + +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? + posts Post[] +} + +model Post { + id Int @id @default(autoincrement()) + title String + published Boolean @default(false) + authorId Int + author User @relation(fields: [authorId], references: [id], onDelete: Cascade) + + @@index([authorId]) +} +``` + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { defineConfig } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: process.env["DATABASE_URL"], + }, +}); +``` + +```typescript title="src/db.ts" +import "dotenv/config"; +import { PrismaPg } from "@prisma/adapter-pg"; +import { PrismaClient } from "../generated/prisma/client"; + +const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! }); + +export const prisma = new PrismaClient({ adapter }); +``` + +Two routes read and write through this client, `/users` and `/posts`: + +```typescript title="src/routes/users.ts" +import { Hono } from "hono"; +import { prisma } from "../db"; + +export const users = new Hono(); + +users.get("/", async (c) => { + const result = await prisma.user.findMany({ + include: { posts: true }, + orderBy: { id: "asc" }, + }); + return c.json(result); +}); + +users.post("/", async (c) => { + const body = await c.req.json<{ email: string; name?: string }>(); + const user = await prisma.user.create({ data: body }); + return c.json(user, 201); +}); +``` + +`src/routes/posts.ts` follows the same pattern for `Post`. + +Start the app and run a read and a write: + +```npm +npm run dev +``` + +```bash +curl -X POST localhost:3000/users -H 'content-type: application/json' \ + -d '{"email":"alice@prisma.io","name":"Alice"}' +curl localhost:3000/users +``` + +Do not continue until both requests succeed. That confirms the Prisma ORM 7 application works before you change its configuration. + +### 1.2. Replace the `prisma` package with `@prisma/prisma7` + +```npm +npm uninstall prisma +npm install --save-dev @prisma/prisma7@7.10.1 +``` + +`@prisma/prisma7` is the same Prisma ORM 7 CLI under a version-specific name. It exposes a `prisma7` binary and keeps `prisma` 7 as a transitive dependency. Your `@prisma/client` and `@prisma/adapter-pg` dependencies stay untouched. + +### 1.3. Rename the Prisma ORM 7 config + +```bash +mv prisma.config.ts prisma7.config.ts +``` + +```typescript title="prisma7.config.ts" +import "dotenv/config"; +import { defineConfig } from "prisma/config"; // [!code --] +import { defineConfig } from "@prisma/prisma7/config"; // [!code ++] + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: process.env["DATABASE_URL"], + }, +}); +``` + +The `prisma7` CLI discovers `prisma7.config.ts` automatically, so no `--config` flag is needed. Renaming frees the `prisma.config.ts` name for Prisma ORM 8, which only accepts its own config format under that name. + +### 1.4. Point scripts at the `prisma7` binary + +```json title="package.json (excerpt)" +{ + "scripts": { + "prisma:generate": "prisma generate", // [!code --] + "db:migrate": "prisma migrate dev" // [!code --] + "prisma7:generate": "prisma7 generate", // [!code ++] + "prisma7:migrate": "prisma7 migrate dev" // [!code ++] + } +} +``` + +After Prisma ORM 8 is installed, the `prisma` binary runs the Prisma ORM 8 CLI. Update every script, CI job, and deployment command that must continue using Prisma ORM 7 to call `prisma7` instead. + +### 1.5. Check that Prisma ORM 7 still works + +```npm +npx prisma7 generate +npx prisma7 migrate status +``` + +**Expected result:** `generate` writes the client to `generated/prisma` as before, and `migrate status` reports that the database schema is up to date. Start the app and query each route; behavior should be identical to step 1.1. + +## 2. Add Prisma ORM 8 + +### 2.1. Install the Prisma ORM 8 packages + +```npm +npm install --save-dev prisma@latest +npm install @prisma/orm-postgres +``` + +`prisma@latest` is the Prisma ORM 8 CLI, and its `prisma/config` subpath provides `definePrismaConfig` for the Prisma ORM 8 config file. Installing it locally (not only running it through `npx`) is what makes that import resolve. `@prisma/orm-postgres` is the PostgreSQL ORM runtime your application code will import. + +After this install, `npx prisma ` runs the Prisma ORM 8 CLI and `npx prisma7 ` runs Prisma ORM 7: + +```npm +npx prisma --version +``` + +**Expected result:** the command prints `8.0.0-rc.33` or a newer version. That number does not match the version of `@prisma/orm-postgres`, because the CLI is released separately. + +### 2.2. Create the Prisma ORM 8 config + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { definePrismaConfig } from "prisma/config"; +import { defineConfig as definePostgresConfig } from "@prisma/orm-postgres/config"; + +export default definePrismaConfig({ + orm: definePostgresConfig({ + contract: "prisma8/contract.prisma", + output: "generated/prisma8", + db: { + connection: process.env["DATABASE_URL"], + }, + }), +}); +``` + +Both configs point at the **same** `DATABASE_URL`. Everything else is separate: + +| | Prisma ORM 7 | Prisma ORM 8 | +|---|---|---| +| CLI | `prisma7` | `prisma` | +| Config | `prisma7.config.ts` | `prisma.config.ts` | +| Schema | `prisma/schema.prisma` | `prisma8/contract.prisma` | +| Generated client | `generated/prisma` | `generated/prisma8` | + +Because the config carries the connection, the Prisma ORM 8 CLI commands below don't need a `--db` flag. + +:::tip[Read the Prisma ORM 7 schema instead] + +Instead of generating a contract file in steps 2.3 and 2.4, Prisma ORM 8 can read `prisma/schema.prisma` directly as its contract, so you keep one schema file while Prisma ORM 7 owns migrations. `schema.prisma` does not need the `// use prisma-8` first line that a contract file written for Prisma ORM 8 starts with (step 2.4 shows one). Skip steps 2.3 and 2.4, and change two lines in the `prisma.config.ts` you just wrote: + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { definePrismaConfig } from "prisma/config"; +import { defineConfig as definePostgresConfig } from "@prisma/orm-postgres/config"; // [!code --] +import { defineConfig as definePostgresConfig, prisma7Schema } from "@prisma/orm-postgres/config"; // [!code ++] + +export default definePrismaConfig({ + orm: definePostgresConfig({ + contract: "prisma8/contract.prisma", // [!code --] + contract: prisma7Schema("prisma/schema.prisma"), // [!code ++] + output: "generated/prisma8", + db: { + connection: process.env["DATABASE_URL"], + }, + }), +}); +``` + +Read this way, a `DateTime` field and the `@db.Timestamp` and `@db.Timestamptz` fields are JavaScript `Date` objects in Prisma ORM 8, as in Prisma ORM 7. The `@db.Date` and `@db.Time` fields are ISO 8601 strings, such as `"2026-09-14"` and `"10:00:00.5"`, where Prisma ORM 7 gave you `Date` objects. The Prisma ORM 8 client needs no `Temporal` for any of them. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) has the details. + +After step 2.5, run `npx prisma db sign`. [`db sign`](/cli/db-sign) checks that the database matches the contract Prisma ORM 8 read from `schema.prisma` and records in the database that it does. Signing does not move your migrations to Prisma ORM 8. Prisma ORM 7 keeps planning and applying them, so after each Prisma ORM 7 migration, whether you ran `prisma7 migrate dev` or `prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign` again. If you emit without signing, the Prisma ORM 8 client still runs queries, but `npx prisma db verify` reports that the contract no longer matches the one recorded in the database. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists the parts of a Prisma ORM 7 schema that Prisma ORM 8 cannot read. + +If you have not started phase 1 yet, one command does phase 1 and this setup for you: + +```npm title="Terminal" +npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma +``` + +Write `prisma@latest`, because in a Prisma ORM 7 project `npx prisma` runs version 7. The command moves Prisma ORM 7 to the `prisma7` command and `prisma7.config.ts`, installs the Prisma ORM 8 packages, writes `prisma.config.ts` and a Prisma ORM 8 client in `src/prisma/db.ts`, and emits the contract. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with phase 3, using the `db` client from `src/prisma/db.ts` instead of adding one to `src/db.ts` in step 3.1. + +Prisma ORM 7 keeps owning migrations on this path until you are ready for [phase 4](#4-transfer-migration-ownership), where Prisma ORM 8 takes them over. Phase 4 needs a contract file written for Prisma ORM 8, so switch to one first. Either run `npx prisma contract print --output prisma8/contract.prisma`, which writes the contract Prisma ORM 8 read from `schema.prisma` as a Prisma ORM 8 contract file, or run steps 2.3 to 2.5. Then set `contract` in `prisma.config.ts` to `"prisma8/contract.prisma"`, the file you created. Then follow phase 4 as written. Its first step, `db sign`, checks the new contract against the database before Prisma ORM 8 takes over. + +::: + +### 2.3. Infer the contract from the live database + +Prisma ORM 8 describes your schema as a [contract](/orm/contract-authoring/the-data-contract). Generate it from the database Prisma ORM 7 built: + +```npm title="Terminal" +npx prisma contract infer --output prisma8/contract.prisma +``` + +### 2.4. Review the inferred contract + +`contract infer` reads every table in the database except `_prisma_migrations`, the table where Prisma ORM 7 records which migrations it has applied, so the contract has no model for it and Prisma ORM 8 never manages it. The table itself stays in the database, and `db verify --strict` does not report it. + +You do not need to add `@@map` to the other models: a model without `@@map` uses its name, exactly as written, as its table name, so `User` reads and writes the `"User"` table that Prisma ORM 7 created. + +The inferred contract looks like this: + +```prisma title="prisma8/contract.prisma" +// use prisma-8 + +model User { + id Int @id(map: "User_pkey") @default(autoincrement()) + email String + name String? + posts Post[] + + @@index([email], map: "User_email_key", unique: true) +} + +model Post { + id Int @id(map: "Post_pkey") @default(autoincrement()) + title String + published Boolean @default(false) + authorId Int + author User @relation(fields: [authorId], references: [id], onDelete: Cascade, onUpdate: Cascade, map: "Post_authorId_fkey") + + @@index([authorId], map: "Post_authorId_idx") +} +``` + +Keep `// use prisma-8` as the first line of `prisma8/contract.prisma`. `contract emit` reads only `.prisma` files that start with this line, and this is the only file in your contract, so without it `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`. A `schema.prisma` that Prisma ORM 8 reads through `prisma7Schema(...)`, as in the tip at the end of step 2.2, does not need the line. + +### 2.5. Emit the contract artifacts + +```npm +npx prisma contract emit +``` + +`contract emit` writes `contract.json` and `contract.d.ts` to `generated/prisma8`, the runtime and type inputs for the Prisma ORM 8 client. Re-run it after every contract change. + +### 2.6. Set up tsconfig.json for the Prisma ORM 8 client + +Your `tsconfig.json` must allow the JSON import you will write in step 3.1: `import contractJson from "../generated/prisma8/contract.json" with { type: "json" }`. TypeScript accepts the `with { type: "json" }` part only when `module` is `esnext`, `node18`, `node20`, `nodenext`, or `preserve`, and only in a file it treats as an ES module. Any other value, such as `commonjs`, `es2022`, or `node16`, rejects it, and leaving `module` unset fails too. Take the first case below that matches how your app runs: + +- **`module` is already one of the five values and your build works with it, and either `package.json` has `"type": "module"` or `module` is `esnext` or `preserve`.** Keep it. Set `moduleResolution` to `bundler` if `module` is `esnext` or `preserve`, to `nodenext` if `module` is `nodenext`, and remove it if `module` is `node18` or `node20`. A `moduleResolution` of `node` or `node10` cannot resolve the `@prisma/orm-*` packages, so do not leave that in place. +- **You compile with `tsc`, run the output with `node`, and `package.json` has no `"type": "module"` (or has `"type": "commonjs"`).** Your app runs as CommonJS, and it can stay that way. Set `"module": "nodenext"` and `"moduleResolution": "nodenext"`, and do not add `"type": "module"`. Prisma ORM 8 works from CommonJS code, and your relative imports stay as they are, without extensions. TypeScript treats `db.ts` as CommonJS here, so in step 3.1 write the JSON import without the `with` part and copy the other import lines as shown. + + ```typescript title="src/db.ts (CommonJS excerpt)" + import contractJson from "../generated/prisma8/contract.json"; + ``` + +- **The app runs through `tsx`, or a bundler such as `vite`, `next`, or `esbuild` builds it, and you never run `tsc` output with plain `node`.** Set `"module": "preserve"` and `"moduleResolution": "bundler"`. You do not need file extensions on relative imports, and the import lines in step 3.1 work as shown. The [example project](https://github.com/prisma/prisma8-and-7-example) is set up this way. If you run the `.ts` files directly with `node` instead, its type stripping needs the `.ts` extension on every relative import, so add `"allowImportingTsExtensions": true` as well. +- **You compile with `tsc`, run the output with `node`, and `package.json` has `"type": "module"`, even if you use `tsx` in development.** Set `"module": "nodenext"` and `"moduleResolution": "nodenext"`. Node then requires an explicit file extension on every relative import, which for compiled TypeScript files is `.js`, so this is the one setup that makes you rewrite imports; [the TypeScript module reference](https://www.typescriptlang.org/docs/handbook/modules/reference.html#node16-node18-nodenext) explains the rule. + +Whichever case applies, add `"resolveJsonModule": true` so TypeScript can type the JSON import, and add `generated/prisma8/**/*.d.ts` to `include` so it sees the emitted `contract.d.ts`. If your `tsconfig.json` has no `include`, TypeScript already picks up every file under the project, so skip that part: + +```json title="tsconfig.json (excerpt)" +{ + "compilerOptions": { + "resolveJsonModule": true // [!code ++] + }, + "include": [ + "src/**/*.ts", + "generated/prisma/**/*.ts", + "generated/prisma8/**/*.d.ts" // [!code ++] + ] +} +``` + +**Check:** `npx tsc --noEmit` passes. Prisma ORM 8 is now installed and configured, but no application code uses it yet. This check does not test your `module` choice, because nothing imports `contract.json` until step 3.1; if TypeScript reports TS2823 there, the `module` value rejects the `with` part, and if it reports TS2856, the file compiles as CommonJS and the `with` part has to go, as the CommonJS case shows. + +## 3. Migrate one route + +Pick one small route and move only that code. The rest of the application stays on Prisma ORM 7. + +### 3.1. Instantiate both clients + +```typescript title="src/db.ts" +import "dotenv/config"; +import { PrismaPg } from "@prisma/adapter-pg"; +import postgres from "@prisma/orm-postgres/runtime"; // [!code ++] +import { contractFromJson } from "@prisma/orm-postgres/static"; // [!code ++] +import type { Contract } from "../generated/prisma8/contract.d"; // [!code ++] +import contractJson from "../generated/prisma8/contract.json" with { type: "json" }; // [!code ++] +import { PrismaClient } from "../generated/prisma/client"; + +const connectionString = process.env.DATABASE_URL!; + +const adapter = new PrismaPg({ connectionString }); + +export const prisma = new PrismaClient({ adapter }); + +export const contract = contractFromJson(contractJson); // [!code ++] + +export const db = postgres({ url: connectionString, contract }); // [!code ++] +``` + +`prisma` is the Prisma ORM 7 client and `db` is the Prisma ORM 8 client, both connected to the same database. `contractFromJson` turns the emitted `contract.json` into a typed contract value, which the Prisma ORM 8 client takes as `contract`. + +### 3.2. Rewrite the route + +Move the users route to the Prisma ORM 8 [ORM client](/orm/reference/orm-client). Queries start from `db.orm..` (`public` here) and chain instead of taking one options object: + +```typescript title="src/routes/users.ts" tab="After" +import { Hono } from "hono"; +import { db } from "../db"; + +export const users = new Hono(); + +users.get("/", async (c) => { + const result = await db.orm.public.User.include("posts", (posts) => + posts.orderBy((post) => post.id.asc()), + ) + .orderBy((user) => user.id.asc()) + .all(); + return c.json(result); +}); + +users.post("/", async (c) => { + const body = await c.req.json<{ email: string; name?: string }>(); + const user = await db.orm.public.User.create(body); + return c.json(user, 201); +}); +``` + +```typescript title="src/routes/users.ts" tab="Before" +import { Hono } from "hono"; +import { prisma } from "../db"; + +export const users = new Hono(); + +users.get("/", async (c) => { + const result = await prisma.user.findMany({ + include: { posts: true }, + orderBy: { id: "asc" }, + }); + return c.json(result); +}); + +users.post("/", async (c) => { + const body = await c.req.json<{ email: string; name?: string }>(); + const user = await prisma.user.create({ data: body }); + return c.json(user, 201); +}); +``` + +`src/routes/posts.ts` stays unchanged, on Prisma ORM 7. + +### 3.3. Exercise both code paths + +Start the app and hit both routes: + +```bash +curl localhost:3000/users +curl -X POST localhost:3000/posts -H 'content-type: application/json' \ + -d '{"title":"Written by Prisma 7","authorId":1}' +curl localhost:3000/users +``` + +**Expected result:** the first request runs through Prisma ORM 8. The second writes through Prisma ORM 7. The third, through Prisma ORM 8 again, includes the post Prisma ORM 7 just wrote. + +Remaining routes can move over the same way, one at a time, on any schedule. Prisma ORM 7 still owns schema migrations in this phase. If the schema changes, run `prisma7 migrate dev`, then re-run `contract infer` and `contract emit` so the Prisma ORM 8 contract stays current. + +## 4. Transfer migration ownership + +So far every schema change has gone through `prisma7 migrate dev`. In this phase Prisma ORM 8 takes over planning and applying schema changes, and `prisma/schema.prisma` is frozen. + +Treat the switch as a decision, not a routine step. After it, your team and your pipelines must stop using the Prisma ORM 7 migration workflow, even though routes still on the Prisma ORM 7 client keep working. See [how migrations work](/orm/migrations/how-migrations-work) for the full picture. + +Prisma ORM 8 tracks schema state with four pieces, and the handoff creates each one exactly once: + +- A **contract hash** identifies one version of the emitted contract. +- A **migration** is an on-disk package recording how to get from one contract hash to another. `migrate` only replays recorded migrations; it never invents one. +- The **marker** is Prisma ORM 8's record, stored in the database, of which contract hash the database currently satisfies. +- A **ref** is a named pointer at a contract hash. `migration plan` uses the `db` ref as its starting point. + +Step 4.1 creates the marker and the ref with one command. The baseline migration is written by the first `migration plan` in step 4.3. + +### 4.1. Sign the existing database + +Your database already has every table the contract describes, so adopt it rather than replay anything: + +```npm +npx prisma db sign +npx prisma migration status +``` + +`db sign` verifies that the live schema matches the emitted contract, writes Prisma ORM 8's marker at that contract version, stores the contract snapshot under `migrations/snapshots/`, and points a [ref](/orm/migrations/the-migration-graph#name-important-states-with-refs) named `db` at it. `migration plan` starts from that ref, so plans chain from the schema Prisma ORM 7 built and contain only your own changes. + +**Expected result:** `Database signed`, and `migration status` shows the current and target contract hashes match with nothing pending. + +### 4.2. Retire the Prisma ORM 7 migration scripts + +Remove `prisma7 migrate` from your scripts so nobody runs it by accident. Keep `prisma7 generate`, because the legacy routes still need their client: + +```json title="package.json (excerpt)" +{ + "scripts": { + "prisma7:generate": "prisma7 generate", + "prisma7:migrate": "prisma7 migrate dev", // [!code --] + "prisma8:migrate": "prisma db migrate --advance-ref db" // [!code ++] + } +} +``` + +### 4.3. Verify the handoff with a schema change + +Verify the migration handoff with a small additive schema change. Add a field to the contract: + +```prisma title="prisma8/contract.prisma (excerpt)" +model User { + id Int @id(map: "User_pkey") @default(autoincrement()) + email String + name String? + bio String? // [!code ++] + ... +} +``` + +Emit, plan, and apply: + +```npm +npx prisma contract emit +npx prisma migration plan --name add_user_bio +npx prisma db migrate --advance-ref db +npx prisma db verify +``` + +**Expected result:** `migration plan` reports `Planned baseline + 1 operation(s)` and writes two packages under `migrations/app/`: a baseline that records the schema you adopted in step 4.1, and `add_user_bio` with the single operation `Add column "bio" to "User"`. `db migrate` skips the baseline, because the marker already records that state, and applies `add_user_bio`. `--advance-ref db` moves the ref so the next plan chains correctly, and `db verify` reports that marker and schema match the contract. + +Restart the app: the Prisma ORM 8 route returns users with `bio`, and the Prisma ORM 7 route keeps working untouched, because its client doesn't know about the new column. Additive changes like nullable columns are safe next to legacy Prisma ORM 7 code. Be careful with renames or drops of columns that Prisma ORM 7 routes still read. + +## 5. Remove Prisma ORM 7 + +Migrate the remaining routes as in phase 3. For `posts` here, that means swapping `prisma.post.findMany(...)` for `db.orm.public.Post.include("author").all()` and `prisma.post.create({ data })` for `db.orm.public.Post.create(data)`. + +When nothing imports `generated/prisma` anymore, remove Prisma ORM 7: + +```npm +npm uninstall @prisma/prisma7 @prisma/client @prisma/adapter-pg +``` + +```bash +rm prisma7.config.ts +rm -r prisma generated/prisma +``` + +Then delete the `prisma7:*` scripts from `package.json` and drop `generated/prisma/**/*.ts` from the `include` array in `tsconfig.json`. + +Verify the end state: + +```npm +npx tsc --noEmit +npx prisma db verify +``` + +Start the app and run a query against every route. The application now runs entirely on Prisma ORM 8, with schema changes managed by `prisma migration plan` and `prisma db migrate`. + +:::note + +Prisma ORM 7's `_prisma_migrations` table remains in the database. It is inert: Prisma ORM 8 leaves it out of `db verify`, `db update` and `contract infer`, and you can drop it whenever you like. + +::: + +## Next steps + +- [How migrations work in Prisma ORM](/orm/migrations/how-migrations-work): the day-to-day `contract emit` → `migration plan` → `migrate` loop for schema changes +- [Contract authoring](/orm/contract-authoring/psl-syntax): the full PSL syntax for evolving `contract.prisma` +- [Prisma ORM CLI reference](/cli): every command used in this guide diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx index fac9e68ce6b..5a563cd19d8 100644 --- a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx +++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx @@ -1,246 +1,124 @@ --- -title: Prisma ORM 7 to 8 (PostgreSQL) -description: 'Migrate a PostgreSQL project from Prisma ORM 7 to Prisma ORM 8 incrementally, with both versions running side by side' +title: Prisma ORM 6 or 7 to 8 (PostgreSQL) +description: 'Use when a PostgreSQL app on Prisma ORM 6 or 7 should move to Prisma 8 in one pass, keeping its schema.prisma, its database and its data' url: /guides/upgrade-prisma-orm/postgresql -metaTitle: How to migrate a PostgreSQL project from Prisma ORM 7 to 8 -metaDescription: 'Step-by-step guide to migrating a Prisma ORM 7 PostgreSQL project to Prisma ORM 8 incrementally. Run both clients side by side, migrate routes one at a time, then move migrations to Prisma ORM 8.' +metaTitle: How to upgrade a PostgreSQL app from Prisma ORM 6 or 7 to Prisma 8 +metaDescription: 'Step-by-step guide to upgrading a Prisma ORM 6 or 7 PostgreSQL app to Prisma 8 in one pass: read your existing schema.prisma as the contract, hand migrations to Prisma 8, rewrite queries, and remove the old client.' --- -This guide is for teams running a Prisma ORM 7 application on PostgreSQL who want to move to **Prisma ORM 8** without a rewrite. You will install Prisma ORM 8 next to Prisma ORM 7 in the same application, move routes over one at a time, hand migration ownership to Prisma ORM 8, and remove Prisma ORM 7 once nothing depends on it. +{/* lint-versions-ignore-file: this page pins the Prisma 8 versions that the Console's Compute setup installs, not npm latest, so an app upgraded with it can deploy on Prisma Compute. They are PRISMA_CLI_VERSION and ORM_POSTGRES_VERSION in planComposerSetup.ts in prisma/pdp-control-plane; update them together with those constants. */} -Both versions run against the same PostgreSQL database the whole time. The database, its data, and its connection string do not change; only application code and tooling do. Because each route stays on Prisma ORM 7 until you deliberately move it, the application remains shippable at every point in the migration. +{/* cspell:ignore feedbackboard */} -This guide covers **PostgreSQL only**, and guidance for other databases will follow. If you are coming from v6 on MongoDB, see the [MongoDB guide](/guides/upgrade-prisma-orm/mongodb). +:::note[Not for a route-by-route upgrade, MongoDB, or deploying] -:::info - -Step 2.1 installs the latest Prisma ORM 8 packages. This guide was written for the Prisma ORM 8 CLI as of `8.0.0-rc.26` and `@prisma/orm-postgres` as of `8.0.0-rc.23`. The two packages have separate version numbers. The Prisma ORM 7 side of the app stays at `7.10.1` throughout. +To keep Prisma ORM 7 running beside Prisma 8 and move one route at a time, follow [Prisma ORM 7 to 8, route by route](/guides/upgrade-prisma-orm/postgresql-incremental). For MongoDB, follow [Prisma ORM 6 to 8 (MongoDB)](/guides/upgrade-prisma-orm/mongodb). To host the upgraded app, continue with [Deploy an existing app on Prisma Compute](/guides/compute/deploy-existing-app) when you finish this guide. ::: -## How the incremental migration works - -The migration runs in five phases. The application works at the end of each one. - -1. **Prepare Prisma ORM 7 for side-by-side operation.** Move Prisma ORM 7 onto its own package name, binary, and config file. No behavior changes. -2. **Add Prisma ORM 8.** Install the Prisma ORM 8 CLI and runtime with their own config, schema contract, and generated client. No application code uses them yet. -3. **Migrate one route.** One route runs on Prisma ORM 8 while the rest stay on Prisma ORM 7, all against the same database. -4. **Transfer migration ownership.** Prisma ORM 8 takes over planning and applying schema changes. -5. **Remove Prisma ORM 7** once nothing imports it. - -The ownership timeline matters more than the code timeline. Prisma ORM 7 owns schema migrations through phases 1 to 3, and routes move to Prisma ORM 8 independently of that. Prisma ORM 8 takes over migrations only in phase 4, after a database signature and a `db` ref are in place; the first `migration plan` then writes the baseline migration itself. You can pause between phases for as long as you need. - -The [prisma8-and-7-example](https://github.com/prisma/prisma8-and-7-example) repository shows the finished result of each phase (tags `step-0` through `step-3`). +This guide moves an Express, Fastify, Hono or other Node.js server from Prisma ORM 6 or 7 on PostgreSQL to Prisma 8 in one pass. You keep your `schema.prisma`, your database and its data. At the end, Prisma 8 owns your migrations, every query runs through the Prisma 8 client, and the app runs wherever it ran before, reading `DATABASE_URL` as it does today. -## Prerequisites - -- **Node.js 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer**; Node.js 24 recommended -- A working **Prisma ORM 7** application on PostgreSQL: `prisma.config.ts`, the `prisma-client` generator, and a driver adapter -- **TypeScript 5.9 or newer** with `"strict": true`. [Step 2.6](#26-set-up-tsconfigjson-for-the-prisma-orm-8-client) tells you whether to change the `module` setting in `tsconfig.json` - -## 1. Prepare Prisma ORM 7 for side-by-side operation +A Prisma ORM 6 app does not need to upgrade to Prisma ORM 7 first, because Prisma 8 reads a Prisma ORM 6 schema as it is. -Prisma ORM 8 expects the `prisma` package name, the `prisma` binary, and the `prisma.config.ts` file name. In this phase you move Prisma ORM 7 off those three names so Prisma ORM 8 can take them without ambiguity. Nothing migrates yet. +The examples follow a small feedback board: Express 4, EJS views, Prisma ORM 6.19, compiled with `tsc` and run with `node`. Its models are `Board`, `Post`, `Vote` and `Comment`, with a `PostStatus` enum. Map the names to your own app. -### 1.1. Confirm the application works +## Two ways to upgrade -The guide follows a small Hono API with two routes. Map the file names to your own project. The Prisma ORM 7 pieces that matter: +Follow the steps below yourself, or have your coding agent follow them with the `prisma-postgres-upgrade` [skill](/ai/tools/skills): -```json title="package.json (excerpt)" -{ - "scripts": { - "prisma:generate": "prisma generate", - "db:migrate": "prisma migrate dev" - }, - "dependencies": { - "@prisma/adapter-pg": "^7.10.0", - "@prisma/client": "^7.10.0" - }, - "devDependencies": { - "prisma": "^7.10.0" - } -} +```npm +npx skills add prisma/skills --skill prisma-postgres-upgrade ``` -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} - -datasource db { - provider = "postgresql" -} - -model User { - id Int @id @default(autoincrement()) - email String @unique - name String? - posts Post[] -} +Then ask your agent from the project root: -model Post { - id Int @id @default(autoincrement()) - title String - published Boolean @default(false) - authorId Int - author User @relation(fields: [authorId], references: [id], onDelete: Cascade) + - @@index([authorId]) -} +```text +Upgrade this app from Prisma ORM 6 to Prisma 8. ``` -```typescript title="prisma.config.ts" -import "dotenv/config"; -import { defineConfig } from "prisma/config"; + -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - datasource: { - url: process.env["DATABASE_URL"], - }, -}); -``` +The agent runs your project's type check, build and tests before and after the upgrade, and leaves the change for you to review. To deploy the upgraded app afterwards, add the `prisma-compute` skill, which follows [Deploy an existing app on Prisma Compute](/guides/compute/deploy-existing-app): -```typescript title="src/db.ts" -import "dotenv/config"; -import { PrismaPg } from "@prisma/adapter-pg"; -import { PrismaClient } from "../generated/prisma/client"; - -const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! }); - -export const prisma = new PrismaClient({ adapter }); +```npm +npx skills add prisma/skills --skill prisma-compute ``` -Two routes read and write through this client, `/users` and `/posts`: - -```typescript title="src/routes/users.ts" -import { Hono } from "hono"; -import { prisma } from "../db"; - -export const users = new Hono(); +## Prerequisites -users.get("/", async (c) => { - const result = await prisma.user.findMany({ - include: { posts: true }, - orderBy: { id: "asc" }, - }); - return c.json(result); -}); +- **Node.js 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer**; Node.js 24 recommended. See [Supported versions](/orm/supported-versions). +- **A working Prisma ORM 6 or 7 app on PostgreSQL**, and a database it has migrated. Start the app and load a page that queries the database before you change anything, so you have something to compare with. +- **TypeScript 5.9 or newer**, with `"strict": true`. -users.post("/", async (c) => { - const body = await c.req.json<{ email: string; name?: string }>(); - const user = await prisma.user.create({ data: body }); - return c.json(user, 201); -}); -``` +## 1. Install Prisma 8 -`src/routes/posts.ts` follows the same pattern for `Post`. +### 1.1. Replace the Prisma CLI -Start the app and run a read and a write: +Remove the Prisma ORM 6 or 7 CLI and install the Prisma 8 CLI and its PostgreSQL runtime: ```npm -npm run dev +npm uninstall prisma +npm install --save-dev --save-exact prisma@8.0.0-rc.27 +npm install --save-exact @prisma/orm-postgres@8.0.0-rc.20 +npm install dotenv ``` -```bash -curl -X POST localhost:3000/users -H 'content-type: application/json' \ - -d '{"email":"alice@prisma.io","name":"Alice"}' -curl localhost:3000/users -``` +`prisma` is the Prisma 8 CLI, and `@prisma/orm-postgres` is the PostgreSQL runtime your code imports. The two packages have separate version numbers. `dotenv` loads your `.env` file in `prisma.config.ts` and `src/db.ts`, because the Prisma 8 CLI does not load it the way Prisma ORM 6 did. Install it even if `node_modules` already has a copy that another package brought in. -Do not continue until both requests succeed. That confirms the Prisma ORM 7 application works before you change its configuration. +Install these exact versions, not `@latest`. They are the versions Prisma Compute deploys today, so the app stays ready for [Deploy an existing app on Prisma Compute](/guides/compute/deploy-existing-app): the Console's setup keeps the `prisma` and `@prisma/orm-postgres` versions your `package.json` declares, and the latest pair on npm does not work with the Composer version it installs. The rest of this guide, including the query notes in step 5, was tested at these versions. -### 1.2. Replace the `prisma` package with `@prisma/prisma7` +Leave `@prisma/client`, a driver adapter such as `@prisma/adapter-pg`, and the generated client in place for now. Step 6 removes them. -```npm -npm uninstall prisma -npm install --save-dev @prisma/prisma7@7.10.1 -``` +:::note[Your old client after a fresh install] -`@prisma/prisma7` is the same Prisma ORM 7 CLI under a version-specific name. It exposes a `prisma7` binary and keeps `prisma` 7 as a transitive dependency. Your `@prisma/client` and `@prisma/adapter-pg` dependencies stay untouched. +From here on, `prisma` is the Prisma 8 CLI and nothing regenerates your old client, so this guide rewrites every query in one pass. To move a Prisma ORM 7 app gradually instead, keep its CLI as `prisma7` with `@prisma/prisma7` and follow the [route-by-route guide](/guides/upgrade-prisma-orm/postgresql-incremental). Prisma ORM 6 has no equivalent. -### 1.3. Rename the Prisma ORM 7 config +The client you already generated keeps working on your machine while you rewrite queries in step 5. A fresh install, such as a CI run or a new clone, has none, and a Prisma ORM 6 app then fails with `@prisma/client did not initialize yet`. Rewrite every query before you push this work to a branch that CI builds. -```bash -mv prisma.config.ts prisma7.config.ts -``` - -```typescript title="prisma7.config.ts" -import "dotenv/config"; -import { defineConfig } from "prisma/config"; // [!code --] -import { defineConfig } from "@prisma/prisma7/config"; // [!code ++] - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - datasource: { - url: process.env["DATABASE_URL"], - }, -}); -``` +::: -The `prisma7` CLI discovers `prisma7.config.ts` automatically, so no `--config` flag is needed. Renaming frees the `prisma.config.ts` name for Prisma ORM 8, which only accepts its own config format under that name. +### 1.2. Remove `prisma generate` from your scripts -### 1.4. Point scripts at the `prisma7` binary +The Prisma 8 CLI has no `generate` command. `npx prisma generate` now fails with `CLI.UNKNOWN_COMMAND` and exit code `2`, so any script that runs it, such as `build` or `postinstall`, fails too. Remove it, along with the Prisma ORM 6 or 7 migration and seed scripts. Step 3 sets up the Prisma 8 migration command: ```json title="package.json (excerpt)" { "scripts": { - "prisma:generate": "prisma generate", // [!code --] - "db:migrate": "prisma migrate dev" // [!code --] - "prisma7:generate": "prisma7 generate", // [!code ++] - "prisma7:migrate": "prisma7 migrate dev" // [!code ++] - } + "build": "prisma generate && tsc", // [!code --] + "build": "tsc", // [!code ++] + "postinstall": "prisma generate", // [!code --] + "db:migrate": "prisma migrate dev", // [!code --] + "db:deploy": "prisma migrate deploy", // [!code --] + "db:seed": "prisma db seed", // [!code --] + "db:migrate": "prisma db migrate" // [!code ++] + }, + "prisma": { "seed": "tsx prisma/seed.ts" } // [!code --] } ``` -After Prisma ORM 8 is installed, the `prisma` binary runs the Prisma ORM 8 CLI. Update every script, CI job, and deployment command that must continue using Prisma ORM 7 to call `prisma7` instead. - -### 1.5. Check that Prisma ORM 7 still works - -```npm -npx prisma7 generate -npx prisma7 migrate status -``` - -**Expected result:** `generate` writes the client to `generated/prisma` as before, and `migrate status` reports that the database schema is up to date. Start the app and query each route; behavior should be identical to step 1.1. +Prisma 8 has no seed command. To seed, write a script that imports the client from step 5 and calls `.create(...)`, and run it with `tsx`. -## 2. Add Prisma ORM 8 +**Check:** `npx prisma --version` prints `8.0.0-rc.27`. -### 2.1. Install the Prisma ORM 8 packages +## 2. Create the contract from your schema -```npm -npm install --save-dev prisma@latest -npm install @prisma/orm-postgres -``` +Prisma 8 describes your models as a [contract](/orm/contract-authoring/the-data-contract). It can read your existing `schema.prisma` as that contract, so you keep editing the file you have. -`prisma@latest` is the Prisma ORM 8 CLI, and its `prisma/config` subpath provides `definePrismaConfig` for the Prisma ORM 8 config file. Installing it locally (not only running it through `npx`) is what makes that import resolve. `@prisma/orm-postgres` is the PostgreSQL ORM runtime your application code will import. +### 2.1. Write `prisma.config.ts` -After this install, `npx prisma ` runs the Prisma ORM 8 CLI and `npx prisma7 ` runs Prisma ORM 7: - -```npm -npx prisma --version -``` - -**Expected result:** the command prints `8.0.0-rc.32` or a newer version. That number does not match the version of `@prisma/orm-postgres`, because the CLI is released separately. - -### 2.2. Create the Prisma ORM 8 config +Create `prisma.config.ts` in the project root. In a Prisma ORM 7 app, replace the `prisma.config.ts` you have, because Prisma 8 reads only its own config format under that name: ```typescript title="prisma.config.ts" import "dotenv/config"; import { definePrismaConfig } from "prisma/config"; -import { defineConfig as definePostgresConfig } from "@prisma/orm-postgres/config"; +import { defineConfig, prisma7Schema } from "@prisma/orm-postgres/config"; export default definePrismaConfig({ - orm: definePostgresConfig({ - contract: "prisma8/contract.prisma", - output: "generated/prisma8", + orm: defineConfig({ + contract: prisma7Schema("prisma/schema.prisma"), + output: "src/prisma", db: { connection: process.env["DATABASE_URL"], }, @@ -248,330 +126,280 @@ export default definePrismaConfig({ }); ``` -Both configs point at the **same** `DATABASE_URL`. Everything else is separate: +`prisma7Schema(...)` reads a Prisma ORM 7 schema, and it reads a Prisma ORM 6 schema unchanged too: the `generator client { provider = "prisma-client-js" }` block and `url = env("DATABASE_URL")` in the datasource stay as they are, and Prisma 8 ignores them. `output: "src/prisma"` writes the emitted contract inside `src/`, where `tsc` compiles it. -| | Prisma ORM 7 | Prisma ORM 8 | -|---|---|---| -| CLI | `prisma7` | `prisma` | -| Config | `prisma7.config.ts` | `prisma.config.ts` | -| Schema | `prisma/schema.prisma` | `prisma8/contract.prisma` | -| Generated client | `generated/prisma` | `generated/prisma8` | +[Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists how each date and time type reads, and the parts of a schema Prisma 8 cannot read, such as `view` blocks. If your schema uses PostgreSQL extensions such as `pgvector` or `citext`, that section also shows the packs to add to the config. -Because the config carries the connection, the Prisma ORM 8 CLI commands below don't need a `--db` flag. +If you use a coding agent, install the [agent skills](/cli/skills) that ship inside the Prisma 8 packages, matched to their versions: -:::tip[Read the Prisma ORM 7 schema instead] +```npm +npx prisma skills sync +``` -Instead of generating a contract file in steps 2.3 and 2.4, Prisma ORM 8 can read `prisma/schema.prisma` directly as its contract, so you keep one schema file while Prisma ORM 7 owns migrations. `schema.prisma` does not need the `// use prisma-8` first line that a contract file written for Prisma ORM 8 starts with (step 2.4 shows one). Skip steps 2.3 and 2.4, and change two lines in the `prisma.config.ts` you just wrote: +It needs the Prisma 8 `prisma.config.ts`: with a Prisma ORM 7 config still in place, it fails with `CLI.CONFIG_UNREADABLE`. If you later deploy on Prisma Compute, run it again after you add Composer, which ships a skill of its own. -```typescript title="prisma.config.ts" -import "dotenv/config"; -import { definePrismaConfig } from "prisma/config"; -import { defineConfig as definePostgresConfig } from "@prisma/orm-postgres/config"; // [!code --] -import { defineConfig as definePostgresConfig, prisma7Schema } from "@prisma/orm-postgres/config"; // [!code ++] +### 2.2. Emit the contract -export default definePrismaConfig({ - orm: definePostgresConfig({ - contract: "prisma8/contract.prisma", // [!code --] - contract: prisma7Schema("prisma/schema.prisma"), // [!code ++] - output: "generated/prisma8", - db: { - connection: process.env["DATABASE_URL"], - }, - }), -}); +```npm +npx prisma contract emit ``` -Read this way, a `DateTime` field and the `@db.Timestamp` and `@db.Timestamptz` fields are JavaScript `Date` objects in Prisma ORM 8, as in Prisma ORM 7. The `@db.Date` and `@db.Time` fields are ISO 8601 strings, such as `"2026-09-14"` and `"10:00:00.5"`, where Prisma ORM 7 gave you `Date` objects. The Prisma ORM 8 client needs no `Temporal` for any of them. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) has the details. +**Expected result:** `Emitted contract.json and contract.d.ts`, and the two files in `src/prisma/`. `contract.json` is what the Prisma 8 client reads at runtime, and `contract.d.ts` holds its types. Commit both, and run `contract emit` again after every change to `schema.prisma`. + +If `contract emit` fails, its error names the line in `schema.prisma` and the edit to make. -After step 2.5, run `npx prisma db sign`. [`db sign`](/cli/db-sign) checks that the database matches the contract Prisma ORM 8 read from `schema.prisma` and records in the database that it does. Signing does not move your migrations to Prisma ORM 8. Prisma ORM 7 keeps planning and applying them, so after each Prisma ORM 7 migration, whether you ran `prisma7 migrate dev` or `prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign` again. If you emit without signing, the Prisma ORM 8 client still runs queries, but `npx prisma db verify` reports that the contract no longer matches the one recorded in the database. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists the parts of a Prisma ORM 7 schema that Prisma ORM 8 cannot read. +### 2.3. Sign the existing database -If you have not started phase 1 yet, one command does phase 1 and this setup for you: +Your database already has every table the contract describes. Record that in the database: -```npm title="Terminal" -npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma +```npm +npx prisma db sign ``` -Write `prisma@latest`, because in a Prisma ORM 7 project `npx prisma` runs version 7. The command moves Prisma ORM 7 to the `prisma7` command and `prisma7.config.ts`, installs the Prisma ORM 8 packages, writes `prisma.config.ts` and a Prisma ORM 8 client in `src/prisma/db.ts`, and emits the contract. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with phase 3, using the `db` client from `src/prisma/db.ts` instead of adding one to `src/db.ts` in step 3.1. +[`db sign`](/cli/db-sign) checks that the tables match the contract, then writes a marker in the database that names the contract it matches. It does not change your tables. It also writes a snapshot of the contract under `migrations/snapshots/` and a ref named `db` in `migrations/app/refs/db.json`, which step 3 plans from. -Prisma ORM 7 keeps owning migrations on this path until you are ready for [phase 4](#4-transfer-migration-ownership), where Prisma ORM 8 takes them over. Phase 4 needs a contract file written for Prisma ORM 8, so switch to one first. Either run `npx prisma contract print --output prisma8/contract.prisma`, which writes the contract Prisma ORM 8 read from `schema.prisma` as a Prisma ORM 8 contract file, or run steps 2.3 to 2.5. Then set `contract` in `prisma.config.ts` to `"prisma8/contract.prisma"`, the file you created. Then follow phase 4 as written. Its first step, `db sign`, checks the new contract against the database before Prisma ORM 8 takes over. +**Expected result:** the command prints `Database signed` and `Advanced ref "db"`. If you keep using other existing databases, such as a staging database, run `db sign` once against each of them with `DATABASE_URL` pointing at it. A new, empty database does not need it, because `db migrate` in step 3 creates its tables. -::: +## 3. Hand migrations to Prisma 8 -### 2.3. Infer the contract from the live database +From here on, Prisma 8 plans and applies schema changes, and you stop running `prisma migrate`. Prisma 8 keeps reading `prisma/schema.prisma`, so you go on editing the same file. -Prisma ORM 8 describes your schema as a [contract](/orm/contract-authoring/the-data-contract). Generate it from the database Prisma ORM 7 built: +### 3.1. Plan the baseline migration -```npm title="Terminal" -npx prisma contract infer --output prisma8/contract.prisma +```npm +npx prisma migration plan --name init ``` -### 2.4. Review the inferred contract - -`contract infer` reads every table in the database except `_prisma_migrations`, the table where Prisma ORM 7 records which migrations it has applied, so the contract has no model for it and Prisma ORM 8 never manages it. The table itself stays in the database, and `db verify --strict` does not report it. +**Expected result:** `Planned baseline (12 operation(s)) + 0 operation(s)`, with your own number of operations, and a folder `migrations/app/_baseline`. On a signed database, the first `migration plan` always names that folder `baseline` and ignores `--name`. The baseline creates every table, index and foreign key in the contract, so a new, empty database ends up with your schema. Your existing database skips it, because its marker already names that contract: -You do not need to add `@@map` to the other models: a model without `@@map` uses its name, exactly as written, as its table name, so `User` reads and writes the `"User"` table that Prisma ORM 7 created. - -The inferred contract looks like this: +```npm +npx prisma db migrate +``` -```prisma title="prisma8/contract.prisma" -// use prisma-8 +**Expected result:** the command prints `(no operations)`. Against a new, empty database, such as one for CI or a new environment, the same command applies the baseline. -model User { - id Int @id(map: "User_pkey") @default(autoincrement()) - email String - name String? - posts Post[] +Commit the `migrations/` folder, which holds the baseline, the snapshot and the `db` ref, together with `src/prisma/contract.json` and `src/prisma/contract.d.ts`. - @@index([email], map: "User_email_key", unique: true) -} +### 3.2. Retire `prisma/migrations` -model Post { - id Int @id(map: "Post_pkey") @default(autoincrement()) - title String - published Boolean @default(false) - authorId Int - author User @relation(fields: [authorId], references: [id], onDelete: Cascade, onUpdate: Cascade, map: "Post_authorId_fkey") +Prisma 8 does not read the `prisma/migrations` folder, and the baseline already describes the schema those migrations built. Delete the folder, including `migration_lock.toml`: - @@index([authorId], map: "Post_authorId_idx") -} +```bash +rm -r prisma/migrations ``` -Keep `// use prisma-8` as the first line of `prisma8/contract.prisma`. `contract emit` reads only `.prisma` files that start with this line, and this is the only file in your contract, so without it `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`. A `schema.prisma` that Prisma ORM 8 reads through `prisma7Schema(...)`, as in the tip at the end of step 2.2, does not need the line. +Keep `prisma/schema.prisma`: it is still your contract. Prisma ORM 6 and 7 recorded applied migrations in a `_prisma_migrations` table, which stays in the database. Prisma 8 leaves it out of `db verify` and `contract infer`, and you can drop it whenever you like. -### 2.5. Emit the contract artifacts +From now on, a schema change is: edit `prisma/schema.prisma`, then run ```npm npx prisma contract emit +npx prisma migration plan --name +npx prisma db migrate --advance-ref db ``` -`contract emit` writes `contract.json` and `contract.d.ts` to `generated/prisma8`, the runtime and type inputs for the Prisma ORM 8 client. Re-run it after every contract change. - -### 2.6. Set up tsconfig.json for the Prisma ORM 8 client - -Your `tsconfig.json` must allow the JSON import you will write in step 3.1: `import contractJson from "../generated/prisma8/contract.json" with { type: "json" }`. TypeScript accepts the `with { type: "json" }` part only when `module` is `esnext`, `node18`, `node20`, `nodenext`, or `preserve`, and only in a file it treats as an ES module. Any other value, such as `commonjs`, `es2022`, or `node16`, rejects it, and leaving `module` unset fails too. Take the first case below that matches how your app runs: - -- **`module` is already one of the five values and your build works with it, and either `package.json` has `"type": "module"` or `module` is `esnext` or `preserve`.** Keep it. Set `moduleResolution` to `bundler` if `module` is `esnext` or `preserve`, to `nodenext` if `module` is `nodenext`, and remove it if `module` is `node18` or `node20`. A `moduleResolution` of `node` or `node10` cannot resolve the `@prisma/orm-*` packages, so do not leave that in place. -- **You compile with `tsc`, run the output with `node`, and `package.json` has no `"type": "module"` (or has `"type": "commonjs"`).** Your app runs as CommonJS, and it can stay that way. Set `"module": "nodenext"` and `"moduleResolution": "nodenext"`, and do not add `"type": "module"`. Prisma ORM 8 works from CommonJS code, and your relative imports stay as they are, without extensions. TypeScript treats `db.ts` as CommonJS here, so in step 3.1 write the JSON import without the `with` part and copy the other import lines as shown. - - ```typescript title="src/db.ts (CommonJS excerpt)" - import contractJson from "../generated/prisma8/contract.json"; - ``` +`--advance-ref db` points `migrations/app/refs/db.json` at the new contract, so the next `migration plan` starts from it. [How migrations work](/orm/migrations/how-migrations-work) covers the full loop. -- **The app runs through `tsx`, or a bundler such as `vite`, `next`, or `esbuild` builds it, and you never run `tsc` output with plain `node`.** Set `"module": "preserve"` and `"moduleResolution": "bundler"`. You do not need file extensions on relative imports, and the import lines in step 3.1 work as shown. The [example project](https://github.com/prisma/prisma8-and-7-example) is set up this way. If you run the `.ts` files directly with `node` instead, its type stripping needs the `.ts` extension on every relative import, so add `"allowImportingTsExtensions": true` as well. -- **You compile with `tsc`, run the output with `node`, and `package.json` has `"type": "module"`, even if you use `tsx` in development.** Set `"module": "nodenext"` and `"moduleResolution": "nodenext"`. Node then requires an explicit file extension on every relative import, which for compiled TypeScript files is `.js`, so this is the one setup that makes you rewrite imports; [the TypeScript module reference](https://www.typescriptlang.org/docs/handbook/modules/reference.html#node16-node18-nodenext) explains the rule. +## 4. Point TypeScript at the Prisma 8 client -Whichever case applies, add `"resolveJsonModule": true` so TypeScript can type the JSON import, and add `generated/prisma8/**/*.d.ts` to `include` so it sees the emitted `contract.d.ts`. If your `tsconfig.json` has no `include`, TypeScript already picks up every file under the project, so skip that part: +Every Prisma 8 package is published as ES modules, and your code imports the emitted `contract.json`. An app that compiles with `tsc` and runs the output with `node` can stay CommonJS. Set `module` and `moduleResolution` to `nodenext`, and turn on `resolveJsonModule`: ```json title="tsconfig.json (excerpt)" { "compilerOptions": { - "resolveJsonModule": true // [!code ++] + "module": "commonjs", // [!code --] + "module": "nodenext", // [!code ++] + "moduleResolution": "nodenext", // [!code ++] + "resolveJsonModule": true, // [!code ++] + "outDir": "dist", + "rootDir": "src", + "strict": true }, - "include": [ - "src/**/*.ts", - "generated/prisma/**/*.ts", - "generated/prisma8/**/*.d.ts" // [!code ++] - ] + "include": ["src"] } ``` -**Check:** `npx tsc --noEmit` passes. Prisma ORM 8 is now installed and configured, but no application code uses it yet. This check does not test your `module` choice, because nothing imports `contract.json` until step 3.1; if TypeScript reports TS2823 there, the `module` value rejects the `with` part, and if it reports TS2856, the file compiles as CommonJS and the `with` part has to go, as the CommonJS case shows. +Keep `package.json` without `"type": "module"`, and your relative imports stay as they are, without extensions. Keep `include` limited to `src` as well, so `tsc` does not compile `prisma.config.ts` into `dist/`. If your app runs through `tsx` or a bundler, or `package.json` has `"type": "module"`, [Set up tsconfig.json](/guides/upgrade-prisma-orm/postgresql-incremental#26-set-up-tsconfigjson-for-the-prisma-orm-8-client) gives the settings for each case. -## 3. Migrate one route +## 5. Rewrite your queries -Pick one small route and move only that code. The rest of the application stays on Prisma ORM 7. +### 5.1. Create the Prisma 8 client -### 3.1. Instantiate both clients +Replace the file that creates `PrismaClient`. The Prisma 8 client reads `DATABASE_URL`, as your Prisma ORM 6 or 7 client did. -```typescript title="src/db.ts" +```typescript title="src/db.ts" tab="Prisma 8" import "dotenv/config"; -import { PrismaPg } from "@prisma/adapter-pg"; -import postgres from "@prisma/orm-postgres/runtime"; // [!code ++] -import { contractFromJson } from "@prisma/orm-postgres/static"; // [!code ++] -import type { Contract } from "../generated/prisma8/contract.d"; // [!code ++] -import contractJson from "../generated/prisma8/contract.json" with { type: "json" }; // [!code ++] -import { PrismaClient } from "../generated/prisma/client"; +import postgres from "@prisma/orm-postgres/runtime"; +import { contractFromJson } from "@prisma/orm-postgres/static"; +import type { Contract } from "./prisma/contract.d"; +import contractJson from "./prisma/contract.json"; + +export const db = postgres({ + contract: contractFromJson(contractJson), + url: process.env["DATABASE_URL"]!, +}); +``` -const connectionString = process.env.DATABASE_URL!; +```typescript title="src/db.ts" tab="Prisma ORM 6" +import { PrismaClient } from "@prisma/client"; -const adapter = new PrismaPg({ connectionString }); +export const prisma = new PrismaClient(); +``` -export const prisma = new PrismaClient({ adapter }); +```typescript title="src/db.ts" tab="Prisma ORM 7" +import { PrismaPg } from "@prisma/adapter-pg"; +import { PrismaClient } from "../generated/prisma/client"; -export const contract = contractFromJson(contractJson); // [!code ++] +const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! }); -export const db = postgres({ url: connectionString, contract }); // [!code ++] +export const prisma = new PrismaClient({ adapter }); ``` -`prisma` is the Prisma ORM 7 client and `db` is the Prisma ORM 8 client, both connected to the same database. `contractFromJson` turns the emitted `contract.json` into a typed contract value, which the Prisma ORM 8 client takes as `contract`. +In a file that compiles as an ES module, write the JSON import as `import contractJson from "./prisma/contract.json" with { type: "json" };`. -### 3.2. Rewrite the route +### 5.2. Rewrite each query -Move the users route to the Prisma ORM 8 [ORM client](/orm/reference/orm-client). Queries start from `db.orm..` (`public` here) and chain instead of taking one options object: +A Prisma 8 query starts from `db.orm.public.`, where `public` is the PostgreSQL schema your tables are in, and chains calls instead of taking one options object. The last call, such as `.all()`, `.first()` or `.create(...)`, says what you get back. The calls in Prisma ORM 6 and 7 are the same, so one rewrite covers both: -```typescript title="src/routes/users.ts" tab="After" -import { Hono } from "hono"; -import { db } from "../db"; +```typescript title="src/server.ts (excerpt)" tab="Prisma 8" +import { db } from "./db"; -export const users = new Hono(); - -users.get("/", async (c) => { - const result = await db.orm.public.User.include("posts", (posts) => - posts.orderBy((post) => post.id.asc()), - ) - .orderBy((user) => user.id.asc()) - .all(); - return c.json(result); -}); - -users.post("/", async (c) => { - const body = await c.req.json<{ email: string; name?: string }>(); - const user = await db.orm.public.User.create(body); - return c.json(user, 201); -}); -``` +// findMany with a relation count and orderBy +const boards = await db.orm.public.Board.include("posts", (posts) => posts.count()) + .orderBy((b) => b.createdAt.asc()) + .all(); +// boards[0].posts is a number -```typescript title="src/routes/users.ts" tab="Before" -import { Hono } from "hono"; -import { prisma } from "../db"; +// findMany with where, two counts, and ordering by a relation count +const posts = await db.orm.public.Post.where({ boardId: board.id }) + .include("votes", (votes) => votes.count()) + .include("comments", (comments) => comments.count()) + .orderBy([(p) => p.votes.count().desc(), (p) => p.createdAt.desc()]) + .all(); -export const users = new Hono(); +// findUnique by primary key, with relations +const post = await db.orm.public.Post.whereUnique({ id }) + .include("board") + .include("comments", (comments) => comments.orderBy((c) => c.createdAt.asc())) + .include("votes", (votes) => votes.count()) + .first(); -users.get("/", async (c) => { - const result = await prisma.user.findMany({ - include: { posts: true }, - orderBy: { id: "asc" }, - }); - return c.json(result); -}); +// findUnique by a @unique field, and by a compound @@unique +const bySlug = await db.orm.public.Board.where({ slug }).first(); +const vote = await db.orm.public.Vote.where({ postId, voterId }).first(); -users.post("/", async (c) => { - const body = await c.req.json<{ email: string; name?: string }>(); - const user = await prisma.user.create({ data: body }); - return c.json(user, 201); +// create with a nested create +const created = await db.orm.public.Post.create({ + boardId: board.id, + title, + body, + author, + votes: (v) => v.create([{ voterId }]), }); -``` -`src/routes/posts.ts` stays unchanged, on Prisma ORM 7. +// deleteMany, returning the number of deleted rows +const deleted = await db.orm.public.Vote.where({ postId, voterId }).deleteAndCount(); -### 3.3. Exercise both code paths +// count +const { total } = await db.orm.public.Post.where({ boardId: board.id }).aggregate((agg) => ({ + total: agg.count(), +})); -Start the app and hit both routes: +// $queryRaw +await db.query(db.raw.sql`SELECT 1 AS ok`.returnsRow({ ok: "pg/int4@1" }).build()); -```bash -curl localhost:3000/users -curl -X POST localhost:3000/posts -H 'content-type: application/json' \ - -d '{"title":"Written by Prisma 7","authorId":1}' -curl localhost:3000/users +// enum values +const STATUSES = db.nativeEnums.public.PostStatus.values; ``` -**Expected result:** the first request runs through Prisma ORM 8. The second writes through Prisma ORM 7. The third, through Prisma ORM 8 again, includes the post Prisma ORM 7 just wrote. - -Remaining routes can move over the same way, one at a time, on any schedule. Prisma ORM 7 still owns schema migrations in this phase. If the schema changes, run `prisma7 migrate dev`, then re-run `contract infer` and `contract emit` so the Prisma ORM 8 contract stays current. - -## 4. Transfer migration ownership - -So far every schema change has gone through `prisma7 migrate dev`. In this phase Prisma ORM 8 takes over planning and applying schema changes, and `prisma/schema.prisma` is frozen. - -Treat the switch as a decision, not a routine step. After it, your team and your pipelines must stop using the Prisma ORM 7 migration workflow, even though routes still on the Prisma ORM 7 client keep working. See [how migrations work](/orm/migrations/how-migrations-work) for the full picture. - -Prisma ORM 8 tracks schema state with four pieces, and the handoff creates each one exactly once: - -- A **contract hash** identifies one version of the emitted contract. -- A **migration** is an on-disk package recording how to get from one contract hash to another. `migrate` only replays recorded migrations; it never invents one. -- The **marker** is Prisma ORM 8's record, stored in the database, of which contract hash the database currently satisfies. -- A **ref** is a named pointer at a contract hash. `migration plan` uses the `db` ref as its starting point. +```typescript title="src/server.ts (excerpt)" tab="Prisma ORM 6 and 7" +import { PostStatus } from "@prisma/client"; +import { prisma } from "./db"; -Step 4.1 creates the marker and the ref with one command. The baseline migration is written by the first `migration plan` in step 4.3. +const boards = await prisma.board.findMany({ + orderBy: { createdAt: "asc" }, + include: { _count: { select: { posts: true } } }, +}); +// boards[0]._count.posts is a number -### 4.1. Sign the existing database +const posts = await prisma.post.findMany({ + where: { boardId: board.id }, + include: { _count: { select: { votes: true, comments: true } } }, + orderBy: [{ votes: { _count: "desc" } }, { createdAt: "desc" }], +}); -Your database already has every table the contract describes, so adopt it rather than replay anything: +const post = await prisma.post.findUnique({ + where: { id }, + include: { + board: true, + comments: { orderBy: { createdAt: "asc" } }, + _count: { select: { votes: true } }, + }, +}); -```npm -npx prisma db sign -npx prisma migration status -``` +const bySlug = await prisma.board.findUnique({ where: { slug } }); +const vote = await prisma.vote.findUnique({ + where: { postId_voterId: { postId, voterId } }, +}); -`db sign` verifies that the live schema matches the emitted contract, writes Prisma ORM 8's marker at that contract version, stores the contract snapshot under `migrations/snapshots/`, and points a [ref](/orm/migrations/the-migration-graph#name-important-states-with-refs) named `db` at it. `migration plan` starts from that ref, so plans chain from the schema Prisma ORM 7 built and contain only your own changes. +const created = await prisma.post.create({ + data: { boardId: board.id, title, body, author, votes: { create: { voterId } } }, +}); -**Expected result:** `Database signed`, and `migration status` shows the current and target contract hashes match with nothing pending. +const deleted = (await prisma.vote.deleteMany({ where: { postId, voterId } })).count; -### 4.2. Retire the Prisma ORM 7 migration scripts +const total = await prisma.post.count({ where: { boardId: board.id } }); -Remove `prisma7 migrate` from your scripts so nobody runs it by accident. Keep `prisma7 generate`, because the legacy routes still need their client: +await prisma.$queryRaw`SELECT 1`; -```json title="package.json (excerpt)" -{ - "scripts": { - "prisma7:generate": "prisma7 generate", - "prisma7:migrate": "prisma7 migrate dev", // [!code --] - "prisma8:migrate": "prisma db migrate --advance-ref db" // [!code ++] - } -} +const STATUSES = Object.values(PostStatus); ``` -### 4.3. Verify the handoff with a schema change +Five differences catch most rewrites: -Verify the migration handoff with a small additive schema change. Add a field to the contract: +- **A count lands on the relation's own key.** `include("votes", (votes) => votes.count())` puts the number in `post.votes`, where Prisma ORM 6 and 7 put it in `post._count.votes`. Update the views and response code that read `_count`. `tsc` does not check templates such as EJS views, so they still compile while they read `_count.*`. +- **`whereUnique` takes only the primary key here.** A schema read through `prisma7Schema(...)` keeps each `@unique` and `@@unique` as the unique index Prisma ORM 6 and 7 created, and `whereUnique` accepts only a primary key or a unique constraint. Look rows up by those fields with `.where({ ... }).first()`, which runs the same query. +- **Enums come from the client.** An `enum` in a Prisma ORM 6 or 7 schema is a PostgreSQL enum type, so its values are in `db.nativeEnums.public..values`. Fields of that type still read and write the same strings. +- **At `@prisma/orm-postgres@8.0.0-rc.20`, a `DateTime` field reads as a string**, such as `"2026-11-06 09:10:48.497"`: the stored UTC time, without an offset. Code that calls a `Date` method on it, such as `post.createdAt.toISOString()` in a template, fails. Use the string, or convert it with `new Date(value.replace(" ", "T") + "Z")`. Templates that `tsc` does not check still compile while they call it. Later releases read the field as a `Date` again, so check this when you upgrade. +- **At the same version, `@default(now())` is filled by the database.** A `@default(now())` field you leave out of `.create(...)` gets its value from the database's `now()`, which for a `timestamp` column is the database's local time. Prisma ORM 6 and 7 sent the UTC time instead. Run `SHOW timezone` on your database: if it prints anything other than `UTC`, new rows store local time where old rows store UTC. Decide how to handle it before you ship, for example by setting the database's time zone with `ALTER DATABASE SET timezone TO 'UTC'`, or by passing the field yourself in `.create(...)`. -```prisma title="prisma8/contract.prisma (excerpt)" -model User { - id Int @id(map: "User_pkey") @default(autoincrement()) - email String - name String? - bio String? // [!code ++] - ... -} -``` +The [ORM client reference](/orm/reference/orm-client) has every method, and [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7#queries) maps the rest of the Prisma ORM 6 and 7 query API, including what has no Prisma 8 form yet, such as `increment` in an update. -Emit, plan, and apply: +### 5.3. Run the app locally ```npm -npx prisma contract emit -npx prisma migration plan --name add_user_bio -npx prisma db migrate --advance-ref db -npx prisma db verify +npm run build +npm start ``` -**Expected result:** `migration plan` reports `Planned baseline + 1 operation(s)` and writes two packages under `migrations/app/`: a baseline that records the schema you adopted in step 4.1, and `add_user_bio` with the single operation `Add column "bio" to "User"`. `db migrate` skips the baseline, because the marker already records that state, and applies `add_user_bio`. `--advance-ref db` moves the ref so the next plan chains correctly, and `db verify` reports that marker and schema match the contract. - -Restart the app: the Prisma ORM 8 route returns users with `bio`, and the Prisma ORM 7 route keeps working untouched, because its client doesn't know about the new column. Additive changes like nullable columns are safe next to legacy Prisma ORM 7 code. Be careful with renames or drops of columns that Prisma ORM 7 routes still read. - -## 5. Remove Prisma ORM 7 +Load the same pages as before you started, and try each write. **Expected result:** the pages show the same data as on Prisma ORM 6 or 7, and `npx tsc --noEmit` passes with no file importing `@prisma/client` or the generated client. -Migrate the remaining routes as in phase 3. For `posts` here, that means swapping `prisma.post.findMany(...)` for `db.orm.public.Post.include("author").all()` and `prisma.post.create({ data })` for `db.orm.public.Post.create(data)`. - -When nothing imports `generated/prisma` anymore, remove Prisma ORM 7: - -```npm -npm uninstall @prisma/prisma7 @prisma/client @prisma/adapter-pg -``` +Then search the code `tsc` does not check, such as views, for the two Prisma ORM 6 and 7 habits that fail only at runtime: ```bash -rm prisma7.config.ts -rm -r prisma generated/prisma +grep -rn "_count\|toISOString" views src ``` -Then delete the `prisma7:*` scripts from `package.json` and drop `generated/prisma/**/*.ts` from the `include` array in `tsconfig.json`. +Each match is a place that still reads `_count` or calls a `Date` method on a field that is now a string. + +## 6. Remove Prisma ORM 6 or 7 -Verify the end state: +When no file imports `@prisma/client` or the generated client, remove them and the driver adapter: ```npm -npx tsc --noEmit -npx prisma db verify +npm uninstall @prisma/client @prisma/adapter-pg ``` -Start the app and run a query against every route. The application now runs entirely on Prisma ORM 8, with schema changes managed by `prisma migration plan` and `prisma db migrate`. +Then delete the generated Prisma ORM 7 client folder, such as `generated/prisma`, and any seed script that still imports `@prisma/client`. `npm uninstall` leaves a generated Prisma ORM 6 client behind in `node_modules/.prisma`, where code can still import it without an error until the next clean install. Delete it too: -:::note - -Prisma ORM 7's `_prisma_migrations` table remains in the database. It is inert: Prisma ORM 8 leaves it out of `db verify`, `db update` and `contract infer`, and you can drop it whenever you like. +```bash +rm -rf node_modules/.prisma +``` -::: +**Check:** `npm run build` passes, and `npx prisma db verify` reports that the database matches the contract. ## Next steps -- [How migrations work in Prisma ORM](/orm/migrations/how-migrations-work): the day-to-day `contract emit` → `migration plan` → `migrate` loop for schema changes -- [Contract authoring](/orm/contract-authoring/psl-syntax): the full PSL syntax for evolving `contract.prisma` -- [Prisma ORM CLI reference](/cli): every command used in this guide +- [How migrations work](/orm/migrations/how-migrations-work): the day-to-day `contract emit`, `migration plan` and `db migrate` loop. +- [ORM client reference](/orm/reference/orm-client): every Prisma 8 query method. +- [Deploy an existing app on Prisma Compute](/guides/compute/deploy-existing-app): host the upgraded app, with a Prisma Postgres database for each branch. diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/v1.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/v1.mdx index 7b044a7d4f6..8efb196c576 100644 --- a/apps/docs/content/docs/guides/upgrade-prisma-orm/v1.mdx +++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/v1.mdx @@ -7,7 +7,7 @@ metaDescription: 'Upgrading your project from Prisma 1 to Prisma ORM 2' --- -This guide covers migrating your project from Prisma 1 to Prisma ORM 7, the last release built on the `schema.prisma` workflow. Once you are on Prisma ORM 7, continue with the [Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql). The migration involves significant architectural changes, so plan it and test it in a separate environment before touching production. +This guide covers migrating your project from Prisma 1 to Prisma ORM 7, the last release built on the `schema.prisma` workflow. Once you are on Prisma ORM 7, continue with the [Prisma 8 upgrade guide](/guides/upgrade-prisma-orm). The migration involves significant architectural changes, so plan it and test it in a separate environment before touching production. ## Before you begin @@ -358,7 +358,7 @@ This tool helps with: ## Next Steps -Your project now runs on Prisma ORM 7. To move to Prisma ORM 8, a [release candidate](/orm/release-status), follow the [Prisma ORM 7 to 8 guide](/guides/upgrade-prisma-orm/postgresql) (or the [MongoDB version](/guides/upgrade-prisma-orm/mongodb)). +Your project now runs on Prisma ORM 7. To move to Prisma ORM 8, a [release candidate](/orm/release-status), follow the [Prisma 8 upgrade guide](/guides/upgrade-prisma-orm). - [Prisma ORM Documentation](/orm/v7) - [Prisma Schema Reference](/orm/v7/reference/prisma-schema-reference) diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/v7.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/v7.mdx index 19ddc842b13..fbeaf53fc15 100644 --- a/apps/docs/content/docs/guides/upgrade-prisma-orm/v7.mdx +++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/v7.mdx @@ -1,6 +1,6 @@ --- title: Upgrade to v7 -description: Guide for upgrading to Prisma ORM v7 +description: 'Use when an app on Prisma ORM 6 or earlier is moving to Prisma ORM 7 and staying there; to go to Prisma 8, start at Upgrade to Prisma 8' url: /guides/upgrade-prisma-orm/v7 metaTitle: 'Upgrade to Prisma ORM 7' metaDescription: 'Guide on how to upgrade to Prisma ORM 7' @@ -9,9 +9,9 @@ metaDescription: 'Guide on how to upgrade to Prisma ORM 7' 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. -:::note[Upgrading to Prisma ORM 8?] +:::note[Not for an upgrade to Prisma 8] -Prisma ORM 8 is a [release candidate](/orm/release-status). If you are moving a Prisma ORM 7 project to Prisma ORM 8, use the [PostgreSQL](/guides/upgrade-prisma-orm/postgresql) or [MongoDB](/guides/upgrade-prisma-orm/mongodb) upgrade guide instead. +This guide is for apps staying on Prisma ORM 7. To go to Prisma 8, a [release candidate](/orm/release-status), see [Upgrade to Prisma 8](/guides/upgrade-prisma-orm). On PostgreSQL, a Prisma ORM 6 app does not need to pass through Prisma ORM 7 first. ::: diff --git a/apps/docs/content/docs/guides/v7/meta.json b/apps/docs/content/docs/guides/v7/meta.json index 3f2756d741e..7af2d2da5b5 100644 --- a/apps/docs/content/docs/guides/v7/meta.json +++ b/apps/docs/content/docs/guides/v7/meta.json @@ -10,7 +10,7 @@ "integrations", "authentication", "---Upgrade Prisma ORM---", - "[Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql)", + "[Upgrade to Prisma 8](/guides/upgrade-prisma-orm)", "[Prisma ORM 6 to 8 (MongoDB)](/guides/upgrade-prisma-orm/mongodb)" ] } diff --git a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx index 337296a2dd9..6d1a4bab09e 100644 --- a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx +++ b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx @@ -8,13 +8,13 @@ metaDescription: 'A lookup table from Prisma ORM 7 to Prisma ORM 8: schema attri If you know Prisma ORM 7, this page tells you what each thing you already use is called in Prisma ORM 8. Two renamed things to know before the tables: the schema file is now called the contract (the same file, renamed), and generating the client types is now called `emit`. This page is a lookup table, not a tutorial: one table each for the schema, the command-line tool, and the query API, and a final section on what is missing. -To move a running application, follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql) instead. It runs both versions side by side against the same database and moves one part of the app at a time. To decide whether to move at all, see [Release status](/orm/release-status). +To move a running application, follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql-incremental) instead. It runs both versions side by side against the same database and moves one part of the app at a time. To decide whether to move at all, see [Release status](/orm/release-status). All examples use PostgreSQL. ## Before you start -If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, do not run the new-project commands further down in that project, because `npm install prisma` installs version 8 in place of the version 7 command-line tool. Follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql) instead. It runs both versions side by side against your existing database without changing its data, and ends with Prisma ORM 8 managing its migrations. +If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, do not run the new-project commands further down in that project, because `npm install prisma` installs version 8 in place of the version 7 command-line tool. Follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql-incremental) instead. It runs both versions side by side against your existing database without changing its data, and ends with Prisma ORM 8 managing its migrations. On PostgreSQL, the following command moves Prisma ORM 7 to the `prisma7` command and `prisma7.config.ts`, and sets up Prisma ORM 8 to read your `schema.prisma` as its contract: @@ -22,7 +22,7 @@ On PostgreSQL, the following command moves Prisma ORM 7 to the `prisma7` command npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma ``` -It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with [phase 3 of the guide](/guides/upgrade-prisma-orm/postgresql#3-migrate-one-route), moving routes one at a time to the client in `src/prisma/db.ts`. Prisma ORM 7 keeps owning your migrations until the guide's [phase 4](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership), where Prisma ORM 8 takes them over. Phase 4 needs a contract file written for Prisma ORM 8. Before you start it, create one with the guide's steps 2.3 to 2.5, and set `contract` in `prisma.config.ts` to that file's path. +It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with [phase 3 of the guide](/guides/upgrade-prisma-orm/postgresql-incremental#3-migrate-one-route), moving routes one at a time to the client in `src/prisma/db.ts`. Prisma ORM 7 keeps owning your migrations until the guide's [phase 4](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership), where Prisma ORM 8 takes them over. Phase 4 needs a contract file written for Prisma ORM 8. Before you start it, create one with the guide's steps 2.3 to 2.5, and set `contract` in `prisma.config.ts` to that file's path. To set up Prisma ORM 8 in a new project, install `prisma` and `@prisma/orm-postgres`, then run `orm init`: @@ -179,18 +179,18 @@ The Prisma ORM 8 command-line tool groups commands by what they act on: `contrac | `prisma migrate dev` | `prisma db update`, or `prisma migration plan` then `prisma db migrate` | see the paragraph below the table | | `prisma migrate deploy` | `prisma db migrate` | applies the migration files in your repository | | `prisma migrate status` | `prisma migration status` | reports which migrations the database has applied | -| `prisma db push` | `prisma db init` the first time, on an empty database; `prisma db update` after that | `db init` creates the tables; `db update` changes existing tables to match the contract. For a database that already has your Prisma ORM 7 tables, run neither; see [step 4 of the migration guide](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership). See [`db update`](/cli/db-update) | +| `prisma db push` | `prisma db init` the first time, on an empty database; `prisma db update` after that | `db init` creates the tables; `db update` changes existing tables to match the contract. For a database that already has your Prisma ORM 7 tables, run neither; see [step 4 of the migration guide](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership). See [`db update`](/cli/db-update) | | `prisma db pull` | `prisma contract infer` | writes a first draft of a contract from an existing database | | `prisma migrate diff` | `prisma db update --dry-run` to see what would change in the database, or `prisma migration show ` to print what a migration file does | `` is a folder name under `migrations/app/`, for example `20260911T1030_add_bio`. To diff two migrations into a new migration file, `prisma migration plan --from --to ` | | `prisma migrate resolve --applied` | see [Rollbacks and recovery](/orm/migrations/rollbacks-and-recovery) | for a migration that failed half way | -| `prisma migrate resolve` for a database that already matches your schema | [step 4 of the migration guide](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) | the guide records which contract the database matches, both in the database and in your repository. Follow it rather than running the commands by hand | +| `prisma migrate resolve` for a database that already matches your schema | [step 4 of the migration guide](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership) | the guide records which contract the database matches, both in the database and in your repository. Follow it rather than running the commands by hand | | `prisma migrate reset` | `prisma db update` | Prisma ORM 8 never resets a database. `db update` moves a database whose migration history does not need to be kept to your contract, and asks before it loses data. A database that changes only through migrations, such as production, is moved with `prisma db migrate` | | `prisma db seed` | none | there is no seed command. Write a script that imports `db` from `src/prisma/db.ts` and calls `.create(...)`, and run it the way you run any TypeScript file, for example `npx tsx src/prisma/seed.ts` | | `prisma studio` | none in the Prisma ORM 8 tool | run Studio from the Prisma ORM 7 tool, from a directory outside your project, with the connection string spelled out: `cd /tmp && npx prisma@7 studio --url "postgresql://user:password@localhost:5432/mydb"`. See [Studio with Prisma ORM](/studio/prisma-next) | | `prisma format` | `prisma contract format` | | | `prisma validate` | none | `prisma contract emit` fails if the contract is invalid, and `prisma db verify` checks it against the database | -If you type `prisma migrate dev`, `deploy`, `status`, `diff`, `reset` or `resolve` in the Prisma ORM 8 tool, it exits with code `2` and the error code `CLI.COMMAND_MOVED`, and its next action names the Prisma ORM 8 command to use. Until you hand your migrations to Prisma ORM 8, in [step 4 of the migration guide](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership), keep running `migrate dev`, `migrate deploy` and `migrate status` with the Prisma ORM 7 tool, which the guide installs as `prisma7`: for example, `npx prisma7 migrate dev`. +If you type `prisma migrate dev`, `deploy`, `status`, `diff`, `reset` or `resolve` in the Prisma ORM 8 tool, it exits with code `2` and the error code `CLI.COMMAND_MOVED`, and its next action names the Prisma ORM 8 command to use. Until you hand your migrations to Prisma ORM 8, in [step 4 of the migration guide](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership), keep running `migrate dev`, `migrate deploy` and `migrate status` with the Prisma ORM 7 tool, which the guide installs as `prisma7`: for example, `npx prisma7 migrate dev`. Day to day, the loop that replaces `prisma migrate dev` is: edit the contract, run `prisma contract emit`, then `prisma db update` to apply the change to your development database. `db update --dry-run` shows what it would change, and `db update` asks before it applies an operation that loses data. To rename a model or field and keep its data, pass `--rename :`. When you want a migration file to commit, run `prisma migration plan` instead of `db update`; it writes a folder under `migrations/app/` with a `migration.ts` you can read, edit, and commit. Then `prisma db migrate` applies it. See [Generating a migration](/orm/migrations/generating-a-migration). @@ -422,7 +422,7 @@ Also not available today: ## Where to go next -- [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql), the step-by-step migration for a running PostgreSQL application. +- [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql-incremental), the step-by-step migration for a running PostgreSQL application. - [Core concepts](/orm/core-concepts), for what a contract is and what `contract emit` does. - [ORM client reference](/orm/reference/orm-client), for every query method. - [Reading data](/orm/fundamentals/reading-data) and [Writing data](/orm/fundamentals/writing-data), for the query API in full. diff --git a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx index 56802d6a638..50b684844a5 100644 --- a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx +++ b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx @@ -62,7 +62,7 @@ export default definePrismaConfig({ `definePrismaConfig` holds the whole config: which contract file to use and how to reach your database. Your connection string is in `prisma.config.ts` now, and the contract has no `datasource` block. `npx prisma orm init` writes `.env.example`, and your `DATABASE_URL` goes in `.env`. `@prisma/orm-postgres/config` exports `defineConfig`, which the example renames to `ormConfig` on import. The packages are `@prisma/orm-postgres` for PostgreSQL, `@prisma/orm-sqlite` for SQLite, and `@prisma/orm-mongo` for MongoDB. The examples here use PostgreSQL. -To start a new project, run `npm create prisma@latest -- my-app`. To add Prisma ORM 8 to a project that has no Prisma ORM at all, run `npx prisma orm init`. If you already have a Prisma ORM 7 `schema.prisma`, follow the [PostgreSQL upgrade guide](/guides/upgrade-prisma-orm/postgresql) instead, and [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) lists what changed. Both `npm create prisma@latest` and `npx prisma orm init` write `prisma.config.ts`, the contract file, and `src/prisma/db.ts`, and install the database package. +To start a new project, run `npm create prisma@latest -- my-app`. To add Prisma ORM 8 to a project that has no Prisma ORM at all, run `npx prisma orm init`. If you already have a Prisma ORM 7 `schema.prisma`, follow [Upgrade to Prisma 8](/guides/upgrade-prisma-orm) instead, and [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) lists what changed. Both `npm create prisma@latest` and `npx prisma orm init` write `prisma.config.ts`, the contract file, and `src/prisma/db.ts`, and install the database package. The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. You can also split a PSL contract across several files by setting `contract` to a glob such as `./src/prisma/**/*.prisma`, as [Configuration](/cli/configuration#split-the-schema-across-several-files) shows. Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features. For example, `@prisma/orm-extension-pgvector` adds vector columns, which it stores with pgvector, a PostgreSQL extension. diff --git a/apps/docs/content/docs/orm/core-concepts.mdx b/apps/docs/content/docs/orm/core-concepts.mdx index bebb04afc33..0b0e0ceb722 100644 --- a/apps/docs/content/docs/orm/core-concepts.mdx +++ b/apps/docs/content/docs/orm/core-concepts.mdx @@ -90,7 +90,7 @@ npx prisma db verify --db "$DATABASE_URL" :::note[Adopting an existing database] -If Prisma ORM 7 still runs migrations on the database, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) in the upgrade guide, which runs `db sign` at the right point. For any other database you did not create with Prisma ORM 8, emit your contract and run `db sign` before any other `db` or `migration` command, as [Adopting an existing database](#adopting-an-existing-database) explains. +If Prisma ORM 7 still runs migrations on the database, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership) in the upgrade guide, which runs `db sign` at the right point. For any other database you did not create with Prisma ORM 8, emit your contract and run `db sign` before any other `db` or `migration` command, as [Adopting an existing database](#adopting-an-existing-database) explains. ::: @@ -186,7 +186,7 @@ Other refs, such as `production` or `staging`, name the contract hash an environ ### Adopting an existing database -If Prisma ORM 7 still runs migrations on the database, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) in the upgrade guide, which runs `db sign` at the right point. For any other database you did not create with Prisma ORM 8, follow the steps below. +If Prisma ORM 7 still runs migrations on the database, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership) in the upgrade guide, which runs `db sign` at the right point. For any other database you did not create with Prisma ORM 8, follow the steps below. What Prisma ORM 7 called baselining, marking an existing database as already migrated, is `db sign` in Prisma ORM 8. The order of commands matters. Write the contract ([`contract infer`](/cli/contract-infer) gives you a draft to review), emit it, and sign the database before you plan anything: diff --git a/apps/docs/content/docs/orm/index.mdx b/apps/docs/content/docs/orm/index.mdx index 03dcbd47cde..2ea602b3f1a 100644 --- a/apps/docs/content/docs/orm/index.mdx +++ b/apps/docs/content/docs/orm/index.mdx @@ -70,8 +70,8 @@ Pick the page that matches where you are starting from. Each page uses PostgreSQ }> Write the contract from the tables you have, then make your first change to the tables as a migration. - }> - Install Prisma ORM 8 next to Prisma ORM 7 in the same app, against the same database, and move one part of the app at a time. + }> + Upgrade in one pass, or run Prisma ORM 7 and Prisma 8 side by side and move one route at a time. diff --git a/apps/docs/content/docs/orm/meta.json b/apps/docs/content/docs/orm/meta.json index ad71f8a512f..ece0e43a247 100644 --- a/apps/docs/content/docs/orm/meta.json +++ b/apps/docs/content/docs/orm/meta.json @@ -11,7 +11,7 @@ "supported-databases", "supported-versions", "coming-from-prisma-orm-7", - "[Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql)", + "[Upgrade to Prisma 8](/guides/upgrade-prisma-orm)", "[Prisma ORM 6 to 8 (MongoDB)](/guides/upgrade-prisma-orm/mongodb)", "---Data Modeling---", "...data-modeling", diff --git a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx index d2acd86750e..96047a519b6 100644 --- a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx +++ b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx @@ -127,7 +127,7 @@ MongoDB does not give you that clean slate, because a run there is not one trans The error's `why` says which of these happened, and its next actions give two ways back that do not reset the database: `db update` for a database whose migration history does not need to be kept, and new migrations for a database that changes only through migrations, such as production. Never reset the database. [Drift](/orm/migrations/rollbacks-and-recovery#drift-when-the-database-isnt-where-migrations-left-it) walks through both. -A database that already had tables gets its marker from `npx prisma db sign`, so `db migrate` refuses to run against it until a migration in your history ends at the signed state, as [The automatic baseline](/orm/migrations/generating-a-migration#the-automatic-baseline) shows. For a database Prisma ORM 7 migrated, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) in the upgrade guide. +A database that already had tables gets its marker from `npx prisma db sign`, so `db migrate` refuses to run against it until a migration in your history ends at the signed state, as [The automatic baseline](/orm/migrations/generating-a-migration#the-automatic-baseline) shows. For a database Prisma ORM 7 migrated, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership) in the upgrade guide. ## Development vs. production diff --git a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx index 16b69121614..017e3ebd849 100644 --- a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx +++ b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx @@ -71,7 +71,7 @@ Read the rest of that output closely, because it tells you what was planned and The `No db ref set` line is telling you that nothing in this project records which contract state your database matches, so `migration plan` assumed an empty database and planned from there. That assumption is right for a new project. If you already have a database, tell Prisma ORM what is in it before you plan anything, and which command does that depends on what the database holds: -- If Prisma ORM 7 migrated the database, follow the steps in the [upgrade guide](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) first. +- If Prisma ORM 7 migrated the database, follow the steps in the [upgrade guide](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership) first. - If the database is empty, you need nothing: `npx prisma db migrate` creates the tables for you, though it does not create the database itself. - If every table in the database already matches your contract, run [`npx prisma db sign`](/cli/db-sign) and then read [The automatic baseline](#the-automatic-baseline) below. `db sign` checks the tables against your contract and then writes the [marker](/orm/migrations/the-migration-graph#terms-used-on-this-page), which is the record in the database of which contract state it matches. - If the database has only some of your tables, run [`npx prisma db init`](/cli/db-init). It adds what is missing and nothing else, and it stops if matching your contract would need a change that could lose data, such as dropping a column. diff --git a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx index 5d92749c50b..4557bd338a0 100644 --- a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx +++ b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx @@ -170,7 +170,7 @@ If you used Prisma ORM 7, these commands replace its migrate commands: - `migrate deploy` becomes `db migrate`. - `migrate reset` has no equivalent, because Prisma ORM 8 never resets a database. On a database whose migration history does not need to be kept, such as a development database, [`npx prisma db update`](/cli/db-update) moves it to your contract and asks before it loses data. A database that changes only through migrations, such as production, is moved with `npx prisma db migrate`. Neither runs a seed script, so run yours afterwards. - `migrate diff` becomes `migration show `, which prints one migration, or `db update --dry-run`, which shows the operations that would make a database match the contract. -- Baselining, marking an existing database as already migrated, is now [`npx prisma db sign`](/cli/db-sign), which checks that the tables match your contract before it writes the marker. For a database Prisma ORM 7 migrated, follow [Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership). +- Baselining, marking an existing database as already migrated, is now [`npx prisma db sign`](/cli/db-sign), which checks that the tables match your contract before it writes the marker. For a database Prisma ORM 7 migrated, follow [Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership). [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7#commands) has the full table, including `migrate resolve`. diff --git a/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx b/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx index a4f31b2551c..55faed0289b 100644 --- a/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx +++ b/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx @@ -127,7 +127,7 @@ When a change was made by hand, you have to decide whether you want to keep it, - **Undo it.** Change the tables back by hand until `npx prisma db verify --schema-only --strict` passes. The marker never changed, so there is nothing else you need to put right. - **Keep it.** Add the change to your contract, run `npx prisma contract emit`, then plan and apply a migration as usual. `db migrate` skips the change you already made there. -[`npx prisma db sign`](/cli/db-sign) fixes neither kind of drift, because it is for [baselining](/orm/migrations/the-migration-graph#baselines) a database that has no marker at all but whose tables already match your contract. For a database that Prisma ORM 7 migrated, follow [step 4 of the upgrade guide](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) instead. +[`npx prisma db sign`](/cli/db-sign) fixes neither kind of drift, because it is for [baselining](/orm/migrations/the-migration-graph#baselines) a database that has no marker at all but whose tables already match your contract. For a database that Prisma ORM 7 migrated, follow [step 4 of the upgrade guide](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership) instead. :::note[What's early] diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx index 0820418708e..7a2a28c6754 100644 --- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx +++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx @@ -184,7 +184,7 @@ The word "baseline" turns up in several different places, and which one you are - **A label in command output.** `(baseline)` in `migration plan` output means the migration starts from an empty database. - **A Prisma ORM 7 task.** What Prisma ORM 7 called baselining, marking an existing database as already migrated, is `npx prisma db sign` in Prisma ORM 8. -Reach for [`npx prisma db sign`](/cli/db-sign) when a database has no marker and its tables already match your contract. It checks the tables, writes the marker, and points the `db` ref at the signed contract. Signing alone is not enough to start migrating, though, because `db migrate` refuses a signed database until a migration in your history ends at the signed state. Your next `migration plan` writes that one for you, because the `db` ref now names the signed state; [The automatic baseline](/orm/migrations/generating-a-migration#the-automatic-baseline) explains what it writes. For a database Prisma ORM 7 migrated, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) instead. +Reach for [`npx prisma db sign`](/cli/db-sign) when a database has no marker and its tables already match your contract. It checks the tables, writes the marker, and points the `db` ref at the signed contract. Signing alone is not enough to start migrating, though, because `db migrate` refuses a signed database until a migration in your history ends at the signed state. Your next `migration plan` writes that one for you, because the `db` ref now names the signed state; [The automatic baseline](/orm/migrations/generating-a-migration#the-automatic-baseline) explains what it writes. For a database Prisma ORM 7 migrated, follow [Transfer migration ownership](/guides/upgrade-prisma-orm/postgresql-incremental#4-transfer-migration-ownership) instead. ## Database-specific details diff --git a/apps/docs/content/docs/orm/reference/error-reference.mdx b/apps/docs/content/docs/orm/reference/error-reference.mdx index 48e8bec004a..23bb35ebe2d 100644 --- a/apps/docs/content/docs/orm/reference/error-reference.mdx +++ b/apps/docs/content/docs/orm/reference/error-reference.mdx @@ -1391,7 +1391,7 @@ Statistics execution was requested for a Mongo command that does not expose affe ### RUNTIME.MULTIPLE_ORM_COPIES [#RUNTIME.MULTIPLE_ORM_COPIES] -Retired. 8.0.0-rc.22 raised this when Prisma ORM was loaded from more than one folder, and commands and clients refused to start. Later releases removed the check, because a host that loads the ORM in two module instances, such as Prisma Composer's boot wrapper beside the application bundle, cannot satisfy it. Nothing raises this code. +Retired: until 8.0.0-rc.22, Prisma ORM raised this when it was loaded from more than one folder, and commands and clients refused to start. Later releases removed the check, because a host that loads the ORM in two module instances, such as Prisma Composer's boot wrapper beside the application bundle, cannot satisfy it. Nothing raises this code. A second copy still breaks values and registries that cross between copies. Install the same version of every `@prisma/orm-*` package and a `prisma` CLI that runs it. `npm ls @prisma/orm-framework`, `pnpm why @prisma/orm-framework` or `bun why @prisma/orm-framework` shows which package brought each copy. diff --git a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx index 1ce86436193..96e89858137 100644 --- a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx +++ b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx @@ -88,7 +88,7 @@ export const contract = contractFromJson(contractJson); export const db = postgres({ contract, url: process.env.DATABASE_URL! }); ``` -These examples assume the file is beside `contract.json` in `src/prisma/`, so from anywhere else, change the relative paths. Write `./contract.d` exactly like that, with no extension. It resolves under `preserve` or `esnext` with `bundler`, the settings `prisma orm init` writes, and under `nodenext` as CommonJS; under `nodenext`, `node18`, or `node20` as ES modules it does not, and the upgrade guide covers that case. The line `import contractJson from './contract.json' with { type: 'json' }` needs Node.js 22.18 or newer and TypeScript 5.9 or newer. In `tsconfig.json` it needs `resolveJsonModule: true` and one of these `module` settings, each with its `moduleResolution`: `preserve` with `bundler`, `esnext` with `bundler`, or `nodenext` with `nodenext`. `node18` and `node20` also work, with `moduleResolution` left unset. `prisma orm init` writes `preserve` and `bundler` into new projects. When `module` is `nodenext` and `package.json` has no `"type": "module"`, TypeScript treats the file as CommonJS, and there the import is `import contractJson from './contract.json';` with no `with` part. The [Prisma ORM 7 to 8 upgrade guide](/guides/upgrade-prisma-orm/postgresql#26-set-up-tsconfigjson-for-the-prisma-orm-8-client) walks through which setting fits which kind of project. TypeScript types every `process.env` value as possibly undefined, so the examples write `!` after it, the same way `prisma orm init` does. +These examples assume the file is beside `contract.json` in `src/prisma/`, so from anywhere else, change the relative paths. Write `./contract.d` exactly like that, with no extension. It resolves under `preserve` or `esnext` with `bundler`, the settings `prisma orm init` writes, and under `nodenext` as CommonJS; under `nodenext`, `node18`, or `node20` as ES modules it does not, and the upgrade guide covers that case. The line `import contractJson from './contract.json' with { type: 'json' }` needs Node.js 22.18 or newer and TypeScript 5.9 or newer. In `tsconfig.json` it needs `resolveJsonModule: true` and one of these `module` settings, each with its `moduleResolution`: `preserve` with `bundler`, `esnext` with `bundler`, or `nodenext` with `nodenext`. `node18` and `node20` also work, with `moduleResolution` left unset. `prisma orm init` writes `preserve` and `bundler` into new projects. When `module` is `nodenext` and `package.json` has no `"type": "module"`, TypeScript treats the file as CommonJS, and there the import is `import contractJson from './contract.json';` with no `with` part. The [Prisma ORM 7 to 8 upgrade guide](/guides/upgrade-prisma-orm/postgresql-incremental#26-set-up-tsconfigjson-for-the-prisma-orm-8-client) walks through which setting fits which kind of project. TypeScript types every `process.env` value as possibly undefined, so the examples write `!` after it, the same way `prisma orm init` does. ##### Bind to an existing `pg` pool diff --git a/apps/docs/content/docs/orm/release-status.mdx b/apps/docs/content/docs/orm/release-status.mdx index 64ad0cab4a6..312fc54147a 100644 --- a/apps/docs/content/docs/orm/release-status.mdx +++ b/apps/docs/content/docs/orm/release-status.mdx @@ -41,7 +41,7 @@ The two packages have different version numbers, and that is normal: they are re | Package | `latest` on 6 November 2026 | | --- | --- | -| `prisma` (the command-line tool) | `8.0.0-rc.32` | +| `prisma` (the command-line tool) | `8.0.0-rc.33` | | `@prisma/orm-postgres` (the library) | `8.0.0-rc.23` | | `@prisma/orm-mongo` (the MongoDB library) | `8.0.0-rc.23` | @@ -76,5 +76,5 @@ The Prisma ORM 7 documentation is at [/orm/v7](/orm/v7), its setup guides at [/v ## Next steps -- To move an existing Prisma ORM 7 app, follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql). It runs both versions side by side and moves one part of the app at a time. +- To move an existing Prisma ORM 7 app, follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql-incremental). It runs both versions side by side and moves one part of the app at a time. - To see what each Prisma ORM 7 command and query is called now, and what is not available yet, see [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7). diff --git a/apps/docs/content/docs/orm/supported-versions.mdx b/apps/docs/content/docs/orm/supported-versions.mdx index 1118847b97e..ebcfd16d111 100644 --- a/apps/docs/content/docs/orm/supported-versions.mdx +++ b/apps/docs/content/docs/orm/supported-versions.mdx @@ -45,7 +45,7 @@ Without it, reading such a field, or writing a row whose default generates the c Prisma ORM does not require TypeScript, so a plain JavaScript project works, but when TypeScript is present it must be 5.9 or newer. -The `tsconfig.json` settings depend on how you run the app. An app that runs through `tsx`, or that a bundler such as Vite, Next.js, or esbuild builds, uses `"module": "preserve"` and `"moduleResolution": "bundler"`, which is what `npx prisma orm init` writes, along with `"strict": true` and `"resolveJsonModule": true`. If your project already has a `tsconfig.json`, `orm init` sets `module`, `moduleResolution`, and `resolveJsonModule` to those values, adds `node` to `types`, and keeps your other settings. An app that compiles with `tsc` and runs the output with `node` uses `"module": "nodenext"` and `"moduleResolution": "nodenext"` instead, so change them back after `orm init`. [Set up tsconfig.json](/guides/upgrade-prisma-orm/postgresql#26-set-up-tsconfigjson-for-the-prisma-orm-8-client) covers each way of running an app, and it applies to MongoDB projects too. +The `tsconfig.json` settings depend on how you run the app. An app that runs through `tsx`, or that a bundler such as Vite, Next.js, or esbuild builds, uses `"module": "preserve"` and `"moduleResolution": "bundler"`, which is what `npx prisma orm init` writes, along with `"strict": true` and `"resolveJsonModule": true`. If your project already has a `tsconfig.json`, `orm init` sets `module`, `moduleResolution`, and `resolveJsonModule` to those values, adds `node` to `types`, and keeps your other settings. An app that compiles with `tsc` and runs the output with `node` uses `"module": "nodenext"` and `"moduleResolution": "nodenext"` instead, so change them back after `orm init`. [Set up tsconfig.json](/guides/upgrade-prisma-orm/postgresql-incremental#26-set-up-tsconfigjson-for-the-prisma-orm-8-client) covers each way of running an app, and it applies to MongoDB projects too. ## ES modules only diff --git a/apps/docs/scripts/lint-versions.ts b/apps/docs/scripts/lint-versions.ts index 7083b112eb7..f01dc835837 100644 --- a/apps/docs/scripts/lint-versions.ts +++ b/apps/docs/scripts/lint-versions.ts @@ -7,6 +7,8 @@ * the one in the `dependencies` of `prisma@latest`. A version mentioned as history ("since 8.0.0-rc.10", * an "Added in" column) is allowed to be older, and so is a pin to an older * major line, such as a `prisma@6.x` install step for readers staying on 6. + * A page whose source contains `lint-versions-ignore-file` is skipped, for pins that + * must follow something other than npm, such as the Console's Compute setup. * * Usage: npx tsx scripts/lint-versions.ts [--fix] */ @@ -18,6 +20,7 @@ import { fetchVersions, isVersionedTree, lintVersions, rewriteVersions } from ". const __dirname = path.dirname(fileURLToPath(import.meta.url)); const DOCS_DIR = path.join(__dirname, "../content/docs"); +const IGNORE_MARKER = "lint-versions-ignore-file"; function findMdxFiles(dir: string, fileList: string[] = []): string[] { for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { @@ -35,7 +38,12 @@ async function main() { }); const relativePath = (file: string) => path.relative(DOCS_DIR, file).split(path.sep).join("/"); - const files = findMdxFiles(DOCS_DIR).filter((file) => !isVersionedTree(relativePath(file))); + // Pages holding IGNORE_MARKER pin something other than npm latest, such as the Console's Compute setup. + // They are listed on every run, so the opt-out stays visible in CI output. + const current = findMdxFiles(DOCS_DIR).filter((file) => !isVersionedTree(relativePath(file))); + const ignored = current.filter((file) => fs.readFileSync(file, "utf8").includes(IGNORE_MARKER)); + const files = current.filter((file) => !ignored.includes(file)); + for (const file of ignored) console.log(`Skipped (${IGNORE_MARKER}): ${relativePath(file)}`); if (process.argv.includes("--fix")) { for (const file of files) { const content = fs.readFileSync(file, "utf8"); diff --git a/apps/docs/vercel.json b/apps/docs/vercel.json index 399facf4b7e..527131f55e0 100644 --- a/apps/docs/vercel.json +++ b/apps/docs/vercel.json @@ -5265,11 +5265,6 @@ "destination": "/docs/orm/v7/prisma-client/using-raw-sql/typedsql", "permanent": true }, - { - "source": "/docs/guides/upgrade-prisma-orm", - "destination": "/docs/guides/upgrade-prisma-orm/v7", - "permanent": true - }, { "source": "/docs/reference/api-reference/connection-management", "destination": "/docs/orm/v7/prisma-client/setup-and-configuration/databases-connections/connection-management",