From 95dc2ba382eca5f8e455c50f9a53c9b44db12e27 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 30 Sep 2026 00:11:22 +0200 Subject: [PATCH 1/7] docs(orm): group the Quickstart sidebar by the reader's starting point The Getting Started > Prisma ORM sidebar now has one Quickstart group with four entries: I'm creating a new app, I have an app but no database yet, I have a database already, and I have a Prisma 7 app. No URL changes. Adds the page pair for an app with an empty database, for PostgreSQL and MongoDB. Extends the PostgreSQL page for an existing database with what contract infer reads, what db sign checks, and the second migration. Each page in a pair names its database and links its twin. The Prisma ORM introduction shows the four starting points as cards, and link text across the docs uses the new page titles. Every command and output block on the new and extended pages comes from a run against prisma 8.0.0-rc.19 and the ORM packages at 8.0.0-rc.13. Agent: nimue-20 Signed-off-by: willbot Signed-off-by: Will Madden Co-Authored-By: Claude Fable 5.1 --- .../content/docs/(index)/getting-started.mdx | 4 +- .../add-to-existing-project/mongodb.mdx | 8 +- .../add-to-existing-project/postgresql.mdx | 218 +++++++++++-- .../docs/(index)/prisma-orm/create-prisma.mdx | 4 +- .../docs/(index)/prisma-orm/from-scratch.mdx | 4 +- .../content/docs/(index)/prisma-orm/index.mdx | 19 +- .../content/docs/(index)/prisma-orm/meta.json | 5 +- .../quickstart/existing-app/mongodb.mdx | 302 ++++++++++++++++++ .../quickstart/existing-app/postgresql.mdx | 290 +++++++++++++++++ .../(index)/prisma-orm/quickstart/meta.json | 8 +- .../(index)/prisma-orm/quickstart/mongodb.mdx | 8 +- .../prisma-orm/quickstart/postgresql.mdx | 6 +- .../(index)/prisma-postgres/from-the-cli.mdx | 2 +- .../import-from-existing-database-mysql.mdx | 2 +- .../prisma-postgres/quickstart/prisma-orm.mdx | 2 +- apps/docs/content/docs/cli/index.mdx | 2 +- apps/docs/content/docs/cli/orm-init.mdx | 2 +- .../guides/authentication/authjs/nextjs.mdx | 2 +- .../authentication/better-auth/astro.mdx | 2 +- .../authentication/better-auth/nextjs.mdx | 2 +- .../guides/authentication/clerk/astro.mdx | 2 +- .../guides/authentication/clerk/nextjs.mdx | 2 +- .../docs/guides/database/schema-changes.mdx | 2 +- apps/docs/content/docs/guides/index.mdx | 2 +- .../docs/guides/integrations/datadog.mdx | 2 +- .../content/docs/guides/integrations/deno.mdx | 2 +- .../docs/guides/integrations/embed-studio.mdx | 2 +- .../docs/guides/integrations/permit-io.mdx | 2 +- .../docs/guides/integrations/pgfence.mdx | 2 +- .../docs/guides/integrations/plasmic.mdx | 2 +- .../docs/guides/integrations/shopify.mdx | 2 +- .../content/docs/guides/making-guides.mdx | 2 +- .../content/docs/guides/postgres/flyio.mdx | 2 +- .../content/docs/guides/postgres/netlify.mdx | 2 +- .../switch-to-prisma-orm/from-sql-orms.mdx | 2 +- .../docs/orm/extensions/using-extensions.mdx | 4 +- .../authoring-custom-middleware.mdx | 2 +- .../orm/migrations/generating-a-migration.mdx | 2 +- .../orm/migrations/how-migrations-work.mdx | 2 +- .../content/docs/orm/supported-databases.mdx | 2 +- 40 files changed, 864 insertions(+), 70 deletions(-) create mode 100644 apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx create mode 100644 apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/postgresql.mdx diff --git a/apps/docs/content/docs/(index)/getting-started.mdx b/apps/docs/content/docs/(index)/getting-started.mdx index 4e926484c04..08fbeb4bd48 100644 --- a/apps/docs/content/docs/(index)/getting-started.mdx +++ b/apps/docs/content/docs/(index)/getting-started.mdx @@ -22,10 +22,10 @@ The [create-prisma reference](/prisma-orm/create-prisma) lists every template an }> The whole journey in one sitting: scaffold, Prisma Postgres, first query, and a Prisma Compute deploy. - }> + }> Create the app, run it against a local Prisma Postgres from Composer or your own PostgreSQL, and run the first query. - }> + }> Create the app, connect a MongoDB deployment, apply the first migration, and run the first query. diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx index b678f3e6a43..3a5f3e06fad 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx @@ -1,14 +1,16 @@ --- -title: MongoDB -description: Add Prisma ORM to an existing MongoDB project. +title: Add Prisma ORM to an existing MongoDB database +description: Add Prisma ORM to an app whose MongoDB database already has collections. url: /prisma-orm/add-to-existing-project/mongodb metaTitle: Add Prisma ORM to an existing MongoDB project metaDescription: Add Prisma ORM to an existing MongoDB project. --- +This page uses MongoDB. [Use PostgreSQL instead](/prisma-orm/add-to-existing-project/postgresql). + To add Prisma ORM to a project that already uses MongoDB, you will run `orm init`, describe the collections you want to work with, emit the generated artifacts, and run a couple of queries. -Use this path when you already have an application and database. Make sure the app can already reach its MongoDB deployment and runs on Node.js 22.18 or newer (on the 24 line, 24.11 or newer; Node.js 24 is recommended). If you want Prisma ORM to create a new app for you, use the [MongoDB quickstart](/prisma-orm/quickstart/mongodb). +Use this path when you already have an application and database. Make sure the app can already reach its MongoDB deployment and runs on Node.js 22.18 or newer (on the 24 line, 24.11 or newer; Node.js 24 is recommended). If your database has no collections yet, follow [Add Prisma ORM and MongoDB to an existing app](/prisma-orm/quickstart/existing-app/mongodb) instead. If you want Prisma ORM to create a new app for you, follow [Create a new app with MongoDB](/prisma-orm/quickstart/mongodb). :::note[Using Prisma ORM 7?] 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 652913bf0fd..e6565e10f47 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 @@ -1,14 +1,16 @@ --- -title: PostgreSQL -description: Add Prisma ORM to an existing PostgreSQL project. +title: Add Prisma ORM to an existing PostgreSQL database +description: Add Prisma ORM to an app whose PostgreSQL database already has tables. url: /prisma-orm/add-to-existing-project/postgresql metaTitle: Add Prisma ORM to an existing PostgreSQL project metaDescription: Add Prisma ORM to an existing PostgreSQL project. --- -To add Prisma ORM to a project that already uses PostgreSQL, you will run `orm init`, infer a contract from the live schema, sign the database, and run a couple of queries. +This page uses PostgreSQL. [Use MongoDB instead](/prisma-orm/add-to-existing-project/mongodb). -Use this path when you already have an application and database. Make sure the app can already reach its PostgreSQL database and runs on Node.js 22.18 or newer (on the 24 line, 24.11 or newer; Node.js 24 is recommended). If you want Prisma ORM to create a new app for you, use the [PostgreSQL quickstart](/prisma-orm/quickstart/postgresql). +On this page you add Prisma ORM to an app whose PostgreSQL database already has tables. The contract is the file that holds your models, and in Prisma ORM 7 it was `schema.prisma`. You run `orm init`, generate the contract from your tables, run two queries, and apply your first schema change. + +Use this path when you already have an application and database. Make sure the app can already reach its PostgreSQL database and runs on Node.js 22.18 or newer (on the 24 line, 24.11 or newer; Node.js 24 is recommended). If your database has no tables yet, follow [Add Prisma ORM and PostgreSQL to an existing app](/prisma-orm/quickstart/existing-app/postgresql) instead. If you want Prisma ORM to create a new app for you, follow [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). :::note[Using Prisma ORM 7?] @@ -40,7 +42,7 @@ This command is for a project that already exists: it preselects PostgreSQL, add `orm init` also changes the `module` settings in `tsconfig.json`, and adds `"type": "module"` to `package.json` when the file has no `"type"` field. If your app is CommonJS, follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you run the app again. The scripts in this guide run through `tsx`, which works in both kinds of project. -It also adds `prisma-8.md`, a short project-level reference your coding agent can read. It does not install agent skills; the Prisma ORM skill ships inside the `@prisma/orm-postgres` package your project installs. If you later run `prisma init` or `prisma skills sync`, Prisma writes skill files for coding agents into your repo. To stop that, pass `--skills=none` to [`init`](/cli/init) or set the [`skills.agents`](/cli/configuration#agent-skills) config field to `[]`; the next [`skills sync`](/cli/skills) removes any copies already written. +It also adds `prisma-8.md`, a short project-level reference your coding agent can read. It does not install agent skills; the Prisma ORM skill ships inside the `@prisma/orm-postgres` package your project installs. From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. The skills are instruction files for coding agents, and the line does not change what the command does. If you want the skills, [`npx prisma@latest init`](/cli/init) installs them, which also stops the line. The output on this page leaves the line out. If you later run `prisma init` or `prisma skills sync`, Prisma writes skill files for coding agents into your repo. To stop that, pass `--skills=none` to [`init`](/cli/init) or set the [`skills.agents`](/cli/configuration#agent-skills) config field to `[]`; the next [`skills sync`](/cli/skills) removes any copies already written. When Prisma ORM asks the remaining setup questions: @@ -82,7 +84,69 @@ Run: npx prisma contract infer --output ./src/prisma/contract.prisma ``` -The command writes a first draft of `src/prisma/contract.prisma`. +```text no-copy +✔ Connecting to database... +✔ Introspecting database schema... +│ database: postgres://****@127.0.0.1:54329/legacy + +✔ Contract written to src/prisma/contract.prisma +``` + +The command writes a first draft of `src/prisma/contract.prisma`. For a database with a `user` table and a `post` table, the draft looks like this: + +```prisma title="src/prisma/contract.prisma" +// use prisma-8 +// Contract inferred from the live database schema. Edit as needed, then run `prisma contract emit`. + +namespace public { + model User { + id Int @id(map: "user_pkey") @default(autoincrement()) + email String @unique(map: "user_email_key") + name String? + role String @default("member") + age Int? + createdAt Timestamptz @default(now()) @map("created_at") + posts Post[] + + @@check(expression: "(age >= 0)", map: "user_age_check") + @@map("user") + } + + model Post { + id Int @id(map: "post_pkey") @default(autoincrement()) + title VarChar(200) + published Boolean @default(false) + authorId Int @map("author_id") + author User @relation(fields: [authorId], references: [id], onDelete: Cascade, map: "post_author_id_fkey") + + @@index([authorId], map: "post_author_id_idx") + @@index([title], map: "post_published_idx", where: "published") + @@index(expression: "lower(title::text)", map: "post_title_lower_idx") + @@rls + @@map("post") + } + + policy_select post_read { + target = Post + roles = [public] + using = "published" + @@map("post_read") + } +} +``` + +`contract infer` reads these parts of the database and writes each one into the draft: + +| In the database | In the draft above | +| --- | --- | +| Primary keys and unique constraints | `@id`, `@unique` | +| Column defaults | `@default("member")`, `@default(now())` | +| Foreign keys, with what happens on delete | `@relation(..., onDelete: Cascade)` and the `posts` field | +| Check constraints | `@@check` | +| Indexes, including an index on part of a table and an index on an expression | the three `@@index` lines | +| Row-level security and its policies | `@@rls` and the `policy_select` block | + +`contract infer` reads only the PostgreSQL schema named `public`. It skips tables in any other schema and prints no message about them. Open that file and review it before you go on. This is the moment to clean up model names, keep only the tables you want Prisma ORM to know about first, and make the file easier to read. A model's table is the model name exactly as written, so a table such as `User` gets a model with no `@@map`, and a table such as `user` or `user_profile` gets `@@map` with its name. Keep those `@@map` lines when you rename a model, so the table stays the same. @@ -104,6 +168,14 @@ npx prisma contract emit This refreshes `src/prisma/contract.json` and `src/prisma/contract.d.ts` so the runtime and query APIs match the contract you just reviewed. +If the inferred contract has a policy, a check, or an index that contains SQL text, `contract emit` prints one warning for each, and still writes both files. Each warning starts like this: + +```text no-copy +(node:15169) [PN_EXACT_NAME_BODY_COMPARISON] Warning: check "user_age_check" uses map: with a SQL body. +``` + +These warnings are expected on a contract that `contract infer` wrote, and you do not need to change anything. + ## 6. Sign the database Record that the live database matches the emitted contract: @@ -112,7 +184,34 @@ Record that the live database matches the emitted contract: npx prisma db sign ``` -**Expected result:** `Database signed`. The command also stores the contract snapshot under `migrations/snapshots/` and points the `db` ref at it, so a later [migration plan](/cli/migration-plan) starts from the schema you just adopted instead of from an empty database. +```text no-copy +✔ Connecting to database... +✔ Verifying database schema... +✔ Signing database... +│ contract: src/prisma/contract.json +│ database: postgres://****@127.0.0.1:54329/legacy + +✔ Database signed + +from: none +to: 596586f61799d5b2585df874a00f8d6f12d73a522d2eefbcbec62dba4e9904a4 + +✔ Advanced ref "db" → 596586f61799d5b2585df874a00f8d6f12d73a522d2eefbcbec62dba4e9904a4 +``` + +Before it writes anything, `db sign` checks that the database has everything the contract declares. A table or a column that the database has and the contract does not declare is not a problem. When something the contract declares is missing from the database, `db sign` writes nothing and exits with code 4. For example, with a `phone` field in the `User` model and no `phone` column in the table: + +```text no-copy +✘ Schema issues +└─ ✘ missing: database/public/user/column:phone + +✘ [CONTRACT.SCHEMA_VERIFICATION_FAILED] Database schema does not satisfy contract (1 failure) + why: The live schema differs: missing: database/public/user/column:phone. +``` + +To fix it, remove from the contract what the database does not have, run `npx prisma contract emit`, and sign again. + +When the check passes, `db sign` stores a record in the database of which contract it matches. The record holds the hash of the contract, which is the long hexadecimal text after `to:` in the output. The command also writes two things into your project: a copy of the contract under `migrations/snapshots/`, and the `db` ref, which is the file `migrations/app/refs/db.json` and holds the same hash. A later [migration plan](/cli/migration-plan) reads them, so it starts from the tables you just adopted instead of from an empty database. Commit the `migrations/` directory. This step matters in two common cases: @@ -123,7 +222,7 @@ This step matters in two common cases: With the database signed, you can test the higher-level API first and confirm Prisma ORM is reading the existing schema correctly. -Create a `script.ts` file: +Create `script.ts` with the code below, which reads the `User` model from step 4. Use one of your own models and its fields in its place: ```typescript title="script.ts" import { db } from "./src/prisma/db"; @@ -151,11 +250,18 @@ Run it: npx tsx script.ts ``` +```text no-copy +[ + { id: 1, email: 'alice@example.com', name: 'Alice' }, + { id: 2, email: 'bob@example.com', name: 'Bob' } +] +``` + ## 8. Run a simple low-level query After the ORM example, this step shows the lower-level SQL builder against the same existing schema. -The SQL builder names the table, where the ORM API names the model. This example reads a table named `User`. If your model has `@@map("user")`, write `db.sql.public.user`. +The SQL builder names the table, where the ORM API names the model. This example reads the table `user`, which the `User` model in step 4 maps with `@@map("user")`. For a model without `@@map`, the table has the name of the model. Replace `script.ts` with this version: @@ -163,7 +269,7 @@ Replace `script.ts` with this version: import { db } from "./src/prisma/db"; async function main() { - const plan = db.sql.public.User + const plan = db.sql.public.user .select("id", "email", "name") .limit(2) .build(); @@ -186,25 +292,95 @@ Run it again: npx tsx script.ts ``` -## 9. Next steps +```text no-copy +[ + { id: 1, email: 'alice@example.com', name: 'Alice' }, + { id: 2, email: 'bob@example.com', name: 'Bob' } +] +``` + +## 9. Make your first schema change + +From here on, you change the database by changing the contract. Add a field to a model in `src/prisma/contract.prisma`. This example adds `phone` to the `User` model from step 4, so use a model and a field of your own: -When you change `src/prisma/contract.prisma`, emit the contract again: +```prisma title="src/prisma/contract.prisma" + model User { + id Int @id(map: "user_pkey") @default(autoincrement()) + email String @unique(map: "user_email_key") + name String? + phone String? // [!code ++] +``` + +Emit the contract again, then plan a migration. `migration plan` writes the difference between the new contract and the one that `db sign` recorded into a new directory under `migrations/app/`. `--name` sets the name of that directory. ```npm npx prisma contract emit +npx prisma migration plan --name add_user_phone +``` + +```text no-copy +│ contract: src/prisma/contract.json +│ migrations: migrations/app +│ name: add_user_phone + +✔ Planned baseline (10 operation(s)) + 1 operation(s) + +migrations/app/20260929T2130_baseline +├─ Create schema "public" +├─ Create table "post" +├─ Create table "user" +├─ Add unique constraint on "user" (email) +├─ Create index "post_author_id_idx" on "post" +├─ Create index "post_published_idx" on "post" +├─ Create index "post_title_lower_idx" on "post" +├─ Add foreign key "post_author_id_fkey" on "post" +├─ Enable row-level security on "post" +└─ Create RLS policy "post_read" on "post" +migrations/app/20260929T2131_add_user_phone +└─ Add column "phone" to "user" + +from: 596586f61799d5b2585df874a00f8d6f12d73a522d2eefbcbec62dba4e9904a4 +to: 4ef74b97c298402786f23bf299e17baba815e8d521bc90aaab59ab7de747c969 +baseline: migrations/app/20260929T2130_baseline +app space: migrations/app/20260929T2131_add_user_phone ``` -Use [db update](/cli/db-update) for a direct development update, or [migration plan](/cli/migration-plan) when you want a checked-in migration. +The output continues with a preview of the SQL. The first plan writes two directories. The baseline records the tables you adopted. It lists `Create table` operations, and the next command runs none of them on your database. The second directory is your change. Commit both directories. [The automatic baseline](/cli/migration-plan#the-automatic-baseline) explains when `migration plan` writes a baseline. -Put together, adopting the database and making a first schema change is this sequence: +Apply the migration: ```npm -npx prisma contract infer --output ./src/prisma/contract.prisma -npx prisma contract emit -npx prisma db sign -# edit src/prisma/contract.prisma -npx prisma contract emit -npx prisma migration plan --name +npx prisma db migrate --advance-ref db +``` + +```text no-copy +✔ Running migration plan across spaces +│ migrations: migrations +│ database: postgres://****@127.0.0.1:54329/legacy + +✔ Applied 1 migration(s) (1 operation(s)) across 1 contract space(s) + +App space +├─ Add column "phone" to "user" +└─ marker 4ef74b97c298402786f23bf299e17baba815e8d521bc90aaab59ab7de747c969 + +✔ Advanced ref "db" → 4ef74b97c298402786f23bf299e17baba815e8d521bc90aaab59ab7de747c969 +``` + +`db migrate` reads the record that `db sign` stored to see which contract the database already has, so only your change runs, and the rows in your tables stay as they are. `--advance-ref db` updates the `db` ref to the new hash, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. + +To apply the migration to any other database that has the same tables, such as production, pass its connection string. Leave out `--advance-ref`, because the `db` ref describes your development database: + +```npm +npx prisma db migrate --db "$PRODUCTION_DATABASE_URL" ``` -The plan starts from the contract `db sign` recorded, so it contains only your change. Because `migrations/app/` is still empty, that first plan also writes a baseline package recording the schema you adopted; see [the automatic baseline](/cli/migration-plan#the-automatic-baseline). +You do not need to run `db sign` on that database first. It has no record of a contract yet, so `db migrate` starts at the baseline, finds the tables already there, leaves them and their rows as they are, and then adds the `phone` column. + +## Next steps + +Every later change follows the same four steps: edit `src/prisma/contract.prisma`, run `npx prisma contract emit`, run `npx prisma migration plan --name `, and run `npx prisma db migrate --advance-ref db`. + +- [Generating a migration](/orm/migrations/generating-a-migration) for what a migration directory contains and how to edit it. +- [`db update`](/cli/db-update) to apply a contract change to a development database without writing migration files. +- [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) for the Prisma ORM 8 name of each Prisma ORM 7 call. diff --git a/apps/docs/content/docs/(index)/prisma-orm/create-prisma.mdx b/apps/docs/content/docs/(index)/prisma-orm/create-prisma.mdx index 7e6489138e0..4759ed23e7e 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/create-prisma.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/create-prisma.mdx @@ -8,7 +8,7 @@ metaDescription: Use npm create prisma@latest to create a Prisma ORM app from a `create-prisma` creates a new Prisma ORM project from an app template. It installs Prisma ORM, emits the contract, and generates a deployable [Prisma Composer](/composer) app. PostgreSQL projects use Composer's native Prisma Postgres provider, including migrations and a typed runtime client. -Use it when you want to start from a working app. If you already have an app, follow [Add Prisma ORM to an existing PostgreSQL project](/prisma-orm/add-to-existing-project/postgresql) or [Add Prisma ORM to an existing MongoDB project](/prisma-orm/add-to-existing-project/mongodb) instead. +Use it when you want to start from a working app. If you already have an app, follow [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql) or [Add Prisma ORM to an existing MongoDB database](/prisma-orm/add-to-existing-project/mongodb) instead. :::note[Prisma ORM 7] @@ -93,7 +93,7 @@ npm run db:init npm run dev ``` -Sample records are seeded on the app's first query. From there, evolve the contract under `src/prisma/`, run `npm run contract:emit`, and plan and apply the migration with `npx prisma migration plan` and `npx prisma db migrate`. The [quickstart](/prisma-orm/quickstart/postgresql) covers that loop in detail, and the [MongoDB quickstart](/prisma-orm/quickstart/mongodb) covers the MongoDB connection string. +Sample records are seeded on the app's first query. From there, evolve the contract under `src/prisma/`, run `npm run contract:emit`, and plan and apply the migration with `npx prisma migration plan` and `npx prisma db migrate`. [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) covers that loop in detail, and [Create a new app with MongoDB](/prisma-orm/quickstart/mongodb) covers the MongoDB connection string. ### Generated scripts 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 b15f20ad57a..193df7b7dba 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx @@ -8,7 +8,7 @@ metaDescription: 'Add Prisma ORM 8 to an empty Node.js project without a templat By the end of this page you have a project with a `prisma.config.ts`, a `prisma/contract.prisma` holding one `User` model, and a single `index.ts` that writes, updates, and reads rows in PostgreSQL through Prisma ORM 8, plus a migration you planned and applied. No template generates anything: you create every file yourself and see what each one is for. -Use this path when you want to see every file Prisma ORM needs, or when you are adding Prisma ORM to a repository that already has its own layout. If you would rather have the files written for you, run `npm create prisma@latest` and follow the [PostgreSQL quickstart](/prisma-orm/quickstart/postgresql). +Use this path when you want to see every file Prisma ORM needs, or when you are adding Prisma ORM to a repository that already has its own layout. If you would rather have the files written for you, run `npm create prisma@latest` and follow [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). :::note[Using Prisma ORM 7?] @@ -279,4 +279,4 @@ From here, every schema change follows the same routine: edit `prisma/contract.p - [Data modeling](/orm/data-modeling) for relations, more field types, and indexes. - [Generating a migration](/orm/migrations/generating-a-migration) for what is in a migration directory and how to edit one. -- [PostgreSQL quickstart](/prisma-orm/quickstart/postgresql) if you want the same setup generated for you with a starter app. +- [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) if you want the same setup generated for you with a starter app. diff --git a/apps/docs/content/docs/(index)/prisma-orm/index.mdx b/apps/docs/content/docs/(index)/prisma-orm/index.mdx index 8825b9d7479..7a71ae22d13 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/index.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/index.mdx @@ -8,6 +8,23 @@ metaDescription: 'Start here for Prisma ORM 8, the TypeScript-native rebuild of Prisma ORM 8 is a ground-up rebuild of Prisma ORM, from the runtime and query APIs to the migration flow and project setup. +Pick the page that matches where you are starting from: + + + }> + Create an app from a template and run your first query. + + }> + Add Prisma ORM to your app, create the tables, and apply your first migration. + + }> + 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. + + + :::note[Prisma ORM 7] Prisma ORM 8 is the current release, as a release candidate. Prisma ORM 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). @@ -22,8 +39,6 @@ Prisma ORM 8 is the recommended starting point for new projects. npm create prisma@latest ``` -Start with the setup page when you want a guided first run, or read the [create-prisma reference](/prisma-orm/create-prisma) for every template and flag. To add Prisma ORM to a project by hand, without the template, follow [Set up Prisma ORM from scratch](/prisma-orm/from-scratch). - }> Scaffold, provision Prisma Postgres, query, and deploy to Prisma Compute in one sitting. diff --git a/apps/docs/content/docs/(index)/prisma-orm/meta.json b/apps/docs/content/docs/(index)/prisma-orm/meta.json index 07c5709226a..d308be2075e 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/meta.json +++ b/apps/docs/content/docs/(index)/prisma-orm/meta.json @@ -5,9 +5,8 @@ "index", "[Release status](/orm/release-status)", "[Supported databases](/orm/supported-databases)", - "create-prisma", "quickstart", - "from-scratch", - "add-to-existing-project" + "[Editor setup](/orm/contract-authoring/editor-support)", + "create-prisma" ] } diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx new file mode 100644 index 00000000000..db30b37eda0 --- /dev/null +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx @@ -0,0 +1,302 @@ +--- +title: Add Prisma ORM and MongoDB to an existing app +description: Add Prisma ORM to an app you already have, create the collections in an empty MongoDB database, run a first query, and apply a first migration. +url: /prisma-orm/quickstart/existing-app/mongodb +metaTitle: Add Prisma ORM and MongoDB to an existing app +metaDescription: 'Add Prisma ORM to an app you already have: run orm init, write one model, create the collection in an empty MongoDB database, query it, and apply a migration.' +--- + +This page uses MongoDB. [Use PostgreSQL instead](/prisma-orm/quickstart/existing-app/postgresql). + +Use this page when you already have an app and its database has no collections yet. By the end, your app has one model, the database has a collection for it, a script writes and reads a document, and you have applied one change to the model as a migration. If your database already has collections, follow [Add Prisma ORM to an existing MongoDB database](/prisma-orm/add-to-existing-project/mongodb) instead. + +:::note[Using Prisma ORM 7?] + +Prisma ORM 8 is the current release, as a release candidate. Prisma ORM 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). + +For what release candidate means, when the final release is expected, and how to stay on version 7, see [Release status](/orm/release-status). + +::: + +## Prerequisites + +- A project directory with a `package.json`, on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. +- A way to run a TypeScript file. This page uses `tsx`. If your project does not have it, run `npm install --save-dev tsx typescript`. +- An empty MongoDB database, version 8.0 or newer. A single `mongod` server is enough. You need a replica set only for transactions and change streams. + +## 1. Add Prisma ORM to the project + +The command changes two files that your app may already have. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. A CommonJS app is one whose code loads other files with `require`, and these changes can stop it from starting. If that is your app, you can still finish this page, because its steps run a script through `tsx` and work either way. Then follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start the app again. + +From the root of your project, run: + +```npm +npx prisma@latest orm init --yes --target mongodb --authoring psl --write-env +``` + +`--target mongodb` picks MongoDB, `--authoring psl` picks the `.prisma` file format you know from earlier Prisma ORM versions, and `--write-env` writes a `.env` file. `--yes` accepts the default location for the files, so the command asks no questions. The other value for `--authoring` is `typescript`, which this page does not use. The command installs the packages, writes the files, and ends with the summary below. In `package.json`, the command adds the packages and a `contract:emit` script. If your project already has a `tsconfig.json` or a `.gitignore`, the command edits that file and keeps the rest of it. It leaves a `.env` that you already have untouched. + +```text no-copy +│ target: mongodb +│ authoring: psl +│ schema: src/prisma/contract.prisma + +written +├─ src/prisma/contract.prisma +├─ prisma.config.ts +├─ src/prisma/db.ts +├─ prisma-8.md +├─ .env.example +├─ .env +├─ tsconfig.json +├─ .gitignore +├─ .gitattributes +└─ package.json +installed +├─ @prisma/orm-mongo +├─ dotenv +├─ prisma@latest (dev) +├─ @types/node (dev) +└─ @prisma/cli-engine@0.6.2 (dev) + +✔ Done. Open prisma-8.md to get started. +``` + +You work with three of these files: + +- `src/prisma/contract.prisma` holds your models. It is what `schema.prisma` was in earlier Prisma ORM versions, and Prisma ORM 8 calls it the contract. +- `prisma.config.ts` tells the `prisma` commands where the contract is and which database to connect to. +- `src/prisma/db.ts` is the file your app imports to run queries. + +You do not need `prisma-8.md` for this page. It is a short reference for writing queries. + +This is `src/prisma/db.ts` in full: + +```typescript title="src/prisma/db.ts" +import 'dotenv/config'; +import mongo from '@prisma/orm-mongo/runtime'; +import type { Contract } from './contract.d'; +import contractJson from './contract.json' with { type: 'json' }; + +export const db = mongo({ + contractJson, + url: process.env['DATABASE_URL']!, +}); +``` + +The first line loads `.env`, so every file that imports `db` reads `DATABASE_URL` from there. The two `contract` files it imports are written by `contract emit` in step 4. + +From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. The skills are instruction files for coding agents, and the line does not change what the command does. If you want the skills, [`npx prisma@latest init`](/cli/init) installs them, which also stops the line. The output on this page leaves the line out. + +## 2. Set the connection string + +If you had no `.env`, `orm init` wrote one with a placeholder, `DATABASE_URL="mongodb://user:password@localhost:27017/mydb"`. Open `.env` and set `DATABASE_URL` to the connection string of your database: + +```bash title=".env" +DATABASE_URL="mongodb://username:password@host:27017/database" +``` + +The last part of the connection string is the name of the database. + +`orm init` added `.env` to `.gitignore`, so the password stays out of version control. + +## 3. Write one model + +`orm init` wrote a starter contract with a `User` and a `Post` model. Replace the contents of `src/prisma/contract.prisma` with one model: + +```prisma title="src/prisma/contract.prisma" +// use prisma-8 + +model User { + id ObjectId @id @map("_id") + email String @unique + name String? + @@map("users") +} +``` + +Keep the first line, because `contract emit` reads only `.prisma` files that start with it. `@@map("users")` names the collection that stores the model. The file has no `datasource` or `generator` block. The connection string comes from `.env`, and `contract emit` in the next step takes the place of the generator. [Data modeling](/orm/data-modeling) covers field types and relations. + +## 4. Generate the files your code imports + +Run `contract emit` after every change to the contract. It takes the place of `prisma generate`. This command and the ones after it start with `npx prisma`, without `@latest`, which runs the version that `orm init` installed in your project: + +```npm +npx prisma contract emit +``` + +```text no-copy +✔ Resolving contract source... +✔ Emitting contract... +│ contract: src/prisma/contract.json +│ types: src/prisma/contract.d.ts + +✔ Emitted contract.json and contract.d.ts +``` + +The command writes `contract.json` and `contract.d.ts` next to the contract. Commit both files, because `db.ts` imports them. + +## 5. Create the collection + +```npm +npx prisma db init +``` + +```text no-copy +✔ Introspecting database schema +✔ Planning migration +✔ Initialising database across spaces +│ contract: src/prisma/contract.json +│ database: mongodb://127.0.0.1:27029/app1 + +✔ Applied 2 operation(s) across 1 contract space + +App space +├─ Create collection users +├─ Create index on users (email:1) +└─ marker 778f20d8e17f0107ce8a9f84577123728a700cb38e1b2b2689949ae658d3776e + +✔ Advanced ref "db" → 778f20d8e17f0107ce8a9f84577123728a700cb38e1b2b2689949ae658d3776e +``` + +`db init` creates the collections and indexes your contract declares. It also gives each collection a validator, which is the MongoDB rule that lists the fields a document may have. MongoDB then rejects a document with a field that the contract does not declare. The output names two more things it wrote: + +- The `marker` is a record that `db init` stores in the database. It holds the hash of your contract, which is the long hexadecimal text in the output. The hash changes whenever the contract changes, so later commands compare it with your contract to tell whether the database is up to date. +- The `db` ref is the file `migrations/app/refs/db.json` in your project. It holds the same hash. `migration plan` in step 7 does not connect to the database, so it reads this file to find out which version of the contract your development database has. + +Commit the `migrations/` directory together with your code, because `migration plan` reads it on every later change. If the command fails with `DRIVER.CONNECTION_FAILED`, the value of `DATABASE_URL` in `.env` is wrong or the database is not reachable. + +## 6. Write and read a document + +Create `script.ts` in the root of your project: + +```typescript title="script.ts" +import { db } from "./src/prisma/db"; + +async function main() { + const created = await db.orm.users.create({ + email: "alice@example.com", + name: "Alice", + }); + console.log("Created:", created); + + const users = await db.orm.users.all(); + console.log("All users:", users); + + await db.close(); +} + +main().catch((error) => { + console.error(error); + process.exit(1); +}); +``` + +You reach the model as `db.orm.users`. On MongoDB you address a model by the name of its collection, which is the name in `@@map`. `await db.close()` closes the database connections, and without it the script keeps running after the last query. `create` takes the fields directly, with no `data` wrapper, and `.all()` does what `findMany()` did. + +Run it: + +```npm +npx tsx script.ts +``` + +```text no-copy +Created: { + _id: '6abc2ce7b04f66be2c85564d', + email: 'alice@example.com', + name: 'Alice' +} +All users: [ + { + _id: '6abc2ce7b04f66be2c85564d', + email: 'alice@example.com', + name: 'Alice' + } +] +``` + +The script passes no identifier, and the new document gets one. The result names it `_id`, as MongoDB stores it, and returns it as a string. Use `_id` in filters too, as in `db.orm.users.where({ _id: created._id }).first()`. + +In your app, import `db` from `src/prisma/db.ts` the same way. [Reading data](/orm/fundamentals/reading-data) and [Writing data](/orm/fundamentals/writing-data) show the other queries. + +## 7. Change the model and apply the change + +Add a field to the model: + +```prisma title="src/prisma/contract.prisma" +// use prisma-8 + +model User { + id ObjectId @id @map("_id") + email String @unique + name String? + phone String? // [!code ++] + @@map("users") +} +``` + +Generate the files again, then plan a migration. `migration plan` writes the difference between the new contract and the one your database has into a new directory under `migrations/app/`. `--name` sets the name of that directory. + +```npm +npx prisma contract emit +npx prisma migration plan --name add_user_phone +``` + +```text no-copy +│ contract: src/prisma/contract.json +│ migrations: migrations/app +│ name: add_user_phone + +✔ Planned baseline (2 operation(s)) + 1 operation(s) + +migrations/app/20260929T2126_baseline +├─ Create collection users +└─ Create index on users (email:1) +migrations/app/20260929T2127_add_user_phone +└─ Update validator on users + +from: 778f20d8e17f0107ce8a9f84577123728a700cb38e1b2b2689949ae658d3776e +to: f0035d1963f127dc8ee91e154d51810755ee91b090659127881d1ab31e03e3cf +baseline: migrations/app/20260929T2126_baseline +app space: migrations/app/20260929T2127_add_user_phone +``` + +The output continues with a preview of the MongoDB commands. The first plan in a project writes two directories. The baseline records the collection and the index that `db init` already created. The second directory is your change. Your change updates the validator, so that a document may have the `phone` field. + +Apply the migration: + +```npm +npx prisma db migrate --advance-ref db +``` + +```text no-copy +✔ Running migration plan across spaces +│ migrations: migrations +│ database: mongodb://127.0.0.1:27029/app1 + +✔ Applied 1 migration(s) (1 operation(s)) across 1 contract space(s) + +App space +├─ Update validator on users +└─ marker f0035d1963f127dc8ee91e154d51810755ee91b090659127881d1ab31e03e3cf + +✔ Advanced ref "db" → f0035d1963f127dc8ee91e154d51810755ee91b090659127881d1ab31e03e3cf +``` + +`db migrate` reads the marker to see which contract the database already has, so here it runs only your change. `--advance-ref db` then updates the `db` ref to the new hash, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. Commit the two new directories. + +To apply the migrations to any other database, such as production, pass its connection string. Leave out `--advance-ref`, because the `db` ref describes your development database: + +```npm +npx prisma db migrate --db "$PRODUCTION_DATABASE_URL" +``` + +`db migrate` runs the migrations that this database does not have yet. An empty database has no marker, so there `db migrate` runs the baseline and then your change. + +Every later change follows the same four steps, which take the place of `prisma migrate dev`: edit `src/prisma/contract.prisma`, run `npx prisma contract emit`, run `npx prisma migration plan --name `, and run `npx prisma db migrate --advance-ref db`. + +## Next steps + +- [Data modeling](/orm/data-modeling) for relations, more field types, and indexes. +- [Generating a migration](/orm/migrations/generating-a-migration) for what a migration directory contains and how to edit it. +- [`db update`](/cli/db-update) to apply a contract change to a development database without writing migration files. 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 new file mode 100644 index 00000000000..8104069a22a --- /dev/null +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/postgresql.mdx @@ -0,0 +1,290 @@ +--- +title: Add Prisma ORM and PostgreSQL to an existing app +description: Add Prisma ORM to an app you already have, create the tables in an empty PostgreSQL database, run a first query, and apply a first migration. +url: /prisma-orm/quickstart/existing-app/postgresql +metaTitle: Add Prisma ORM and PostgreSQL to an existing app +metaDescription: 'Add Prisma ORM to an app you already have: run orm init, write one model, create the table in an empty PostgreSQL database, query it, and apply a migration.' +--- + +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, a script writes and reads a row, and you have applied one change to the model as 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). + +:::note[Using Prisma ORM 7?] + +Prisma ORM 8 is the current release, as a release candidate. Prisma ORM 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). + +For what release candidate means, when the final release is expected, and how to stay on version 7, see [Release status](/orm/release-status). For the Prisma ORM 8 name of every Prisma ORM 7 API, see [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7). + +::: + +## Prerequisites + +- A project directory with a `package.json`, on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. +- A way to run a TypeScript file. This page uses `tsx`. If your project does not have it, run `npm install --save-dev tsx typescript`. +- An empty PostgreSQL database, version 15 or newer. Step 2 shows how to get one if you have none. + +## 1. Add Prisma ORM to the project + +The command changes two files that your app may already have. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. A CommonJS app is one whose code loads other files with `require`, and these changes can stop it from starting. If that is your app, you can still finish this page, because its steps run a script through `tsx` and work either way. Then follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start the app again. + +From the root of your project, run: + +```npm +npx prisma@latest orm init --yes --target postgres --authoring psl --write-env +``` + +`--target postgres` picks PostgreSQL, `--authoring psl` picks the `.prisma` file format you know from Prisma ORM 7, and `--write-env` writes a `.env` file. `--yes` accepts the default location for the files, so the command asks no questions. The other value for `--authoring` is `typescript`, which this page does not use. The command installs the packages, writes the files, and ends with the summary below. In `package.json`, the command adds the packages and a `contract:emit` script. If your project already has a `tsconfig.json` or a `.gitignore`, the command edits that file and keeps the rest of it. It leaves a `.env` that you already have untouched. + +```text no-copy +│ target: postgres +│ authoring: psl +│ schema: src/prisma/contract.prisma + +written +├─ src/prisma/contract.prisma +├─ prisma.config.ts +├─ src/prisma/db.ts +├─ prisma-8.md +├─ .env.example +├─ .env +├─ tsconfig.json +├─ .gitignore +├─ .gitattributes +└─ package.json +installed +├─ @prisma/orm-postgres +├─ dotenv +├─ prisma@latest (dev) +├─ @types/node (dev) +└─ @prisma/cli-engine@0.6.2 (dev) + +✔ Done. Open prisma-8.md to get started. +``` + +You work with three of these files: + +- `src/prisma/contract.prisma` holds your models. It is what `schema.prisma` was in Prisma ORM 7, and Prisma ORM 8 calls it the contract. +- `prisma.config.ts` tells the `prisma` commands where the contract is and which database to connect to. +- `src/prisma/db.ts` is the file your app imports to run queries. + +You do not need `prisma-8.md` for this page. It is a short reference for writing queries. + +This is `src/prisma/db.ts` in full: + +```typescript title="src/prisma/db.ts" +import 'dotenv/config'; +import postgres from '@prisma/orm-postgres/runtime'; +import type { Contract } from './contract.d'; +import contractJson from './contract.json' with { type: 'json' }; + +export const db = postgres({ + contractJson, + url: process.env['DATABASE_URL']!, +}); +``` + +The first line loads `.env`, so every file that imports `db` reads `DATABASE_URL` from there. The two `contract` files it imports are written by `contract emit` in step 4. + +From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. The skills are instruction files for coding agents, and the line does not change what the command does. If you want the skills, [`npx prisma@latest init`](/cli/init) installs them, which also stops the line. The output on this page leaves the line out. + +## 2. Set the connection string + +If you had no `.env`, `orm init` wrote one with a placeholder, `DATABASE_URL="postgresql://user:password@localhost:5432/mydb"`. Open `.env` and set `DATABASE_URL` to the connection string of your database: + +```bash title=".env" +DATABASE_URL="postgresql://username:password@host:5432/database" +``` + +If you have no database at all, [`npx create-db@latest`](/postgres/npx-create-db) creates a temporary Prisma Postgres database and prints its connection string. + +`orm init` added `.env` to `.gitignore`, so the password stays out of version control. + +## 3. Write one model + +`orm init` wrote a starter contract with a `User` and a `Post` model. Replace the contents of `src/prisma/contract.prisma` with one model: + +```prisma title="src/prisma/contract.prisma" +// use prisma-8 + +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? +} +``` + +Keep the first line, because `contract emit` reads only `.prisma` files that start with it. The file has no `datasource` or `generator` block. The connection string comes from `.env`, and `contract emit` in the next step takes the place of the generator. [Data modeling](/orm/data-modeling) covers field types and relations. + +## 4. Generate the files your code imports + +Run `contract emit` after every change to the contract. It takes the place of `prisma generate`. This command and the ones after it start with `npx prisma`, without `@latest`, which runs the version that `orm init` installed in your project: + +```npm +npx prisma contract emit +``` + +```text no-copy +✔ Resolving contract source... +✔ Emitting contract... +│ contract: src/prisma/contract.json +│ types: src/prisma/contract.d.ts + +✔ Emitted contract.json and contract.d.ts +``` + +The command writes `contract.json` and `contract.d.ts` next to the contract. Commit both files, because `db.ts` imports them. + +## 5. Create the table + +```npm +npx prisma db init +``` + +```text no-copy +✔ Introspecting database schema +✔ Planning migration +✔ Initialising database across spaces +│ contract: src/prisma/contract.json +│ database: postgres://****@127.0.0.1:54329/app1 + +✔ Applied 2 operation(s) across 1 contract space + +App space +├─ Create table "User" +├─ Add unique constraint on "User" (email) +└─ marker b5ae4e66fad1f0b7dd5590568f75a12a6f4576e9f367a787a69a4e729abac1fb + +✔ Advanced ref "db" → b5ae4e66fad1f0b7dd5590568f75a12a6f4576e9f367a787a69a4e729abac1fb +``` + +`db init` creates the tables your contract declares. The output names two more things it wrote: + +- The `marker` is a record that `db init` stores in the database. It holds the hash of your contract, which is the long hexadecimal text in the output. The hash changes whenever the contract changes, so later commands compare it with your contract to tell whether the database is up to date. +- The `db` ref is the file `migrations/app/refs/db.json` in your project. It holds the same hash. `migration plan` in step 7 does not connect to the database, so it reads this file to find out which version of the contract your development database has. + +Commit the `migrations/` directory together with your code, because `migration plan` reads it on every later change. If the command fails with `DRIVER.CONNECTION_FAILED`, the value of `DATABASE_URL` in `.env` is wrong or the database is not reachable. + +## 6. Write and read a row + +Create `script.ts` in the root of your project: + +```typescript title="script.ts" +import { db } from "./src/prisma/db"; + +async function main() { + const created = await db.orm.public.User.create({ + email: "alice@example.com", + name: "Alice", + }); + console.log("Created:", created); + + const users = await db.orm.public.User.all(); + console.log("All users:", users); + + await db.close(); +} + +main().catch((error) => { + console.error(error); + process.exit(1); +}); +``` + +You reach the model as `db.orm.public.User`, where `public` is the name of the PostgreSQL schema that holds your tables. `await db.close()` closes the database connections, and without it the script keeps running after the last query. `create` takes the fields directly, with no `data` wrapper, and `.all()` does what `findMany()` did. + +Run it: + +```npm +npx tsx script.ts +``` + +```text no-copy +Created: { email: 'alice@example.com', id: 1, name: 'Alice' } +All users: [ { email: 'alice@example.com', id: 1, name: 'Alice' } ] +``` + +In your app, import `db` from `src/prisma/db.ts` the same way. [Reading data](/orm/fundamentals/reading-data) and [Writing data](/orm/fundamentals/writing-data) show the other queries. + +## 7. Change the model and apply the change + +Add a field to the model: + +```prisma title="src/prisma/contract.prisma" +// use prisma-8 + +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? + phone String? // [!code ++] +} +``` + +Generate the files again, then plan a migration. `migration plan` writes the difference between the new contract and the one your database has into a new directory under `migrations/app/`. `--name` sets the name of that directory. + +```npm +npx prisma contract emit +npx prisma migration plan --name add_user_phone +``` + +```text no-copy +│ contract: src/prisma/contract.json +│ migrations: migrations/app +│ name: add_user_phone + +✔ Planned baseline (3 operation(s)) + 1 operation(s) + +migrations/app/20260929T2120_baseline +├─ Create schema "public" +├─ Create table "User" +└─ Add unique constraint on "User" (email) +migrations/app/20260929T2121_add_user_phone +└─ Add column "phone" to "User" + +from: b5ae4e66fad1f0b7dd5590568f75a12a6f4576e9f367a787a69a4e729abac1fb +to: 300832575ace8feebb3d3442d1bca52150c46628de3e4c6c32a61cb0ab21100f +baseline: migrations/app/20260929T2120_baseline +app space: migrations/app/20260929T2121_add_user_phone +``` + +The output continues with a preview of the SQL. The first plan in a project writes two directories. The baseline records the table that `db init` already created. The second directory is your change. + +Apply the migration: + +```npm +npx prisma db migrate --advance-ref db +``` + +```text no-copy +✔ Running migration plan across spaces +│ migrations: migrations +│ database: postgres://****@127.0.0.1:54329/app1 + +✔ Applied 1 migration(s) (1 operation(s)) across 1 contract space(s) + +App space +├─ Add column "phone" to "User" +└─ marker 300832575ace8feebb3d3442d1bca52150c46628de3e4c6c32a61cb0ab21100f + +✔ Advanced ref "db" → 300832575ace8feebb3d3442d1bca52150c46628de3e4c6c32a61cb0ab21100f +``` + +`db migrate` reads the marker to see which contract the database already has, so here it runs only your change. `--advance-ref db` then updates the `db` ref to the new hash, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. Commit the two new directories. + +To apply the migrations to any other database, such as production, pass its connection string. Leave out `--advance-ref`, because the `db` ref describes your development database: + +```npm +npx prisma db migrate --db "$PRODUCTION_DATABASE_URL" +``` + +`db migrate` runs the migrations that this database does not have yet. An empty database has no marker, so there `db migrate` runs the baseline and then your change. + +Every later change follows the same four steps, which take the place of `prisma migrate dev`: edit `src/prisma/contract.prisma`, run `npx prisma contract emit`, run `npx prisma migration plan --name `, and run `npx prisma db migrate --advance-ref db`. + +## Next steps + +- [Data modeling](/orm/data-modeling) for relations, more field types, and indexes. +- [Generating a migration](/orm/migrations/generating-a-migration) for what a migration directory contains and how to edit it. +- [`db update`](/cli/db-update) to apply a contract change to a development database without writing migration files. +- [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) for the Prisma ORM 8 name of each Prisma ORM 7 call. 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 3a7edc76ece..99ab8d34b93 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json @@ -1,4 +1,10 @@ { "title": "Quickstart", - "pages": ["postgresql", "mongodb"] + "defaultOpen": true, + "pages": [ + "[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)" + ] } diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx index 81089232c78..0e0440fd4d5 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx @@ -1,11 +1,13 @@ --- -title: MongoDB +title: Create a new app with MongoDB description: Create a new Prisma ORM project with MongoDB using create-prisma@latest. url: /prisma-orm/quickstart/mongodb metaTitle: 'Quickstart: Prisma ORM with MongoDB' metaDescription: 'Scaffold a Prisma ORM project with MongoDB, apply the starter migration, and run your first query.' --- +This page uses MongoDB. [Use PostgreSQL instead](/prisma-orm/quickstart/postgresql). + Create a Prisma ORM app with MongoDB, apply the first migration, and run your first query against seeded data. :::note[Using Prisma ORM 7?] @@ -22,7 +24,7 @@ For what release candidate means, when the final release is expected, and how to npm create prisma@latest -- --provider mongodb --no-deploy ``` -Run this from a Node.js 22.18 or newer (on the 24 line, 24.11 or newer) environment; Node.js 24 is recommended. The command preselects MongoDB and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. +Run this from a Node.js 22.18 or newer (on the 24 line, 24.11 or newer) environment; Node.js 24 is recommended. The command preselects MongoDB and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. If you would rather add Prisma ORM to a project by hand, without the generated template, follow [Set up Prisma ORM from scratch](/prisma-orm/from-scratch), which uses PostgreSQL. Setup gives you the app template, a starter contract, `prisma-8.md`, project-level Prisma ORM skills for your coding agent, and package scripts for the database steps below. Answer no at the skills prompt, or pass `--skills none`, to skip the agent skill files; to remove them later, see [`skills sync`](/cli/skills) and the [`skills` config section](/cli/configuration#agent-skills). Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. @@ -78,5 +80,5 @@ Use the URL or terminal output shown by your template. You should see the seeded ## Next steps - Open `src/prisma/contract.prisma` or `src/prisma/contract.ts` and change the starter model. -- Use the [MongoDB existing-project guide](/prisma-orm/add-to-existing-project/mongodb) if you already have an app and database. +- If you already have an app, follow [Add Prisma ORM and MongoDB to an existing app](/prisma-orm/quickstart/existing-app/mongodb) when its database is empty, or [Add Prisma ORM to an existing MongoDB database](/prisma-orm/add-to-existing-project/mongodb) when the database already has collections. - Read the [Prisma ORM overview](/orm) when you want the concepts behind contracts, query APIs, and migrations. diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx index 2fa8e5fd514..7cd8c3a3377 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx @@ -1,11 +1,13 @@ --- -title: PostgreSQL +title: Create a new app with PostgreSQL description: Create a new Prisma ORM project with PostgreSQL using create-prisma@latest. url: /prisma-orm/quickstart/postgresql metaTitle: 'Quickstart: Prisma ORM with PostgreSQL' metaDescription: 'Scaffold a Prisma ORM project with PostgreSQL, initialize the database, and run your first query.' --- +This page uses PostgreSQL. [Use MongoDB instead](/prisma-orm/quickstart/mongodb). + Create a Prisma ORM app with PostgreSQL and run your first query against seeded data. :::note[Using Prisma ORM 7?] @@ -73,5 +75,5 @@ Use the URL or terminal output shown by your template. You should see the seeded ## Next steps - Open `src/prisma/contract.prisma` or `src/prisma/contract.ts` and change the starter model. -- Use the [PostgreSQL existing-project guide](/prisma-orm/add-to-existing-project/postgresql) if you already have an app and database. +- If you already have an app, follow [Add Prisma ORM and PostgreSQL to an existing app](/prisma-orm/quickstart/existing-app/postgresql) when its database is empty, or [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql) when the database already has tables. - Read the [Prisma ORM overview](/orm) when you want the concepts behind contracts, query APIs, and migrations. diff --git a/apps/docs/content/docs/(index)/prisma-postgres/from-the-cli.mdx b/apps/docs/content/docs/(index)/prisma-postgres/from-the-cli.mdx index 28716271ac6..6fcd4f38e79 100644 --- a/apps/docs/content/docs/(index)/prisma-postgres/from-the-cli.mdx +++ b/apps/docs/content/docs/(index)/prisma-postgres/from-the-cli.mdx @@ -54,7 +54,7 @@ If the app already exists, run Prisma ORM from the project root: npx prisma@latest orm init ``` -Choose PostgreSQL and set `DATABASE_URL` to your Prisma Postgres connection string. Init adds `prisma-8.md`, package scripts, and the Prisma ORM skills for your coding agent. Then follow the [PostgreSQL existing-project guide](/prisma-orm/add-to-existing-project/postgresql). +Choose PostgreSQL and set `DATABASE_URL` to your Prisma Postgres connection string. Init adds `prisma-8.md`, package scripts, and the Prisma ORM skills for your coding agent. Then follow [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). ## Import an existing database diff --git a/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-mysql.mdx b/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-mysql.mdx index 59d27e0df19..ffcc055caa0 100644 --- a/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-mysql.mdx +++ b/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-mysql.mdx @@ -66,5 +66,5 @@ npx prisma db sign ## Next steps - Review table and column names in the inferred contract. -- Use the [PostgreSQL existing-project guide](/prisma-orm/add-to-existing-project/postgresql) for the first Prisma ORM query. +- Use [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql) for the first Prisma ORM query. - Use the [full Prisma Postgres MySQL import guide](/prisma-postgres/import-from-existing-database-mysql) for deeper migration details. diff --git a/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-orm.mdx b/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-orm.mdx index ae497720126..e986494ffea 100644 --- a/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-orm.mdx +++ b/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-orm.mdx @@ -56,4 +56,4 @@ Use the URL or terminal output shown by your template to confirm the sample quer - Open the generated contract and change the starter model. - Use [Import from PostgreSQL](/prisma-postgres/import-from-existing-database-postgresql) or [Import from MySQL](/prisma-postgres/import-from-existing-database-mysql) when you want to move an existing database to Prisma Postgres. -- Use the [PostgreSQL existing-project guide](/prisma-orm/add-to-existing-project/postgresql) when your app already has a Prisma Postgres database. +- Use [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql) when your app already has a Prisma Postgres database. diff --git a/apps/docs/content/docs/cli/index.mdx b/apps/docs/content/docs/cli/index.mdx index 49fc3c948b3..d02d8aa3887 100644 --- a/apps/docs/content/docs/cli/index.mdx +++ b/apps/docs/content/docs/cli/index.mdx @@ -25,7 +25,7 @@ npx prisma contract emit With `prisma` installed in your project, these commands become plain `prisma contract emit` and so on. -For a full app scaffold, use a [Prisma ORM quickstart](/prisma-orm/quickstart/postgresql). That path creates the project files and package scripts for you. This CLI reference is for the lower-level commands those scripts call. +For a full app scaffold, follow [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). That path creates the project files and package scripts for you. This CLI reference is for the lower-level commands those scripts call. ## Platform commands diff --git a/apps/docs/content/docs/cli/orm-init.mdx b/apps/docs/content/docs/cli/orm-init.mdx index 41535279345..456434ccf41 100644 --- a/apps/docs/content/docs/cli/orm-init.mdx +++ b/apps/docs/content/docs/cli/orm-init.mdx @@ -8,7 +8,7 @@ metaDescription: Learn how to initialize Prisma ORM files in an existing project `orm init` scaffolds the Prisma ORM config, contract source, and runtime files inside an existing project, installs dependencies, and emits the contract. It gets you from zero to typed queries in one step. -Use a [Prisma ORM quickstart](/prisma-orm/quickstart/postgresql) when you want a complete new application template. Use `orm init` when you already have a project and want to add the lower-level Prisma ORM files. +Follow [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) when you want a complete new application template. Use `orm init` when you already have a project and want to add the lower-level Prisma ORM files. ## Usage diff --git a/apps/docs/content/docs/guides/authentication/authjs/nextjs.mdx b/apps/docs/content/docs/guides/authentication/authjs/nextjs.mdx index 03f24d6a0d8..80bdc9c2087 100644 --- a/apps/docs/content/docs/guides/authentication/authjs/nextjs.mdx +++ b/apps/docs/content/docs/guides/authentication/authjs/nextjs.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to use Prisma ORM in a Next.js app with Auth.js :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is not available yet: `@auth/prisma-adapter` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is not available yet: `@auth/prisma-adapter` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. ::: diff --git a/apps/docs/content/docs/guides/authentication/better-auth/astro.mdx b/apps/docs/content/docs/guides/authentication/better-auth/astro.mdx index a24fbab90ea..5ebb644bf90 100644 --- a/apps/docs/content/docs/guides/authentication/better-auth/astro.mdx +++ b/apps/docs/content/docs/guides/authentication/better-auth/astro.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to use Prisma ORM in an Astro app with Better Auth :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is not available yet: Better Auth's `prismaAdapter` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is not available yet: Better Auth's `prismaAdapter` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. ::: diff --git a/apps/docs/content/docs/guides/authentication/better-auth/nextjs.mdx b/apps/docs/content/docs/guides/authentication/better-auth/nextjs.mdx index 38519bce12f..c346e80442d 100644 --- a/apps/docs/content/docs/guides/authentication/better-auth/nextjs.mdx +++ b/apps/docs/content/docs/guides/authentication/better-auth/nextjs.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to use Prisma ORM in a Next.js app with Better Auth :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is not available yet: Better Auth's `prismaAdapter` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is not available yet: Better Auth's `prismaAdapter` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. ::: diff --git a/apps/docs/content/docs/guides/authentication/clerk/astro.mdx b/apps/docs/content/docs/guides/authentication/clerk/astro.mdx index 0c2f60ab7f0..2cc49feeab3 100644 --- a/apps/docs/content/docs/guides/authentication/clerk/astro.mdx +++ b/apps/docs/content/docs/guides/authentication/clerk/astro.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to use Prisma ORM in an Astro app with Clerk Auth :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. ::: diff --git a/apps/docs/content/docs/guides/authentication/clerk/nextjs.mdx b/apps/docs/content/docs/guides/authentication/clerk/nextjs.mdx index ab77715272f..42a06686a58 100644 --- a/apps/docs/content/docs/guides/authentication/clerk/nextjs.mdx +++ b/apps/docs/content/docs/guides/authentication/clerk/nextjs.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to use Prisma ORM in a Next.js app with Clerk Auth :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. ::: diff --git a/apps/docs/content/docs/guides/database/schema-changes.mdx b/apps/docs/content/docs/guides/database/schema-changes.mdx index 3ba94c9cdec..84c1afd508e 100644 --- a/apps/docs/content/docs/guides/database/schema-changes.mdx +++ b/apps/docs/content/docs/guides/database/schema-changes.mdx @@ -22,7 +22,7 @@ Prisma ORM 8 is the current release. Prisma ORM 7 remains fully supported; the P ## Prerequisites - [Node.js](https://nodejs.org) 24 or later -- A Prisma ORM project with a contract and at least one migration (the [PostgreSQL quickstart](/prisma-orm/quickstart/postgresql) gives you one) +- A Prisma ORM project with a contract and at least one migration ([Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) gives you one) - A PostgreSQL database per developer, reachable as `DATABASE_URL` - Basic familiarity with Git branches and merges - The [migration loop](/orm/migrations/how-migrations-work): `contract emit`, `migration plan`, `db migrate` diff --git a/apps/docs/content/docs/guides/index.mdx b/apps/docs/content/docs/guides/index.mdx index 7c44d732353..d667de6ed6a 100644 --- a/apps/docs/content/docs/guides/index.mdx +++ b/apps/docs/content/docs/guides/index.mdx @@ -78,6 +78,6 @@ The authentication guides and the remaining integration and Prisma Postgres guid ## Next steps -- [Start with the quickstart](/prisma-orm/quickstart/postgresql) if you don't have a Prisma ORM project yet. +- [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) if you don't have a Prisma ORM project yet. - [Learn the fundamentals](/orm/fundamentals/reading-data): reading, writing, relations, transactions, and advanced queries. - [Read the Prisma ORM overview](/orm) for the concepts behind contracts, typed queries, and migrations. diff --git a/apps/docs/content/docs/guides/integrations/datadog.mdx b/apps/docs/content/docs/guides/integrations/datadog.mdx index bbfa687b14f..23c0d15ed3b 100644 --- a/apps/docs/content/docs/guides/integrations/datadog.mdx +++ b/apps/docs/content/docs/guides/integrations/datadog.mdx @@ -9,7 +9,7 @@ metaDescription: 'Learn how to configure Datadog tracing for a Prisma ORM projec :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. ::: diff --git a/apps/docs/content/docs/guides/integrations/deno.mdx b/apps/docs/content/docs/guides/integrations/deno.mdx index afb4819a944..4287ba85a49 100644 --- a/apps/docs/content/docs/guides/integrations/deno.mdx +++ b/apps/docs/content/docs/guides/integrations/deno.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to integrate Prisma Postgres in a Deno Deploy project :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. ::: diff --git a/apps/docs/content/docs/guides/integrations/embed-studio.mdx b/apps/docs/content/docs/guides/integrations/embed-studio.mdx index 8927a7738ba..51e3ebd270f 100644 --- a/apps/docs/content/docs/guides/integrations/embed-studio.mdx +++ b/apps/docs/content/docs/guides/integrations/embed-studio.mdx @@ -9,7 +9,7 @@ metaDescription: 'Embed Prisma Studio in a Next.js application with @prisma/stud :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. ::: diff --git a/apps/docs/content/docs/guides/integrations/permit-io.mdx b/apps/docs/content/docs/guides/integrations/permit-io.mdx index c3bf5074c53..d6dfe69c272 100644 --- a/apps/docs/content/docs/guides/integrations/permit-io.mdx +++ b/apps/docs/content/docs/guides/integrations/permit-io.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to implement access control with Prisma ORM with Perm :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: `@permitio/permit-prisma` is a Prisma Client extension, and Prisma ORM 8 uses [middleware](/orm/middleware/how-middleware-works) instead of client extensions. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: `@permitio/permit-prisma` is a Prisma Client extension, and Prisma ORM 8 uses [middleware](/orm/middleware/how-middleware-works) instead of client extensions. ::: diff --git a/apps/docs/content/docs/guides/integrations/pgfence.mdx b/apps/docs/content/docs/guides/integrations/pgfence.mdx index 664ba99e718..83f2dc93592 100644 --- a/apps/docs/content/docs/guides/integrations/pgfence.mdx +++ b/apps/docs/content/docs/guides/integrations/pgfence.mdx @@ -8,7 +8,7 @@ metaDescription: Learn how to analyze Prisma migration SQL files with pgfence to :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: pgfence reads `migration.sql` files, and Prisma ORM 8 migrations are TypeScript and JSON files with no SQL output to scan. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: pgfence reads `migration.sql` files, and Prisma ORM 8 migrations are TypeScript and JSON files with no SQL output to scan. ::: diff --git a/apps/docs/content/docs/guides/integrations/plasmic.mdx b/apps/docs/content/docs/guides/integrations/plasmic.mdx index 1fb82e703a3..032aefb8d1c 100644 --- a/apps/docs/content/docs/guides/integrations/plasmic.mdx +++ b/apps/docs/content/docs/guides/integrations/plasmic.mdx @@ -9,7 +9,7 @@ metaDescription: Set up the Plasmic Prisma integration, configure queries from P :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: the Plasmic starter project is built on Prisma Client 7. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: the Plasmic starter project is built on Prisma Client 7. ::: diff --git a/apps/docs/content/docs/guides/integrations/shopify.mdx b/apps/docs/content/docs/guides/integrations/shopify.mdx index 874b96f87cd..4bf73be0433 100644 --- a/apps/docs/content/docs/guides/integrations/shopify.mdx +++ b/apps/docs/content/docs/guides/integrations/shopify.mdx @@ -9,7 +9,7 @@ metaDescription: Learn how to use Prisma Postgres with Shopify :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: `@shopify/shopify-app-session-storage-prisma` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version is not available yet: `@shopify/shopify-app-session-storage-prisma` requires Prisma Client, which Prisma ORM 8 replaces with the `@prisma/orm-postgres` runtime. ::: diff --git a/apps/docs/content/docs/guides/making-guides.mdx b/apps/docs/content/docs/guides/making-guides.mdx index 5a455132b90..069bb0280e2 100644 --- a/apps/docs/content/docs/guides/making-guides.mdx +++ b/apps/docs/content/docs/guides/making-guides.mdx @@ -26,7 +26,7 @@ Every command, file, and code block in a published guide was run by its author a Two reference guides show the finished shape. Read them before writing: - [Hono](/guides/frameworks/hono): a new project scaffolded with `create-prisma`, deployed to Prisma Compute. -- [PostgreSQL, existing project](/prisma-orm/add-to-existing-project/postgresql): the `orm init` and `contract infer` path for an app that already exists. +- [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql): the `orm init` and `contract infer` path for an app that already exists. ## Guide structure diff --git a/apps/docs/content/docs/guides/postgres/flyio.mdx b/apps/docs/content/docs/guides/postgres/flyio.mdx index 1a2b065b913..9521a60ced1 100644 --- a/apps/docs/content/docs/guides/postgres/flyio.mdx +++ b/apps/docs/content/docs/guides/postgres/flyio.mdx @@ -8,7 +8,7 @@ metaDescription: Learn how to deploy applications using Prisma Postgres to Fly.i :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. ::: diff --git a/apps/docs/content/docs/guides/postgres/netlify.mdx b/apps/docs/content/docs/guides/postgres/netlify.mdx index b510aa18183..779d6806a1c 100644 --- a/apps/docs/content/docs/guides/postgres/netlify.mdx +++ b/apps/docs/content/docs/guides/postgres/netlify.mdx @@ -8,7 +8,7 @@ metaDescription: Learn how to create Prisma Postgres databases via the official :::note[This guide uses Prisma ORM 7] -The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see the [Prisma ORM 8 quickstart](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add to an existing project](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. +The commands and code on this page target Prisma ORM 7, which remains fully supported. To start a new Prisma ORM 8 project, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql); to add Prisma ORM 8 to an existing app, see [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql). A Prisma ORM 8 version of this guide is planned. ::: diff --git a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx index 1a0ae5129b5..c948d723c0c 100644 --- a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx +++ b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx @@ -421,4 +421,4 @@ Run [`npx prisma@latest init`](/cli/init) once to install the [Prisma ORM skills - [Reading data](/orm/fundamentals/reading-data) and [writing data](/orm/fundamentals/writing-data): the full filter, sort, pagination, and mutation surface. - [Relations and joins](/orm/fundamentals/relations-and-joins): `.include()` with refinements and relation filters. - [How migrations work](/orm/migrations/how-migrations-work): once Prisma ORM owns the schema, change the contract and use [`db update`](/cli/db-update) in development or [`migration plan`](/cli/migration-plan) for checked-in migrations. -- [Add Prisma ORM to an existing PostgreSQL project](/prisma-orm/add-to-existing-project/postgresql): the same `orm init`, `contract infer`, `db sign` flow without the ORM context. +- [Add Prisma ORM to an existing PostgreSQL database](/prisma-orm/add-to-existing-project/postgresql): the same `orm init`, `contract infer`, `db sign` flow without the ORM context. diff --git a/apps/docs/content/docs/orm/extensions/using-extensions.mdx b/apps/docs/content/docs/orm/extensions/using-extensions.mdx index c7914e991f2..1f3210064a1 100644 --- a/apps/docs/content/docs/orm/extensions/using-extensions.mdx +++ b/apps/docs/content/docs/orm/extensions/using-extensions.mdx @@ -12,7 +12,7 @@ Reach for an extension when your application needs one of those database feature Your contract is what Prisma ORM 8 calls your schema: `contract.prisma` in place of `schema.prisma`. In a project made with `npm create prisma@latest` it is at `src/prisma/contract.prisma`. -Adding an extension means installing its package and then registering it in two places, your config file and your client. These steps use pgvector, the vector search extension, as the example, and they assume a PostgreSQL project from the [quickstart](/prisma-orm/quickstart/postgresql), so `@prisma/orm-postgres` is already installed and the extension package is added next to it. Supabase is set up differently, so if that is the extension you are adding, read [the note under the catalog](#available-extensions) first. +Adding an extension means installing its package and then registering it in two places, your config file and your client. These steps use pgvector, the vector search extension, as the example, and they assume a PostgreSQL project from [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql), so `@prisma/orm-postgres` is already installed and the extension package is added next to it. Supabase is set up differently, so if that is the extension you are adding, read [the note under the catalog](#available-extensions) first. ## 1. Install the package @@ -222,6 +222,6 @@ If the extension you need does not exist yet, you can build it. An extension is - [Advanced queries](/orm/fundamentals/advanced-queries): the SQL query builder, where extension operations like `cosineDistance` appear - [How middleware works](/orm/middleware/how-middleware-works) for wrapping queries rather than adding database features -- [Quickstart with PostgreSQL](/prisma-orm/quickstart/postgresql) to set up a project to add extensions to +- [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) to set up a project to add extensions to - [Extensions overview](/orm/extensions) for the full catalog, including middleware - [Prisma ORM overview](/orm) for how your contract, your migrations, and your client fit together diff --git a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx index 823a07f37c0..f33fdc9a33b 100644 --- a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx +++ b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx @@ -16,7 +16,7 @@ The steps that follow build a query logger that prints every query with its row ## Prerequisites -- A Prisma ORM project with a working `src/prisma/db.ts`, the file where the client is created, because that is where middleware is registered. If you already have a project, you can use the `db.ts` you have. You also need a PostgreSQL database to run against, because `db.ts` reads its connection string from the `DATABASE_URL` environment variable, which you export in the shell you run the commands from. The [PostgreSQL quickstart](/prisma-orm/quickstart/postgresql) sets both up in a few minutes: +- A Prisma ORM project with a working `src/prisma/db.ts`, the file where the client is created, because that is where middleware is registered. If you already have a project, you can use the `db.ts` you have. You also need a PostgreSQL database to run against, because `db.ts` reads its connection string from the `DATABASE_URL` environment variable, which you export in the shell you run the commands from. [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) sets both up in a few minutes: ```npm npm create prisma@latest -- --provider postgres --no-deploy 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 58c9b209894..0048efb3076 100644 --- a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx +++ b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx @@ -6,7 +6,7 @@ metaTitle: Generating a migration in Prisma ORM metaDescription: 'A tutorial for the migration plan command, from a contract change to a migration you can review, without connecting to a database.' --- -This tutorial takes a change you have made to your contract, the `contract.prisma` file that replaced `schema.prisma`, and turns it into a migration that you read and approve before it runs against a database. To create a project first, see the [quickstart](/prisma-orm/quickstart/postgresql). +This tutorial takes a change you have made to your contract, the `contract.prisma` file that replaced `schema.prisma`, and turns it into a migration that you read and approve before it runs against a database. To create a project first, see [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). Two commands do the work, and you run them in this order every time you change your contract. `npx prisma contract emit` replaces `prisma generate`: it reads `contract.prisma` and writes `contract.json` and `contract.d.ts` next to it, so that everything downstream reads your latest edit and not the version before it. `npx prisma migration plan` then reads `contract.json` and writes a new migration for the change, without applying it. Planning never connects to a database, which means you can run it in CI or in a sandbox with no database credentials. To work out what your change is a change from, `migration plan` looks by default at the `db` [ref](/orm/migrations/the-migration-graph#terms-used-on-this-page), a file in `migrations/app/refs/` that records the contract version you last applied in development. 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 249e53d3785..f2bfd269ec6 100644 --- a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx +++ b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx @@ -19,7 +19,7 @@ You run this loop many times a day: 3. **Review it**: before anything touches the database, run `npx prisma migration show ` to see the operations and SQL that `db migrate` will run. If you want the migration to change rows as well, [edit `migration.ts` and recompile it](/orm/migrations/editing-a-migration) by running `node migrations/app//migration.ts` from your project root, which rewrites `ops.json`. Nothing extra is needed to run that file, because the Prisma ORM CLI already requires Node.js 22.18 or later, which runs `migration.ts` directly. 4. **Apply it**: `db migrate` starts by reading the database's marker, the record in the database of which contract state it matches, so it knows how much of your history the database has already seen, and then runs the migrations from that state to your current contract. In development, add [`--advance-ref db`](/orm/migrations/generating-a-migration#the-db-ref-skipping---from) so the next `migration plan` starts from what you just applied. -This example uses the contract from [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration), whose `User` model is stored in the table `user` because it sets `@@map("user")`. Its first migration is already applied, with `npx prisma db migrate --advance-ref db`, and a database connection is set up as in the [quickstart](/prisma-orm/quickstart/postgresql). Add an optional `phone String?` field to `User`, then run: +This example uses the contract from [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration), whose `User` model is stored in the table `user` because it sets `@@map("user")`. Its first migration is already applied, with `npx prisma db migrate --advance-ref db`, and a database connection is set up as in [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). Add an optional `phone String?` field to `User`, then run: ```npm npx prisma contract emit diff --git a/apps/docs/content/docs/orm/supported-databases.mdx b/apps/docs/content/docs/orm/supported-databases.mdx index f2861c3eca4..34c3b7a7bc0 100644 --- a/apps/docs/content/docs/orm/supported-databases.mdx +++ b/apps/docs/content/docs/orm/supported-databases.mdx @@ -18,7 +18,7 @@ Prisma ORM 8 ships one library per database, and installing the one that matches | Microsoft SQL Server | Coming soon | | | | CockroachDB | Coming soon | | | -`npm create prisma@latest -- my-app` asks which database you use and installs the right library for you. See the [PostgreSQL quickstart](/prisma-orm/quickstart/postgresql) or the [MongoDB quickstart](/prisma-orm/quickstart/mongodb). +`npm create prisma@latest -- my-app` asks which database you use and installs the right library for you. See [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql) or [Create a new app with MongoDB](/prisma-orm/quickstart/mongodb). ## What the labels mean From 4b50597b46e6d75c4d658f523d0e25788b0cf670 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 30 Sep 2026 08:15:05 +0200 Subject: [PATCH 2/7] docs(orm): keep Quickstart twins in the Getting Started sidebar, and fix reader marks The MongoDB twins and from-scratch were no longer in any meta.json, so they opened with the top-level "All docs" sidebar. A meta.json can now name pages under `hiddenPages`: they belong to that folder, so they keep its section's sidebar, but the sidebar and the previous/next links do not list them. The Quickstart folder uses it for its four hidden pages and still shows exactly four entries. The orphaned add-to-existing-project/meta.json is removed. The PostgreSQL page for an existing database now uses the flags form of orm init, explains which Node.js versions need temporal-polyfill for date and time columns and where the import goes, shows how to model a table in another PostgreSQL schema, and says that db sign fails when a table with row-level security policies has no model. The MongoDB pages say why the id field is _id in queries and results. All four existing-app pages get the fixes from two cold reader rounds. Every new command and output comes from runs against prisma 8.0.0-rc.19 and the ORM packages at 8.0.0-rc.13. Agent: nimue-20 Signed-off-by: willbot Signed-off-by: Will Madden Co-Authored-By: Claude Opus 5.5 --- .../add-to-existing-project/meta.json | 4 - .../add-to-existing-project/mongodb.mdx | 124 ++++++++------ .../add-to-existing-project/postgresql.mdx | 159 +++++++++++------- .../quickstart/existing-app/mongodb.mdx | 38 +++-- .../quickstart/existing-app/postgresql.mdx | 32 ++-- .../(index)/prisma-orm/quickstart/meta.json | 6 + apps/docs/source.config.ts | 6 +- apps/docs/src/lib/hidden-pages.test.ts | 74 ++++++++ apps/docs/src/lib/hidden-pages.ts | 86 ++++++++++ apps/docs/src/lib/source.ts | 3 +- apps/docs/src/lib/versioned-sidebar-tree.ts | 5 + 11 files changed, 383 insertions(+), 154 deletions(-) delete mode 100644 apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/meta.json create mode 100644 apps/docs/src/lib/hidden-pages.test.ts create mode 100644 apps/docs/src/lib/hidden-pages.ts diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/meta.json b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/meta.json deleted file mode 100644 index 84c814653c2..00000000000 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Add to Existing Project", - "pages": ["postgresql", "mongodb"] -} diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx index 3a5f3e06fad..b2a94707390 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx @@ -8,9 +8,11 @@ metaDescription: Add Prisma ORM to an existing MongoDB project. This page uses MongoDB. [Use PostgreSQL instead](/prisma-orm/add-to-existing-project/postgresql). -To add Prisma ORM to a project that already uses MongoDB, you will run `orm init`, describe the collections you want to work with, emit the generated artifacts, and run a couple of queries. +On this page you add Prisma ORM to an app whose MongoDB database already has collections. You run `orm init`, write a contract that describes your collections, and run two queries. The contract is the file that holds your models. In earlier Prisma ORM versions, it was `schema.prisma`. -Use this path when you already have an application and database. Make sure the app can already reach its MongoDB deployment and runs on Node.js 22.18 or newer (on the 24 line, 24.11 or newer; Node.js 24 is recommended). If your database has no collections yet, follow [Add Prisma ORM and MongoDB to an existing app](/prisma-orm/quickstart/existing-app/mongodb) instead. If you want Prisma ORM to create a new app for you, follow [Create a new app with MongoDB](/prisma-orm/quickstart/mongodb). +Your app must reach its MongoDB database and run on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. A single `mongod` server is enough. You need a replica set only for transactions and change streams, and MongoDB Atlas already runs one. + +If your database has no collections yet, follow [Add Prisma ORM and MongoDB to an existing app](/prisma-orm/quickstart/existing-app/mongodb) instead, which creates the collections for you. If you want Prisma ORM to create a new app for you, follow [Create a new app with MongoDB](/prisma-orm/quickstart/mongodb). :::note[Using Prisma ORM 7?] @@ -20,13 +22,9 @@ For what release candidate means, when the final release is expected, and how to ::: -A standalone `mongod` is enough for the steps below. A replica set is only needed for transactions and change streams; MongoDB Atlas already gives you one. - -## 1. Make sure you can run the example script +## 1. Install `tsx` -If your project already runs TypeScript scripts, you can skip this step. - -Otherwise, install the script tooling: +The scripts on this page run with `tsx`. If your project does not have it, install it: ```npm npm install --save-dev tsx typescript @@ -34,64 +32,67 @@ npm install --save-dev tsx typescript ## 2. Initialize Prisma ORM -From the root of your existing project, run: +The `orm init` command below changes your `tsconfig.json` and your `package.json`. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. If it has `"type": "commonjs"`, the command keeps it and prints a warning. If your app runs as CommonJS, for example because it loads files with `require` or because `tsc` compiles it to `require` calls, follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start your app again. `tsx` runs the scripts on this page in both kinds of app, so you can finish this page first. + +From the root of your project, run: ```npm -npx prisma@latest orm init --target mongodb +npx prisma@latest orm init --yes --target mongodb --authoring psl --write-env ``` -This command is for a project that already exists: it preselects MongoDB, adds Prisma ORM files and package scripts to the app you already have, and does not scaffold a new framework project. +`prisma@latest` runs Prisma ORM 8, and `--target mongodb` picks MongoDB. `--authoring psl` picks PSL, the Prisma Schema Language, which is the `.prisma` file format you know from earlier Prisma ORM versions. `--write-env` writes a `.env` file, unless you already have one. `--yes` accepts the default answer to every question, so the command asks nothing. -`orm init` also changes the `module` settings in `tsconfig.json`, and adds `"type": "module"` to `package.json` when the file has no `"type"` field. If your app is CommonJS, follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you run the app again. +The command installs the Prisma ORM packages and writes its files. You use three of them on this page: -It also adds `prisma-8.md`, a short project-level reference your coding agent can read. It does not install agent skills; the Prisma ORM skill ships inside the `@prisma/orm-mongo` package your project installs. If you later run `prisma init` or `prisma skills sync`, Prisma writes skill files for coding agents into your repo. To stop that, pass `--skills=none` to [`init`](/cli/init) or set the [`skills.agents`](/cli/configuration#agent-skills) config field to `[]`; the next [`skills sync`](/cli/skills) removes any copies already written. +- `src/prisma/contract.prisma`, an example contract. In step 4 you change it to describe your collections. +- `src/prisma/db.ts`, the file your code imports to run queries. +- `.env`, which holds the connection string. -When Prisma ORM asks the remaining setup questions: +The command also writes `prisma-8.md`, a short reference for writing queries. You do not need it for this page. -- choose `PSL` -- keep the default schema path, `src/prisma/contract.prisma`. Pass `--schema-path` if you want the contract somewhere else; the rest of this page assumes the default. -- answer the last question, `Also write a .env file from .env.example? (gitignored)`, with Yes. It defaults to No, and `--write-env` skips the prompt and writes the file. +From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. You can ignore it, because it does not change what the command does. Agent skills are instruction files that AI coding tools read, and the line appears because your project has none yet. To add them and stop the line, run [`npx prisma@latest init`](/cli/init). In Prisma ORM 8, `init` adds the skills and a `postinstall` script that keeps them up to date, and it leaves your contract and your `.env` alone. `orm init` is the command that sets up Prisma ORM. ## 3. Set your database connection string -`orm init` always writes `.env.example`, and writes `.env` only if you asked it to. Put the connection string for the MongoDB deployment your app already uses into `.env`: +If you had no `.env`, `orm init` wrote one with a placeholder, `DATABASE_URL="mongodb://user:password@localhost:27017/mydb"`. Set `DATABASE_URL` in `.env` to the connection string of the database your app already uses: ```text title=".env" -DATABASE_URL="mongodb://127.0.0.1:27017/app?replicaSet=rs0" +DATABASE_URL="mongodb://username:password@host:27017/database" ``` -`orm init` also writes `src/prisma/db.ts`, the file your application imports. It builds the Prisma ORM client from the emitted contract and reads the connection string from the environment: +The part after the last `/`, and before any `?`, is the name of the database. + +`orm init` wrote `src/prisma/db.ts`, and you do not need to change it: ```typescript title="src/prisma/db.ts" -import "dotenv/config"; -import mongo from "@prisma/orm-mongo/runtime"; -import type { Contract } from "./contract.d"; -import contractJson from "./contract.json" with { type: "json" }; +import 'dotenv/config'; +import mongo from '@prisma/orm-mongo/runtime'; +import type { Contract } from './contract.d'; +import contractJson from './contract.json' with { type: 'json' }; export const db = mongo({ contractJson, - url: process.env["DATABASE_URL"]!, + url: process.env['DATABASE_URL']!, }); ``` -The first line is `import "dotenv/config"`, so any script that imports `db` loads `.env` for itself. You do not need to pass the URL again at the call site. - -## 4. Describe the collections you want Prisma ORM to know about +The first line loads `.env`, so every file that imports `db` reads `DATABASE_URL` from there. The two `contract` files it imports are written by `contract emit` in step 5. -This is the key adoption step for MongoDB, because you decide which part of the existing database Prisma ORM should model first. +## 4. Describe your collections in the contract -PostgreSQL has `contract infer`, but MongoDB does not, so this step is manual. +Prisma ORM cannot read a MongoDB database to write the contract for you, so you write it yourself. Describe only the collections that your code reads and writes through Prisma ORM. The other collections stay as they are. -Open `src/prisma/contract.prisma` and make it match the collections you want Prisma ORM to query first. If your existing database already has `users` and `posts` collections with `email`, `name`, `title`, and `authorId`, the starter contract is already a useful first draft: +The example contract in `src/prisma/contract.prisma` describes a `users` collection and a `posts` collection: ```prisma title="src/prisma/contract.prisma" // use prisma-8 model User { - id ObjectId @id @map("_id") - email String @unique - name String? - posts Post[] + id ObjectId @id @map("_id") + email String @unique + username String? + name String? + posts Post[] @@map("users") } @@ -105,25 +106,25 @@ model Post { } ``` -You do not need to model every collection on day one. Start with the part of the database you want to read and write first. +Keep the first line, because `contract emit` reads only `.prisma` files that start with it. `@@map("users")` names the collection that stores the model. MongoDB stores the identifier of every document in `_id`. On MongoDB, `contract emit` names each field in `contract.json` by the name in its `@map`, so in queries and in results you use `_id`, not `id`. The same goes for any other field with `@map`. -## 5. Emit the generated artifacts +Change the models to match your documents: one model for each collection, with one field for each field of its documents. [Data modeling](/orm/data-modeling) lists the field types. -Once the contract looks right, this step turns it into the generated files the runtime and query APIs use. +## 5. Generate the files your code imports -Run: +`contract emit` takes the place of `prisma generate`, and you run it after every change to the contract: ```npm npx prisma contract emit ``` -This refreshes `src/prisma/contract.json` and `src/prisma/contract.d.ts` so the runtime and query APIs match the contract you just reviewed. +The command writes `src/prisma/contract.json` and `src/prisma/contract.d.ts`, and `db.ts` imports both of them. Commit them, because your app cannot run without them. -## 6. Run a simple high-level query +## 6. Query a collection with `db.orm` -With the emitted artifacts in place, you can test the higher-level API first and confirm Prisma ORM can read the existing collections. +`db.orm` queries your models, the way Prisma Client did in earlier Prisma ORM versions. On MongoDB you reach a model by the name of its collection, which is the name in `@@map`. So the `User` model is `db.orm.users`. -Create a `script.ts` file: +Create `script.ts` with the code below, and put your own names in it: replace `users` with the name of one of your collections, and replace `email` and `existing@example.com` with a field and a value from its documents. ```typescript title="script.ts" import { db } from "./src/prisma/db"; @@ -147,11 +148,20 @@ Run it: npx tsx script.ts ``` -## 7. Run a simple low-level query +```text no-copy +{ + username: undefined, + _id: '6abca6a1e7a9bb8d8c716f65', + email: 'existing@example.com', + name: 'Existing User' +} +``` + +The document has no `username` field, so the result shows it as `undefined`. If no document matches, the script prints `null`. -After the ORM example, this step shows the lower-level MongoDB pipeline builder against the same existing collections. +## 7. Query a collection with a pipeline -Pipeline plans run through the runtime. On MongoDB `db.runtime()` returns a promise, so it has to be awaited; on PostgreSQL the same call is synchronous. +`db.query` builds a MongoDB aggregation pipeline on a collection, which it names as it is stored in MongoDB. `.build()` returns the pipeline, and `runtime.query()` runs it, where `runtime` is the object that `await db.runtime()` returns. Replace `users`, `email`, and the value with your own again. Replace `script.ts` with this version: @@ -160,13 +170,13 @@ import { db } from "./src/prisma/db"; async function main() { const runtime = await db.runtime(); - const plan = db.query + const query = db.query .from("users") .match((fields) => fields.email.eq("existing@example.com")) .project("email", "name") .build(); - const rows = await runtime.query(plan); + const rows = await runtime.query(query); console.log(rows); await db.close(); @@ -184,12 +194,18 @@ Run it again: npx tsx script.ts ``` -## 8. Next steps +```text no-copy +[ + { + email: 'existing@example.com', + name: 'Existing User', + _id: '6abca6a1e7a9bb8d8c716f65' + } +] +``` -When you change `src/prisma/contract.prisma`, emit the contract again: +## 8. Next steps -```npm -npx prisma contract emit -``` +When you change `src/prisma/contract.prisma`, run `npx prisma contract emit` again. -You do not need a migration just to read collections that already exist. Use [migration plan](/cli/migration-plan) when you want Prisma ORM to own a schema change. +You can read and write documents in collections that already exist without a migration. Use [`migration plan`](/cli/migration-plan) when you want Prisma ORM to create or change collections and indexes. 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 e6565e10f47..1db41f76f35 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 @@ -8,9 +8,11 @@ metaDescription: Add Prisma ORM to an existing PostgreSQL project. This page uses PostgreSQL. [Use MongoDB instead](/prisma-orm/add-to-existing-project/mongodb). -On this page you add Prisma ORM to an app whose PostgreSQL database already has tables. The contract is the file that holds your models, and in Prisma ORM 7 it was `schema.prisma`. You run `orm init`, generate the contract from your tables, run two queries, and apply your first schema change. +On this page you add Prisma ORM to an app whose PostgreSQL database already has tables. You run `orm init`, generate the contract from your tables, run two queries, and apply your first change to the tables. The contract is the file that holds your models. In Prisma ORM 7, it was `schema.prisma`. -Use this path when you already have an application and database. Make sure the app can already reach its PostgreSQL database and runs on Node.js 22.18 or newer (on the 24 line, 24.11 or newer; Node.js 24 is recommended). If your database has no tables yet, follow [Add Prisma ORM and PostgreSQL to an existing app](/prisma-orm/quickstart/existing-app/postgresql) instead. If you want Prisma ORM to create a new app for you, follow [Create a new app with PostgreSQL](/prisma-orm/quickstart/postgresql). +Your app must reach its PostgreSQL database and run on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. 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). :::note[Using Prisma ORM 7?] @@ -20,11 +22,9 @@ For what release candidate means, when the final release is expected, and how to ::: -## 1. Make sure you can run the example script - -If your project already runs TypeScript scripts, you can skip this step. +## 1. Install `tsx` -Otherwise, install the script tooling: +The scripts on this page run with `tsx`. If your project does not have it, install it: ```npm npm install --save-dev tsx typescript @@ -32,53 +32,53 @@ npm install --save-dev tsx typescript ## 2. Initialize Prisma ORM -From the root of your existing project, run: +The `orm init` command below changes your `tsconfig.json` and your `package.json`. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. If it has `"type": "commonjs"`, the command keeps it and prints a warning. If your app runs as CommonJS, for example because it loads files with `require` or because `tsc` compiles it to `require` calls, follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start your app again. `tsx` runs the scripts on this page in both kinds of app, so you can finish this page first. + +From the root of your project, run: ```npm -npx prisma@latest orm init --target postgres +npx prisma@latest orm init --yes --target postgres --authoring psl --write-env ``` -This command is for a project that already exists: it preselects PostgreSQL, adds Prisma ORM files and package scripts to the app you already have, and does not scaffold a new framework project. +`prisma@latest` runs Prisma ORM 8, and `--target postgres` picks PostgreSQL. `--authoring psl` picks PSL, the Prisma Schema Language, which is the `.prisma` file format you know from Prisma ORM 7. `--write-env` writes a `.env` file, unless you already have one. `--yes` accepts the default answer to every question, so the command asks nothing. -`orm init` also changes the `module` settings in `tsconfig.json`, and adds `"type": "module"` to `package.json` when the file has no `"type"` field. If your app is CommonJS, follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you run the app again. The scripts in this guide run through `tsx`, which works in both kinds of project. +The command installs the Prisma ORM packages and writes its files. You use three of them on this page: -It also adds `prisma-8.md`, a short project-level reference your coding agent can read. It does not install agent skills; the Prisma ORM skill ships inside the `@prisma/orm-postgres` package your project installs. From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. The skills are instruction files for coding agents, and the line does not change what the command does. If you want the skills, [`npx prisma@latest init`](/cli/init) installs them, which also stops the line. The output on this page leaves the line out. If you later run `prisma init` or `prisma skills sync`, Prisma writes skill files for coding agents into your repo. To stop that, pass `--skills=none` to [`init`](/cli/init) or set the [`skills.agents`](/cli/configuration#agent-skills) config field to `[]`; the next [`skills sync`](/cli/skills) removes any copies already written. +- `src/prisma/contract.prisma`, an example contract. Step 4 replaces it with a contract generated from your tables. +- `src/prisma/db.ts`, the file your code imports to run queries. +- `.env`, which holds the connection string. -When Prisma ORM asks the remaining setup questions: +The command also writes `prisma-8.md`, a short reference for writing queries. You do not need it for this page. -- choose `PSL` -- keep the default schema path, `src/prisma/contract.prisma`. Pass `--schema-path` if you want the contract somewhere else; the rest of this page assumes the default. -- answer the last question, `Also write a .env file from .env.example? (gitignored)`, with Yes. It defaults to No, and `--write-env` skips the prompt and writes the file. +From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. You can ignore it, because it does not change what the command does. Agent skills are instruction files that AI coding tools read, and the line appears because your project has none yet. To add them and stop the line, run [`npx prisma@latest init`](/cli/init). In Prisma ORM 8, `init` adds the skills and a `postinstall` script that keeps them up to date, and it leaves your contract and your `.env` alone. `orm init` is the command that sets up Prisma ORM. ## 3. Set your database connection string -`orm init` always writes `.env.example`, and writes `.env` only if you asked it to. Put the connection string for the database your app already uses into `.env`: +If you had no `.env`, `orm init` wrote one with a placeholder, `DATABASE_URL="postgresql://user:password@localhost:5432/mydb"`. Set `DATABASE_URL` in `.env` to the connection string of the development copy of your database: ```text title=".env" DATABASE_URL="postgres://username:password@host:5432/database?sslmode=require" ``` -`orm init` also writes `src/prisma/db.ts`, the file your application imports. It builds the Prisma ORM client from the emitted contract and reads the connection string from the environment: +`orm init` wrote `src/prisma/db.ts`, and you do not need to change it: ```typescript title="src/prisma/db.ts" -import "dotenv/config"; -import postgres from "@prisma/orm-postgres/runtime"; -import type { Contract } from "./contract.d"; -import contractJson from "./contract.json" with { type: "json" }; +import 'dotenv/config'; +import postgres from '@prisma/orm-postgres/runtime'; +import type { Contract } from './contract.d'; +import contractJson from './contract.json' with { type: 'json' }; export const db = postgres({ contractJson, - url: process.env["DATABASE_URL"]!, + url: process.env['DATABASE_URL']!, }); ``` -The first line is `import "dotenv/config"`, so any script that imports `db` loads `.env` for itself. You do not need to pass the URL again at the call site. - -## 4. Infer a starter contract from the live database +The first line loads `.env`, so every file that imports `db` reads `DATABASE_URL` from there. The two `contract` files it imports are written by `contract emit` in step 5. -This step gives you a starting contract by reading the schema that already exists in PostgreSQL. +## 4. Generate the contract from your tables -Run: +`contract infer` reads the tables in your database and writes a contract that describes them. It does what `prisma db pull` did in Prisma ORM 7. Run: ```npm npx prisma contract infer --output ./src/prisma/contract.prisma @@ -87,12 +87,13 @@ npx prisma contract infer --output ./src/prisma/contract.prisma ```text no-copy ✔ Connecting to database... ✔ Introspecting database schema... +Overwriting existing file: src/prisma/contract.prisma │ database: postgres://****@127.0.0.1:54329/legacy ✔ Contract written to src/prisma/contract.prisma ``` -The command writes a first draft of `src/prisma/contract.prisma`. For a database with a `user` table and a `post` table, the draft looks like this: +The command replaces the example contract from step 2. For a database with a `user` table and a `post` table, the new contract looks like this: ```prisma title="src/prisma/contract.prisma" // use prisma-8 @@ -135,9 +136,11 @@ namespace public { } ``` -`contract infer` reads these parts of the database and writes each one into the draft: +Keep the first line, because `contract emit` reads only `.prisma` files that start with it. `namespace public` holds the models of the tables in the PostgreSQL schema `public`. Where Prisma ORM 7 wrote `DateTime @db.Timestamptz`, the contract writes `Timestamptz`, and `String @db.VarChar(200)` becomes `VarChar(200)`. In the policy block, `roles = [public]` is the PostgreSQL role `PUBLIC`, not the schema. -| In the database | In the draft above | +`contract infer` reads these parts of the database and writes each one into the contract: + +| In the database | In the contract above | | --- | --- | | Primary keys and unique constraints | `@id`, `@unique` | | Column defaults | `@default("member")`, `@default(now())` | @@ -146,39 +149,68 @@ namespace public { | Indexes, including an index on part of a table and an index on an expression | the three `@@index` lines | | Row-level security and its policies | `@@rls` and the `policy_select` block | -`contract infer` reads only the PostgreSQL schema named `public`. It skips tables in any other schema and prints no message about them. +Review the file before you go on. You can rename models, and you can remove the models of tables you do not want to use yet. A model uses the table with exactly the model's name, unless the model has `@@map`. So for the table `user`, `contract infer` wrote the model `User` with `@@map("user")`. Keep the `@@map` lines when you rename a model, so that the model still reads the same table. -Open that file and review it before you go on. This is the moment to clean up model names, keep only the tables you want Prisma ORM to know about first, and make the file easier to read. A model's table is the model name exactly as written, so a table such as `User` gets a model with no `@@map`, and a table such as `user` or `user_profile` gets `@@map` with its name. Keep those `@@map` lines when you rename a model, so the table stays the same. +A table without a model stays in your database, and later migrations leave it alone. Do not remove the model of a table that has row-level security policies, though. If you do, `db sign` in step 6 fails, because it finds policies that the contract does not declare. -:::note[Temporal types on inferred date and time columns] +### Date and time columns on Node.js 24 and older -`contract infer` maps `timestamp` columns to `Timestamp` and `timestamptz` columns to `Timestamptz`. Both read and write their values through the global `Temporal` API. Node.js 26 ships it enabled by default (check with `node -p "typeof Temporal"`, which prints `object` when it is there); on Node.js 24 and earlier, reading such a column fails with `RUNTIME.TEMPORAL_UNAVAILABLE` unless you install [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill) and add `import "temporal-polyfill/full/global";` before the first query. If you would rather not add the polyfill, change the field's type in the contract to `TimestamptzString` and read and write PostgreSQL's own text instead. +`contract infer` gives a `timestamptz` column the type `Timestamptz`, and a `timestamp` column the type `Timestamp`. Prisma ORM returns the values of these columns as `Temporal` objects. `Temporal` is the new date and time API of JavaScript. Node.js 26 has it built in. Node.js 24 and older do not, and there the first query that reads such a column fails with `RUNTIME.TEMPORAL_UNAVAILABLE`. -::: +On Node.js 24 or older, install the `temporal-polyfill` package: -## 5. Emit the generated artifacts +```npm +npm install temporal-polyfill +``` -Once the contract looks right, this step turns it into the generated files the runtime and CLI use. +Then add this line at the top of `src/prisma/db.ts`: -After you are happy with the contract, run: +```typescript title="src/prisma/db.ts" +import "temporal-polyfill/global"; +``` + +If you would rather not add the package, change the type of each such field in the contract: `Timestamptz` becomes `TimestamptzString`, and `Timestamp` becomes `TimestampString`. The field then holds the text that PostgreSQL returns, such as `2026-09-30 07:36:38.60182+02`, and needs no `Temporal`. The column in the database stays as it is. + +### Tables in other PostgreSQL schemas + +`contract infer` reads only the PostgreSQL schema named `public`. It skips tables in any other schema and prints no message about them. + +To use a table from another schema, write its model by hand inside a `namespace` block with the name of that schema. For a table `event` in the schema `audit`, add this to the end of the contract: + +```prisma title="src/prisma/contract.prisma" +namespace audit { + model Event { + id Int @id @default(autoincrement()) + message String + + @@map("event") + } +} +``` + +`db sign` in step 6 checks this table like the tables in `public`. Your code reaches the model as `db.orm.audit.Event`. + +## 5. Generate the files your code imports + +`contract emit` takes the place of `prisma generate`, and you run it after every change to the contract: ```npm npx prisma contract emit ``` -This refreshes `src/prisma/contract.json` and `src/prisma/contract.d.ts` so the runtime and query APIs match the contract you just reviewed. +The command writes `src/prisma/contract.json` and `src/prisma/contract.d.ts`, and `db.ts` imports both of them. Commit them, because your app cannot run without them. -If the inferred contract has a policy, a check, or an index that contains SQL text, `contract emit` prints one warning for each, and still writes both files. Each warning starts like this: +If the contract has a policy, a check, or an index that contains SQL text, `contract emit` prints one warning for each, and still writes both files. Each warning starts like this: ```text no-copy (node:15169) [PN_EXACT_NAME_BODY_COMPARISON] Warning: check "user_age_check" uses map: with a SQL body. ``` -These warnings are expected on a contract that `contract infer` wrote, and you do not need to change anything. +You can ignore these warnings on a contract that `contract infer` wrote. They are about SQL text that you write by hand, which Prisma ORM compares character by character with the text that PostgreSQL reports. ## 6. Sign the database -Record that the live database matches the emitted contract: +`db sign` checks that your database has what the contract describes. Then it records which contract the database matches. `migration plan` in step 9 needs that record to start from the tables you already have, instead of from an empty database. ```npm npx prisma db sign @@ -199,7 +231,7 @@ to: 596586f61799d5b2585df874a00f8d6f12d73a522d2eefbcbec62dba4e9904a4 ✔ Advanced ref "db" → 596586f61799d5b2585df874a00f8d6f12d73a522d2eefbcbec62dba4e9904a4 ``` -Before it writes anything, `db sign` checks that the database has everything the contract declares. A table or a column that the database has and the contract does not declare is not a problem. When something the contract declares is missing from the database, `db sign` writes nothing and exits with code 4. For example, with a `phone` field in the `User` model and no `phone` column in the table: +A table or a column that the database has and the contract does not declare is not a problem. When something the contract declares is missing from the database, `db sign` writes nothing and exits with code 4. For example, with a `phone` field in the `User` model and no `phone` column in the table: ```text no-copy ✘ Schema issues @@ -211,18 +243,19 @@ Before it writes anything, `db sign` checks that the database has everything the To fix it, remove from the contract what the database does not have, run `npx prisma contract emit`, and sign again. -When the check passes, `db sign` stores a record in the database of which contract it matches. The record holds the hash of the contract, which is the long hexadecimal text after `to:` in the output. The command also writes two things into your project: a copy of the contract under `migrations/snapshots/`, and the `db` ref, which is the file `migrations/app/refs/db.json` and holds the same hash. A later [migration plan](/cli/migration-plan) reads them, so it starts from the tables you just adopted instead of from an empty database. Commit the `migrations/` directory. +When the check passes, `db sign` stores a record in the database and writes files into your project: -This step matters in two common cases: +- A record in the database of which contract it matches, in the table `prisma_contract.marker`. The record holds the hash of the contract, which is the long text after `to:` in the output. +- A copy of the contract, under `migrations/snapshots/` in your project. +- The `db` ref, which is the file `migrations/app/refs/db.json`. It holds the same hash. The line `Advanced ref "db"` in the output means that the command wrote this file. -- the database has never been signed by Prisma ORM before -- the database was signed earlier, but under an older contract hash +The next [`migration plan`](/cli/migration-plan) reads the copy and the `db` ref, so it starts from the tables you already have. Commit the `migrations/` directory. -## 7. Run a simple high-level query +Until you plan your first migration, you can add models for tables that are already in the database. Run `npx prisma contract emit` and then `npx prisma db sign` again, which checks the database against the new contract and replaces the record. -With the database signed, you can test the higher-level API first and confirm Prisma ORM is reading the existing schema correctly. +## 7. Query a model with `db.orm` -Create `script.ts` with the code below, which reads the `User` model from step 4. Use one of your own models and its fields in its place: +`db.orm` queries your models, the way Prisma Client did in Prisma ORM 7. Create `script.ts` with the code below, which reads the `User` model from step 4. Use one of your own models and its fields in its place: ```typescript title="script.ts" import { db } from "./src/prisma/db"; @@ -257,11 +290,9 @@ npx tsx script.ts ] ``` -## 8. Run a simple low-level query - -After the ORM example, this step shows the lower-level SQL builder against the same existing schema. +## 8. Query a table with `db.sql` -The SQL builder names the table, where the ORM API names the model. This example reads the table `user`, which the `User` model in step 4 maps with `@@map("user")`. For a model without `@@map`, the table has the name of the model. +`db.sql` builds SQL queries: where `db.orm` names models and fields, `db.sql` names tables and columns as they are in the database. This example reads the table `user`, which the `User` model maps with `@@map("user")`. `.build()` returns the query without running it, and `db.runtime().query()` runs it. Replace `script.ts` with this version: @@ -269,12 +300,12 @@ Replace `script.ts` with this version: import { db } from "./src/prisma/db"; async function main() { - const plan = db.sql.public.user + const query = db.sql.public.user .select("id", "email", "name") .limit(2) .build(); - const rows = await db.runtime().query(plan); + const rows = await db.runtime().query(query); console.log(rows); await db.close(); @@ -299,9 +330,9 @@ npx tsx script.ts ] ``` -## 9. Make your first schema change +## 9. Make your first change to the tables -From here on, you change the database by changing the contract. Add a field to a model in `src/prisma/contract.prisma`. This example adds `phone` to the `User` model from step 4, so use a model and a field of your own: +From here on, you change the tables by changing the contract. Add a field to a model in `src/prisma/contract.prisma`. This example adds `phone` to the `User` model from step 4, so use a model and a field of your own: ```prisma title="src/prisma/contract.prisma" model User { @@ -311,7 +342,7 @@ From here on, you change the database by changing the contract. Add a field to a phone String? // [!code ++] ``` -Emit the contract again, then plan a migration. `migration plan` writes the difference between the new contract and the one that `db sign` recorded into a new directory under `migrations/app/`. `--name` sets the name of that directory. +Generate the files again, then plan a migration. `migration plan` compares the new contract with the last one you signed or applied, and writes the difference into a new directory under `migrations/app/`. `--name` sets the end of the directory's name, after the date and time. ```npm npx prisma contract emit @@ -345,7 +376,9 @@ baseline: migrations/app/20260929T2130_baseline app space: migrations/app/20260929T2131_add_user_phone ``` -The output continues with a preview of the SQL. The first plan writes two directories. The baseline records the tables you adopted. It lists `Create table` operations, and the next command runs none of them on your database. The second directory is your change. Commit both directories. [The automatic baseline](/cli/migration-plan#the-automatic-baseline) explains when `migration plan` writes a baseline. +The output continues with a preview of the SQL. The first plan writes two directories. The baseline describes the tables you had when you ran `db sign`. It lists `Create table` operations, but `db migrate` does not run them on a database that already has those tables. The second directory is your change. Commit both directories. [The automatic baseline](/cli/migration-plan#the-automatic-baseline) explains when `migration plan` writes a baseline. + +You can ignore the word `space` in the output, because all your migrations are in `migrations/app/`. Apply the migration: @@ -367,15 +400,15 @@ App space ✔ Advanced ref "db" → 4ef74b97c298402786f23bf299e17baba815e8d521bc90aaab59ab7de747c969 ``` -`db migrate` reads the record that `db sign` stored to see which contract the database already has, so only your change runs, and the rows in your tables stay as they are. `--advance-ref db` updates the `db` ref to the new hash, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. +`db migrate` runs only the migrations that the database does not have yet. Here it adds the `phone` column, and the rows in your tables stay as they are. `marker` in the output is the record from `db sign`, which now holds the new hash. Pass `--advance-ref db` every time you apply a migration to your development database, so that the next `migration plan` contains only your next change. -To apply the migration to any other database that has the same tables, such as production, pass its connection string. Leave out `--advance-ref`, because the `db` ref describes your development database: +To apply the migration to another database with the same tables, such as production, pass its connection string. Leave out `--advance-ref` there, because the `db` ref tracks your development database: ```npm npx prisma db migrate --db "$PRODUCTION_DATABASE_URL" ``` -You do not need to run `db sign` on that database first. It has no record of a contract yet, so `db migrate` starts at the baseline, finds the tables already there, leaves them and their rows as they are, and then adds the `phone` column. +You do not need to run `db sign` on that database. `db migrate` finds that the tables of the baseline are already there, leaves them and their rows as they are, and then adds the `phone` column. ## Next steps diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx index db30b37eda0..3374b365a81 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx @@ -8,7 +8,7 @@ metaDescription: 'Add Prisma ORM to an app you already have: run orm init, write This page uses MongoDB. [Use PostgreSQL instead](/prisma-orm/quickstart/existing-app/postgresql). -Use this page when you already have an app and its database has no collections yet. By the end, your app has one model, the database has a collection for it, a script writes and reads a document, and you have applied one change to the model as a migration. If your database already has collections, follow [Add Prisma ORM to an existing MongoDB database](/prisma-orm/add-to-existing-project/mongodb) instead. +Use this page when you already have an app and its database has no collections yet. By the end, your app has one model, the database has a collection for it, and a script writes and reads a document. You also change the model once and apply the change to the database with a migration. If your database already has collections, follow [Add Prisma ORM to an existing MongoDB database](/prisma-orm/add-to-existing-project/mongodb) instead. :::note[Using Prisma ORM 7?] @@ -26,7 +26,7 @@ For what release candidate means, when the final release is expected, and how to ## 1. Add Prisma ORM to the project -The command changes two files that your app may already have. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. A CommonJS app is one whose code loads other files with `require`, and these changes can stop it from starting. If that is your app, you can still finish this page, because its steps run a script through `tsx` and work either way. Then follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start the app again. +The `orm init` command below changes your `tsconfig.json` and your `package.json`. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. If it has `"type": "commonjs"`, the command keeps it and prints a warning. If your app runs as CommonJS, for example because it loads files with `require` or because `tsc` compiles it to `require` calls, follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start your app again. `tsx` runs the scripts on this page in both kinds of app, so you can finish this page first. From the root of your project, run: @@ -34,7 +34,9 @@ From the root of your project, run: npx prisma@latest orm init --yes --target mongodb --authoring psl --write-env ``` -`--target mongodb` picks MongoDB, `--authoring psl` picks the `.prisma` file format you know from earlier Prisma ORM versions, and `--write-env` writes a `.env` file. `--yes` accepts the default location for the files, so the command asks no questions. The other value for `--authoring` is `typescript`, which this page does not use. The command installs the packages, writes the files, and ends with the summary below. In `package.json`, the command adds the packages and a `contract:emit` script. If your project already has a `tsconfig.json` or a `.gitignore`, the command edits that file and keeps the rest of it. It leaves a `.env` that you already have untouched. +`prisma@latest` runs Prisma ORM 8, and `--target mongodb` picks MongoDB. `--authoring psl` picks PSL, the Prisma Schema Language, which is the `.prisma` file format you know from earlier Prisma ORM versions. `--write-env` writes a `.env` file, unless you already have one. `--yes` accepts the default answer to every question, so the command asks nothing. + +The command installs the packages, writes the files, and ends with the summary below. In `package.json`, it adds the packages with their current version numbers, and a `contract:emit` script that runs `prisma contract emit`. If your project already has a `tsconfig.json` or a `.gitignore`, the command edits that file and keeps the rest of it. ```text no-copy │ target: mongodb @@ -64,13 +66,13 @@ installed You work with three of these files: -- `src/prisma/contract.prisma` holds your models. It is what `schema.prisma` was in earlier Prisma ORM versions, and Prisma ORM 8 calls it the contract. +- `src/prisma/contract.prisma` holds your models. It is what `schema.prisma` was in earlier Prisma ORM versions, and Prisma ORM 8 calls it the contract. The summary lists it as `schema`. - `prisma.config.ts` tells the `prisma` commands where the contract is and which database to connect to. - `src/prisma/db.ts` is the file your app imports to run queries. -You do not need `prisma-8.md` for this page. It is a short reference for writing queries. +You do not need `prisma-8.md` for this page. It is a short reference for writing queries. `.gitattributes` marks the files that Prisma ORM generates, so that GitHub collapses them in pull request diffs. -This is `src/prisma/db.ts` in full: +`orm init` wrote `src/prisma/db.ts`, and you do not need to change it: ```typescript title="src/prisma/db.ts" import 'dotenv/config'; @@ -86,7 +88,7 @@ export const db = mongo({ The first line loads `.env`, so every file that imports `db` reads `DATABASE_URL` from there. The two `contract` files it imports are written by `contract emit` in step 4. -From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. The skills are instruction files for coding agents, and the line does not change what the command does. If you want the skills, [`npx prisma@latest init`](/cli/init) installs them, which also stops the line. The output on this page leaves the line out. +From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. You can ignore it, because it does not change what the command does. Agent skills are instruction files that AI coding tools read, and the line appears because your project has none yet. To add them and stop the line, run [`npx prisma@latest init`](/cli/init). In Prisma ORM 8, `init` adds the skills and a `postinstall` script that keeps them up to date, and it leaves your contract and your `.env` alone. `orm init` is the command that sets up Prisma ORM. ## 2. Set the connection string @@ -96,7 +98,7 @@ If you had no `.env`, `orm init` wrote one with a placeholder, `DATABASE_URL="mo DATABASE_URL="mongodb://username:password@host:27017/database" ``` -The last part of the connection string is the name of the database. +The part after the last `/`, and before any `?`, is the name of the database. `orm init` added `.env` to `.gitignore`, so the password stays out of version control. @@ -115,11 +117,11 @@ model User { } ``` -Keep the first line, because `contract emit` reads only `.prisma` files that start with it. `@@map("users")` names the collection that stores the model. The file has no `datasource` or `generator` block. The connection string comes from `.env`, and `contract emit` in the next step takes the place of the generator. [Data modeling](/orm/data-modeling) covers field types and relations. +Keep the first line, because `contract emit` reads only `.prisma` files that start with it. `@@map("users")` names the collection that stores the model. MongoDB stores the identifier of every document in `_id`. On MongoDB, `contract emit` names each field in `contract.json` by the name in its `@map`, so in queries and in results you use `_id`, not `id`. The same goes for any other field with `@map`. The file has no `datasource` or `generator` block. The connection string comes from `.env`, and `contract emit` in the next step takes the place of the generator. [Data modeling](/orm/data-modeling) covers field types and relations. ## 4. Generate the files your code imports -Run `contract emit` after every change to the contract. It takes the place of `prisma generate`. This command and the ones after it start with `npx prisma`, without `@latest`, which runs the version that `orm init` installed in your project: +Run `contract emit` after every change to the contract. It takes the place of `prisma generate`. From here on, commands start with `npx prisma`, without `@latest`. That runs the version of Prisma ORM that `orm init` installed in your project: ```npm npx prisma contract emit @@ -161,8 +163,10 @@ App space `db init` creates the collections and indexes your contract declares. It also gives each collection a validator, which is the MongoDB rule that lists the fields a document may have. MongoDB then rejects a document with a field that the contract does not declare. The output names two more things it wrote: -- The `marker` is a record that `db init` stores in the database. It holds the hash of your contract, which is the long hexadecimal text in the output. The hash changes whenever the contract changes, so later commands compare it with your contract to tell whether the database is up to date. -- The `db` ref is the file `migrations/app/refs/db.json` in your project. It holds the same hash. `migration plan` in step 7 does not connect to the database, so it reads this file to find out which version of the contract your development database has. +- The `marker` is a record in the database. It holds the hash of your contract, which is the long text in the output, so that later commands can tell which version of the contract the database has. +- The `db` ref is the file `migrations/app/refs/db.json` in your project. It holds the same hash. The line `Advanced ref "db"` means that the command wrote this file. `migration plan` in step 7 reads it to find out which contract your development database has. + +You can ignore the word `space` in the output, because all your migrations are in `migrations/app/`. Commit the `migrations/` directory together with your code, because `migration plan` reads it on every later change. If the command fails with `DRIVER.CONNECTION_FAILED`, the value of `DATABASE_URL` in `.env` is wrong or the database is not reachable. @@ -192,7 +196,7 @@ main().catch((error) => { }); ``` -You reach the model as `db.orm.users`. On MongoDB you address a model by the name of its collection, which is the name in `@@map`. `await db.close()` closes the database connections, and without it the script keeps running after the last query. `create` takes the fields directly, with no `data` wrapper, and `.all()` does what `findMany()` did. +`db.orm` queries your models, the way Prisma Client did in earlier Prisma ORM versions. You reach this model as `db.orm.users`, because on MongoDB you address a model by the name of its collection, which is the name in `@@map`. `await db.close()` closes the database connections, and without it the script keeps running after the last query. `create` takes the fields directly, with no `data` wrapper, and `.all()` does what `findMany()` did. Run it: @@ -215,7 +219,7 @@ All users: [ ] ``` -The script passes no identifier, and the new document gets one. The result names it `_id`, as MongoDB stores it, and returns it as a string. Use `_id` in filters too, as in `db.orm.users.where({ _id: created._id }).first()`. +The script passes no identifier, and the new document gets one in `_id`, returned as a string. To find a document by it, filter on `_id`, as in `db.orm.users.where({ _id: created._id }).first()`. In your app, import `db` from `src/prisma/db.ts` the same way. [Reading data](/orm/fundamentals/reading-data) and [Writing data](/orm/fundamentals/writing-data) show the other queries. @@ -235,7 +239,7 @@ model User { } ``` -Generate the files again, then plan a migration. `migration plan` writes the difference between the new contract and the one your database has into a new directory under `migrations/app/`. `--name` sets the name of that directory. +Generate the files again, then plan a migration. `migration plan` compares the new contract with the last one you applied to your development database, and writes the difference into a new directory under `migrations/app/`. `--name` sets the end of the directory's name, after the date and time. ```npm npx prisma contract emit @@ -261,7 +265,7 @@ baseline: migrations/app/20260929T2126_baseline app space: migrations/app/20260929T2127_add_user_phone ``` -The output continues with a preview of the MongoDB commands. The first plan in a project writes two directories. The baseline records the collection and the index that `db init` already created. The second directory is your change. Your change updates the validator, so that a document may have the `phone` field. +The output continues with a preview of the MongoDB commands. The first plan in a project writes two directories. The baseline holds the steps that create the collection and the index, which `db init` already ran on your development database. The second directory is your change. Your change updates the validator, so that a document may have the `phone` field. Apply the migration: @@ -283,7 +287,7 @@ App space ✔ Advanced ref "db" → f0035d1963f127dc8ee91e154d51810755ee91b090659127881d1ab31e03e3cf ``` -`db migrate` reads the marker to see which contract the database already has, so here it runs only your change. `--advance-ref db` then updates the `db` ref to the new hash, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. Commit the two new directories. +`db migrate` runs only the migrations that the database does not have yet, so here it runs only your change. `--advance-ref db` writes the new hash to the `db` ref, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. Commit the `migrations/` directory again. To apply the migrations to any other database, such as production, pass its connection string. Leave out `--advance-ref`, because the `db` ref describes your development database: 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 8104069a22a..4d12d0a5fca 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, a script writes and reads a row, and you have applied one change to the model as 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 7 today, follow [Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql). :::note[Using Prisma ORM 7?] @@ -26,7 +26,7 @@ For what release candidate means, when the final release is expected, and how to ## 1. Add Prisma ORM to the project -The command changes two files that your app may already have. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. A CommonJS app is one whose code loads other files with `require`, and these changes can stop it from starting. If that is your app, you can still finish this page, because its steps run a script through `tsx` and work either way. Then follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start the app again. +The `orm init` command below changes your `tsconfig.json` and your `package.json`. In `tsconfig.json`, it sets `module` to `preserve` and `moduleResolution` to `bundler`. If your `package.json` has no `"type"` field, it adds `"type": "module"`. If it has `"type": "commonjs"`, the command keeps it and prints a warning. If your app runs as CommonJS, for example because it loads files with `require` or because `tsc` compiles it to `require` calls, follow [In a CommonJS project](/cli/orm-init#in-a-commonjs-project) before you start your app again. `tsx` runs the scripts on this page in both kinds of app, so you can finish this page first. From the root of your project, run: @@ -34,7 +34,9 @@ From the root of your project, run: npx prisma@latest orm init --yes --target postgres --authoring psl --write-env ``` -`--target postgres` picks PostgreSQL, `--authoring psl` picks the `.prisma` file format you know from Prisma ORM 7, and `--write-env` writes a `.env` file. `--yes` accepts the default location for the files, so the command asks no questions. The other value for `--authoring` is `typescript`, which this page does not use. The command installs the packages, writes the files, and ends with the summary below. In `package.json`, the command adds the packages and a `contract:emit` script. If your project already has a `tsconfig.json` or a `.gitignore`, the command edits that file and keeps the rest of it. It leaves a `.env` that you already have untouched. +`prisma@latest` runs Prisma ORM 8, and `--target postgres` picks PostgreSQL. `--authoring psl` picks PSL, the Prisma Schema Language, which is the `.prisma` file format you know from Prisma ORM 7. `--write-env` writes a `.env` file, unless you already have one. `--yes` accepts the default answer to every question, so the command asks nothing. + +The command installs the packages, writes the files, and ends with the summary below. In `package.json`, it adds the packages with their current version numbers, and a `contract:emit` script that runs `prisma contract emit`. If your project already has a `tsconfig.json` or a `.gitignore`, the command edits that file and keeps the rest of it. ```text no-copy │ target: postgres @@ -64,13 +66,13 @@ installed You work with three of these files: -- `src/prisma/contract.prisma` holds your models. It is what `schema.prisma` was in Prisma ORM 7, and Prisma ORM 8 calls it the contract. +- `src/prisma/contract.prisma` holds your models. It is what `schema.prisma` was in Prisma ORM 7, and Prisma ORM 8 calls it the contract. The summary lists it as `schema`. - `prisma.config.ts` tells the `prisma` commands where the contract is and which database to connect to. - `src/prisma/db.ts` is the file your app imports to run queries. -You do not need `prisma-8.md` for this page. It is a short reference for writing queries. +You do not need `prisma-8.md` for this page. It is a short reference for writing queries. `.gitattributes` marks the files that Prisma ORM generates, so that GitHub collapses them in pull request diffs. -This is `src/prisma/db.ts` in full: +`orm init` wrote `src/prisma/db.ts`, and you do not need to change it: ```typescript title="src/prisma/db.ts" import 'dotenv/config'; @@ -86,7 +88,7 @@ export const db = postgres({ The first line loads `.env`, so every file that imports `db` reads `DATABASE_URL` from there. The two `contract` files it imports are written by `contract emit` in step 4. -From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. The skills are instruction files for coding agents, and the line does not change what the command does. If you want the skills, [`npx prisma@latest init`](/cli/init) installs them, which also stops the line. The output on this page leaves the line out. +From now on, every `prisma` command ends with the line `Prisma agent skills are out of date`. You can ignore it, because it does not change what the command does. Agent skills are instruction files that AI coding tools read, and the line appears because your project has none yet. To add them and stop the line, run [`npx prisma@latest init`](/cli/init). In Prisma ORM 8, `init` adds the skills and a `postinstall` script that keeps them up to date, and it leaves your contract and your `.env` alone. `orm init` is the command that sets up Prisma ORM. ## 2. Set the connection string @@ -118,7 +120,7 @@ Keep the first line, because `contract emit` reads only `.prisma` files that sta ## 4. Generate the files your code imports -Run `contract emit` after every change to the contract. It takes the place of `prisma generate`. This command and the ones after it start with `npx prisma`, without `@latest`, which runs the version that `orm init` installed in your project: +Run `contract emit` after every change to the contract. It takes the place of `prisma generate`. From here on, commands start with `npx prisma`, without `@latest`. That runs the version of Prisma ORM that `orm init` installed in your project: ```npm npx prisma contract emit @@ -160,8 +162,10 @@ App space `db init` creates the tables your contract declares. The output names two more things it wrote: -- The `marker` is a record that `db init` stores in the database. It holds the hash of your contract, which is the long hexadecimal text in the output. The hash changes whenever the contract changes, so later commands compare it with your contract to tell whether the database is up to date. -- The `db` ref is the file `migrations/app/refs/db.json` in your project. It holds the same hash. `migration plan` in step 7 does not connect to the database, so it reads this file to find out which version of the contract your development database has. +- The `marker` is a record in the database. It holds the hash of your contract, which is the long text in the output, so that later commands can tell which version of the contract the database has. +- The `db` ref is the file `migrations/app/refs/db.json` in your project. It holds the same hash. The line `Advanced ref "db"` means that the command wrote this file. `migration plan` in step 7 reads it to find out which contract your development database has. + +You can ignore the word `space` in the output, because all your migrations are in `migrations/app/`. Commit the `migrations/` directory together with your code, because `migration plan` reads it on every later change. If the command fails with `DRIVER.CONNECTION_FAILED`, the value of `DATABASE_URL` in `.env` is wrong or the database is not reachable. @@ -191,7 +195,7 @@ main().catch((error) => { }); ``` -You reach the model as `db.orm.public.User`, where `public` is the name of the PostgreSQL schema that holds your tables. `await db.close()` closes the database connections, and without it the script keeps running after the last query. `create` takes the fields directly, with no `data` wrapper, and `.all()` does what `findMany()` did. +`db.orm` queries your models, the way Prisma Client did in Prisma ORM 7. You reach this model as `db.orm.public.User`, where `public` is the name of the PostgreSQL schema that holds your tables. `await db.close()` closes the database connections, and without it the script keeps running after the last query. `create` takes the fields directly, with no `data` wrapper, and `.all()` does what `findMany()` did. Run it: @@ -221,7 +225,7 @@ model User { } ``` -Generate the files again, then plan a migration. `migration plan` writes the difference between the new contract and the one your database has into a new directory under `migrations/app/`. `--name` sets the name of that directory. +Generate the files again, then plan a migration. `migration plan` compares the new contract with the last one you applied to your development database, and writes the difference into a new directory under `migrations/app/`. `--name` sets the end of the directory's name, after the date and time. ```npm npx prisma contract emit @@ -248,7 +252,7 @@ baseline: migrations/app/20260929T2120_baseline app space: migrations/app/20260929T2121_add_user_phone ``` -The output continues with a preview of the SQL. The first plan in a project writes two directories. The baseline records the table that `db init` already created. The second directory is your change. +The output continues with a preview of the SQL. The first plan in a project writes two directories. The baseline holds the steps that create the table, which `db init` already ran on your development database. The second directory is your change. Apply the migration: @@ -270,7 +274,7 @@ App space ✔ Advanced ref "db" → 300832575ace8feebb3d3442d1bca52150c46628de3e4c6c32a61cb0ab21100f ``` -`db migrate` reads the marker to see which contract the database already has, so here it runs only your change. `--advance-ref db` then updates the `db` ref to the new hash, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. Commit the two new directories. +`db migrate` runs only the migrations that the database does not have yet, so here it runs only your change. `--advance-ref db` writes the new hash to the `db` ref, so that the next `migration plan` contains only your next change. Pass it every time you apply a migration to your development database. Commit the `migrations/` directory again. To apply the migrations to any other database, such as production, pass its connection string. Leave out `--advance-ref`, because the `db` ref describes your development database: 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 99ab8d34b93..50ff6c8d9d0 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json @@ -6,5 +6,11 @@ "[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)" + ], + "hiddenPages": [ + "mongodb", + "../from-scratch", + "existing-app/mongodb", + "../add-to-existing-project/mongodb" ] } diff --git a/apps/docs/source.config.ts b/apps/docs/source.config.ts index aa69fe44cc3..c2307073400 100644 --- a/apps/docs/source.config.ts +++ b/apps/docs/source.config.ts @@ -69,7 +69,11 @@ export const docs = defineDocs({ }, }, meta: { - schema: metaSchema, + schema: metaSchema.extend({ + // Pages that belong to this folder but get no sidebar entry; see + // `src/lib/hidden-pages.ts`. + hiddenPages: z.array(z.string()).optional(), + }), }, }); diff --git a/apps/docs/src/lib/hidden-pages.test.ts b/apps/docs/src/lib/hidden-pages.test.ts new file mode 100644 index 00000000000..10756e5f93a --- /dev/null +++ b/apps/docs/src/lib/hidden-pages.test.ts @@ -0,0 +1,74 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { searchPath } from "fumadocs-core/breadcrumb"; +import { flattenTree } from "fumadocs-core/page-tree"; +import type * as PageTree from "fumadocs-core/page-tree"; +import { loader } from "fumadocs-core/source"; +// @ts-expect-error Node's TypeScript test runner requires the explicit extension. +import { hiddenPagesPlugin, withoutHiddenPages } from "./hidden-pages.ts"; + +function buildSource(hiddenPages: string[]) { + return loader({ + baseUrl: "/", + source: { + files: [ + { + type: "meta", + path: "(index)/meta.json", + data: { title: "Getting Started", root: true, pages: ["index", "quickstart"] }, + }, + { type: "page", path: "(index)/index.mdx", data: { title: "Home" } }, + { type: "page", path: "(index)/from-scratch.mdx", data: { title: "From scratch" } }, + { + type: "meta", + path: "(index)/quickstart/meta.json", + data: { + title: "Quickstart", + pages: ["[New app](/quickstart/postgresql)"], + hiddenPages, + }, + }, + { type: "page", path: "(index)/quickstart/postgresql.mdx", data: { title: "PostgreSQL" } }, + { type: "page", path: "(index)/quickstart/mongodb.mdx", data: { title: "MongoDB" } }, + ], + }, + plugins: [hiddenPagesPlugin()], + }); +} + +function sectionOf(tree: PageTree.Root, url: string) { + const path = searchPath(tree.children, url) ?? []; + return path.findLast((node) => node.type === "folder" && node.root) as + | PageTree.Folder + | undefined; +} + +test("a hidden page keeps the sidebar of its folder's section", () => { + const { pageTree } = buildSource(["mongodb", "../from-scratch"]); + + assert.equal(sectionOf(pageTree, "/quickstart/mongodb")?.name, "Getting Started"); + assert.equal(sectionOf(pageTree, "/from-scratch")?.name, "Getting Started"); +}); + +test("withoutHiddenPages leaves only the listed entries", () => { + const { pageTree } = buildSource(["mongodb", "../from-scratch"]); + const section = sectionOf(pageTree, "/quickstart/mongodb"); + assert.ok(section); + + const urls = flattenTree(withoutHiddenPages(section).children).map((item) => item.url); + + assert.deepEqual(urls, ["/", "/quickstart/postgresql"]); +}); + +test("withoutHiddenPages returns the same tree when nothing is hidden", () => { + const { pageTree } = buildSource([]); + + assert.equal(withoutHiddenPages(pageTree), pageTree); +}); + +test("a hiddenPages entry that is not a page fails the build", () => { + assert.throws( + () => buildSource(["missing"]).pageTree, + /hiddenPages entry "missing" is not a page/, + ); +}); diff --git a/apps/docs/src/lib/hidden-pages.ts b/apps/docs/src/lib/hidden-pages.ts new file mode 100644 index 00000000000..6400a02832c --- /dev/null +++ b/apps/docs/src/lib/hidden-pages.ts @@ -0,0 +1,86 @@ +import type * as PageTree from "fumadocs-core/page-tree"; +import type { LoaderPlugin } from "fumadocs-core/source"; + +/** + * Adds the pages a meta.json names in `hiddenPages` to that folder, flagged + * `hidden`. They are in the folder's section, so they keep its sidebar, but + * `withoutHiddenPages` drops them from what the sidebar lists. + */ +export function hiddenPagesPlugin(): LoaderPlugin { + let hiddenFiles = new Set(); + + return { + name: "docs:hidden-pages", + transformStorage({ storage }) { + hiddenFiles = new Set(); + const files = storage.getFiles(); + + for (const metaPath of files) { + const meta = storage.read(metaPath); + if (meta?.format !== "meta") continue; + + const { pages = ["..."], hiddenPages } = meta.data as { + pages?: string[]; + hiddenPages?: string[]; + }; + if (!hiddenPages?.length) continue; + + const folder = metaPath.split("/").slice(0, -1).join("/"); + for (const item of hiddenPages) { + const target = joinPath(folder, item); + const file = files.find( + (path) => storage.read(path)?.format === "page" && withoutExtension(path) === target, + ); + if (!file) throw new Error(`${metaPath}: hiddenPages entry "${item}" is not a page`); + hiddenFiles.add(file); + } + + storage.write(metaPath, { + ...meta, + data: { ...meta.data, pages: [...pages, ...hiddenPages] }, + }); + } + }, + transformPageTree: { + file(node, file) { + if (file && hiddenFiles.has(file)) Object.assign(node, { hidden: true }); + return node; + }, + }, + }; +} + +export function withoutHiddenPages(node: T): T { + let changed = false; + const children: PageTree.Node[] = []; + + for (const child of node.children) { + if (child.type === "page" && isHidden(child)) { + changed = true; + continue; + } + + const visible = child.type === "folder" ? withoutHiddenPages(child) : child; + if (visible !== child) changed = true; + children.push(visible); + } + + return changed ? { ...node, children } : node; +} + +function isHidden(node: PageTree.Item) { + return (node as { hidden?: boolean }).hidden === true; +} + +function joinPath(folder: string, item: string) { + const segments = folder ? folder.split("/") : []; + for (const segment of item.split("/")) { + if (segment === "..") segments.pop(); + else if (segment && segment !== ".") segments.push(segment); + } + return segments.join("/"); +} + +function withoutExtension(path: string) { + return path.replace(/\.[^/.]+$/, ""); +} diff --git a/apps/docs/src/lib/source.ts b/apps/docs/src/lib/source.ts index d340d616351..b72caf7d07c 100644 --- a/apps/docs/src/lib/source.ts +++ b/apps/docs/src/lib/source.ts @@ -4,6 +4,7 @@ import { type InferPageType, type LoaderPlugin, loader } from "fumadocs-core/sou import { lucideIconsPlugin } from "fumadocs-core/source/lucide-icons"; import { openapiPlugin } from "fumadocs-openapi/server"; import { BucketIcon } from "../components/icons/bucket"; +import { hiddenPagesPlugin } from "./hidden-pages"; // Icons meta.json can name that lucide does not ship. Runs before // lucideIconsPlugin, which leaves already-resolved (non-string) icons alone. @@ -28,7 +29,7 @@ function customIconsPlugin(): LoaderPlugin { export const source = loader({ baseUrl: "/", source: docs.toFumadocsSource(), - plugins: [customIconsPlugin(), lucideIconsPlugin(), openapiPlugin()], + plugins: [hiddenPagesPlugin(), customIconsPlugin(), lucideIconsPlugin(), openapiPlugin()], }); export function getPageImage(page: InferPageType) { diff --git a/apps/docs/src/lib/versioned-sidebar-tree.ts b/apps/docs/src/lib/versioned-sidebar-tree.ts index 19ab6737e50..5cfc9330c2e 100644 --- a/apps/docs/src/lib/versioned-sidebar-tree.ts +++ b/apps/docs/src/lib/versioned-sidebar-tree.ts @@ -1,4 +1,5 @@ import type * as PageTree from "fumadocs-core/page-tree"; +import { withoutHiddenPages } from "./hidden-pages"; import { LATEST_VERSION, getCliVersionFromPathname, @@ -359,6 +360,10 @@ function getCliSidebarTree(tree: TreeRootNode, version: Version): TreeRootNode { } export function getVersionedSidebarTree(tree: PageTree.Root, route?: string | string[]) { + return selectVersion(withoutHiddenPages(tree), route); +} + +function selectVersion(tree: PageTree.Root, route?: string | string[]) { const gettingStartedVersion = typeof route === "string" ? getGettingStartedVersionFromPathname(route) : null; From 83e41e634e5de9bc146546765a63540a718f4096 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 30 Sep 2026 08:24:13 +0200 Subject: [PATCH 3/7] docs(app): drop the comment on hiddenPages Co-Authored-By: Claude Opus 5.5 Signed-off-by: willbot Signed-off-by: Will Madden --- apps/docs/source.config.ts | 2 -- 1 file changed, 2 deletions(-) diff --git a/apps/docs/source.config.ts b/apps/docs/source.config.ts index c2307073400..4de40cee7de 100644 --- a/apps/docs/source.config.ts +++ b/apps/docs/source.config.ts @@ -70,8 +70,6 @@ export const docs = defineDocs({ }, meta: { schema: metaSchema.extend({ - // Pages that belong to this folder but get no sidebar entry; see - // `src/lib/hidden-pages.ts`. hiddenPages: z.array(z.string()).optional(), }), }, From b15420f0b2bd95499b493b8a3970b318cab648f6 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 30 Sep 2026 08:27:24 +0200 Subject: [PATCH 4/7] docs(orm): new Quickstart pages state the Node.js 22.18 floor without the 24.11 carve-out Co-Authored-By: Claude Opus 5.5 Signed-off-by: willbot Signed-off-by: Will Madden --- .../docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx | 2 +- .../(index)/prisma-orm/quickstart/existing-app/postgresql.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx index 3374b365a81..1f08723d300 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/existing-app/mongodb.mdx @@ -20,7 +20,7 @@ For what release candidate means, when the final release is expected, and how to ## Prerequisites -- A project directory with a `package.json`, on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. +- A project directory with a `package.json`, on Node.js 22.18 or newer. - A way to run a TypeScript file. This page uses `tsx`. If your project does not have it, run `npm install --save-dev tsx typescript`. - An empty MongoDB database, version 8.0 or newer. A single `mongod` server is enough. You need a replica set only for transactions and change streams. 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 4d12d0a5fca..29c4a7f232d 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 @@ -20,7 +20,7 @@ For what release candidate means, when the final release is expected, and how to ## Prerequisites -- A project directory with a `package.json`, on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. +- A project directory with a `package.json`, on Node.js 22.18 or newer. - A way to run a TypeScript file. This page uses `tsx`. If your project does not have it, run `npm install --save-dev tsx typescript`. - An empty PostgreSQL database, version 15 or newer. Step 2 shows how to get one if you have none. From 683097d4433e7ba48f29b66ae15bb3ae7a1f65d3 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 30 Sep 2026 08:27:34 +0200 Subject: [PATCH 5/7] docs(orm): drop the Node.js 24.11 carve-out from lines this slice writes Co-Authored-By: Claude Opus 5.5 Signed-off-by: willbot Signed-off-by: Will Madden --- .../docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx | 2 +- .../(index)/prisma-orm/add-to-existing-project/postgresql.mdx | 2 +- .../docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx index b2a94707390..10c90ee8d97 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx @@ -10,7 +10,7 @@ This page uses MongoDB. [Use PostgreSQL instead](/prisma-orm/add-to-existing-pro On this page you add Prisma ORM to an app whose MongoDB database already has collections. You run `orm init`, write a contract that describes your collections, and run two queries. The contract is the file that holds your models. In earlier Prisma ORM versions, it was `schema.prisma`. -Your app must reach its MongoDB database and run on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. A single `mongod` server is enough. You need a replica set only for transactions and change streams, and MongoDB Atlas already runs one. +Your app must reach its MongoDB database and run on Node.js 22.18 or newer. A single `mongod` server is enough. You need a replica set only for transactions and change streams, and MongoDB Atlas already runs one. If your database has no collections yet, follow [Add Prisma ORM and MongoDB to an existing app](/prisma-orm/quickstart/existing-app/mongodb) instead, which creates the collections for you. If you want Prisma ORM to create a new app for you, follow [Create a new app with MongoDB](/prisma-orm/quickstart/mongodb). 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 1db41f76f35..5a5943f1a49 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 @@ -10,7 +10,7 @@ This page uses PostgreSQL. [Use MongoDB instead](/prisma-orm/add-to-existing-pro On this page you add Prisma ORM to an app whose PostgreSQL database already has tables. You run `orm init`, generate the contract from your tables, run two queries, and apply your first change to the tables. The contract is the file that holds your models. In Prisma ORM 7, it was `schema.prisma`. -Your app must reach its PostgreSQL database and run on Node.js 22.18 or newer. If you use Node.js 24, use 24.11 or newer. 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. +Your app must reach its PostgreSQL database and run on Node.js 22.18 or newer. 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). diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx index 0e0440fd4d5..9335ba66971 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx @@ -24,7 +24,7 @@ For what release candidate means, when the final release is expected, and how to npm create prisma@latest -- --provider mongodb --no-deploy ``` -Run this from a Node.js 22.18 or newer (on the 24 line, 24.11 or newer) environment; Node.js 24 is recommended. The command preselects MongoDB and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. If you would rather add Prisma ORM to a project by hand, without the generated template, follow [Set up Prisma ORM from scratch](/prisma-orm/from-scratch), which uses PostgreSQL. +Run this on Node.js 22.18 or newer. The command preselects MongoDB and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. If you would rather add Prisma ORM to a project by hand, without the generated template, follow [Set up Prisma ORM from scratch](/prisma-orm/from-scratch), which uses PostgreSQL. Setup gives you the app template, a starter contract, `prisma-8.md`, project-level Prisma ORM skills for your coding agent, and package scripts for the database steps below. Answer no at the skills prompt, or pass `--skills none`, to skip the agent skill files; to remove them later, see [`skills sync`](/cli/skills) and the [`skills` config section](/cli/configuration#agent-skills). Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. From 3470fa13d8d5187a64bcd29f2cbee8fbae51f3e4 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 30 Sep 2026 09:28:36 +0200 Subject: [PATCH 6/7] docs(orm): drop the Node.js 24.0 to 24.10 carve-out from release status and the quickstarts The 'I have an app, but no database yet' flow for PostgreSQL passes every step on Node.js 24.10.0 and 24.11.1 alike (prisma 8.0.0-rc.19, @prisma/orm-postgres 8.0.0-rc.13), so the range is not a known break. 24.11 is where Node.js 24 became a long-term support release. Co-Authored-By: Claude Fable 5.1 Signed-off-by: willbot Signed-off-by: Will Madden --- apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx | 2 +- .../content/docs/(index)/prisma-orm/quickstart/postgresql.mdx | 2 +- apps/docs/content/docs/orm/release-status.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) 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 193df7b7dba..a9d109cf313 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx @@ -22,7 +22,7 @@ Two commands have new names in Prisma ORM 8. `contract emit` does what `prisma g ## Prerequisites -- Node.js 22.18 or newer (on the 24 line, 24.11 or newer); Node.js 24 is recommended. +- Node.js 22.18 or newer. - A connection string for an empty PostgreSQL database. Step 4 creates the tables and step 5 clears the `User` table on every run, so do not point this page at a database that holds data you need. Any PostgreSQL URL works. If you don't have one, `npx create-db@latest` creates a temporary Prisma Postgres database and prints its connection string, plus a claim URL if you want to keep it. ## 1. Create the project diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx b/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx index 7cd8c3a3377..076e8d9dc1f 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx @@ -24,7 +24,7 @@ For what release candidate means, when the final release is expected, and how to npm create prisma@latest -- --provider postgres --no-deploy ``` -Run this from a Node.js 22.18 or newer (on the 24 line, 24.11 or newer) environment; Node.js 24 is recommended. The command preselects PostgreSQL and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. If you would rather add Prisma ORM to a project by hand, without the generated template, follow [Set up Prisma ORM from scratch](/prisma-orm/from-scratch). +Run this on Node.js 22.18 or newer. The command preselects PostgreSQL and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. If you would rather add Prisma ORM to a project by hand, without the generated template, follow [Set up Prisma ORM from scratch](/prisma-orm/from-scratch). Setup gives you the app template, a starter contract, `prisma-8.md`, project-level Prisma ORM skills for your coding agent, and package scripts for the database steps below. Answer no at the skills prompt, or pass `--skills none`, to skip the agent skill files; to remove them later, see [`skills sync`](/cli/skills) and the [`skills` config section](/cli/configuration#agent-skills). Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. diff --git a/apps/docs/content/docs/orm/release-status.mdx b/apps/docs/content/docs/orm/release-status.mdx index f32b9282045..7e8ba526fbc 100644 --- a/apps/docs/content/docs/orm/release-status.mdx +++ b/apps/docs/content/docs/orm/release-status.mdx @@ -8,7 +8,7 @@ metaDescription: 'Prisma ORM 8 is a release candidate, with general availability Prisma ORM 8 is a **release candidate**: you can install it and build with it today. Until the final release, some details of the API may still change, so code you write now may need small edits later. Each release candidate fixes bugs found in the previous one. What Prisma ORM 8 changes, and why, is on the [Prisma ORM overview](/orm). -It needs Node.js 22.18 or newer (on the 24 line, 24.11 or newer; 24.0 to 24.10 do not work) and TypeScript 5.9 or newer. +It needs Node.js 22.18 or newer and TypeScript 5.9 or newer. Before you decide, read [what is not available yet](/orm/coming-from-prisma-orm-7#not-available-yet). Today that includes `$extends`, filtering inside JSON columns, atomic `increment`, most nested writes, transaction isolation levels, and the `P2002`-style error codes. From c229f38328f16c890c455da5c0f63e88cfb81d89 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 30 Sep 2026 09:43:46 +0200 Subject: [PATCH 7/7] chore: retrigger the Vercel blog deployment Co-Authored-By: Claude Fable 5.1 Signed-off-by: willbot Signed-off-by: Will Madden