diff --git a/.claude/skills/docs-writer/SKILL.md b/.claude/skills/docs-writer/SKILL.md index 5deeb1c857..0e9b31a5c7 100644 --- a/.claude/skills/docs-writer/SKILL.md +++ b/.claude/skills/docs-writer/SKILL.md @@ -14,7 +14,7 @@ If a rule here conflicts with house style, follow the house style and flag the c For a step-by-step example of writing each kind of page (how-to, concept, reference) and rewriting an existing one, see `references/how-to-use.md`. -For a Prisma 8 docs page or section (anything under `content/docs/orm/v8/` or `content/docs/(index)/next/`), also read `references/prisma-8.md`: page location, redirect handling (commented out until the URL cutover), tested-example requirements, tab and diagram conventions, and naming rules. +For a Prisma 8 docs page or section (anything under `content/docs/orm/` outside `v6/` and `v7/`, or the Prisma 8 getting-started pages under `content/docs/(index)/`), also read `references/prisma-8.md`: page location, redirect handling (commented out until the URL cutover), tested-example requirements, tab and diagram conventions, and naming rules. ## Foundation diff --git a/.claude/skills/docs-writer/references/prisma-8.md b/.claude/skills/docs-writer/references/prisma-8.md index 9ac832b175..7406db4b35 100644 --- a/.claude/skills/docs-writer/references/prisma-8.md +++ b/.claude/skills/docs-writer/references/prisma-8.md @@ -4,15 +4,15 @@ Follow these when writing or reviewing a Prisma 8 docs section in `apps/docs` (t ## Where pages live -- Concept and task docs go in the ORM "Next" version tree: `content/docs/orm/v8/
/` served at `/docs/orm/v8/
/`. The version dropdown keys off the `/orm/v8/*` path. -- Getting-started funnel pages stay under `content/docs/(index)/next/`. -- Frontmatter `url` must mirror the file path. Register the section in `content/docs/orm/v8/meta.json`. +- Prisma 8 is the default docs version. Concept and task docs go in the unversioned ORM tree: `content/docs/orm/
/` served at `/docs/orm/
/`. Prisma 7 docs live under `content/docs/orm/v7/` (and `(index)/v7/`, `cli/v7/`, `guides/v7/`). The version dropdown keys off the `/orm/v7/*` path. +- Getting-started funnel pages live under `content/docs/(index)/` (`getting-started.mdx`, `prisma-orm/`, `prisma-postgres/`). +- Frontmatter `url` must mirror the file path. Register the section in `content/docs/orm/meta.json`. ## Redirects: commented out until the cutover -Do not add live Prisma 7 → Prisma 8 redirects yet. They retire live URLs, and they ship together when the `/orm/v8` tree becomes `/orm` (DR-8687). +The Prisma 7 → Prisma 8 URL cutover (DR-8687) has shipped: `/orm/v8` is now `/orm`, and the Prisma 7 tree moved to `/orm/v7`. Add redirects for any further page move in the live region of `next.config.mjs` `redirects()`. -Instead, append your section's redirect map to the commented block in `apps/docs/v8.config.mjs` (search for "Prisma 8 URL cutover"). Keep the entries commented, one per line, `permanent: false`, with your DR reference. Pages with no Prisma 8 equivalent stay live on the Prisma 7 tree; list them in the same comment block for the SEO owner. +Prefer page-to-page redirects; the cutover block in `next.config.mjs` (search for "Prisma 8 URL cutover") is the reference for the shape. Keep the entries commented, one per line, `permanent: false`, with your DR reference. Pages with no Prisma 8 equivalent stay live on the Prisma 7 tree; list them in the same comment block for the SEO owner. ## Accuracy: test before you write @@ -37,4 +37,4 @@ Every code sample must be executed against the published `@prisma/orm-*` package - The product is "Prisma 8", not "Prisma 8 ORM". The high-level query lane is "the ORM API"; the low-level lanes are "the SQL query builder" and "the pipeline builder". - No em dashes. Be honest about Release Candidate status; state limitations in user-facing language ("X is not supported yet. For now, do Y") and show the tested workaround. -- Validate with `pnpm --filter docs types:check`, `pnpm lint:links`, `pnpm exec cspell --no-progress "content/docs/orm/v8/**/*.mdx"` (use placeholder ids in result blocks; random cuid fragments fail cspell), and a dev-server smoke test. +- Validate with `pnpm --filter docs types:check`, `pnpm lint:links`, `pnpm exec cspell --no-progress "content/docs/orm/**/*.mdx"` (use placeholder ids in result blocks; random cuid fragments fail cspell), and a dev-server smoke test. diff --git a/.github/workflows/error-reference-check.yml b/.github/workflows/error-reference-check.yml index 4640bfc89b..e98ee234f6 100644 --- a/.github/workflows/error-reference-check.yml +++ b/.github/workflows/error-reference-check.yml @@ -2,7 +2,7 @@ name: Error Reference Check # The published error-reference page must list every structured error code the # product (prisma/prisma main) can emit — each emitted error links to -# /docs/orm/v8/reference/error-reference#. This check fails if any +# /docs/orm/reference/error-reference#. This check fails if any # known code is missing from the page, even if the sync workflow breaks. # # Runs on pushes to main, on PRs that touch the page or its tooling, and on a @@ -14,7 +14,7 @@ on: branches: [main] pull_request: paths: - - apps/docs/content/docs/orm/v8/reference/error-reference.mdx + - apps/docs/content/docs/orm/reference/error-reference.mdx - apps/docs/scripts/generate-error-reference.mjs - .github/workflows/error-reference-check.yml - .github/workflows/sync-error-reference-docs.yml @@ -49,4 +49,4 @@ jobs: node-version: "20" - name: Verify page lists every known error code - run: node prisma-src/scripts/list-error-codes.mjs --root prisma-src --verify apps/docs/content/docs/orm/v8/reference/error-reference.mdx + run: node prisma-src/scripts/list-error-codes.mjs --root prisma-src --verify apps/docs/content/docs/orm/reference/error-reference.mdx diff --git a/.github/workflows/sync-error-reference-docs.yml b/.github/workflows/sync-error-reference-docs.yml index da80f04d98..3a83169cfa 100644 --- a/.github/workflows/sync-error-reference-docs.yml +++ b/.github/workflows/sync-error-reference-docs.yml @@ -42,18 +42,18 @@ jobs: run: node ./scripts/generate-error-reference.mjs --source ../../prisma-src/docs/reference/error-reference.md - name: Verify page lists every known error code - run: node prisma-src/scripts/list-error-codes.mjs --root prisma-src --verify apps/docs/content/docs/orm/v8/reference/error-reference.mdx + run: node prisma-src/scripts/list-error-codes.mjs --root prisma-src --verify apps/docs/content/docs/orm/reference/error-reference.mdx - name: Check for changes id: changes run: | - if [[ -z "$(git status --porcelain --untracked-files=all -- apps/docs/content/docs/orm/v8/reference/error-reference.mdx)" ]]; then + if [[ -z "$(git status --porcelain --untracked-files=all -- apps/docs/content/docs/orm/reference/error-reference.mdx)" ]]; then echo "changed=false" >> $GITHUB_OUTPUT echo "No changes detected" else echo "changed=true" >> $GITHUB_OUTPUT echo "Changes detected:" - git status --short -- apps/docs/content/docs/orm/v8/reference/error-reference.mdx + git status --short -- apps/docs/content/docs/orm/reference/error-reference.mdx fi - name: Commit and push @@ -65,7 +65,7 @@ jobs: run: | git config user.email "prismabots@gmail.com" git config user.name "Prismo" - git add apps/docs/content/docs/orm/v8/reference/error-reference.mdx + git add apps/docs/content/docs/orm/reference/error-reference.mdx git commit -m "chore(docs): sync Prisma 8 error reference" git push "https://x-access-token:${BOT_TOKEN}@github.com/${TARGET_REPO}.git" "HEAD:${TARGET_REF}" diff --git a/apps/blog/content/blog/advanced-database-schema-management-with-atlas-and-prisma-orm/index.mdx b/apps/blog/content/blog/advanced-database-schema-management-with-atlas-and-prisma-orm/index.mdx index 23db307dc2..b1b873d1cb 100644 --- a/apps/blog/content/blog/advanced-database-schema-management-with-atlas-and-prisma-orm/index.mdx +++ b/apps/blog/content/blog/advanced-database-schema-management-with-atlas-and-prisma-orm/index.mdx @@ -30,7 +30,7 @@ You can find the [example repo](https://github.com/prisma/prisma-atlas) for this ## Why use Atlas instead of Prisma Migrate? -[Prisma Migrate](https://www.prisma.io/migrate) is a migration tool that covers the majority of use cases application developers have when managing their database schemas. It provides workflows specifically designed for taking you [from development to production](https://www.prisma.io/docs/orm/prisma-migrate/workflows/development-and-production) and with [team collaboration](https://www.prisma.io/docs/orm/prisma-migrate/workflows/team-development) in mind. +[Prisma Migrate](https://www.prisma.io/migrate) is a migration tool that covers the majority of use cases application developers have when managing their database schemas. It provides workflows specifically designed for taking you [from development to production](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/development-and-production) and with [team collaboration](https://www.prisma.io/docs/orm/prisma-migrate/workflows/team-development) in mind. However, for even more capabilities, you may use a dedicated tool like Atlas to extend your migration workflows in the following scenarios: @@ -49,7 +49,7 @@ To complete this guide, you need: For the purpose of this guide, we'll assume that your Prisma schema contains the standard `User` and `Post` models that we use as [main examples](https://www.prisma.io/docs/orm/overview/introduction/what-is-prisma) across our documentation. If you don't have a Prisma ORM project, you can use the [`orm/script`](https://github.com/prisma/prisma-examples/tree/latest/orm/script) example to follow this guide. -In Prisma ORM 7, the database connection URL lives in [`prisma.config.ts`](https://www.prisma.io/docs/orm/reference/prisma-config-reference), not in the `datasource` block of `schema.prisma`. A minimal config looks like this: +In Prisma ORM 7, the database connection URL lives in [`prisma.config.ts`](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference), not in the `datasource` block of `schema.prisma`. A minimal config looks like this: ```ts // prisma.config.ts @@ -120,7 +120,7 @@ In the above snippet, you're doing two things: - Define an `external_schema` called `prisma` via the `data` block: Atlas integrates database schema definitions from various sources. In this case, the _source_ is the SQL that's generated by the `prisma migrate diff` command, specified via the `program` field. (In Prisma ORM 7, the flag is `--to-schema`; the older `--to-schema-datamodel` was removed.) - Specify details about your environment (called `local`) using the `env` block: - - `dev`: Points to a [shadow database](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/shadow-database) (which is called _dev database_ in Atlas). Similar to Prisma Migrate, Atlas uses a shadow database to "dry-run" migrations. The connection you provide here is similar to the `shadowDatabaseUrl` in the Prisma schema. For convenience we're using Docker in this case to manage these ephemeral database instances. + - `dev`: Points to a [shadow database](https://www.prisma.io/docs/orm/v7/prisma-migrate/understanding-prisma-migrate/shadow-database) (which is called _dev database_ in Atlas). Similar to Prisma Migrate, Atlas uses a shadow database to "dry-run" migrations. The connection you provide here is similar to the `shadowDatabaseUrl` in the Prisma schema. For convenience we're using Docker in this case to manage these ephemeral database instances. - `schema`: Points to the database connection URL of the database targeted by Prisma ORM (in most cases, this will be identical to the `DATABASE_URL` environment variable). - `migration`: Points to the directory on your file system where you want to store the Atlas migration files (similar to the `prisma/migrations` folder). Note that you're also [excluding](https://atlasgo.io/versioned/diff) the `_prisma_migrations` table from being tracked in Atlas' migration history. @@ -196,7 +196,7 @@ Next, you'll learn how to make edits to your Prisma schema and reflect the chang 4. Run `npx prisma generate` to update your Prisma Client 5. Access the modified schema in your application code via Prisma Client -For the purpose of this tutorial, we're going to expand the Prisma schema with a `Tag` model that has a [many-to-many relation](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations/many-to-many-relations#implicit-many-to-many-relations) to the `Post` model: +For the purpose of this tutorial, we're going to expand the Prisma schema with a `Tag` model that has a [many-to-many relation](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/many-to-many-relations#implicit-many-to-many-relations) to the `Post` model: ```diff model User { @@ -258,7 +258,7 @@ atlas migrate apply \ --env local \ --url __DATABASE_URL__ ``` -Your database schema is now updated, but your generated Prisma Client isn't aware of the schema change yet. In Prisma ORM 7, the recommended [`prisma-client` generator](https://www.prisma.io/docs/orm/prisma-schema/overview/generators) writes the Client to an explicit `output` path rather than into `node_modules`: +Your database schema is now updated, but your generated Prisma Client isn't aware of the schema change yet. In Prisma ORM 7, the recommended [`prisma-client` generator](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators) writes the Client to an explicit `output` path rather than into `node_modules`: ```prisma generator client { @@ -394,4 +394,4 @@ In this tutorial, you learned how to integrate Atlas into an existing Prisma ORM Check out the [example repo](https://github.com/prisma/prisma-atlas/) if you want to have a quick look at the final result of this tutorial. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/agents-md-for-databases/index.mdx b/apps/blog/content/blog/agents-md-for-databases/index.mdx index 333d233424..d5591bb40f 100644 --- a/apps/blog/content/blog/agents-md-for-databases/index.mdx +++ b/apps/blog/content/blog/agents-md-for-databases/index.mdx @@ -62,7 +62,7 @@ Be clear about what the rehearsal proves: the migration applies cleanly to real ### Prefer machine-readable output -Terminal output with spinners and box-drawing characters is written for humans. An agent can read it, but it spends tokens on decoration and invites misextraction; a named JSON field is unambiguous. Where a CLI offers structured output, the agent should use it: `create-db` has `--json`, the Prisma CLI supports it on commands like `prisma version --json`, and the [Prisma 8](https://www.prisma.io/docs/cli/v8) CLI (the next-generation Prisma ORM, currently a Release Candidate) carries `--json` across its command surface, from `db schema` to `migration show`. The rule generalizes beyond Prisma: prefer a `--json` flag anywhere one exists, and parse fields instead of scraping text. +Terminal output with spinners and box-drawing characters is written for humans. An agent can read it, but it spends tokens on decoration and invites misextraction; a named JSON field is unambiguous. Where a CLI offers structured output, the agent should use it: `create-db` has `--json`, the Prisma CLI supports it on commands like `prisma version --json`, and the [Prisma 8](https://www.prisma.io/docs/cli) CLI (the next-generation Prisma ORM, currently a Release Candidate) carries `--json` across its command surface, from `db schema` to `migration show`. The rule generalizes beyond Prisma: prefer a `--json` flag anywhere one exists, and parse fields instead of scraping text. ### Connection strings live in the environment diff --git a/apps/blog/content/blog/announcing-prisma-6-18-0/index.mdx b/apps/blog/content/blog/announcing-prisma-6-18-0/index.mdx index d014cefbbe..b3dfc5194e 100644 --- a/apps/blog/content/blog/announcing-prisma-6-18-0/index.mdx +++ b/apps/blog/content/blog/announcing-prisma-6-18-0/index.mdx @@ -104,7 +104,7 @@ export default defineConfig({ } }); ``` -For a full reference of the options that can be used in Prisma Config, see the [docs](https://www.prisma.io/docs/orm/reference/prisma-config-reference). +For a full reference of the options that can be used in Prisma Config, see the [docs](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference). Be sure to follow us on social media to stay up to date with all the latest release of Prisma ORM and Prisma Postgres diff --git a/apps/blog/content/blog/announcing-prisma-6-19-0/index.mdx b/apps/blog/content/blog/announcing-prisma-6-19-0/index.mdx index 79405118e1..c877394d6c 100644 --- a/apps/blog/content/blog/announcing-prisma-6-19-0/index.mdx +++ b/apps/blog/content/blog/announcing-prisma-6-19-0/index.mdx @@ -90,7 +90,7 @@ With this release, we’re very close to the next major release of Prisma, v7. T }); ``` -For a full reference of the options that can be used in Prisma Config, see the [docs](https://www.prisma.io/docs/orm/reference/prisma-config-reference). +For a full reference of the options that can be used in Prisma Config, see the [docs](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference). If you want to go deeper on the Postgres side of this release, explore [Prisma Postgres](https://www.prisma.io/postgres), review [pricing](https://www.prisma.io/pricing), and check the [connection pooling docs](https://www.prisma.io/docs/postgres/database/connection-pooling). diff --git a/apps/blog/content/blog/announcing-prisma-orm-7-2-0/index.mdx b/apps/blog/content/blog/announcing-prisma-orm-7-2-0/index.mdx index 27b79dfe2a..594fb6be78 100644 --- a/apps/blog/content/blog/announcing-prisma-orm-7-2-0/index.mdx +++ b/apps/blog/content/blog/announcing-prisma-orm-7-2-0/index.mdx @@ -20,10 +20,10 @@ To upgrade to the latest release, install the appropriate packages using the `@l ```shell # The Prisma CLI -npm install prisma@latest --save-dev +npm install prisma@7.9.1 --save-dev # The Prisma Client Library -npm install @prisma/client@latest +npm install @prisma/client@7.9.1 # The adapter for your database npm install @prisma/adapter-pg@latest @@ -46,7 +46,7 @@ As part of the move to a Prisma config file, running `prisma init` would generat ```tsx // This file was generated by Prisma and assumes you have installed the following: -// npm install --save-dev prisma dotenv +// npm install --save-dev prisma@7.9.1 dotenv import "dotenv/config"; import { defineConfig, env } from "prisma/config"; @@ -82,7 +82,7 @@ For Node environments (`npx`, `pnpm`, `bunx`, `bun run`): ```tsx // This file was generated by Prisma and assumes you have installed the following: -// npm install --save-dev prisma dotenv +// npm install --save-dev prisma@7.9.1 dotenv import "dotenv/config"; import { defineConfig } from "prisma/config"; @@ -122,7 +122,7 @@ This issue was reported back in July, and we’re thrilled that it’s been fixe - [Explore Prisma ORM](https://www.prisma.io/orm) for the latest Prisma 7 releases and capabilities. - [Review the Prisma 7 upgrade guide](https://www.prisma.io/docs/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-7) before rolling 7.2.0 out more broadly. -- [Refresh your Prisma Client generation setup](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client) if you're adopting the newer Prisma config workflow. +- [Refresh your Prisma Client generation setup](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/generating-prisma-client) if you're adopting the newer Prisma config workflow. ## Parting Thoughts diff --git a/apps/blog/content/blog/announcing-prisma-postgres-for-ai-coding-agents/index.mdx b/apps/blog/content/blog/announcing-prisma-postgres-for-ai-coding-agents/index.mdx index e6d3d3db93..bf0ec9c1e7 100644 --- a/apps/blog/content/blog/announcing-prisma-postgres-for-ai-coding-agents/index.mdx +++ b/apps/blog/content/blog/announcing-prisma-postgres-for-ai-coding-agents/index.mdx @@ -84,7 +84,7 @@ It offers the reliability developers need without the operational complexity tha To try out Prisma Postgres, simply run this command in your terminal: ``` -npx prisma init --db +npx prisma@7.9.1 init --db ``` Prisma Postgres also integrates directly with your favorite LLM and AI coding environment via the Model Context Protocol (MCP). diff --git a/apps/blog/content/blog/announcing-typedsql-make-your-raw-sql-queries-type-safe-with-prisma-orm/index.mdx b/apps/blog/content/blog/announcing-typedsql-make-your-raw-sql-queries-type-safe-with-prisma-orm/index.mdx index 79a866aaed..ce1272f283 100644 --- a/apps/blog/content/blog/announcing-typedsql-make-your-raw-sql-queries-type-safe-with-prisma-orm/index.mdx +++ b/apps/blog/content/blog/announcing-typedsql-make-your-raw-sql-queries-type-safe-with-prisma-orm/index.mdx @@ -14,7 +14,7 @@ tags: - "announcement" --- -[TypedSQL](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/typedsql) is a Prisma ORM feature that turns raw SQL queries written in `.sql` files into fully typed TypeScript functions. You write plain SQL, run `prisma generate --sql`, and Prisma ORM generates a function with typed arguments and a typed result that you execute with `$queryRawTyped`. This guide walks through the complete workflow on Prisma ORM 7. +[TypedSQL](https://www.prisma.io/docs/orm/v7/prisma-client/using-raw-sql/typedsql) is a Prisma ORM feature that turns raw SQL queries written in `.sql` files into fully typed TypeScript functions. You write plain SQL, run `prisma generate --sql`, and Prisma ORM generates a function with typed arguments and a typed result that you execute with `$queryRawTyped`. This guide walks through the complete workflow on Prisma ORM 7. > **Updated (July 2026):** This post originally announced TypedSQL in Prisma ORM [v5.19.0](https://github.com/prisma/prisma/releases/tag/5.19.0). It is now maintained as an evergreen guide. TypedSQL remains a Preview feature in Prisma ORM 7. Every command and code block below was run end-to-end against `prisma@7.8` and `@prisma/client@7.8`, using the `prisma-client` generator and a local [Prisma Postgres](https://www.prisma.io/docs/postgres) database started with `npx prisma dev`. @@ -24,7 +24,7 @@ TypedSQL is a four-step workflow: enable the Preview feature, write a query in a ### 1. Enable the `typedSql` Preview feature -Add `typedSql` to the `previewFeatures` of your [generator](https://www.prisma.io/docs/orm/prisma-schema/overview/generators) block. On Prisma ORM 7, the default generator is `prisma-client`, which emits the client into your own source tree instead of `node_modules`: +Add `typedSql` to the `previewFeatures` of your [generator](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators) block. On Prisma ORM 7, the default generator is `prisma-client`, which emits the client into your own source tree instead of `node_modules`: ```prisma // prisma/schema.prisma @@ -56,7 +56,7 @@ model TrackingEvent { } ``` -On Prisma ORM 7, the connection URL no longer lives in the `datasource` block. It belongs in [`prisma.config.ts`](https://www.prisma.io/docs/orm/reference/prisma-config-reference), and you load environment variables yourself, for example with `dotenv`: +On Prisma ORM 7, the connection URL no longer lives in the `datasource` block. It belongs in [`prisma.config.ts`](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference), and you load environment variables yourself, for example with `dotenv`: ```typescript // prisma.config.ts @@ -219,7 +219,7 @@ ORDER BY "conversion" DESC ` ``` -The problem: this query returns `unknown`. To get typed results you have to write the result type by hand, and nothing keeps that type honest when the schema changes. TypedSQL closes that gap by generating the types from the database itself. It is inspired by projects like PgTyped and sqlx that are built on the same idea, and the details are covered in the [raw queries documentation](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries). +The problem: this query returns `unknown`. To get typed results you have to write the result type by hand, and nothing keeps that type honest when the schema changes. TypedSQL closes that gap by generating the types from the database itself. It is inspired by projects like PgTyped and sqlx that are built on the same idea, and the details are covered in the [raw queries documentation](https://www.prisma.io/docs/orm/v7/prisma-client/using-raw-sql/raw-queries). ## TypedSQL and the Prisma Client API @@ -258,6 +258,6 @@ No. TypedSQL types each query at generate time, so the SQL text must be static. ## Summary -TypedSQL gives you raw SQL with the type safety of the Prisma Client API: write a query in `prisma/sql`, run `npx prisma generate --sql` against a live database, and call the generated function with `$queryRawTyped` for fully typed results. On Prisma ORM 7 it stays behind the `typedSql` Preview flag, works with the `prisma-client` generator's custom output directory, and fits any PostgreSQL or modern MySQL setup, including [Prisma Postgres](https://www.prisma.io/docs/postgres). The [TypedSQL documentation](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/typedsql) covers the full reference, including argument annotations and database support. +TypedSQL gives you raw SQL with the type safety of the Prisma Client API: write a query in `prisma/sql`, run `npx prisma generate --sql` against a live database, and call the generated function with `$queryRawTyped` for fully typed results. On Prisma ORM 7 it stays behind the `typedSql` Preview flag, works with the `prisma-client` generator's custom output directory, and fits any PostgreSQL or modern MySQL setup, including [Prisma Postgres](https://www.prisma.io/docs/postgres). The [TypedSQL documentation](https://www.prisma.io/docs/orm/v7/prisma-client/using-raw-sql/typedsql) covers the full reference, including argument annotations and database support. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-auth-mngp1ps7kip4/index.mdx b/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-auth-mngp1ps7kip4/index.mdx index 916c2725db..60e0149879 100644 --- a/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-auth-mngp1ps7kip4/index.mdx +++ b/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-auth-mngp1ps7kip4/index.mdx @@ -39,7 +39,7 @@ The goal of the series is to explore and demonstrate different patterns, problem ### What you will learn today -In the first article, you designed a [data model](/backend-prisma-typescript-orm-with-postgresql-data-modeling-tsjs1ps7kip1) and wrote a seed script that uses [Prisma Client](https://www.prisma.io/docs/orm/prisma-client) to save data. +In the first article, you designed a [data model](/backend-prisma-typescript-orm-with-postgresql-data-modeling-tsjs1ps7kip1) and wrote a seed script that uses [Prisma Client](https://www.prisma.io/docs/orm/v7/prisma-client) to save data. In the second article, you built a [REST API](/backend-prisma-typescript-orm-with-postgresql-rest-api-validation-dcba1ps7kip3) with [Hono](https://hono.dev/) on top of that data model. diff --git a/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-data-modeling-tsjs1ps7kip1/index.mdx b/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-data-modeling-tsjs1ps7kip1/index.mdx index eacb50b86a..a1ab6f7296 100644 --- a/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-data-modeling-tsjs1ps7kip1/index.mdx +++ b/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-data-modeling-tsjs1ps7kip1/index.mdx @@ -42,7 +42,7 @@ The series focuses on the role of the database in every aspect of backend develo This first article lays out the problem domain and develops the following aspects of the backend: 1. **Data modeling:** Mapping the problem domain to a database schema -2. **CRUD:** Implementing Create, Read, Update, and Delete queries with [Prisma Client](https://www.prisma.io/docs/orm/prisma-client) +2. **CRUD:** Implementing Create, Read, Update, and Delete queries with [Prisma Client](https://www.prisma.io/docs/orm/v7/prisma-client) 3. **Aggregation:** Implementing aggregate queries with Prisma Client to calculate averages and more By the end of this article you will have a Prisma schema, a corresponding database schema created by Prisma Migrate, and a seed script that uses Prisma Client to perform CRUD and aggregation queries. @@ -79,8 +79,8 @@ npm install typescript tsx @types/node --save-dev Install Prisma ORM and the packages it needs to talk to PostgreSQL: ```sh -npm install prisma @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install prisma@7.9.1 @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` Here is what each package does: @@ -241,7 +241,7 @@ The diagram has the following relations: - `User` ↔ `TestResult` (via `graderId`) - `User` ↔ `TestResult` (via `studentId`) - **many-to-many (also known as `m-n`):** - - `User` ↔ `Course` via the `CourseEnrollment` [relation table](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations/many-to-many-relations) with two _foreign keys_: `userId` and `courseId`. Many-to-many relations typically require an additional table. This is necessary so that the grading system can have the following properties: + - `User` ↔ `Course` via the `CourseEnrollment` [relation table](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/many-to-many-relations) with two _foreign keys_: `userId` and `courseId`. Many-to-many relations typically require an additional table. This is necessary so that the grading system can have the following properties: - A single course can have many associated users (as students or teachers) - A single user can be associated with many courses. @@ -249,11 +249,11 @@ The diagram has the following relations: ### Understanding the Prisma schema -To create the tables in your database, you first define your [Prisma schema](https://www.prisma.io/docs/orm/prisma-schema). The Prisma schema is a declarative definition of your database tables. It serves as the source of truth for both the generated Prisma Client and for [Prisma Migrate](https://www.prisma.io/docs/orm/prisma-migrate), which creates the database schema. +To create the tables in your database, you first define your [Prisma schema](https://www.prisma.io/docs/orm/prisma-schema). The Prisma schema is a declarative definition of your database tables. It serves as the source of truth for both the generated Prisma Client and for [Prisma Migrate](https://www.prisma.io/docs/orm/v7/prisma-migrate), which creates the database schema. ### Define models -The fundamental building block of the Prisma schema is the [`model`](https://www.prisma.io/docs/orm/prisma-schema/data-model/models). Every model maps to a database table. +The fundamental building block of the Prisma schema is the [`model`](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/models). Every model maps to a database table. Here is an example showing the basic signature of a model: @@ -277,7 +277,7 @@ Each field has a name followed by a type and optional field attributes. The `Use | `lastName` | `String` | Scalar | - | - | | `social` | `Json` | Scalar | `?` (optional) | - | -Prisma defines a [set of data types](https://www.prisma.io/docs/orm/prisma-schema/data-model/models#scalar-fields) that map to native database types depending on the database used. +Prisma defines a [set of data types](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/models#scalar-fields) that map to native database types depending on the database used. The `Json` type stores free-form JSON. This is useful for information that can vary across `User` records and change without affecting the core functionality of the backend. In the `User` model it stores social links, for example a Bluesky or LinkedIn handle. Adding a new social profile link requires no database migration. @@ -318,7 +318,7 @@ Each model has all the relevant fields while ignoring relations, which come next #### One-to-many -To define a [one-to-many](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations/one-to-many-relations) relation between `Test` and `TestResult`, add the following three fields: +To define a [one-to-many](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/one-to-many-relations) relation between `Test` and `TestResult`, add the following three fields: - A `testId` field of type `Int` (_relation scalar_) on the "many" side of the relation, `TestResult`. This field represents the _foreign key_ in the underlying database table. - A `test` field of type `Test` (_relation field_) with a `@relation` attribute mapping the relation scalar `testId` to the `id` primary key of the `Test` model. @@ -348,7 +348,7 @@ Relation fields like `test` and `testResults` can be identified by their value t #### Many-to-many -Many-to-many relations can be [_implicit_ or _explicit_](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations/many-to-many-relations) in the Prisma schema. +Many-to-many relations can be [_implicit_ or _explicit_](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations/many-to-many-relations) in the Prisma schema. To create an implicit many-to-many relation between `User` and `Course`, you would define relation fields as lists on both sides: @@ -416,7 +416,7 @@ Things to note about the `CourseEnrollment` model: - It uses the `UserRole` enum to denote whether a user is a student or a teacher of a course. - `@@id([userId, courseId])` defines a multi-field primary key of the two fields. This ensures that every `User` can only be associated with a `Course` once, either as a student or as a teacher but never both. -To learn more about relations, check out the [relations documentation](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations). +To learn more about relations, check out the [relations documentation](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations). ### The full schema @@ -501,7 +501,7 @@ enum UserRole { } ``` -Note that `TestResult` has two relations to the `User` model: `student` and `gradedBy`, representing both the student who took the test and the teacher who graded it. The `name` argument on the `@relation` attribute [disambiguates the relations](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations#disambiguating-relations) when a single model has more than one relation to the same model. +Note that `TestResult` has two relations to the `User` model: `student` and `gradedBy`, representing both the student who took the test and the teacher who graded it. The `name` argument on the `@relation` attribute [disambiguates the relations](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations#disambiguating-relations) when a single model has more than one relation to the same model. ## Migrating the database @@ -544,7 +544,7 @@ The client is generated into `generated/prisma` in your project, as configured b ## Seeding the database -In this step, you will write a seed script that fills the database with sample data using Prisma Client CRUD operations. You will also use [nested writes](https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries#nested-writes) to create database rows for related entities in a single operation. +In this step, you will write a seed script that fills the database with sample data using Prisma Client CRUD operations. You will also use [nested writes](https://www.prisma.io/docs/orm/v7/prisma-client/queries/relation-queries#nested-writes) to create database rows for related entities in a single operation. First, register the seed script in `prisma.config.ts` so the Prisma CLI knows how to run it: @@ -678,7 +678,7 @@ In the case of `tests`, you passed an array of objects to `create` which are all In the case of `members`, both `create` and `connect` were used: even though the user already exists, a _new_ row in the `CourseEnrollment` relation table needs to be created, and `connect` links it to the existing user. -> **Note:** The [`include`](https://www.prisma.io/docs/orm/prisma-client/queries/select-fields) argument fetches relations in the result. Here it returns the created tests, which you will need to relate test results to tests in a later step. +> **Note:** The [`include`](https://www.prisma.io/docs/orm/v7/prisma-client/queries/select-fields) argument fetches relations in the result. Here it returns the created tests, which you will need to relate test results to tests in a later step. ### Creating users and relating them to a course @@ -870,7 +870,7 @@ In this step, you will run two kinds of aggregate operations: ### Grouping aggregates with groupBy -Prisma Client also supports [`groupBy`](https://www.prisma.io/docs/orm/prisma-client/queries/aggregation-grouping-summarizing#group-by) queries, which combine grouping and aggregation in a single database query. The per-test loop above can be expressed as one query: +Prisma Client also supports [`groupBy`](https://www.prisma.io/docs/orm/v7/prisma-client/queries/aggregation-grouping-summarizing#group-by) queries, which combine grouping and aggregation in a single database query. The per-test loop above can be expressed as one query: ```ts const resultsByTest = await prisma.testResult.groupBy({ diff --git a/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-deployment-bbba1ps7kip5/index.mdx b/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-deployment-bbba1ps7kip5/index.mdx index 1c6383cc5b..685f6ece3e 100644 --- a/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-deployment-bbba1ps7kip5/index.mdx +++ b/apps/blog/content/blog/backend-prisma-typescript-orm-with-postgresql-deployment-bbba1ps7kip5/index.mdx @@ -243,7 +243,7 @@ Your backend is now tested on every push and deployed to Prisma Compute. Well do You configured a GitHub Actions workflow that spins up a throwaway PostgreSQL database, applies your migrations, and runs the tests, then deployed the app to Prisma Compute with the Prisma CLI and wired up deploy-on-push with the Git integration. Because the app runs next to your Prisma Postgres database, you skipped the separate database add-on and the connection-churn concerns of hosting them apart. -Over the four parts, you designed a data model, built a REST API with Hono, secured it with passwordless authentication and authorization, and shipped it with CI/CD, using [Prisma Client](https://www.prisma.io/docs/orm/prisma-client) and Prisma Migrate throughout, with the schema as the single source of truth. +Over the four parts, you designed a data model, built a REST API with Hono, secured it with passwordless authentication and authorization, and shipped it with CI/CD, using [Prisma Client](https://www.prisma.io/docs/orm/v7/prisma-client) and Prisma Migrate throughout, with the schema as the single source of truth. If AI agents are part of your workflow, the [Prisma MCP server](https://www.prisma.io/docs/postgres/integrations/mcp-server) lets them create and manage Prisma Postgres databases as they need them. diff --git a/apps/blog/content/blog/build-an-app-with-svelte-and-typescript-PZDY3t93qAtd/index.mdx b/apps/blog/content/blog/build-an-app-with-svelte-and-typescript-PZDY3t93qAtd/index.mdx index 1ed4efe7e2..0a6ddc9978 100644 --- a/apps/blog/content/blog/build-an-app-with-svelte-and-typescript-PZDY3t93qAtd/index.mdx +++ b/apps/blog/content/blog/build-an-app-with-svelte-and-typescript-PZDY3t93qAtd/index.mdx @@ -437,7 +437,7 @@ Next, let's install our regular dependenceis. ```shell -npm install @prisma/client express cors +npm install @prisma/client@7.9.1 express cors ``` @@ -450,7 +450,7 @@ The Prisma CLI gives us an `init` command which takes care of creating a `/prism ```shell -npx prisma init +npx prisma@7.9.1 init ``` diff --git a/apps/blog/content/blog/build-applications-at-the-edge-with-prisma-orm-and-cloudflare-d1-preview/index.mdx b/apps/blog/content/blog/build-applications-at-the-edge-with-prisma-orm-and-cloudflare-d1-preview/index.mdx index 96b0948a13..c81a207718 100644 --- a/apps/blog/content/blog/build-applications-at-the-edge-with-prisma-orm-and-cloudflare-d1-preview/index.mdx +++ b/apps/blog/content/blog/build-applications-at-the-edge-with-prisma-orm-and-cloudflare-d1-preview/index.mdx @@ -37,7 +37,7 @@ Following Cloudflare's principles of geographic distribution and bringing comput This means that read-queries are executed against the D1 instance that's closest to the location from where the query was issued. -> While you can use read replicas using Prisma ORM with other database providers as well, this typically requires you to use the [Read Replica Client extension](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/read-replicas). When using D1, read replicas are supported out-of-the-box without the need for a dedicated Client extension. +> While you can use read replicas using Prisma ORM with other database providers as well, this typically requires you to use the [Read Replica Client extension](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/read-replicas). When using D1, read replicas are supported out-of-the-box without the need for a dedicated Client extension. For write-operations, on the other hand, queries still travel to a single primary instance in order to propagate the changes to all read-replicas and ensure data consistency. @@ -89,12 +89,12 @@ First, navigate into the project directory and install the Prisma CLI: ```shell cd prisma-d1-example -npm install prisma --save-dev +npm install prisma@7.9.1 --save-dev ``` Next, install the Prisma Client package as well as the driver adapter for D1: ```shell -npm install @prisma/client +npm install @prisma/client@7.9.1 npm install @prisma/adapter-d1 ``` Finally, bootstrap the files required by Prisma ORM using the following command: diff --git a/apps/blog/content/blog/caching-database-queries-with-prisma-accelerate/index.mdx b/apps/blog/content/blog/caching-database-queries-with-prisma-accelerate/index.mdx index 29167e3c38..54b981e5a0 100644 --- a/apps/blog/content/blog/caching-database-queries-with-prisma-accelerate/index.mdx +++ b/apps/blog/content/blog/caching-database-queries-with-prisma-accelerate/index.mdx @@ -92,4 +92,4 @@ Caching remains one of the genuinely hard problems of software engineering. Cach With caching built into [Prisma Postgres](https://www.prisma.io/docs/postgres/database/caching) on a per-query basis, the implementation part stops being the hard part, and you can spend the time on the decisions instead. Create a database with `npx create-db`, add a `cacheStrategy` to your hottest query, and measure the difference. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/client-extensions-ga-4g4yIu8eOSbB/index.mdx b/apps/blog/content/blog/client-extensions-ga-4g4yIu8eOSbB/index.mdx index 6b163c2125..f1ed019ea9 100644 --- a/apps/blog/content/blog/client-extensions-ga-4g4yIu8eOSbB/index.mdx +++ b/apps/blog/content/blog/client-extensions-ga-4g4yIu8eOSbB/index.mdx @@ -14,17 +14,17 @@ tags: - "announcement" --- -With the release of version [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) of the Prisma ORM, [Client extensions](https://www.prisma.io/docs/orm/prisma-client/client-extensions) are now Generally Available! This new feature allows users to extend and customize Prisma Client to meet their individual use cases. +With the release of version [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) of the Prisma ORM, [Client extensions](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions) are now Generally Available! This new feature allows users to extend and customize Prisma Client to meet their individual use cases. ## Tailor Prisma Client to meet your codebase's needs -In [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0), we released Prisma Client extensions [as a Preview feature](https://www.prisma.io/docs/orm/more/releases#preview). Today we are happy to announce the General Availability of Prisma Client extensions! Extensions have proven to be extremely useful and powerful during the Preview period, even powering Prisma products like [Accelerate](https://www.prisma.io/data-platform/accelerate) and [Optimize](https://www.prisma.io/docs/optimize)! +In [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0), we released Prisma Client extensions [as a Preview feature](https://www.prisma.io/docs/orm/v7/more/releases#preview). Today we are happy to announce the General Availability of Prisma Client extensions! Extensions have proven to be extremely useful and powerful during the Preview period, even powering Prisma products like [Accelerate](https://www.prisma.io/data-platform/accelerate) and [Optimize](https://www.prisma.io/docs/optimize)! ### A straightforward and easy to use API If this is the first time you're hearing about Client extensions, don't worry. We have [an existing blog post](/client-extensions-preview-8t3w27xkrxxn) that covers the usage in-depth. To sum it up here: creating an extension is as easy as using `$extends`. -This code snippet shows how you can add a _new method_ to the `User` model using a [`model`](https://www.prisma.io/docs/orm/prisma-client/client-extensions/model) extension: +This code snippet shows how you can add a _new method_ to the `User` model using a [`model`](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions/model) extension: ```typescript import { PrismaClient } from '@prisma/client'; diff --git a/apps/blog/content/blog/client-extensions-preview-8t3w27xkrxxn/index.mdx b/apps/blog/content/blog/client-extensions-preview-8t3w27xkrxxn/index.mdx index 068de3efe8..0b1f95ec22 100644 --- a/apps/blog/content/blog/client-extensions-preview-8t3w27xkrxxn/index.mdx +++ b/apps/blog/content/blog/client-extensions-preview-8t3w27xkrxxn/index.mdx @@ -15,7 +15,7 @@ tags: - "orm" --- -[Prisma Client extensions](https://www.prisma.io/docs/orm/prisma-client/client-extensions) let you add custom, fully type-safe behavior to Prisma ORM: computed fields, validation, query hooks, row-level security, retries, and your own model or client methods, all through one `$extends` call. This article catalogs 15 practical extension patterns with runnable code for each. +[Prisma Client extensions](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions) let you add custom, fully type-safe behavior to Prisma ORM: computed fields, validation, query hooks, row-level security, retries, and your own model or client methods, all through one `$extends` call. This article catalogs 15 practical extension patterns with runnable code for each. > **Updated (July 2026):** Prisma Client extensions announced here in Preview have long been **generally available** (since Prisma 4.16.0) and require no preview flag. On Prisma 7, extensions are also the replacement for middleware (`$use`), which was removed. The setup section below reflects Prisma 7; the example catalog is maintained in the [prisma-client-extensions repo](https://github.com/prisma/prisma-client-extensions). @@ -61,7 +61,7 @@ const prisma = new PrismaClient().$extends({ result: { /* ... */ }, }); ``` -To see the full syntax for defining each type of extension component, please refer to [the docs](https://www.prisma.io/docs/orm/prisma-client/client-extensions). +To see the full syntax for defining each type of extension component, please refer to [the docs](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions). ### Sharing an extension @@ -95,7 +95,7 @@ import findOrCreate from "prisma-extension-find-or-create"; const prisma = new PrismaClient().$extends(findOrCreate); const user = await prisma.user.findOrCreate({ /* ... */ }); ``` -Read [our documentation on sharing extensions](https://www.prisma.io/docs/orm/prisma-client/client-extensions/shared-extensions) for more details. +Read [our documentation on sharing extensions](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions/shared-extensions) for more details. ## Sample use cases @@ -798,7 +798,7 @@ This example shows the extension equivalent of what middleware (`$use`) did befo This technique could be used to perform generic logging, emit events, track usage, etc. -> **Note**: You may also be interested in [tracing](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing) and [metrics](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/metrics), which provide detailed insights into performance and how Prisma interacts with the database. +> **Note**: You may also be interested in [tracing](https://www.prisma.io/docs/orm/v7/prisma-client/observability-and-logging/opentelemetry-tracing) and [metrics](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/metrics), which provide detailed insights into performance and how Prisma interacts with the database. @@ -865,7 +865,7 @@ function RetryTransactions(options?: Partial) { return backOff(() => prisma.$transaction.apply(prisma, args), { retry: (e) => { // Retry the transaction only if the error was due to a write conflict or deadlock - // See: https://www.prisma.io/docs/orm/reference/error-reference#p2034 + // See: https://www.prisma.io/docs/orm/v7/reference/error-reference#p2034 return e.code === "P2034"; }, ...options, @@ -912,7 +912,7 @@ model User { [View full example on GitHub](https://github.com/prisma/prisma-client-extensions/tree/main/callback-free-itx) -This example shows a Prisma Client extension which adds a new API for starting [interactive transactions](https://www.prisma.io/docs/orm/prisma-client/queries/transactions#interactive-transactions) without callbacks. +This example shows a Prisma Client extension which adds a new API for starting [interactive transactions](https://www.prisma.io/docs/orm/v7/prisma-client/queries/transactions#interactive-transactions) without callbacks. This gives you the full power of interactive transactions (such as read-modify-write cycles), but in a more imperative API. This may be more convenient than the normal callback-style API for interactive transactions in some scenarios. @@ -1280,4 +1280,4 @@ No. Calling `$extends` returns a new, extended client instance and leaves the or Extensions are how you teach Prisma Client the conventions of your codebase: the 15 patterns above are starting points, and the [examples repo](https://github.com/prisma/prisma-client-extensions) keeps runnable versions of each. They work the same against any Postgres, including a [Prisma Postgres](https://www.prisma.io/docs/postgres) database you can create in seconds with `npx create-db`. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/cloudflare-unikernels-and-bare-metal-life-of-a-prisma-postgres-query/index.mdx b/apps/blog/content/blog/cloudflare-unikernels-and-bare-metal-life-of-a-prisma-postgres-query/index.mdx index 4fc489c07c..3a7d834b45 100644 --- a/apps/blog/content/blog/cloudflare-unikernels-and-bare-metal-life-of-a-prisma-postgres-query/index.mdx +++ b/apps/blog/content/blog/cloudflare-unikernels-and-bare-metal-life-of-a-prisma-postgres-query/index.mdx @@ -203,5 +203,5 @@ In this article, we looked under the covers of Prisma Postgres and the next-gene If you are already using Prisma ORM, give Prisma Postgres a try [by importing the data from your existing database](https://www.prisma.io/docs/getting-started/prisma-postgres/import-from-existing-database) in . Otherwise, try out Prisma Postgres from scratch by running this command in your terminal: ``` -npx prisma@latest init --db +npx prisma@7.9.1 init --db ``` \ No newline at end of file diff --git a/apps/blog/content/blog/data-migrations-in-prisma-next/index.mdx b/apps/blog/content/blog/data-migrations-in-prisma-next/index.mdx index ce0985d1a6..4fe9455f92 100644 --- a/apps/blog/content/blog/data-migrations-in-prisma-next/index.mdx +++ b/apps/blog/content/blog/data-migrations-in-prisma-next/index.mdx @@ -19,11 +19,11 @@ seriesIndex: 5 > _Editor's note: Prisma 8 was developed under the working name Prisma Next. This post has been updated to use the final name._ -Sooner or later, you need a migration to change data as well as schema. In Prisma 8, that happens inside your migration in TypeScript, with the same [query builder](https://www.prisma.io/docs/orm/v8/fundamentals/writing-data) you use in your app. +Sooner or later, you need a migration to change data as well as schema. In Prisma 8, that happens inside your migration in TypeScript, with the same [query builder](https://www.prisma.io/docs/orm/fundamentals/writing-data) you use in your app. -In the [previous post](https://pris.ly/ts-migrations-pn) we covered [how migrations change the database schema](https://www.prisma.io/docs/orm/v8/migrations/how-migrations-work): a TypeScript migration file with a list of operations, compiled to JSON, applied by the [migration runner](https://www.prisma.io/docs/orm/v8/migrations/applying-a-migration). Start there if any of those terms are unfamiliar. +In the [previous post](https://pris.ly/ts-migrations-pn) we covered [how migrations change the database schema](https://www.prisma.io/docs/orm/migrations/how-migrations-work): a TypeScript migration file with a list of operations, compiled to JSON, applied by the [migration runner](https://www.prisma.io/docs/orm/migrations/applying-a-migration). Start there if any of those terms are unfamiliar. -Take a common example. You've added a `displayName` column to `User` in [`contract.prisma`](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract) and you want to make it `NOT NULL`. There's a snag: there are already rows in the table, and they don't have a `displayName` yet, so setting the column `NOT NULL` fails, every existing row violates the constraint. +Take a common example. You've added a `displayName` column to `User` in [`contract.prisma`](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract) and you want to make it `NOT NULL`. There's a snag: there are already rows in the table, and they don't have a `displayName` yet, so setting the column `NOT NULL` fails, every existing row violates the constraint. A simple approach to solve this problem is to: @@ -74,11 +74,11 @@ There's also a quieter problem. The script uses your _current_ Prisma client, wh Whichever path you pick, your data transformation doesn't have access to the same tools, verifications or editor assistance as the rest of your application logic. -People have asked for the obvious fix, being able to use the Prisma client _inside_ a migration, for years (the [docs](https://www.prisma.io/docs/orm/prisma-migrate/workflows/customizing-migrations) point at the SQL or out-of-band script as the official answers; and there are many open issues with suggestions for how to integrate the TypeScript client and migrations: [#11194](https://github.com/prisma/prisma/issues/11194), [#4688](https://github.com/prisma/prisma/issues/4688), [#6345](https://github.com/prisma/prisma/issues/6345), [#10050](https://github.com/prisma/prisma/issues/10050)). +People have asked for the obvious fix, being able to use the Prisma client _inside_ a migration, for years (the [docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/customizing-migrations) point at the SQL or out-of-band script as the official answers; and there are many open issues with suggestions for how to integrate the TypeScript client and migrations: [#11194](https://github.com/prisma/prisma/issues/11194), [#4688](https://github.com/prisma/prisma/issues/4688), [#6345](https://github.com/prisma/prisma/issues/6345), [#10050](https://github.com/prisma/prisma/issues/10050)). ## In Prisma 8, you write the data step in TypeScript -Here is the same example, written as a Prisma 8 migration. The initial file is written for you by [`migration plan`](https://www.prisma.io/docs/orm/v8/migrations/generating-a-migration) when you change your `contract.prisma`. The `dataTransform()` line you'd add by hand: +Here is the same example, written as a Prisma 8 migration. The initial file is written for you by [`migration plan`](https://www.prisma.io/docs/orm/migrations/generating-a-migration) when you change your `contract.prisma`. The `dataTransform()` line you'd add by hand: ```typescript // migrations/20260422T0748_add_user_display_name/migration.ts @@ -186,7 +186,7 @@ This is what lets a data transformation reference columns the same migration is ## MongoDB gets data transformations too -Here's a `dataTransform` against a [Mongo collection](https://www.prisma.io/docs/orm/v8/data-modeling/mongodb), backfilling a `status` field on a `products` collection so it can be made required: +Here's a `dataTransform` against a [Mongo collection](https://www.prisma.io/docs/orm/data-modeling/mongodb), backfilling a `status` field on a `products` collection so it can be made required: ```typescript import { dataTransform } from "@prisma/orm-mongo/target/migration"; @@ -211,7 +211,7 @@ Same `check` and `run` callbacks. Same compilation to a JSON file. Same kind of If you're as excited about this as we are, go ahead and try it out! [The Prisma 8 Release Candidate is available](https://www.prisma.io/blog/prisma-next-early-access-write-your-contract-prompt-your-agent-ship-your-app). ```bash -npx prisma@next orm init +npx prisma@latest orm init ``` This command will set up Prisma 8 in a new or existing project with a simple example contract. Write a schema change with a data step in the same file, plan it, read the JSON it compiled to, and apply it. diff --git a/apps/blog/content/blog/database-access-on-the-edge-8F0t1s1BqOJE/index.mdx b/apps/blog/content/blog/database-access-on-the-edge-8F0t1s1BqOJE/index.mdx index c3c4bafd6b..5ee3799f91 100644 --- a/apps/blog/content/blog/database-access-on-the-edge-8F0t1s1BqOJE/index.mdx +++ b/apps/blog/content/blog/database-access-on-the-edge-8F0t1s1BqOJE/index.mdx @@ -284,7 +284,7 @@ Give your project a name and open up the **Environment Variables** toggle and fi - `DATABASE_URL`: the Prisma Accelerate connection string - `PRISMA_GENERATE_NO_ENGINE`: `true` -> The [`PRISMA_GENERATE_NO_ENGINE`](https://www.prisma.io/docs/orm/reference/environment-variables-reference#prisma_generate_no_engine) can be set to a truthy value to generate a Prisma Client without an included [query engine](https://www.prisma.io/docs/orm/more/under-the-hood/engines#the-query-engine-file) in order to reduce deployed application size when paired with Prisma Accelerate. +> The [`PRISMA_GENERATE_NO_ENGINE`](https://www.prisma.io/docs/orm/v7/reference/environment-variables-reference#prisma_generate_no_engine) can be set to a truthy value to generate a Prisma Client without an included [query engine](https://www.prisma.io/docs/orm/more/under-the-hood/engines#the-query-engine-file) in order to reduce deployed application size when paired with Prisma Accelerate. ![](/database-access-on-the-edge-8F0t1s1BqOJE/imgs/set_env_variables_and_deploy.png) diff --git a/apps/blog/content/blog/e2e-type-safety-graphql-react-2-j9mEyHY0Ej/index.mdx b/apps/blog/content/blog/e2e-type-safety-graphql-react-2-j9mEyHY0Ej/index.mdx index 021c529471..e9bb605724 100644 --- a/apps/blog/content/blog/e2e-type-safety-graphql-react-2-j9mEyHY0Ej/index.mdx +++ b/apps/blog/content/blog/e2e-type-safety-graphql-react-2-j9mEyHY0Ej/index.mdx @@ -192,7 +192,7 @@ Next you will set up Prisma. Your GraphQL server will use Prisma Client to query To set up Prisma, you first need to install Prisma CLI as a development dependency: ```shell -npm i -D prisma +npm i -D prisma@7.9.1 ``` ### Initialize Prisma diff --git a/apps/blog/content/blog/from-local-to-production-with-prisma-postgres/index.mdx b/apps/blog/content/blog/from-local-to-production-with-prisma-postgres/index.mdx index 4df4eee57d..949b565509 100644 --- a/apps/blog/content/blog/from-local-to-production-with-prisma-postgres/index.mdx +++ b/apps/blog/content/blog/from-local-to-production-with-prisma-postgres/index.mdx @@ -105,7 +105,7 @@ Then grab the connection strings you will need: Every Prisma Postgres database has [two connection strings](https://www.prisma.io/docs/postgres/database/connecting-to-your-database): a **pooled** one (hostname `pooled.db.prisma.io`) for application traffic, and a **direct** one (`db.prisma.io`) for migrations and standard Postgres tools like `pg_restore`. You will use both in the next steps. -Two CLI alternatives, depending on where you are: for a brand-new project, `npx prisma init --db` scaffolds the schema and provisions a Prisma Postgres database in one go, and [`npx create-db@latest`](https://www.prisma.io/docs/postgres/npx-create-db) creates a temporary database with no sign-up; claim it within 24 hours to keep it, or it is deleted. +Two CLI alternatives, depending on where you are: for a brand-new project, `npx prisma@7.9.1 init --db` scaffolds the schema and provisions a Prisma Postgres database in one go, and [`npx create-db@latest`](https://www.prisma.io/docs/postgres/npx-create-db) creates a temporary database with no sign-up; claim it within 24 hours to keep it, or it is deleted. ## Update env and config @@ -164,7 +164,7 @@ npx prisma migrate diff \ npx prisma migrate resolve --applied 0_init ``` -That writes the migration your schema implies and records it as already applied locally, without touching your data. Point `.env` back at production before continuing. The [baselining docs](https://www.prisma.io/docs/orm/prisma-migrate/workflows/baselining) cover the workflow in full. Do this before dumping, too, if you are taking the data path below: it gives the dump a migration history to carry. +That writes the migration your schema implies and records it as already applied locally, without touching your data. Point `.env` back at production before continuing. The [baselining docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/baselining) cover the workflow in full. Do this before dumping, too, if you are taking the data path below: it gives the dump a migration history to carry. With `.env` on production, the CLI applies your migrations to the hosted database, over the direct connection: @@ -178,7 +178,7 @@ npx prisma migrate deploy All migrations have been successfully applied. ``` -`migrate deploy` is the production counterpart of `migrate dev`: it applies the committed migration files in order, with no schema drafting, no prompts, and no drift detection. That makes it safe to put in CI or your deploy pipeline, where it belongs. The [development and production workflows docs](https://www.prisma.io/docs/orm/prisma-migrate/workflows/development-and-production) explain the split. If you have a seed script for production defaults, run it once now, while `.env` points at production. +`migrate deploy` is the production counterpart of `migrate dev`: it applies the committed migration files in order, with no schema drafting, no prompts, and no drift detection. That makes it safe to put in CI or your deploy pipeline, where it belongs. The [development and production workflows docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/development-and-production) explain the split. If you have a seed script for production defaults, run it once now, while `.env` points at production. **Bringing the data along.** If the local data matters, copy it with the standard Postgres tools. The dump and restore below both take their database on the command line with `-d`, so neither reads `.env`; it does not matter that `.env` currently points at production. @@ -249,7 +249,7 @@ Yes, that is the intended workflow. Production traffic hits hosted Prisma Postgr The checklist, condensed: 1. **Develop locally.** `npx prisma dev` for a one-command local Prisma Postgres, or keep your Docker Postgres. Apply schema changes with `npx prisma migrate dev`. -2. **Create the hosted database.** Console **New project**, or `npx prisma init --db` for a brand-new project, or `npx create-db@latest` and claim it within 24 hours. Copy the pooled and direct connection strings. +2. **Create the hosted database.** Console **New project**, or `npx prisma@7.9.1 init --db` for a brand-new project, or `npx create-db@latest` and claim it within 24 hours. Copy the pooled and direct connection strings. 3. **Update config.** Set the pooled `DATABASE_URL` and the direct `DIRECT_URL`, point the config's datasource at `DIRECT_URL`, and store the production URLs in your platform's env settings. 4. **Move schema and data.** Fresh start: `npx prisma migrate deploy` plus your seed. With data: `pg_dump -Fc` locally, `pg_restore` over the direct connection, history included. 5. **Validate.** `npx prisma migrate status`, row counts in Prisma Studio, one smoke test, then deploy with `migrate deploy` in the pipeline. diff --git a/apps/blog/content/blog/from-rust-to-typescript-a-new-chapter-for-prisma-orm/index.mdx b/apps/blog/content/blog/from-rust-to-typescript-a-new-chapter-for-prisma-orm/index.mdx index b489c2a096..2eb91b3aee 100644 --- a/apps/blog/content/blog/from-rust-to-typescript-a-new-chapter-for-prisma-orm/index.mdx +++ b/apps/blog/content/blog/from-rust-to-typescript-a-new-chapter-for-prisma-orm/index.mdx @@ -166,7 +166,7 @@ You can now use Prisma in environments that support JavaScript or WASM, such as To enable it, use the new `prisma-client` generator and configure the correct driver adapter for your database, for example `@prisma/adapter-pg` for PostgreSQL. -See the [Prisma Client generator documentation](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#prisma-client?utm_source=chatgpt.com) for setup instructions. +See the [Prisma Client generator documentation](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#prisma-client?utm_source=chatgpt.com) for setup instructions. ### If Rust is already fast, why does switching to TypeScript and WebAssembly make Prisma faster? diff --git a/apps/blog/content/blog/full-stack-typesafety-with-angular-nest-nx-and-prisma-CcMK7fbQfTWc/index.mdx b/apps/blog/content/blog/full-stack-typesafety-with-angular-nest-nx-and-prisma-CcMK7fbQfTWc/index.mdx index dd13a37912..8dedb03162 100644 --- a/apps/blog/content/blog/full-stack-typesafety-with-angular-nest-nx-and-prisma-CcMK7fbQfTWc/index.mdx +++ b/apps/blog/content/blog/full-stack-typesafety-with-angular-nest-nx-and-prisma-CcMK7fbQfTWc/index.mdx @@ -131,7 +131,7 @@ npx prisma init After running this command, a `prisma` directory is created at the workspace root. Inside is a single file called `schema.prisma`. -This file uses the [Prisma Schema Language](https://www.prisma.io/docs/orm/prisma-schema/overview) and is the place where we define the shape of our database. We use it to describe the tables for our databases and their columns, the relationships between tables, and more. +This file uses the [Prisma Schema Language](https://www.prisma.io/docs/orm/v7/prisma-schema/overview) and is the place where we define the shape of our database. We use it to describe the tables for our databases and their columns, the relationships between tables, and more. When we create a Prisma model, we need to select a `provider` for our datasource. The default `schema.prisma` file comes with a datasource called `db` which uses PostgreSQL as the provider. @@ -179,7 +179,7 @@ npx prisma migrate dev --preview-feature An interactive prompt will ask for the name of the migration. Call it whatever you like, something like `init` works fine. -After the migration completes, a `dev.db` file is created in the `prisma` directory, along with a `migrations` directory. It's within the `migrations` directory that all of the SQL that's used to perform our database migrations is stored. Since these files are raw SQL, we have the opportunity to adjust them before they operate on our databases. Read the [migrate docs](https://www.prisma.io/docs/orm/prisma-migrate) to find out more about how you can customize the migration behavior. +After the migration completes, a `dev.db` file is created in the `prisma` directory, along with a `migrations` directory. It's within the `migrations` directory that all of the SQL that's used to perform our database migrations is stored. Since these files are raw SQL, we have the opportunity to adjust them before they operate on our databases. Read the [migrate docs](https://www.prisma.io/docs/orm/v7/prisma-migrate) to find out more about how you can customize the migration behavior. ## View the Database with Prisma Studio and Seed Some Data diff --git a/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-5-m2fna60h7c/index.mdx b/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-5-m2fna60h7c/index.mdx index 6f0d9ab140..bf0a0d2636 100644 --- a/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-5-m2fna60h7c/index.mdx +++ b/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-5-m2fna60h7c/index.mdx @@ -18,7 +18,7 @@ tags: This article is the final part of the course where you build a fullstack app with Next.js, GraphQL, TypeScript, Prisma, and PostgreSQL. In this article, you will learn how to deploy your app to Vercel. -> **Update (May 2026):** This deployment chapter still works as a conceptual guide, but the Prisma Data Proxy steps are now historical. For new projects, prefer [Prisma Accelerate](https://www.prisma.io/accelerate) for connection pooling and caching, use the current [serverless deployment docs](https://www.prisma.io/docs/orm/prisma-client/deployment/serverless/deploy-to-vercel), and consider [Prisma Postgres](https://www.prisma.io/postgres) if you want a managed Postgres database with Prisma ORM. +> **Update (May 2026):** This deployment chapter still works as a conceptual guide, but the Prisma Data Proxy steps are now historical. For new projects, prefer [Prisma Accelerate](https://www.prisma.io/accelerate) for connection pooling and caching, use the current [serverless deployment docs](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/serverless/deploy-to-vercel), and consider [Prisma Postgres](https://www.prisma.io/postgres) if you want a managed Postgres database with Prisma ORM. ## Table of Contents @@ -158,7 +158,7 @@ You: - Learned why serverless deployments need connection pooling and how Prisma approached that problem at the time - Deployed your Next.js application to Vercel -For a modern production setup, use [Prisma Accelerate](https://www.prisma.io/accelerate) together with the latest [Prisma Client deployment docs](https://www.prisma.io/docs/orm/prisma-client/deployment/serverless/deploy-to-vercel). +For a modern production setup, use [Prisma Accelerate](https://www.prisma.io/accelerate) together with the latest [Prisma Client deployment docs](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/serverless/deploy-to-vercel). You can find the complete source code for the app on [GitHub](https://github.com/prisma/awesome-links). Feel free to raise issues or contribute to the repository if you find any bugs or want to make improvements. diff --git a/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-oklidw1rhw/index.mdx b/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-oklidw1rhw/index.mdx index 600557ace1..1af413f702 100644 --- a/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-oklidw1rhw/index.mdx +++ b/apps/blog/content/blog/fullstack-nextjs-graphql-prisma-oklidw1rhw/index.mdx @@ -165,7 +165,7 @@ The database will have the following entities, where each entity will map to a t - `User`: a person with an account. They can bookmark their favorite links and can either be an admin or a regular user. - `Link`: to represent the different attributes for a link such as a title, a description, and a URL. -There's a [many-to-many](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations#many-to-many-relations) (also known as `m-n`) relation between the `User` and `Link` entities. This way a user can have many links and a link can have many users. +There's a [many-to-many](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations#many-to-many-relations) (also known as `m-n`) relation between the `User` and `Link` entities. This way a user can have many links and a link can have many users. ### Add Prisma to your project @@ -252,9 +252,9 @@ enum Role { ``` > **Note**: models are typically spelled in [PascalCase](https://wiki.c2.com/?pascalcase) and should use the singular form. (for example, `User` instead of `user`, `users` or `Users`) -Here we defined a `User` model with several fields. Each field has a name followed by a type and [optional field attributes](https://www.prisma.io/docs/orm/prisma-schema/data-model/models#defining-fields). +Here we defined a `User` model with several fields. Each field has a name followed by a type and [optional field attributes](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/models#defining-fields). -For example, the `id` field is of type `Int` and has the `@id` field attribute, specifying that this is the primary key of the table. The `@default(autoincrement())` attribute sets an auto-incrementing [default value](https://www.prisma.io/docs/orm/reference/prisma-schema-reference#default). +For example, the `id` field is of type `Int` and has the `@id` field attribute, specifying that this is the primary key of the table. The `@default(autoincrement())` attribute sets an auto-incrementing [default value](https://www.prisma.io/docs/orm/v7/reference/prisma-schema-reference#default). All fields are required by default. To make a field optional, you can add a `?` after the field type. @@ -345,7 +345,7 @@ model Link { + users User[] } ``` -This is an [_implicit_ many-to-many](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations#implicit-many-to-many-relations) relation, where we have a relation table in the underlying database. This [relation table](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations#relation-tables) is managed by Prisma. +This is an [_implicit_ many-to-many](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations#implicit-many-to-many-relations) relation, where we have a relation table in the underlying database. This [relation table](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations#relation-tables) is managed by Prisma. Here's what the final schema looks like: @@ -500,9 +500,9 @@ main() await prisma.$disconnect() }) ``` -We are first creating a user using the [`create()`](https://www.prisma.io/docs/orm/reference/prisma-client-reference#create) function, which creates a new database record. +We are first creating a user using the [`create()`](https://www.prisma.io/docs/orm/v7/reference/prisma-client-reference#create) function, which creates a new database record. -Next, we are using the [`createMany()`](https://www.prisma.io/docs/orm/reference/prisma-client-reference#createmany) function to create multiple records. We are passing the hard-coded data we have as a parameter. +Next, we are using the [`createMany()`](https://www.prisma.io/docs/orm/v7/reference/prisma-client-reference#createmany) function to create multiple records. We are passing the hard-coded data we have as a parameter. By default, Next.js [forces the use of `ESNext` modules](https://github.com/vercel/next.js/issues/7361), we need to override this behavior or else we will not be able to execute the seeding script. To do so, first install `ts-node` as a development dependency: diff --git a/apps/blog/content/blog/fullstack-remix-prisma-mongodb-1-7d0bftxbmb6r/index.mdx b/apps/blog/content/blog/fullstack-remix-prisma-mongodb-1-7d0bftxbmb6r/index.mdx index 7bde7d6f15..50814294ab 100644 --- a/apps/blog/content/blog/fullstack-remix-prisma-mongodb-1-7d0bftxbmb6r/index.mdx +++ b/apps/blog/content/blog/fullstack-remix-prisma-mongodb-1-7d0bftxbmb6r/index.mdx @@ -326,7 +326,7 @@ Now that you have a MongoDB database to connect to, it's time to set up Prisma! The first thing you will want to do is install the [Prisma CLI](https://www.prisma.io/docs/orm/tools/prisma-cli) as a development dependency. This is what will allow you to run various Prisma commands. ```shell -npm i -D prisma +npm i -D prisma@7.9.1 ``` To initialize Prisma within the project, simply run: @@ -355,7 +355,7 @@ datasource db { ``` > **Note**: This file is written in PSL (Prisma Schema Language), which allows you to map out your schema. For more information on Prisma schemas and PSL, check out the [Prisma docs](https://www.prisma.io/docs/orm/prisma-schema). -In the `url` of the [`datasource`](https://www.prisma.io/docs/orm/prisma-schema/overview/data-sources) block, you can see it references the `DATABASE_URL` environment variable from the `.env` file using the `env()` function PSL provides. Prisma uses [dotenv](https://www.npmjs.com/package/dotenv) under the hood to expose those variables to Prisma. +In the `url` of the [`datasource`](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/data-sources) block, you can see it references the `DATABASE_URL` environment variable from the `.env` file using the `env()` function PSL provides. Prisma uses [dotenv](https://www.npmjs.com/package/dotenv) under the hood to expose those variables to Prisma. ### Set your environment variable @@ -393,7 +393,7 @@ Now you can begin to think about your data model and start to map out the [colle For this section, however, create a `User` model you will use in the next section of this series which handles setting up authentication. -Over in `prisma/prisma.schema`, add a new [`model`](https://www.prisma.io/docs/orm/prisma-schema/data-model/models#defining-models) to your schema named `User`. This will be where you define what a user should look like in the database. +Over in `prisma/prisma.schema`, add a new [`model`](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/models#defining-models) to your schema named `User`. This will be where you define what a user should look like in the database. ```prisma // ./prisma/schema.prisma diff --git a/apps/blog/content/blog/grover-customer-success-story-nxkWGcGNuvFd/index.mdx b/apps/blog/content/blog/grover-customer-success-story-nxkWGcGNuvFd/index.mdx index 2416a1a983..36c5c211a9 100644 --- a/apps/blog/content/blog/grover-customer-success-story-nxkWGcGNuvFd/index.mdx +++ b/apps/blog/content/blog/grover-customer-success-story-nxkWGcGNuvFd/index.mdx @@ -56,7 +56,7 @@ Prisma offers three core products that help developers move quickly and code saf Prisma Client gives Grover confidence in their database access by providing type safety when making queries. -- [**Prisma Migrate**](https://www.prisma.io/docs/orm/prisma-migrate) - **a tool for seamless database migrations** +- [**Prisma Migrate**](https://www.prisma.io/docs/orm/v7/prisma-migrate) - **a tool for seamless database migrations** Database introspection and migrations are smooth and simple for Grover using Prisma Migrate, especially when they need to change the database structure in production diff --git a/apps/blog/content/blog/how-prisma-orm-became-the-most-downloaded-orm-for-node-js/index.mdx b/apps/blog/content/blog/how-prisma-orm-became-the-most-downloaded-orm-for-node-js/index.mdx index 1ec6850a74..55ba5725dd 100644 --- a/apps/blog/content/blog/how-prisma-orm-became-the-most-downloaded-orm-for-node-js/index.mdx +++ b/apps/blog/content/blog/how-prisma-orm-became-the-most-downloaded-orm-for-node-js/index.mdx @@ -105,7 +105,7 @@ The reason for that direction is the same fragmentation problem the download num Prisma's answer is one platform where the layers are designed to work together: - **[Prisma ORM](https://www.prisma.io/orm)** describes your data in a typed schema and generates a type-safe client. The schema is a source of truth that human developers and coding agents share. -- **[Prisma Postgres](https://www.prisma.io/postgres)** is managed PostgreSQL built into that workflow: `npx prisma init --db` provisions a production database, and `npx prisma dev` runs a local one. +- **[Prisma Postgres](https://www.prisma.io/postgres)** is managed PostgreSQL built into that workflow: `npx prisma@7.9.1 init --db` provisions a production database, and `npx prisma dev` runs a local one. - **[Prisma Compute](https://www.prisma.io/compute)**, now in public beta, deploys TypeScript applications next to your database for low-latency data access. Every layer is operable through the same programmable interfaces: the CLI, the Management API, and the [MCP server](/announcing-prisma-s-mcp-server-vibe-code-with-prisma-postgres). That is what a single-agent experience means in practice. An agent can define a schema, provision a database, run migrations, deploy the application, and debug it, entirely in code, with one bill and predictable spend caps at the end. diff --git a/apps/blog/content/blog/improving-query-performance-using-indexes-2-MyoiJNMFTsfq/index.mdx b/apps/blog/content/blog/improving-query-performance-using-indexes-2-MyoiJNMFTsfq/index.mdx index 2b4b06b0ff..1db2a5d11c 100644 --- a/apps/blog/content/blog/improving-query-performance-using-indexes-2-MyoiJNMFTsfq/index.mdx +++ b/apps/blog/content/blog/improving-query-performance-using-indexes-2-MyoiJNMFTsfq/index.mdx @@ -78,7 +78,7 @@ Create a new project and install the dependencies: ```shell mkdir prisma-indexes && cd prisma-indexes npm init -y -npm install prisma @prisma/client @prisma/adapter-pg @faker-js/faker dotenv tsx typescript @types/node +npm install prisma@7.9.1 @prisma/client@7.9.1 @prisma/adapter-pg @faker-js/faker dotenv tsx typescript @types/node ``` The packages you will use: @@ -195,11 +195,11 @@ npx prisma generate npx prisma db seed ``` -`db push` syncs the schema straight to the database, which is the fastest loop for local prototyping. For a production application backed by a hosted database you would capture schema changes as migration files with [`prisma migrate dev`](https://www.prisma.io/docs/orm/prisma-migrate) instead. Seeding half a million rows takes about 40 seconds. +`db push` syncs the schema straight to the database, which is the fastest loop for local prototyping. For a production application backed by a hosted database you would capture schema changes as migration files with [`prisma migrate dev`](https://www.prisma.io/docs/orm/v7/prisma-migrate) instead. Seeding half a million rows takes about 40 seconds. ### Measure the slow query -The original version of this article measured query time with `prisma.$use()` middleware. Middleware was removed from Prisma ORM; the current way to wrap queries is a [Prisma Client extension](https://www.prisma.io/docs/orm/prisma-client/client-extensions). Create a measurement script: +The original version of this article measured query time with `prisma.$use()` middleware. Middleware was removed from Prisma ORM; the current way to wrap queries is a [Prisma Client extension](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions). Create a measurement script: ```typescript // src/measure.ts @@ -288,7 +288,7 @@ model User { } ``` -`@@index` supports more arguments, such as `map` to control the index name in the database. You can learn more in the [Prisma Schema API Reference](https://www.prisma.io/docs/orm/reference/prisma-schema-reference#index). +`@@index` supports more arguments, such as `map` to control the index name in the database. You can learn more in the [Prisma Schema API Reference](https://www.prisma.io/docs/orm/v7/reference/prisma-schema-reference#index). Because the index is declared in your Prisma schema rather than hand-run against the database, it lives in code: it gets reviewed with the rest of your changes, applies identically in every environment, and gives both your team and your coding agent one source of truth for the data layer. diff --git a/apps/blog/content/blog/improving-query-performance-using-indexes-3-kduk351qv1/index.mdx b/apps/blog/content/blog/improving-query-performance-using-indexes-3-kduk351qv1/index.mdx index ec9e182814..f5bd52af2f 100644 --- a/apps/blog/content/blog/improving-query-performance-using-indexes-3-kduk351qv1/index.mdx +++ b/apps/blog/content/blog/improving-query-performance-using-indexes-3-kduk351qv1/index.mdx @@ -130,7 +130,7 @@ You can define a hash index in your Prisma schema using the `@@index()` attribut - `fields`: the list of fields to be indexed - `type`: the index access method the database should use, `Hash` in this case (the default is `BTree`) -The `@@index` attribute supports more arguments you can learn more about in the [Prisma Schema API Reference](https://www.prisma.io/docs/orm/reference/prisma-schema-reference#index). +The `@@index` attribute supports more arguments you can learn more about in the [Prisma Schema API Reference](https://www.prisma.io/docs/orm/v7/reference/prisma-schema-reference#index). Add a hash index on the `lastName` field: @@ -203,6 +203,6 @@ It depends on table size and how many rows match. In the test in this article, v In this part, you learned what hash indexes are, their internal structure and limitations, and how to define and use a hash index using Prisma ORM: from a 64.1ms sequential scan over 500,000 rows to a 1.6ms lookup, verified with `EXPLAIN ANALYZE`. -The same workflow carries to production: `npx prisma init --db` provisions a managed Prisma Postgres database, and the indexes you declared in your schema apply there exactly as they did locally. +The same workflow carries to production: `npx prisma@7.9.1 init --db` provisions a managed Prisma Postgres database, and the indexes you declared in your schema apply there exactly as they did locally. If you would like to learn about the fundamentals of database indexes and B-tree indexes, refer to [part 1](/improving-query-performance-using-indexes-1-zuLNZwBkuL) and [part 2](/improving-query-performance-using-indexes-2-MyoiJNMFTsfq). diff --git a/apps/blog/content/blog/introducing-create-prisma/index.mdx b/apps/blog/content/blog/introducing-create-prisma/index.mdx index 256f664447..834b442ca8 100644 --- a/apps/blog/content/blog/introducing-create-prisma/index.mdx +++ b/apps/blog/content/blog/introducing-create-prisma/index.mdx @@ -8,7 +8,7 @@ metaTitle: "Introducing Create-Prisma: Start a Prisma App With One Command" metaDescription: "create-prisma is a new CLI that creates an app with Prisma set up, a starter schema, seed data, database scripts, and optional Prisma Postgres setup." excerpt: "create-prisma is a new CLI that creates an app with Prisma set up, including a starter schema, seed data, database scripts, and optional Prisma Postgres setup." heroImagePath: "/introducing-create-prisma/imgs/hero.svg" -heroImageAlt: "An ink terminal card running npm create prisma@latest, with a checklist of what the CLI generates: prisma/schema.prisma, prisma/seed.ts, prisma.config.ts, a .env file with DATABASE_URL, and the db:generate, db:migrate and db:seed scripts." +heroImageAlt: "An ink terminal card running npm create prisma@stable, with a checklist of what the CLI generates: prisma/schema.prisma, prisma/seed.ts, prisma.config.ts, a .env file with DATABASE_URL, and the db:generate, db:migrate and db:seed scripts." metaImagePath: "/introducing-create-prisma/imgs/meta.png" tags: - "announcement" diff --git a/apps/blog/content/blog/learn-typescript-a-pocketguide-tutorial-q329XmXQHUjz/index.mdx b/apps/blog/content/blog/learn-typescript-a-pocketguide-tutorial-q329XmXQHUjz/index.mdx index a8be0c3a0d..16f932317d 100644 --- a/apps/blog/content/blog/learn-typescript-a-pocketguide-tutorial-q329XmXQHUjz/index.mdx +++ b/apps/blog/content/blog/learn-typescript-a-pocketguide-tutorial-q329XmXQHUjz/index.mdx @@ -650,7 +650,7 @@ With the Prisma CLI insatlled, initialize Prisma in your project. ```shell -npx prisma init +npx prisma@7.9.1 init ``` @@ -716,7 +716,7 @@ With the database and table in place, install [Prisma Client](https://www.prisma ```shell -npm install @prisma/client +npm install @prisma/client@7.9.1 ``` diff --git a/apps/blog/content/blog/mongodb-without-compromise/index.mdx b/apps/blog/content/blog/mongodb-without-compromise/index.mdx index 07511dbb06..3996eefd6a 100644 --- a/apps/blog/content/blog/mongodb-without-compromise/index.mdx +++ b/apps/blog/content/blog/mongodb-without-compromise/index.mdx @@ -14,7 +14,7 @@ tags: - "announcement" --- -For the first time, [Prisma 8](https://www.prisma.io/docs/orm/v8) brings the MongoDB-native experience to TypeScript. Type-safe queries, database migrations, polymorphic models, embedded collections and more. Designed in collaboration with the MongoDB DX team. +For the first time, [Prisma 8](https://www.prisma.io/docs/orm) brings the MongoDB-native experience to TypeScript. Type-safe queries, database migrations, polymorphic models, embedded collections and more. Designed in collaboration with the MongoDB DX team. ## What MongoDB development looks like today @@ -25,7 +25,7 @@ If you've built a MongoDB app with TypeScript recently, you've probably gone thr - You write a query and the types don't fully connect, so you cast, add guards, or accept a little `any`. - You need an index, so you drop into the MongoDB shell or a deployment script and hope your database stays in sync with your code. -In Prisma 8, you describe your [data model](https://www.prisma.io/docs/orm/v8/data-modeling/mongodb) as a contract: +In Prisma 8, you describe your [data model](https://www.prisma.io/docs/orm/data-modeling/mongodb) as a contract: ```prisma model User { @@ -97,13 +97,13 @@ const recentPosts = await orm.posts // recentPosts[0].author.bio -> string | null ``` -The [`.include('author')`](https://www.prisma.io/docs/orm/v8/fundamentals/relations-and-joins) compiles to a `$lookup` pipeline stage. Skip the `.include()` and the author isn't loaded and isn't in the type. Your documents are typed all the way down, no matter how far you nest. +The [`.include('author')`](https://www.prisma.io/docs/orm/fundamentals/relations-and-joins) compiles to a `$lookup` pipeline stage. Skip the `.include()` and the author isn't loaded and isn't in the type. Your documents are typed all the way down, no matter how far you nest. ## Real migrations for MongoDB MongoDB is not schema-less. Your deployment has real, persistent, server-side state, and that state directly affects correctness and performance. Yet most tools do not manage it properly. -The `@@index` declarations in the contract above are not just documentation. They are managed by a [migration system](https://www.prisma.io/docs/orm/v8/migrations/how-migrations-work) that versions, diffs, and deploys your database state. +The `@@index` declarations in the contract above are not just documentation. They are managed by a [migration system](https://www.prisma.io/docs/orm/migrations/how-migrations-work) that versions, diffs, and deploys your database state. - **Indexes:** unique, compound, TTL, partial, geospatial, text, and wildcard. If an index is wrong, queries slow down. If a unique constraint is missing, duplicate data can slip in. - **JSON Schema validators:** document-level validation rules generated from your model definitions. Even writes that bypass the ORM are still validated by the server. @@ -112,7 +112,7 @@ The `@@index` declarations in the contract above are not just documentation. The When you update your contract and run `migration plan`, the planner compares the current state with the desired state: ```shell -$ npx prisma@next migration plan +$ npx prisma@latest migration plan Migration: 20260409T1200_add_post_indexes @@ -165,7 +165,7 @@ Polymorphism connects to migrations too. An index on a variant-specific field, ` ## Typed aggregation pipelines -When you need MongoDB's aggregation pipeline for grouping, projecting, or faceting, Prisma 8 provides a [typed pipeline builder](https://www.prisma.io/docs/orm/v8/fundamentals/advanced-queries): +When you need MongoDB's aggregation pipeline for grouping, projecting, or faceting, Prisma 8 provides a [typed pipeline builder](https://www.prisma.io/docs/orm/fundamentals/advanced-queries): ```typescript const { pipeline, runtime } = orm; @@ -198,7 +198,7 @@ Field references like `f.authorId` and `f.createdAt` check against your contract })) ``` -When the pipeline builder doesn't cover what you need, you can drop to [raw MongoDB commands](https://www.prisma.io/docs/orm/v8/reference/raw-queries): +When the pipeline builder doesn't cover what you need, you can drop to [raw MongoDB commands](https://www.prisma.io/docs/orm/reference/raw-queries): ```typescript const raw = orm.raw.collection('posts'); diff --git a/apps/blog/content/blog/nestjs-prisma-authentication-7D056s1s0k3l/index.mdx b/apps/blog/content/blog/nestjs-prisma-authentication-7D056s1s0k3l/index.mdx index d344b0c9a3..419290f140 100644 --- a/apps/blog/content/blog/nestjs-prisma-authentication-7D056s1s0k3l/index.mdx +++ b/apps/blog/content/blog/nestjs-prisma-authentication-7D056s1s0k3l/index.mdx @@ -843,6 +843,6 @@ As long as the `expiresIn` value passed to `JwtModule.register`; this tutorial u In this chapter, you learned how to implement JWT authentication in your NestJS REST API. You also learned about salting passwords and integrating authentication with Swagger. -This wraps up the series. Across five chapters, you built a REST API with NestJS 11 and Prisma ORM 7, added input validation, error handling, relational data and authentication; every piece verified on the current stack. From here, good next steps are [The Ultimate Guide to Testing with Prisma](https://www.prisma.io/blog/series/testing-with-prisma) for test coverage, the [Prisma Migrate docs](https://www.prisma.io/docs/orm/prisma-migrate/getting-started) for evolving your schema, and Prisma Postgres as the database for your production deployment. +This wraps up the series. Across five chapters, you built a REST API with NestJS 11 and Prisma ORM 7, added input validation, error handling, relational data and authentication; every piece verified on the current stack. From here, good next steps are [The Ultimate Guide to Testing with Prisma](https://www.prisma.io/blog/series/testing-with-prisma) for test coverage, the [Prisma Migrate docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/getting-started) for evolving your schema, and Prisma Postgres as the database for your production deployment. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/nestjs-prisma-error-handling-7D056s1kOop2/index.mdx b/apps/blog/content/blog/nestjs-prisma-error-handling-7D056s1kOop2/index.mdx index fb43f1cac1..9074dc72e8 100644 --- a/apps/blog/content/blog/nestjs-prisma-error-handling-7D056s1kOop2/index.mdx +++ b/apps/blog/content/blog/nestjs-prisma-error-handling-7D056s1kOop2/index.mdx @@ -265,7 +265,7 @@ Here you have made the following changes: 2. The exception filter extends the `BaseExceptionFilter` class from the NestJS core package. This class provides a default implementation for the `catch` method that returns an "Internal server error" response to the user. You can learn more about this [in the NestJS docs](https://docs.nestjs.com/exception-filters#inheritance). 3. You added a `console.error` statement to log the error message to the console. This is useful for debugging purposes. -Prisma throws the `PrismaClientKnownRequestError` for many different kinds of errors. So you will need to figure out how to extract the error code from the `PrismaClientKnownRequestError` exception. The `PrismaClientKnownRequestError` exception has a `code` property that contains the error code. You can find the list of error codes in the [Prisma error message reference](https://www.prisma.io/docs/orm/reference/error-reference). +Prisma throws the `PrismaClientKnownRequestError` for many different kinds of errors. So you will need to figure out how to extract the error code from the `PrismaClientKnownRequestError` exception. The `PrismaClientKnownRequestError` exception has a `code` property that contains the error code. You can find the list of error codes in the [Prisma error message reference](https://www.prisma.io/docs/orm/v7/reference/error-reference). The error code you are looking for is `P2002`, which occurs for unique constraint violations. You will now update the `catch` method to throw an HTTP `409 Conflict` response in case of this error. You will also provide a custom error message to the user. @@ -392,7 +392,7 @@ The built-in global exception filter catches it and returns a generic HTTP 500 " From the `Prisma` namespace of your generated Client, for example `import { Prisma } from '../../generated/prisma/client'`. Importing it from `@prisma/client` no longer works with the `prisma-client` generator, which outputs the Client into your project. -`P2002`. The exception filter in this tutorial maps it to an HTTP 409 Conflict response. A related code worth handling is `P2025` (record not found), which fits an HTTP 404 response for update and delete endpoints. The full list is in the [Prisma error reference](https://www.prisma.io/docs/orm/reference/error-reference). +`P2002`. The exception filter in this tutorial maps it to an HTTP 409 Conflict response. A related code worth handling is `P2025` (record not found), which fits an HTTP 404 response for update and delete endpoints. The full list is in the [Prisma error reference](https://www.prisma.io/docs/orm/v7/reference/error-reference). @@ -402,6 +402,6 @@ Congratulations! You took an existing NestJS application in this tutorial and le In this chapter you learned how to handle Prisma errors, like the `P2002` unique constraint violation. But the techniques themselves are not limited to Prisma. You can use them to handle any type of error in your application. -In the [next part](/nestjs-prisma-relational-data-7D056s1kOabc) of this series, you will add a `User` model and learn how to handle relational data in your API. If you want to go deeper on the Prisma side first, the [Prisma getting started guide](https://www.prisma.io/docs/getting-started), [Prisma Migrate docs](https://www.prisma.io/docs/orm/prisma-migrate/getting-started), and Prisma Postgres are the best next resources for taking the app from tutorial to production-ready workflow. +In the [next part](/nestjs-prisma-relational-data-7D056s1kOabc) of this series, you will add a `User` model and learn how to handle relational data in your API. If you want to go deeper on the Prisma side first, the [Prisma getting started guide](https://www.prisma.io/docs/getting-started), [Prisma Migrate docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/getting-started), and Prisma Postgres are the best next resources for taking the app from tutorial to production-ready workflow. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/nestjs-prisma-relational-data-7D056s1kOabc/index.mdx b/apps/blog/content/blog/nestjs-prisma-relational-data-7D056s1kOabc/index.mdx index e2f97cc928..e6f6b22bd7 100644 --- a/apps/blog/content/blog/nestjs-prisma-relational-data-7D056s1kOabc/index.mdx +++ b/apps/blog/content/blog/nestjs-prisma-relational-data-7D056s1kOabc/index.mdx @@ -919,6 +919,6 @@ No. `migrate dev` applies the migration but does not regenerate the Client into In this chapter, you learned how to model relational data in a NestJS application using Prisma ORM. You also learned about the `ClassSerializerInterceptor` and how to use entity classes to control the data that is returned to the client. -In the [next part](/nestjs-prisma-authentication-7D056s1s0k3l) of this series, you will secure these endpoints by adding JWT authentication to the API, and replace the plain text passwords with properly hashed ones. If you want to go deeper on relations first, the [Prisma relations docs](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations) cover one-to-many and other relation types in depth, and Prisma Postgres is an easy way to stand up the database layer for follow-on work. +In the [next part](/nestjs-prisma-authentication-7D056s1s0k3l) of this series, you will secure these endpoints by adding JWT authentication to the API, and replace the plain text passwords with properly hashed ones. If you want to go deeper on relations first, the [Prisma relations docs](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/relations) cover one-to-many and other relation types in depth, and Prisma Postgres is an easy way to stand up the database layer for follow-on work. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/nestjs-prisma-rest-api-7D056s1BmOL0/index.mdx b/apps/blog/content/blog/nestjs-prisma-rest-api-7D056s1BmOL0/index.mdx index 1b75a61a58..35a4df7066 100644 --- a/apps/blog/content/blog/nestjs-prisma-rest-api-7D056s1BmOL0/index.mdx +++ b/apps/blog/content/blog/nestjs-prisma-rest-api-7D056s1BmOL0/index.mdx @@ -179,7 +179,7 @@ Now that the database is ready, it's time to set up Prisma! To get started, install the Prisma CLI along with two helpers you'll use later, `tsx` (to run the TypeScript seed script) and `dotenv` (to load environment variables), as development dependencies: ```shell -npm install -D prisma tsx dotenv +npm install -D prisma@7.9.1 tsx dotenv ``` You can initialize Prisma inside your project by running: @@ -214,7 +214,7 @@ Now open `prisma.config.ts`. Prisma generated it to read `DATABASE_URL` from you // prisma.config.ts // This file was generated by Prisma, and assumes you have installed the following: -// npm install --save-dev prisma dotenv +// npm install --save-dev prisma@7.9.1 dotenv import "dotenv/config"; import { defineConfig } from "prisma/config"; @@ -309,7 +309,7 @@ This command will do two things: 1. **Save the migration**: Prisma Migrate will take a snapshot of your schema and figure out the SQL commands necessary to carry out the migration. Prisma will save the migration file containing the SQL commands to the newly created `prisma/migrations` folder. 2. **Execute the migration**: Prisma Migrate will execute the SQL in the migration file to create the underlying tables in your database. -> **Note**: You can learn more about Prisma Migrate in the [Prisma docs](https://www.prisma.io/docs/orm/prisma-migrate). +> **Note**: You can learn more about Prisma Migrate in the [Prisma docs](https://www.prisma.io/docs/orm/v7/prisma-migrate). If completed successfully, you should see a message like this : ``` @@ -367,7 +367,7 @@ Currently, the database is empty. So you will create a _seed script_ that will p In Prisma 7, the Prisma Client is Rust-free and talks to your database through a **driver adapter**. You need two runtime packages: `@prisma/client` (the runtime that your generated Client imports) and `@prisma/adapter-pg` (the PostgreSQL driver adapter). Install both: ```shell -npm install @prisma/client @prisma/adapter-pg +npm install @prisma/client@7.9.1 @prisma/adapter-pg ``` > **Note**: `@prisma/adapter-pg` pulls in the `pg` driver (and its types) for you, so there's no separate `pg` install. If you skip `@prisma/client`, the app fails at runtime with `Cannot find module '@prisma/client/runtime/client'`. @@ -481,7 +481,7 @@ Running seed command `tsx prisma/seed.ts` ... 🌱 The seed command has been executed. ``` -> **Note**: You can learn more about seeding in the [Prisma Docs](https://www.prisma.io/docs/orm/prisma-migrate/workflows/seeding). +> **Note**: You can learn more about seeding in the [Prisma Docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/seeding). @@ -1023,6 +1023,6 @@ Congratulations! You've built a rudimentary REST API using NestJS and Prisma 7. One of the main takeaways from this tutorial is how easy it is to build a REST API with NestJS and Prisma. This is an incredibly productive stack for rapidly building well structured, type-safe and maintainable backend applications. -In the [next part](/nestjs-prisma-validation-7D056s1kOla1) of this series, you will add input validation and transformation to this API. If you want to go deeper on the Prisma side first, start with the [Prisma getting started guide](https://www.prisma.io/docs/getting-started), learn more about [Prisma Migrate](https://www.prisma.io/docs/orm/prisma-migrate/getting-started), or create a Prisma Postgres database for your next NestJS project. +In the [next part](/nestjs-prisma-validation-7D056s1kOla1) of this series, you will add input validation and transformation to this API. If you want to go deeper on the Prisma side first, start with the [Prisma getting started guide](https://www.prisma.io/docs/getting-started), learn more about [Prisma Migrate](https://www.prisma.io/docs/orm/v7/prisma-migrate/getting-started), or create a Prisma Postgres database for your next NestJS project. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/nestjs-prisma-validation-7D056s1kOla1/index.mdx b/apps/blog/content/blog/nestjs-prisma-validation-7D056s1kOla1/index.mdx index d763cd0d82..5a1229074b 100644 --- a/apps/blog/content/blog/nestjs-prisma-validation-7D056s1kOla1/index.mdx +++ b/apps/blog/content/blog/nestjs-prisma-validation-7D056s1kOla1/index.mdx @@ -383,6 +383,6 @@ Congratulations! In this tutorial, you took an existing REST API built with Nest You might have noticed that NestJS heavily relies on decorators. This is a very intentional design choice. NestJS aims to improve code readability and modularity by heavily leveraging decorators for various kinds of cross-cutting concerns. As a result, controllers and service methods do not need to be bloated with boilerplate code for doing things like validation, caching, logging, etc. -In the [next part](/nestjs-prisma-error-handling-7D056s1kOop2) of this series, you will learn how to handle errors in a NestJS and Prisma application, including the database errors that validation alone can't catch. If you want to go deeper on the Prisma side first, the [Prisma getting started guide](https://www.prisma.io/docs/getting-started) and [Prisma Migrate docs](https://www.prisma.io/docs/orm/prisma-migrate/getting-started) are good next steps, and Prisma Postgres is an easy way to stand up the database layer for follow-on work. +In the [next part](/nestjs-prisma-error-handling-7D056s1kOop2) of this series, you will learn how to handle errors in a NestJS and Prisma application, including the database errors that validation alone can't catch. If you want to go deeper on the Prisma side first, the [Prisma getting started guide](https://www.prisma.io/docs/getting-started) and [Prisma Migrate docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/getting-started) are good next steps, and Prisma Postgres is an easy way to stand up the database layer for follow-on work. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/organize-your-prisma-schema-with-multi-file-support/index.mdx b/apps/blog/content/blog/organize-your-prisma-schema-with-multi-file-support/index.mdx index e32c9c3229..d9e8e11b0c 100644 --- a/apps/blog/content/blog/organize-your-prisma-schema-with-multi-file-support/index.mdx +++ b/apps/blog/content/blog/organize-your-prisma-schema-with-multi-file-support/index.mdx @@ -15,7 +15,7 @@ tags: - "education" --- -Prisma ORM lets you [organize your Prisma Schema into multiple files](https://www.prisma.io/docs/orm/prisma-schema/overview/location#multi-file-prisma-schema). You split your models across as many `.prisma` files as you like, relations work across files without any imports, and Prisma combines everything when you run `prisma generate` or a migration command. The feature is Generally Available since v6.7.0, so no preview flag is needed. In Prisma ORM v7, you point the `schema` property in `prisma.config.ts` at the directory that holds your schema files. This post shows the setup, when to split, and the pitfalls to avoid. +Prisma ORM lets you [organize your Prisma Schema into multiple files](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/location#multi-file-prisma-schema). You split your models across as many `.prisma` files as you like, relations work across files without any imports, and Prisma combines everything when you run `prisma generate` or a migration command. The feature is Generally Available since v6.7.0, so no preview flag is needed. In Prisma ORM v7, you point the `schema` property in `prisma.config.ts` at the directory that holds your schema files. This post shows the setup, when to split, and the pitfalls to avoid. Multi-file schemas were [one of our most requested features](https://github.com/prisma/prisma/issues/2377): they first shipped as the `prismaSchemaFolder` Preview feature in v5.15 and went GA in [v6.7.0](https://github.com/prisma/prisma/releases/tag/6.7.0). @@ -127,6 +127,6 @@ It's fast, too: in [our published benchmark](https://www.prisma.io/blog/prisma-n ## Where to go next -- [Read the multi-file Prisma schema docs](https://www.prisma.io/docs/orm/prisma-schema/overview/location#multi-file-prisma-schema) for the current workflow and caveats. +- [Read the multi-file Prisma schema docs](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/location#multi-file-prisma-schema) for the current workflow and caveats. - [Explore Prisma ORM](https://www.prisma.io/orm) if you're evaluating the broader developer workflow around schema design and generated types. - [Pair it with Prisma Postgres](https://www.prisma.io/postgres) if you want a managed Postgres setup that works naturally with larger Prisma projects. diff --git a/apps/blog/content/blog/orm-6-12-0-esm-compatible-generator-in-preview-and-new-options-for-prisma-config/index.mdx b/apps/blog/content/blog/orm-6-12-0-esm-compatible-generator-in-preview-and-new-options-for-prisma-config/index.mdx index 28e607c7ff..26e962b821 100644 --- a/apps/blog/content/blog/orm-6-12-0-esm-compatible-generator-in-preview-and-new-options-for-prisma-config/index.mdx +++ b/apps/blog/content/blog/orm-6-12-0-esm-compatible-generator-in-preview-and-new-options-for-prisma-config/index.mdx @@ -20,7 +20,7 @@ Yesterday, we released Prisma ORM [v6.12.0](https://pris.ly/release/6.12.0) with ### ESM-compatible `prisma-client` generator now in Preview -We're excited to share that our new and more flexible [`prisma-client`](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#prisma-client-early-access) generator is moving into [Preview](https://www.prisma.io/docs/orm/more/releases#preview)! +We're excited to share that our new and more flexible [`prisma-client`](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#prisma-client-early-access) generator is moving into [Preview](https://www.prisma.io/docs/orm/v7/more/releases#preview)! This new generator is ESM-compatible, customizable for various JS runtimes (like Bun, Deno, CF Workers, …) and gives application developers more control over the generated code. @@ -52,11 +52,11 @@ In addition to moving it into Preview, we also created a couple of new ready-to- ### Specify locations for `views`, `migrations` and `typedSql` in Prisma Config (Early Access) -The [`prisma.config.ts`](https://www.prisma.io/docs/orm/reference/prisma-config-reference) file gives you a TypeScript-native way for configuring your Prisma project. It's convenient in situations when you want to customize the locations of your Prisma schema or use specific driver adapters for Prisma Migrate or Prisma Studio. +The [`prisma.config.ts`](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference) file gives you a TypeScript-native way for configuring your Prisma project. It's convenient in situations when you want to customize the locations of your Prisma schema or use specific driver adapters for Prisma Migrate or Prisma Studio. -As we're getting closer to its [General Availability](https://www.prisma.io/docs/orm/more/releases#generally-available-ga) release, we're adding more capabilities to it! +As we're getting closer to its [General Availability](https://www.prisma.io/docs/orm/v7/more/releases#generally-available-ga) release, we're adding more capabilities to it! -In previous versions, the Prisma CLI implicitly used to infer the location for migration, SQL view definition and [TypedSQL query](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/typedsql) files based on the location of the Prisma schema. In this release, we're adding three new fields (`migrations`, `views` and `typedSql`) to give you more flexibility and clarity on how the Prisma CLI should locate these files: +In previous versions, the Prisma CLI implicitly used to infer the location for migration, SQL view definition and [TypedSQL query](https://www.prisma.io/docs/orm/v7/prisma-client/using-raw-sql/typedsql) files based on the location of the Prisma schema. In this release, we're adding three new fields (`migrations`, `views` and `typedSql`) to give you more flexibility and clarity on how the Prisma CLI should locate these files: ```ts // prisma.config.ts diff --git a/apps/blog/content/blog/orm-6-13-0-ci-cd-workflows-and-pgvector-for-prisma-postgres/index.mdx b/apps/blog/content/blog/orm-6-13-0-ci-cd-workflows-and-pgvector-for-prisma-postgres/index.mdx index 133caafece..0d7773ef63 100644 --- a/apps/blog/content/blog/orm-6-13-0-ci-cd-workflows-and-pgvector-for-prisma-postgres/index.mdx +++ b/apps/blog/content/blog/orm-6-13-0-ci-cd-workflows-and-pgvector-for-prisma-postgres/index.mdx @@ -21,7 +21,7 @@ We’ve been hard at work behind the scenes developing several new features for ### Configuring Prisma ORM via `prisma.config.ts` is now Generally Available -Ever wanted a TypeScript-native way to configure your Prisma ORM project? With [`prisma.config.ts`](https://www.prisma.io/docs/orm/reference/prisma-config-reference) now Generally Available, that’s now a reality! +Ever wanted a TypeScript-native way to configure your Prisma ORM project? With [`prisma.config.ts`](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference) now Generally Available, that’s now a reality! This file provides a native way to specify configuration options for your project, including: @@ -50,7 +50,7 @@ export default defineConfig({ ``` Now, when you run Prisma CLI commands, these custom paths will be respected—for instance, migration files will be created in the specified directories. -Check out [the documentation](https://www.prisma.io/docs/orm/reference/prisma-config-reference) to learn more about the Prisma Config file! +Check out [the documentation](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference) to learn more about the Prisma Config file! ### Using multiple schemas is now Generally Available @@ -80,7 +80,7 @@ model Order { @@schema("shop") } ``` -Learn more about multiple schemas [in our docs](https://www.prisma.io/docs/orm/prisma-schema/data-model/multi-schema). +Learn more about multiple schemas [in our docs](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/multi-schema). ### More robust support for SQL views (Preview) @@ -93,7 +93,7 @@ We’re continuing to make support for views in Prisma ORM more robust. This rel - Writes and implicit ordering are disallowed in Prisma Client for views. - Relationships involving views are disallowed in Prisma Schema. -These updates align Prisma ORM’s API with what SQL views actually support, making it safer and clearer to use them. Learn more about views [in our docs](https://www.prisma.io/docs/orm/prisma-schema/data-model/views). +These updates align Prisma ORM’s API with what SQL views actually support, making it safer and clearer to use them. Learn more about views [in our docs](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/views). ### Externally managed tables: query without migrations @@ -117,7 +117,7 @@ export default defineConfig({ ... }) ``` -A common use case is the [`users` table from Supabase](https://supabase.com/docs/guides/auth/managing-user-data), which you may want to query but never modify via migrations. Learn more about externally managed tables [in our docs](https://www.prisma.io/docs/orm/prisma-schema/data-model/externally-managed-tables). +A common use case is the [`users` table from Supabase](https://supabase.com/docs/guides/auth/managing-user-data), which you may want to query but never modify via migrations. Learn more about externally managed tables [in our docs](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/externally-managed-tables). ## `pgvector` extension support for Prisma Postgres in Early Access @@ -125,7 +125,7 @@ We’ve added a much-requested feature to Prisma Postgres: [Early Access](https: It allows vector storage directly in your Postgres instance, making Prisma Postgres perfect for building AI-powered applications without needing a separate vector database. -Native `pgvector` support in Prisma ORM is coming soon. In the meantime, use it via [custom migrations](https://www.prisma.io/docs/orm/prisma-migrate/workflows/customizing-migrations) and [TypedSQL](https://www.prisma.io/blog/announcing-typedsql-make-your-raw-sql-queries-type-safe-with-prisma-orm). +Native `pgvector` support in Prisma ORM is coming soon. In the meantime, use it via [custom migrations](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/customizing-migrations) and [TypedSQL](https://www.prisma.io/blog/announcing-typedsql-make-your-raw-sql-queries-type-safe-with-prisma-orm). Create a migration like this: diff --git a/apps/blog/content/blog/orm-6-15-0-ai-safety-guardrails-for-destructive-commands-and-more/index.mdx b/apps/blog/content/blog/orm-6-15-0-ai-safety-guardrails-for-destructive-commands-and-more/index.mdx index b6bf347719..0dee251944 100644 --- a/apps/blog/content/blog/orm-6-15-0-ai-safety-guardrails-for-destructive-commands-and-more/index.mdx +++ b/apps/blog/content/blog/orm-6-15-0-ai-safety-guardrails-for-destructive-commands-and-more/index.mdx @@ -33,7 +33,7 @@ This feature ensures that irreversible operations which drop and recreate the da _Want to use a more flexible Prisma Client library with less magic and more control?_ -The new [`prisma-client`](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#prisma-client-preview) generator is ESM-first and more flexible than the current `prisma-client-js` generator. It requires setting a dedicated `output` path in your Prisma schema so the generated code for your Prisma Client library is fully under your control! +The new [`prisma-client`](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#prisma-client-preview) generator is ESM-first and more flexible than the current `prisma-client-js` generator. It requires setting a dedicated `output` path in your Prisma schema so the generated code for your Prisma Client library is fully under your control! In this release, we made the runtime options for the Prisma Client more consistent and easier to understand. Previously there were several overlapping aliases which created confusion. With this release we simplified the inputs while keeping support for all the major environments you might be targeting. diff --git a/apps/blog/content/blog/orm-v6-11-0-embedded-prisma-studio-rust-free-orm-for-mysql-in-preview-and-more/index.mdx b/apps/blog/content/blog/orm-v6-11-0-embedded-prisma-studio-rust-free-orm-for-mysql-in-preview-and-more/index.mdx index 0965eaaf74..e8265b915b 100644 --- a/apps/blog/content/blog/orm-v6-11-0-embedded-prisma-studio-rust-free-orm-for-mysql-in-preview-and-more/index.mdx +++ b/apps/blog/content/blog/orm-v6-11-0-embedded-prisma-studio-rust-free-orm-for-mysql-in-preview-and-more/index.mdx @@ -171,7 +171,7 @@ No more hassle with query engines, binary targets and an even smoother experienc ### Ready-to-run examples for new `prisma-client` generator -Our new [`prisma-client`](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#prisma-client-early-access) generator is more flexible, provides more control about the generated code, works with various JS runtimes and comes with ESM support out-of-the-box. +Our new [`prisma-client`](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#prisma-client-early-access) generator is more flexible, provides more control about the generated code, works with various JS runtimes and comes with ESM support out-of-the-box. To make it easier for you to try it out, we created a few ready-to-run example projects so you can see the new generator in action: diff --git a/apps/blog/content/blog/orm-v6-17-0-new-usage-metrics-and-direct-connections-in-ga-for-prisma-postgres/index.mdx b/apps/blog/content/blog/orm-v6-17-0-new-usage-metrics-and-direct-connections-in-ga-for-prisma-postgres/index.mdx index e494592975..9db523d11e 100644 --- a/apps/blog/content/blog/orm-v6-17-0-new-usage-metrics-and-direct-connections-in-ga-for-prisma-postgres/index.mdx +++ b/apps/blog/content/blog/orm-v6-17-0-new-usage-metrics-and-direct-connections-in-ga-for-prisma-postgres/index.mdx @@ -143,9 +143,9 @@ export default defineConfig({ }, }); ``` -For a full reference of the options that can be used in Prisma Config, see the [docs](https://www.prisma.io/docs/orm/reference/prisma-config-reference). +For a full reference of the options that can be used in Prisma Config, see the [docs](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference). -> **Note**: When using Prisma Config, [automatic loading](https://github.com/prisma/prisma/issues/15620) of env vars is disabled. This means you need to [manually load env vars](https://www.prisma.io/docs/orm/reference/prisma-config-reference#using-environment-variables), e.g. using `dotenv`. +> **Note**: When using Prisma Config, [automatic loading](https://github.com/prisma/prisma/issues/15620) of env vars is disabled. This means you need to [manually load env vars](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference#using-environment-variables), e.g. using `dotenv`. ## Try it out and share your feedback diff --git a/apps/blog/content/blog/overcoming-challenges-in-serverless-and-edge-environments-TQtONA0RVxuW/index.mdx b/apps/blog/content/blog/overcoming-challenges-in-serverless-and-edge-environments-TQtONA0RVxuW/index.mdx index a523a2102b..b4cd41bd41 100644 --- a/apps/blog/content/blog/overcoming-challenges-in-serverless-and-edge-environments-TQtONA0RVxuW/index.mdx +++ b/apps/blog/content/blog/overcoming-challenges-in-serverless-and-edge-environments-TQtONA0RVxuW/index.mdx @@ -81,7 +81,7 @@ To avoid this parallelization issue, let's look at three easy configuration chan #### Change the client connection pool size Most ORMs, including -[Prisma](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/databases-connections/connection-pool#setting-the-connection-pool-size), have a way to modify the number of connections that the client keeps open with the underlying database (known as a [connection pool](https://www.prisma.io/dataguide/database-tools/connection-pooling)). By default, the number of connections in the pool can vary but generally fall between two and ten connections. +[Prisma](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/databases-connections/connection-pool#setting-the-connection-pool-size), have a way to modify the number of connections that the client keeps open with the underlying database (known as a [connection pool](https://www.prisma.io/dataguide/database-tools/connection-pooling)). By default, the number of connections in the pool can vary but generally fall between two and ten connections. If you refer to our example above, even accounting for a large number of connections could be off by an order of magnitude if each function keeps ten connections open! diff --git a/apps/blog/content/blog/performance-benchmarks-comparing-query-latency-across-typescript-orms-and-databases/index.mdx b/apps/blog/content/blog/performance-benchmarks-comparing-query-latency-across-typescript-orms-and-databases/index.mdx index b3f9f518bd..0386d80012 100644 --- a/apps/blog/content/blog/performance-benchmarks-comparing-query-latency-across-typescript-orms-and-databases/index.mdx +++ b/apps/blog/content/blog/performance-benchmarks-comparing-query-latency-across-typescript-orms-and-databases/index.mdx @@ -223,7 +223,7 @@ Here's a basic checklist that helps you ensure that your Prisma ORM queries are - Add indexes to columns that are frequently used in your queries. - Make sure to have least 3 CPU cores available in production environments. - Measure performance and optimize a query with raw SQL when needed. -- Monitor your queries using the [OpenTelemetry tracing](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing) and [metrics](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/metrics) features of Prisma ORM. +- Monitor your queries using the [OpenTelemetry tracing](https://www.prisma.io/docs/orm/v7/prisma-client/observability-and-logging/opentelemetry-tracing) and [metrics](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/metrics) features of Prisma ORM. - Add a caching layer to your DB (e.g. [Prisma Accelerate](https://www.prisma.io/data-platform/accelerate)). - If your app is serverless, follow the [best practices for serverless performance](https://www.prisma.io/blog/how-to-improve-startup-times-kdRB9MjPEv). diff --git a/apps/blog/content/blog/prisma-6-8-0-release/index.mdx b/apps/blog/content/blog/prisma-6-8-0-release/index.mdx index a8497e1eec..aa74b72db1 100644 --- a/apps/blog/content/blog/prisma-6-8-0-release/index.mdx +++ b/apps/blog/content/blog/prisma-6-8-0-release/index.mdx @@ -99,7 +99,7 @@ generator client { + runtime = "deno" } ``` -No adapters, no custom builds—just Prisma ORM, running natively in Deno. Try it out by following the [step-by-step guide here](https://www.prisma.io/docs/orm/prisma-client/deployment/edge/deploy-to-deno-deploy). +No adapters, no custom builds—just Prisma ORM, running natively in Deno. Try it out by following the [step-by-step guide here](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/edge/deploy-to-deno-deploy). ## New Prisma Postgres region: Singapore diff --git a/apps/blog/content/blog/prisma-6-9-0-release/index.mdx b/apps/blog/content/blog/prisma-6-9-0-release/index.mdx index da604d558d..a8906a1981 100644 --- a/apps/blog/content/blog/prisma-6-9-0-release/index.mdx +++ b/apps/blog/content/blog/prisma-6-9-0-release/index.mdx @@ -31,7 +31,7 @@ In case you missed it, we’ve been working on a major shift in how Prisma ORM w This change removes the need for binary targets, avoids native build issues, and makes Prisma ORM easier to run in environments like Bun, Deno, serverless, and edge functions. It also improves performance by skipping serialization between Rust and JavaScript. -The Rust-free version of Prisma ORM is now in [**Preview** for PostgreSQL & SQLite](https://www.prisma.io/docs/orm/more/releases#preview). If you held off during [Early Access](https://www.prisma.io/docs/orm/more/releases#early-access), this is a good time to try it out. Other databases will be supported in future releases. +The Rust-free version of Prisma ORM is now in [**Preview** for PostgreSQL & SQLite](https://www.prisma.io/docs/orm/v7/more/releases#preview). If you held off during [Early Access](https://www.prisma.io/docs/orm/v7/more/releases#early-access), this is a good time to try it out. Other databases will be supported in future releases. To get started with the Query Compiler and PostgreSQL, enable the `queryCompiler` and `driverAdapters` preview features in your generator: diff --git a/apps/blog/content/blog/prisma-6-better-performance-more-flexibility-and-type-safe-sql/index.mdx b/apps/blog/content/blog/prisma-6-better-performance-more-flexibility-and-type-safe-sql/index.mdx index 30a951bdff..61ce815763 100644 --- a/apps/blog/content/blog/prisma-6-better-performance-more-flexibility-and-type-safe-sql/index.mdx +++ b/apps/blog/content/blog/prisma-6-better-performance-more-flexibility-and-type-safe-sql/index.mdx @@ -154,7 +154,7 @@ const posts = prisma.post.createManyAndReturn({ ``` In previous versions, the only way to create multiple records at once was by using `createMany` which only returned the count of the created records. -Another example for more flexibility in the Prisma Client API is the new `omit` option. It is the counterpart to `select` and lets you [exclude fields](https://www.prisma.io/docs/orm/prisma-client/queries/select-fields#omit-specific-fields) from the result payload of a query: +Another example for more flexibility in the Prisma Client API is the new `omit` option. It is the counterpart to `select` and lets you [exclude fields](https://www.prisma.io/docs/orm/v7/prisma-client/queries/select-fields#omit-specific-fields) from the result payload of a query: ```ts const users = await prisma.user.findFirst({ diff --git a/apps/blog/content/blog/prisma-data-proxy-xb16ba0p21/index.mdx b/apps/blog/content/blog/prisma-data-proxy-xb16ba0p21/index.mdx index c6fbd037d1..3522b85db4 100644 --- a/apps/blog/content/blog/prisma-data-proxy-xb16ba0p21/index.mdx +++ b/apps/blog/content/blog/prisma-data-proxy-xb16ba0p21/index.mdx @@ -103,7 +103,7 @@ The Data Proxy also enabled use cases such as accessing a database from limited The problem this post describes has a simpler answer now than it did in 2021: - Use [Prisma Postgres](https://www.prisma.io/docs/postgres) if you want a managed Postgres database with connection pooling built in. It works with Prisma ORM out of the box, serves serverless and edge functions without connection exhaustion, and supports [direct TCP connections](https://www.prisma.io/docs/postgres/database/connecting-to-your-database) for other tools. -- If you bring your own database, follow the current [serverless deployment docs](https://www.prisma.io/docs/orm/prisma-client/deployment/serverless/deploy-to-vercel) for up-to-date connection handling guidance, or run an external pooler like pgBouncer in front of your database. +- If you bring your own database, follow the current [serverless deployment docs](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/serverless/deploy-to-vercel) for up-to-date connection handling guidance, or run an external pooler like pgBouncer in front of your database. ## Frequently asked questions @@ -119,4 +119,4 @@ You need pooling, but not necessarily a separate pooler. Prisma Postgres include -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/prisma-mongodb-preview-release/index.mdx b/apps/blog/content/blog/prisma-mongodb-preview-release/index.mdx index 8e2218a9f5..2985d47d8c 100644 --- a/apps/blog/content/blog/prisma-mongodb-preview-release/index.mdx +++ b/apps/blog/content/blog/prisma-mongodb-preview-release/index.mdx @@ -26,7 +26,7 @@ Today we are excited to expand the range of supported databases with preview sup ## TL;DR -- Prisma release [2.27.0](https://github.com/prisma/prisma/releases/tag/2.27.0) adds [Preview support](https://www.prisma.io/docs/orm/more/releases#preview) for MongoDB. +- Prisma release [2.27.0](https://github.com/prisma/prisma/releases/tag/2.27.0) adds [Preview support](https://www.prisma.io/docs/orm/v7/more/releases#preview) for MongoDB. - Prisma introduces a schema to MongoDB from which Prisma Client is generated, giving you the power of type safety in your queries. - Check out the [**Start from scratch guide**](https://www.prisma.io/docs/getting-started/setup-prisma/start-from-scratch/mongodb-typescript-mongodb) in the docs. - This is a preview release, so there may be bugs and breaking changes. Try it out and share your feedback @@ -43,7 +43,7 @@ Earlier this year, we released an Early Access of the MongoDB connector to Prism This release marks a significant milestone in bringing the benefits of Prisma to more developers by adding support for MongoDB. -MongoDB support has passed rigorous testing internally and by the Early Access participants and is now ready for broader testing by the community. **However, as a Preview feature, it is not production-ready.** To read more about what preview means, check out the [maturity levels](https://www.prisma.io/docs/orm/more/releases#preview) in the Prisma docs. +MongoDB support has passed rigorous testing internally and by the Early Access participants and is now ready for broader testing by the community. **However, as a Preview feature, it is not production-ready.** To read more about what preview means, check out the [maturity levels](https://www.prisma.io/docs/orm/v7/more/releases#preview) in the Prisma docs. Thus, we're inviting the MongoDB community to try it out and [give us feedback](https://github.com/prisma/prisma/issues/8241) so we can bring MongoDB support to general availability. 🚀 diff --git a/apps/blog/content/blog/prisma-next-call-for-extension-authors/index.mdx b/apps/blog/content/blog/prisma-next-call-for-extension-authors/index.mdx index c8ce37ce13..52b86b057f 100644 --- a/apps/blog/content/blog/prisma-next-call-for-extension-authors/index.mdx +++ b/apps/blog/content/blog/prisma-next-call-for-extension-authors/index.mdx @@ -22,13 +22,13 @@ seriesIndex: 6 If you've ever wanted to integrate your tool, your database, or your library with Prisma, or you tried in Prisma 6 or 7 and gave up, this post is for you. Read the [Prisma 8 Early Access announcement](https://www.prisma.io/blog/prisma-next-early-access-write-your-contract-prompt-your-agent-ship-your-app) for the full launch story. -[Prisma 8](https://www.prisma.io/docs/orm/v8) has a deliberately tiny core that knows nothing about any specific database. Postgres support is an extension. Vector search is an extension. JSON-with-schema is an extension. Whatever Prisma 8 can do, it does because someone wrote it using the same components that are available to you. +[Prisma 8](https://www.prisma.io/docs/orm) has a deliberately tiny core that knows nothing about any specific database. Postgres support is an extension. Vector search is an extension. JSON-with-schema is an extension. Whatever Prisma 8 can do, it does because someone wrote it using the same components that are available to you. The API surface is real, the same shape we used to build Postgres support ourselves, and ready to build against today. ## Postgres is an extension -The Prisma 8 framework knows about [contracts](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract), plans, query lifecycle, and the policies that gate execution. It does _not_ know what Postgres, SQL, Mongo, vectors, or any column type other than `unknown` are. +The Prisma 8 framework knows about [contracts](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract), plans, query lifecycle, and the policies that gate execution. It does _not_ know what Postgres, SQL, Mongo, vectors, or any column type other than `unknown` are. Every database we support and every native feature you've used in Prisma 8 was added by an extension package on a public service provider interface (SPI). The Postgres target, the SQL family (its contract shape, operations, and lanes), the Postgres adapter and driver, the pgvector vector type and its similarity operators, and the arktype-JSON codec are all extensions. @@ -36,14 +36,14 @@ There is no "core API" and "plugin API." There is one SPI, used by the team buil ## What an extension can ship -An extension is a normal npm package: `@yourname/prisma-next-extension-foo`. Your users `pnpm add` it, [add one line to `prisma.config.ts`](https://www.prisma.io/docs/orm/v8/extensions/using-extensions), and your additions show up in their contract, their queries, and (if you ship migrations) their migration plans. +An extension is a normal npm package: `@yourname/prisma-next-extension-foo`. Your users `pnpm add` it, [add one line to `prisma.config.ts`](https://www.prisma.io/docs/orm/extensions/using-extensions), and your additions show up in their contract, their queries, and (if you ship migrations) their migration plans. An extension can include any subset of four layers, in any combination: - **Contract layer**: column types, field builders, index types, and authoring constructs that show up in `contract.ts` and `contract.json` with your namespace and your validation rules. This is how pgvector adds dimensioned vector columns and how ParadeDB adds typed BM25 indexes - **Query layer**: typed methods on the query builder. Users discover them through autocomplete; they compile to SQL via lowerers you provide. This is how pgvector adds `cosineDistance` on vector columns -- **Runtime layer**: codecs that translate between the database wire format and your TypeScript types. Codecs can be synchronous (pgvector vectors decode to `number[]`) or asynchronous (encryption codecs decrypt on read with key material from an external service). [Runtime middleware](https://www.prisma.io/docs/orm/v8/middleware/how-middleware-works) is also part of this slice, covering observability, audit, and policy interception around every query -- **Migration layer**: custom DDL and data operations with pre/post checks and idempotency declarations, integrated into the migration planner. ParadeDB's planned BM25 index ops land here, and so does anything else that needs to participate in [the migration graph](https://www.prisma.io/docs/orm/v8/migrations/the-migration-graph) rather than ship as a one-off script +- **Runtime layer**: codecs that translate between the database wire format and your TypeScript types. Codecs can be synchronous (pgvector vectors decode to `number[]`) or asynchronous (encryption codecs decrypt on read with key material from an external service). [Runtime middleware](https://www.prisma.io/docs/orm/middleware/how-middleware-works) is also part of this slice, covering observability, audit, and policy interception around every query +- **Migration layer**: custom DDL and data operations with pre/post checks and idempotency declarations, integrated into the migration planner. ParadeDB's planned BM25 index ops land here, and so does anything else that needs to participate in [the migration graph](https://www.prisma.io/docs/orm/migrations/the-migration-graph) rather than ship as a one-off script Pick the layers you need. A useful extension can be one layer (a single codec, a single index type) or all four for a full vertical slice. diff --git a/apps/blog/content/blog/prisma-next-early-access-write-your-contract-prompt-your-agent-ship-your-app/index.mdx b/apps/blog/content/blog/prisma-next-early-access-write-your-contract-prompt-your-agent-ship-your-app/index.mdx index 1f4d228f3f..842e93670a 100644 --- a/apps/blog/content/blog/prisma-next-early-access-write-your-contract-prompt-your-agent-ship-your-app/index.mdx +++ b/apps/blog/content/blog/prisma-next-early-access-write-your-contract-prompt-your-agent-ship-your-app/index.mdx @@ -63,7 +63,7 @@ model Book { } ``` -This is [the contract](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract) between your application and your database. The models are what your application depends on, and your database promises to store them in the shapes described in the contract. +This is [the contract](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract) between your application and your database. The models are what your application depends on, and your database promises to store them in the shapes described in the contract. It's easy to read, easy to update, and it's the single source of truth for everything in Prisma 8. Queries are type-checked against it, autocomplete reads from it, and when you change it, Prisma 8 plans the migrations to match, so your database continues to satisfy the contract. @@ -86,7 +86,7 @@ Considering the book table in the contract above, you can ask the agent for a fe after={contractAfterAuthor} /> -Then, when you ask the agent to [write a query](https://www.prisma.io/docs/orm/v8/fundamentals/reading-data), it iterates inside its own tool calls until the query type-checks, or until it resolves any errors. Here's what that looks like in practice: +Then, when you ask the agent to [write a query](https://www.prisma.io/docs/orm/fundamentals/reading-data), it iterates inside its own tool calls until the query type-checks, or until it resolves any errors. Here's what that looks like in practice: _Editor's note: Prisma 8 was developed under the working name Prisma Next. This post has been updated to use the final name._ -I needed nested collections for a personal writing project: texts and collections at arbitrary depth, like a category tree of documents. PostgreSQL's [`ltree`](https://www.postgresql.org/docs/current/ltree.html) extension stores those hierarchical paths (for example `essays.drafts.chapter_1`) with native operators for ancestors, descendants, and shared parents. Prisma never shipped an `ltree` type, so I built [`prisma-ltree`](https://github.com/slovakian/prisma-ltree) for [Prisma 8](https://www.prisma.io/docs/orm/v8): typed columns, operators, path validation, and database setup as a community extension pack. +I needed nested collections for a personal writing project: texts and collections at arbitrary depth, like a category tree of documents. PostgreSQL's [`ltree`](https://www.postgresql.org/docs/current/ltree.html) extension stores those hierarchical paths (for example `essays.drafts.chapter_1`) with native operators for ancestors, descendants, and shared parents. Prisma never shipped an `ltree` type, so I built [`prisma-ltree`](https://github.com/slovakian/prisma-ltree) for [Prisma 8](https://www.prisma.io/docs/orm): typed columns, operators, path validation, and database setup as a community extension pack. For years, as a Prisma user, a type the ORM didn't model meant reaching for whatever it did support: occasional raw SQL, later typed SQL once that shipped, but mostly just the models Prisma made easy. If the ORM didn't model something, I usually didn't bother with it. @@ -115,7 +115,7 @@ There is a TypeScript schema lane too, with the same compiled output as PSL (Pri **5. Initialize the database** -The pack ships a baseline migration that runs `CREATE EXTENSION IF NOT EXISTS ltree`. On a fresh project: `npx prisma@next contract emit`, then `npx prisma@next migration plan`, then `npx prisma@next db init`. +The pack ships a baseline migration that runs `CREATE EXTENSION IF NOT EXISTS ltree`. On a fresh project: `npx prisma@latest contract emit`, then `npx prisma@latest migration plan`, then `npx prisma@latest db init`. **6. Insert and query paths** diff --git a/apps/blog/content/blog/prisma-next-performance-benchmark/index.mdx b/apps/blog/content/blog/prisma-next-performance-benchmark/index.mdx index 6151e5ae50..50dd2c48f8 100644 --- a/apps/blog/content/blog/prisma-next-performance-benchmark/index.mdx +++ b/apps/blog/content/blog/prisma-next-performance-benchmark/index.mdx @@ -20,7 +20,7 @@ seriesIndex: 9 Every ORM does work on every query: it turns your query into SQL, sends it, and turns the rows that come back into objects. That work has a cost, and in Prisma 7 it sits deep in the architecture, so reducing it meant rebuilding the layers underneath. -That rebuild is [Prisma 8](https://pris.ly/pn-series), the new foundation for Prisma ORM. It's written in TypeScript end to end and runs on a much lighter core, while keeping the same [model-first, type-safe workflow](https://www.prisma.io/docs/orm/v8) you already use. +That rebuild is [Prisma 8](https://pris.ly/pn-series), the new foundation for Prisma ORM. It's written in TypeScript end to end and runs on a much lighter core, while keeping the same [model-first, type-safe workflow](https://www.prisma.io/docs/orm) you already use. To see where it stands, we ran the same Postgres workload through three setups: Prisma 7, Prisma 8, and the raw `pg` driver. We pushed traffic up until each one reached its limit. @@ -99,7 +99,7 @@ We've shared [our benchmark repo](https://pris.ly/pn-benchmarks), so you can run ## Try Prisma 8 today -There are two ways to [get started](https://www.prisma.io/docs/v8/quickstart/postgresql). To spin up a complete template app, scaffold one with: +There are two ways to [get started](https://www.prisma.io/docs/prisma-orm/quickstart/postgresql). To spin up a complete template app, scaffold one with: ```shell bunx create-prisma@latest @@ -110,7 +110,7 @@ This sets you up with a [Prisma Postgres](https://www.prisma.io/postgres) databa To add Prisma 8 to an existing app, run: ```shell -bunx prisma@next orm init +bunx prisma@latest orm init ``` To learn more, start with the [announcement blog post](https://pris.ly/pn-ea). Star and watch [prisma/prisma](https://github.com/prisma/prisma) on GitHub to follow what ships next, and if you hit a snag, start a thread in [`#prisma-next` on our Discord](https://pris.ly/discord). diff --git a/apps/blog/content/blog/prisma-next-roadmap-april-milestone/index.mdx b/apps/blog/content/blog/prisma-next-roadmap-april-milestone/index.mdx index d1249ad895..b60288b865 100644 --- a/apps/blog/content/blog/prisma-next-roadmap-april-milestone/index.mdx +++ b/apps/blog/content/blog/prisma-next-roadmap-april-milestone/index.mdx @@ -24,7 +24,7 @@ In March we published the [Prisma 8 roadmap](https://pris.ly/AgH6EUa). April was Four extensions now ship on it: [`pgvector`](https://github.com/prisma/prisma-next/pull/391), [`arktype-json`](https://github.com/prisma/prisma-next/pull/402), [ParadeDB](https://github.com/prisma/prisma-next/pull/374), and [CipherStash](https://github.com/prisma/prisma-next/pull/411). One planned piece did not land: streaming subscriptions in the runtime. May shifts to Early Access for users. -If you want to [build a Prisma 8 extension](https://www.prisma.io/docs/orm/v8/extensions/using-extensions), the [call for extension authors](https://pris.ly/pn-extension-authors) is the front door. The API will keep evolving, but it's stable enough to build something real against — and we want to hear what's missing. +If you want to [build a Prisma 8 extension](https://www.prisma.io/docs/orm/extensions/using-extensions), the [call for extension authors](https://pris.ly/pn-extension-authors) is the front door. The API will keep evolving, but it's stable enough to build something real against — and we want to hear what's missing. ## What you can build with the extension API @@ -49,19 +49,19 @@ Data migrations are partly there. You can run a data transformation — say, spl ### Contract authoring -You can define your [data contract](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract) in `contract.prisma` or in TypeScript. Both surfaces produce the same compiled contract, regardless of which you choose. Next up: the everyday helpers, IDE autocomplete, and the patterns a first-time user expects to work without thinking. +You can define your [data contract](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract) in `contract.prisma` or in TypeScript. Both surfaces produce the same compiled contract, regardless of which you choose. Next up: the everyday helpers, IDE autocomplete, and the patterns a first-time user expects to work without thinking. ### Transactions and React Server Components -[Transactions](https://www.prisma.io/docs/orm/v8/fundamentals/transactions) work on Postgres. The ORM can open a transaction, and the [SQL query builder](https://www.prisma.io/docs/orm/v8/reference/sql-query-builder) can run inside it, sharing one database connection — so the SQL escape hatch actually works mid-transaction. +[Transactions](https://www.prisma.io/docs/orm/fundamentals/transactions) work on Postgres. The ORM can open a transaction, and the [SQL query builder](https://www.prisma.io/docs/orm/reference/sql-query-builder) can run inside it, sharing one database connection — so the SQL escape hatch actually works mid-transaction. The runtime runs safely under React Server Components: parallel Server Components, shared runtime state, connection pooling, and query-result caching all behave correctly under concurrency. -[Middleware](https://www.prisma.io/docs/orm/v8/middleware/how-middleware-works) hooks are in place — a middleware function can see a query, return a cached result, or rewrite the response. +[Middleware](https://www.prisma.io/docs/orm/middleware/how-middleware-works) hooks are in place — a middleware function can see a query, return a cached result, or rewrite the response. ### MongoDB -[MongoDB](https://www.prisma.io/docs/orm/v8/data-modeling/mongodb) is a first-class database family in Prisma 8. You get type-safe queries, real database migrations (indexes, JSON Schema validators, collection options), polymorphic collections with discriminated unions, embedded documents, and a typed aggregation pipeline builder. [MongoDB Without Compromise](https://www.prisma.io/blog/mongodb-without-compromise) covers the full story. +[MongoDB](https://www.prisma.io/docs/orm/data-modeling/mongodb) is a first-class database family in Prisma 8. You get type-safe queries, real database migrations (indexes, JSON Schema validators, collection options), polymorphic collections with discriminated unions, embedded documents, and a typed aggregation pipeline builder. [MongoDB Without Compromise](https://www.prisma.io/blog/mongodb-without-compromise) covers the full story. ### SQLite @@ -85,7 +85,7 @@ Three things to watch this month: ## Try it out -You can start building with Prisma 8 today. Run `npx prisma@next orm init`, open the contract, add a model, run `npx prisma@next migration plan` — it takes about as long as reading this paragraph. +You can start building with Prisma 8 today. Run `npx prisma@latest orm init`, open the contract, add a model, run `npx prisma@latest migration plan` — it takes about as long as reading this paragraph. The API is still settling, so expect breaking changes often. If you find rough edges or something you were hoping for that's missing, drop into [`#prisma-next` on Discord](https://pris.ly/discord) and tell us. Feedback right now is the most valuable thing we can get. diff --git a/apps/blog/content/blog/prisma-next-roadmap/index.mdx b/apps/blog/content/blog/prisma-next-roadmap/index.mdx index d48b080d43..b0413e12cc 100644 --- a/apps/blog/content/blog/prisma-next-roadmap/index.mdx +++ b/apps/blog/content/blog/prisma-next-roadmap/index.mdx @@ -22,10 +22,10 @@ On March 4th we [introduced Prisma 8](https://www.prisma.io/blog/the-next-evolut - a brand new query API with custom collection methods for your models - streaming query results -- a low-level, type-safe [SQL query builder](https://www.prisma.io/docs/orm/v8/reference/sql-query-builder) (an escape hatch for complex or custom SQL queries) -- [extensions](https://www.prisma.io/docs/orm/v8/extensions/using-extensions) that let you install new behaviors and data types (including the first extension example: `pgvector`) -- support for [TypeScript Prisma schemas](https://www.prisma.io/docs/orm/v8/contract-authoring/typescript-schema-builder) as an alternative to the traditional `schema.prisma`, so you can pick which you prefer -- [middleware](https://www.prisma.io/docs/orm/v8/middleware/how-middleware-works), validations, query linting, and lots more +- a low-level, type-safe [SQL query builder](https://www.prisma.io/docs/orm/reference/sql-query-builder) (an escape hatch for complex or custom SQL queries) +- [extensions](https://www.prisma.io/docs/orm/extensions/using-extensions) that let you install new behaviors and data types (including the first extension example: `pgvector`) +- support for [TypeScript Prisma schemas](https://www.prisma.io/docs/orm/contract-authoring/typescript-schema-builder) as an alternative to the traditional `schema.prisma`, so you can pick which you prefer +- [middleware](https://www.prisma.io/docs/orm/middleware/how-middleware-works), validations, query linting, and lots more There's a lot still to do, so to make sure we can get Prisma 8 into developers' hands as soon as possible, we're delivering the remaining work in phases. diff --git a/apps/blog/content/blog/prisma-optimize-early-access/index.mdx b/apps/blog/content/blog/prisma-optimize-early-access/index.mdx index 85057ad23b..b9adf5a9a8 100644 --- a/apps/blog/content/blog/prisma-optimize-early-access/index.mdx +++ b/apps/blog/content/blog/prisma-optimize-early-access/index.mdx @@ -42,7 +42,7 @@ Prisma Optimize not only helps you diagnose performance problems but also educat ## A comprehensive tool for data-driven application development -Optimize is a [Client Extension](https://www.prisma.io/docs/orm/prisma-client/client-extensions) that can be enabled in any app that uses the Prisma ORM. It seamlessly collects performance information from your app by integrating with Prisma ORM’s robust [observability and logging](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging) infrastructure. This data is then transmitted and displayed in an intuitive dashboard providing clear and actionable insights. Moving forward, as we grow the product features for Optimize, we will include features that make recommendations on how to address the issues we uncover. Stay tuned! +Optimize is a [Client Extension](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions) that can be enabled in any app that uses the Prisma ORM. It seamlessly collects performance information from your app by integrating with Prisma ORM’s robust [observability and logging](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging) infrastructure. This data is then transmitted and displayed in an intuitive dashboard providing clear and actionable insights. Moving forward, as we grow the product features for Optimize, we will include features that make recommendations on how to address the issues we uncover. Stay tuned! Prisma Optimize is a tool you use during development, and the general workflow looks something like this: * You identify an aspect of your app that you want to analyze. This could be a UI interaction or a background processing job. diff --git a/apps/blog/content/blog/prisma-orm-6-6-0-esm-support-d1-migrations-and-prisma-mcp-server/index.mdx b/apps/blog/content/blog/prisma-orm-6-6-0-esm-support-d1-migrations-and-prisma-mcp-server/index.mdx index 536f019ded..271686f643 100644 --- a/apps/blog/content/blog/prisma-orm-6-6-0-esm-support-d1-migrations-and-prisma-mcp-server/index.mdx +++ b/apps/blog/content/blog/prisma-orm-6-6-0-esm-support-d1-migrations-and-prisma-mcp-server/index.mdx @@ -41,7 +41,7 @@ generator client { moduleFormat = "esm" // or `"cjs"` for CommonJS } ``` -The generator also has more [fields](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#field-reference-2) like `runtime`, `generatedFileExtension` and `importFileExtension` that help you adapt the generated Prisma Client code to your specific project needs. +The generator also has more [fields](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#field-reference-2) like `runtime`, `generatedFileExtension` and `importFileExtension` that help you adapt the generated Prisma Client code to your specific project needs. In your application, you can then import the `PrismaClient` constructor (and anything else) from the generated folder: @@ -88,14 +88,14 @@ To get started, [add this snippet](https://www.prisma.io/docs/postgres/mcp-serve [Cloudflare D1](https://www.prisma.io/docs/orm/overview/databases/cloudflare-d1) and [Turso](https://www.prisma.io/docs/orm/overview/databases/turso) are popular database providers that are both based on SQLite. While you can query them with Prisma ORM using the respective driver adapter, previous versions of Prisma ORM weren't able to make _schema changes_ against these databases. -With today's release, we're sharing the first [Early Access](https://www.prisma.io/docs/orm/more/releases#early-access) version of native migration support for D1 and Turso and these commands: +With today's release, we're sharing the first [Early Access](https://www.prisma.io/docs/orm/v7/more/releases#early-access) version of native migration support for D1 and Turso and these commands: - `prisma db push`: Updates the schema of the remote database based on your Prisma schema - `prisma db pull`: Introspects the schema of the remote database and updates your local Prisma schema - `prisma migrate diff`: Outputs the difference between the schema of the remote database and your local Prisma schema > **Note**: Support for `prisma migrate dev` and `prisma migrate deploy` is underway and will come very soon! -To use these commands, you need to connect the Prisma CLI to your D1 or Turso instance by using the driver adapter in your [`prisma.config.ts`](https://www.prisma.io/docs/orm/reference/prisma-config-reference) file. Here is an example for D1: +To use these commands, you need to connect the Prisma CLI to your D1 or Turso instance by using the driver adapter in your [`prisma.config.ts`](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference) file. Here is an example for D1: ```ts import path from 'node:path' diff --git a/apps/blog/content/blog/prisma-orm-support-for-edge-functions-is-now-in-preview/index.mdx b/apps/blog/content/blog/prisma-orm-support-for-edge-functions-is-now-in-preview/index.mdx index 0575921169..f2ed4a6bdb 100644 --- a/apps/blog/content/blog/prisma-orm-support-for-edge-functions-is-now-in-preview/index.mdx +++ b/apps/blog/content/blog/prisma-orm-support-for-edge-functions-is-now-in-preview/index.mdx @@ -14,7 +14,7 @@ tags: - "orm" --- -We’re thrilled to share that support for edge functions is in Preview! You can now access your database with Prisma ORM from Vercel Edge Functions, Vercel Edge Middleware, Cloudflare Workers, and Cloudflare Pages. [Try it out](https://www.prisma.io/docs/orm/prisma-client/deployment/edge/overview)! +We’re thrilled to share that support for edge functions is in Preview! You can now access your database with Prisma ORM from Vercel Edge Functions, Vercel Edge Middleware, Cloudflare Workers, and Cloudflare Pages. [Try it out](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/edge/overview)! ## What are edge functions? @@ -63,7 +63,7 @@ Additionally, we have been able to drastically reduce the size of Prisma ORM's q > 🔬 If you're interested in seeing an example in action, we put together a little [GitHub repository](https://github.com/prisma/nextjs-edge-functions/) demonstrating how to access your database using Prisma ORM with Vercel Edge Functions. > -Follow along to learn how to get up and running with Prisma ORM in a **Cloudflare Worker** using a **PlanetScale database** (or [check our docs](https://www.prisma.io/docs/orm/prisma-client/deployment/edge/overview) to use a different combination of edge deployment and database provider). +Follow along to learn how to get up and running with Prisma ORM in a **Cloudflare Worker** using a **PlanetScale database** (or [check our docs](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/edge/overview) to use a different combination of edge deployment and database provider). ### 0. Prerequisites @@ -84,7 +84,7 @@ npm create cloudflare@latest prisma-cloudflare-worker-example -- --type hello-wo Navigate into the new directory and install the Prisma CLI: ``` cd prisma-cloudflare-worker-example -npm install --save-dev prisma +npm install --save-dev prisma@7.9.1 ``` Next, initialize Prisma in your project with the following command: ``` @@ -234,6 +234,6 @@ This command will deploy your edge function to Cloudflare and output the URL whe ## Try it out and share your feedback -We would love to know what you think! Try out the new support for edge deployments using [Vercel](https://www.prisma.io/docs/orm/prisma-client/deployment/edge/deploy-to-vercel) or [Cloudflare](https://www.prisma.io/docs/orm/prisma-client/deployment/edge/deploy-to-cloudflare) and share your feedback with us via [X](https://pris.ly/x) or [Discord](http://pris.ly/discord) 🚀 +We would love to know what you think! Try out the new support for edge deployments using [Vercel](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/edge/deploy-to-vercel) or [Cloudflare](https://www.prisma.io/docs/orm/v7/prisma-client/deployment/edge/deploy-to-cloudflare) and share your feedback with us via [X](https://pris.ly/x) or [Discord](http://pris.ly/discord) 🚀 If you run into any issues, you can create a bug report [here](https://github.com/prisma/prisma/issues/new/choose). diff --git a/apps/blog/content/blog/prisma-orm-v6-14-0-relationships-for-sql-views-more-robust-management-api-and-more/index.mdx b/apps/blog/content/blog/prisma-orm-v6-14-0-relationships-for-sql-views-more-robust-management-api-and-more/index.mdx index 53d41d887d..364508dee2 100644 --- a/apps/blog/content/blog/prisma-orm-v6-14-0-relationships-for-sql-views-more-robust-management-api-and-more/index.mdx +++ b/apps/blog/content/blog/prisma-orm-v6-14-0-relationships-for-sql-views-more-robust-management-api-and-more/index.mdx @@ -17,7 +17,7 @@ Yesterday, we released [Prisma ORM v6.14.0](https://pris.ly/release/6.14.0) with ## Relationships & `findUnique` queries for SQL views (Preview) -In the [last release](https://pris.ly/release/6.13.0), we improved the robustness of [SQL views](https://www.prisma.io/docs/orm/prisma-schema/data-model/views) defined in the Prisma schema. Views are _virtual_ tables that don't allow for defining foreign keys in the underlying database. +In the [last release](https://pris.ly/release/6.13.0), we improved the robustness of [SQL views](https://www.prisma.io/docs/orm/v7/prisma-schema/data-model/views) defined in the Prisma schema. Views are _virtual_ tables that don't allow for defining foreign keys in the underlying database. However, as an application developer, it can be convenient to also define relations across them. We've received this feedback from several people who had been using views in that way with Prisma ORM. So, in this release we're re-introducing the `@unique` attribute for views. This attribute enables: @@ -40,7 +40,7 @@ As we're getting closer to Prisma ORM v7, we're focusing a lot on increasing the Additionally, we increased the robustness of Prisma ORM and cleaned up some legacy code: - Fixed several regressions, e.g. related to Prisma Config -- Removed middleware from Prisma Client (i.e. the `prisma.$use` method), which was deprecated since v4.16.0. Use [Prisma Client extensions](https://www.prisma.io/docs/orm/prisma-client/client-extensions) instead. +- Removed middleware from Prisma Client (i.e. the `prisma.$use` method), which was deprecated since v4.16.0. Use [Prisma Client extensions](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions) instead. - Deprecated `metrics` Preview feature (which will be removed in Prisma v7) ## Increased robustness of Prisma Postgres Management API diff --git a/apps/blog/content/blog/prisma-orm-without-rust-latest-performance-benchmarks/index.mdx b/apps/blog/content/blog/prisma-orm-without-rust-latest-performance-benchmarks/index.mdx index 8f5149932f..31e86ca16b 100644 --- a/apps/blog/content/blog/prisma-orm-without-rust-latest-performance-benchmarks/index.mdx +++ b/apps/blog/content/blog/prisma-orm-without-rust-latest-performance-benchmarks/index.mdx @@ -36,7 +36,7 @@ To implement these benefits now, see the [official usage guide for the new Rust- Our move from Rust to TypeScript not only improves the developer experience, it also makes Prisma ORM more flexible and easier to use—whether you're working with different JavaScript runtimes, deployment platforms, or project setups like monorepos. On top of that, it brings significant performance improvements. -Over the past few [releases](https://github.com/prisma/prisma/releases/), we’ve gradually rolled out [Preview](https://www.prisma.io/docs/orm/more/releases#preview) support for Prisma ORM for all major SQL databases supported by Prisma ORM. It’s now available for: PostgreSQL, CockroachDB, Neon, MySQL, MariaDB, PlanetScale, SQLite, D1 and MS SQL Server databases. +Over the past few [releases](https://github.com/prisma/prisma/releases/), we’ve gradually rolled out [Preview](https://www.prisma.io/docs/orm/v7/more/releases#preview) support for Prisma ORM for all major SQL databases supported by Prisma ORM. It’s now available for: PostgreSQL, CockroachDB, Neon, MySQL, MariaDB, PlanetScale, SQLite, D1 and MS SQL Server databases. Our work on moving away from Rust continues with the goal of making “Rust-free” Prisma ORM the default in the upcoming Prisma v7 release. In this article, we are sharing an update on the performance improvements we’ve measured using the latest Rust-free Preview version of Prisma ORM. diff --git a/apps/blog/content/blog/prisma-postgres-the-future-of-serverless-databases/index.mdx b/apps/blog/content/blog/prisma-postgres-the-future-of-serverless-databases/index.mdx index a41023233a..b3b2d67119 100644 --- a/apps/blog/content/blog/prisma-postgres-the-future-of-serverless-databases/index.mdx +++ b/apps/blog/content/blog/prisma-postgres-the-future-of-serverless-databases/index.mdx @@ -34,7 +34,7 @@ Try it now by following the [**Quickstart**](https://pris.ly/ppg-quickstart) or ```shell # Create a new database -npx prisma@latest init --db +npx prisma@7.9.1 init --db ``` ## The serverless database that's built for the future diff --git a/apps/blog/content/blog/prisma-schema-as-llm-context/index.mdx b/apps/blog/content/blog/prisma-schema-as-llm-context/index.mdx index 7f8d1fb279..d149284a5e 100644 --- a/apps/blog/content/blog/prisma-schema-as-llm-context/index.mdx +++ b/apps/blog/content/blog/prisma-schema-as-llm-context/index.mdx @@ -104,7 +104,7 @@ All three are answerable from the schema plus the ORM's documented defaults, inc ## Prisma 8 treats schema-as-context as a feature -[Prisma 8](https://www.prisma.io/docs/orm/v8), the next generation of the ORM currently in release candidate, makes this a design goal rather than a side effect: the schema stays small, dense, and machine-readable, treated as first-class LLM context rather than an implementation detail, and errors are structured for agent consumption, carrying documentation URLs that resolve to a stable reference for the exact error. +[Prisma 8](https://www.prisma.io/docs/orm), the next generation of the ORM currently in release candidate, makes this a design goal rather than a side effect: the schema stays small, dense, and machine-readable, treated as first-class LLM context rather than an implementation detail, and errors are structured for agent consumption, carrying documentation URLs that resolve to a stable reference for the exact error. The schema answers "what is the data model." The other half, "how do we change it safely here," belongs in your agent rules file; we covered a copy-pasteable version in [What to Put in Your AGENTS.md](/agents-md-for-databases). @@ -112,7 +112,7 @@ The schema answers "what is the data model." The other half, "how do we change i Your agent reasons about your data about as well as the context you hand it. A declarative schema is cheap, high-quality context: one parseable file that the client, the migrations, and the agent all start from, kept in step with the database by the migration workflow. -If you already use Prisma, try the three prompts above against your own schema. If your model lives in code today, `npx prisma init` and an introspection run will give you a schema file to compare against, and the [Prisma ORM docs](https://www.prisma.io/docs/orm) cover the path from there. +If you already use Prisma, try the three prompts above against your own schema. If your model lives in code today, `npx prisma@7.9.1 init` and an introspection run will give you a schema file to compare against, and the [Prisma ORM docs](https://www.prisma.io/docs/orm) cover the path from there. ## Frequently asked questions diff --git a/apps/blog/content/blog/prisma-schema-language-the-best-way-to-define-your-data/index.mdx b/apps/blog/content/blog/prisma-schema-language-the-best-way-to-define-your-data/index.mdx index 251a5a0130..ad4b9ece7e 100644 --- a/apps/blog/content/blog/prisma-schema-language-the-best-way-to-define-your-data/index.mdx +++ b/apps/blog/content/blog/prisma-schema-language-the-best-way-to-define-your-data/index.mdx @@ -215,7 +215,7 @@ export const Tasks = defineTable('tasks', { **Prisma Client** -Integration with the [Prisma CLI](https://www.prisma.io/docs/orm/reference/prisma-cli-reference) simplifies many development tasks. Validating and formatting your schema, generating database migrations, even managing your data with a visual tool! +Integration with the [Prisma CLI](https://www.prisma.io/docs/orm/v7/reference/prisma-cli-reference) simplifies many development tasks. Validating and formatting your schema, generating database migrations, even managing your data with a visual tool! As your schema grows, you can also [split it across multiple `.prisma` files](https://www.prisma.io/blog/organize-your-prisma-schema-with-multi-file-support), Generally Available since Prisma ORM v6.7.0. In Prisma ORM v7, you point the `schema` property in `prisma.config.ts` at your schema directory and relations work across files without imports. @@ -330,4 +330,4 @@ It's fast, too: in [our published benchmark](https://www.prisma.io/blog/prisma-n Overall, the Prisma Schema Language is the better choice for modern, team-based development. It offers clear, easy-to-read schemas, simple relationship modeling, and a great developer experience. -Ready to simplify your database schema? [Get started with our documentation](https://www.prisma.io/docs/prisma-orm/quickstart/prisma-postgres). +Ready to simplify your database schema? [Get started with our documentation](https://www.prisma.io/docs/v7/prisma-orm/quickstart/prisma-postgres). diff --git a/apps/blog/content/blog/prisma-studio-3rtf78dg99fe/index.mdx b/apps/blog/content/blog/prisma-studio-3rtf78dg99fe/index.mdx index 252577d99b..af542af78b 100644 --- a/apps/blog/content/blog/prisma-studio-3rtf78dg99fe/index.mdx +++ b/apps/blog/content/blog/prisma-studio-3rtf78dg99fe/index.mdx @@ -78,7 +78,7 @@ Now you can initialize a new Prisma project: ``` -npx prisma init +npx prisma@7.9.1 init ``` @@ -86,7 +86,7 @@ This creates a new directory called `prisma` with an empty [Prisma schema](https ### 2. Connect your database -Next, you need to connect your database by providing your [connection URL](https://www.prisma.io/docs/orm/reference/connection-urls) as the `DATABASE_URL` environment variable in the `.env` file. Here are a few examples for what you connection URL might look like depending on the database you use: +Next, you need to connect your database by providing your [connection URL](https://www.prisma.io/docs/orm/v7/reference/connection-urls) as the `DATABASE_URL` environment variable in the `.env` file. Here are a few examples for what you connection URL might look like depending on the database you use: ``` diff --git a/apps/blog/content/blog/prisma-studio-migrations-view/index.mdx b/apps/blog/content/blog/prisma-studio-migrations-view/index.mdx index ca09212e72..5806754919 100644 --- a/apps/blog/content/blog/prisma-studio-migrations-view/index.mdx +++ b/apps/blog/content/blog/prisma-studio-migrations-view/index.mdx @@ -17,7 +17,7 @@ series: prisma-next seriesIndex: 10 --- -The Migrations view is a new screen in Prisma Studio, the database GUI bundled with the Prisma CLI. It shows the migration history of a [Prisma 8](https://www.prisma.io/docs/orm/v8) database as a timeline: one entry per applied migration, with a visual diff of what changed, the SQL that ran, and a schema diff. +The Migrations view is a new screen in Prisma Studio, the database GUI bundled with the Prisma CLI. It shows the migration history of a [Prisma 8](https://www.prisma.io/docs/orm) database as a timeline: one entry per applied migration, with a visual diff of what changed, the SQL that ran, and a schema diff. Studio reads that history from the database itself, not from your repo. So it works for any Prisma 8 Postgres database you can connect to, including one you have never migrated yourself. The full setup is documented in [Studio with Prisma 8](https://www.prisma.io/docs/studio/prisma-next). @@ -63,7 +63,7 @@ This scaffolds a contract at `src/prisma/contract.prisma`. Then create a [Prisma ### Step 2: Model, plan, apply -Prisma 8 calls your schema a [contract](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract): +Prisma 8 calls your schema a [contract](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract): ```prisma // use prisma-next @@ -89,15 +89,15 @@ model Post { } ``` -Compile it, [plan a migration](https://www.prisma.io/docs/orm/v8/migrations/generating-a-migration), [apply it](https://www.prisma.io/docs/orm/v8/migrations/applying-a-migration): +Compile it, [plan a migration](https://www.prisma.io/docs/orm/migrations/generating-a-migration), [apply it](https://www.prisma.io/docs/orm/migrations/applying-a-migration): ```bash -npx prisma@next contract emit -npx prisma@next migration plan --name init_users_posts -npx prisma@next migrate --advance-ref db +npx prisma@latest contract emit +npx prisma@latest migration plan --name init_users_posts +npx prisma@latest migrate --advance-ref db ``` -`--advance-ref db` moves a [ref](https://www.prisma.io/docs/orm/v8/migrations/the-migration-graph#name-important-states-with-refs), a name pinned to a point in your migration history, onto what you just applied. Later plans start from there and produce a delta instead of recreating everything. +`--advance-ref db` moves a [ref](https://www.prisma.io/docs/orm/migrations/the-migration-graph#name-important-states-with-refs), a name pinned to a point in your migration history, onto what you just applied. Later plans start from there and produce a delta instead of recreating everything. ### Step 3: Change the model @@ -135,9 +135,9 @@ model Post { ``` ```bash -npx prisma@next contract emit -npx prisma@next migration plan --name add_roles_and_publishing -npx prisma@next migrate --advance-ref db +npx prisma@latest contract emit +npx prisma@latest migration plan --name add_roles_and_publishing +npx prisma@latest migrate --advance-ref db ``` Repeat for whatever your app needs; when a change needs a backfill, [Data Migrations in Prisma 8](/data-migrations-in-prisma-next) covers that. The history behind the screenshots here has six migrations: an initial pair of models, this enum-and-fields change, a `Category` model with a relation and two unique constraints, a destructive column drop, and two more field additions. @@ -196,7 +196,7 @@ Every ledger row names the contract it started from and the contract it produced Writing only the destination contract on each apply is enough to cover both ends of every row. The first migration starts from the empty contract. Every origin after that was some earlier apply's destination, so it is already stored. -The practical consequence: a migration applied from CI, from a teammate's laptop, or from a branch you never checked out shows up in your Studio with a full diff. The history belongs to the database. The hashes are the same ones that make Prisma 8 migrations [a graph rather than a numbered list](https://www.prisma.io/docs/orm/v8/migrations/the-migration-graph). +The practical consequence: a migration applied from CI, from a teammate's laptop, or from a branch you never checked out shows up in your Studio with a full diff. The history belongs to the database. The hashes are the same ones that make Prisma 8 migrations [a graph rather than a numbered list](https://www.prisma.io/docs/orm/migrations/the-migration-graph). ## Where you can use it diff --git a/apps/blog/content/blog/prisma-turso-ea-support-rXGd_Tmy3UXX/index.mdx b/apps/blog/content/blog/prisma-turso-ea-support-rXGd_Tmy3UXX/index.mdx index 158a5bea09..0933521476 100644 --- a/apps/blog/content/blog/prisma-turso-ea-support-rXGd_Tmy3UXX/index.mdx +++ b/apps/blog/content/blog/prisma-turso-ea-support-rXGd_Tmy3UXX/index.mdx @@ -147,7 +147,7 @@ To get started using Turso: 5. Install the latest version of Prisma Client: ```shell - npm install @prisma/client@latest + npm install @prisma/client@7.9.1 ``` 6. Install the libSQL database client and the driver adapter for Prisma Client: diff --git a/apps/blog/content/blog/read-replicas-prisma-client-extension-f66prwk56wow/index.mdx b/apps/blog/content/blog/read-replicas-prisma-client-extension-f66prwk56wow/index.mdx index 52b61fe4b1..c8a4ea3fa0 100644 --- a/apps/blog/content/blog/read-replicas-prisma-client-extension-f66prwk56wow/index.mdx +++ b/apps/blog/content/blog/read-replicas-prisma-client-extension-f66prwk56wow/index.mdx @@ -169,7 +169,7 @@ And that's it! When you run your app, the extension will send all read operations, such as `findMany`, to a database replica. A replica will be selected randomly if you have multiple replicas defined. -Any write queries (e.g., `create`, `update`, ...) as well as [`$transaction`](https://www.prisma.io/docs/orm/prisma-client/queries/transactions#the-transaction-api) queries are forwarded to the primary instance of your database, which would consequently propagate the resulting changes to the existing database replicas. +Any write queries (e.g., `create`, `update`, ...) as well as [`$transaction`](https://www.prisma.io/docs/orm/v7/prisma-client/queries/transactions#the-transaction-api) queries are forwarded to the primary instance of your database, which would consequently propagate the resulting changes to the existing database replicas. If you would like to read from the primary database and bypass read replicas, the extension provides the `$primary()` method on your extended Prisma Client instance: @@ -184,7 +184,7 @@ A significant advantage of having the extension as a separate package rather tha A side-effect of shipping it as a separate package/repository is that the codebase will remain relatively small and manageable. This will allow our community members to contribute by creating pull requests to improve the extension. -While [Prisma Client extensions](https://www.prisma.io/docs/orm/prisma-client/client-extensions) have been Generally Available since Prisma [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0), we also used the experience from building an extension ourselves as an opportunity to make further improvements to the Prisma Client extension API. For example, in [5.2.0](https://github.com/prisma/prisma/releases/tag/5.2.0), as preparation for this extension, we removed the datasource name in Prisma Client's constructor configuration, to simplify programmatic connection string overrides, which the extension uses. We also created a few more GitHub issues for [future improvements to Client Extensions](https://github.com/prisma/prisma/issues?q=is:open+label:%22topic:+clientExtensions%22+label:kind/improvement+sort:updated-desc+). Please leave an upvote or comment if you're interested in any of these improvements. +While [Prisma Client extensions](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions) have been Generally Available since Prisma [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0), we also used the experience from building an extension ourselves as an opportunity to make further improvements to the Prisma Client extension API. For example, in [5.2.0](https://github.com/prisma/prisma/releases/tag/5.2.0), as preparation for this extension, we removed the datasource name in Prisma Client's constructor configuration, to simplify programmatic connection string overrides, which the extension uses. We also created a few more GitHub issues for [future improvements to Client Extensions](https://github.com/prisma/prisma/issues?q=is:open+label:%22topic:+clientExtensions%22+label:kind/improvement+sort:updated-desc+). Please leave an upvote or comment if you're interested in any of these improvements. ## Try it out yourself @@ -192,4 +192,4 @@ We encourage you to try out the [`@prisma/extension-read-replicas`](https://pris Check out this [example app](https://github.com/prisma/read-replicas-demo) to learn how to get up and running with read replicas using the `@prisma/extension-read-replicas` extension. -Be sure also to try out [Prisma Client extensions](https://www.prisma.io/docs/orm/prisma-client/client-extensions) and share with us what you build on [Twitter](https://pris.ly/x) or [Discord](https://pris.ly/discord). 🙌 +Be sure also to try out [Prisma Client extensions](https://www.prisma.io/docs/orm/v7/prisma-client/client-extensions) and share with us what you build on [Twitter](https://pris.ly/x) or [Discord](https://pris.ly/discord). 🙌 diff --git a/apps/blog/content/blog/rethinking-database-migrations/index.mdx b/apps/blog/content/blog/rethinking-database-migrations/index.mdx index 848ebd728f..6a1f1de060 100644 --- a/apps/blog/content/blog/rethinking-database-migrations/index.mdx +++ b/apps/blog/content/blog/rethinking-database-migrations/index.mdx @@ -16,7 +16,7 @@ series: prisma-next seriesIndex: 3 --- -Database migrations are brittle and they break when you're most vulnerable; when you're deploying to production. [Prisma 8 migrations](https://www.prisma.io/docs/orm/v8) make them explicit, verifiable and safe to retry. Here's how. +Database migrations are brittle and they break when you're most vulnerable; when you're deploying to production. [Prisma 8 migrations](https://www.prisma.io/docs/orm) make them explicit, verifiable and safe to retry. Here's how. ## The problem with migrations today @@ -54,7 +54,7 @@ With Prisma 8, we set out to build a migration system that handles all of these ## Prisma 8 migrations -In Prisma 8, [a migration](https://www.prisma.io/docs/orm/v8/migrations/how-migrations-work) is explicit about what it needs to do and how it does it. Every migration knows: +In Prisma 8, [a migration](https://www.prisma.io/docs/orm/migrations/how-migrations-work) is explicit about what it needs to do and how it does it. Every migration knows: - The expected DB schema **before** it's executed. - The DB schema **after** it's executed. @@ -87,7 +87,7 @@ migrations/ #### How `from` and `to` work -In Prisma 8, your [`schema.prisma`](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract) is converted into a [JSON file](https://www.prisma.io/docs/orm/v8/contract-authoring/the-contract-artifact) which lists every table, column and relation that's expected to be present in your database, similar to a `package-lock.json`. Hashing that file gives us a simple identifier that describes a specific database state, like a git commit hash. +In Prisma 8, your [`schema.prisma`](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract) is converted into a [JSON file](https://www.prisma.io/docs/orm/contract-authoring/the-contract-artifact) which lists every table, column and relation that's expected to be present in your database, similar to a `package-lock.json`. Hashing that file gives us a simple identifier that describes a specific database state, like a git commit hash. Migrations promise to transition your database from one schema to another, which is recorded as a `from` hash and a `to` hash in the JSON example above. This works the same way as applying a git commit to your filesystem: it moves your filesystem from one state to the next. @@ -123,7 +123,7 @@ Each operation has three parts: ## Migrations are a graph -Because each migration records the schema it starts from and the schema it produces, migrations don't need to be ordered alphabetically. They form a [graph of state transitions](https://www.prisma.io/docs/orm/v8/migrations/the-migration-graph) linked by their `from` and `to` hashes, and the system can figure out which path to follow. +Because each migration records the schema it starts from and the schema it produces, migrations don't need to be ordered alphabetically. They form a [graph of state transitions](https://www.prisma.io/docs/orm/migrations/the-migration-graph) linked by their `from` and `to` hashes, and the system can figure out which path to follow. Here's what that looks like in practice. Two developers have branched from the same schema and each added a migration: @@ -145,7 +145,7 @@ This idea isn't entirely new, tools like [Sqitch](https://sqitch.org/) and [Atla Remember the local-drift scenario? You iterate on a migration locally, your DB ends up in a slightly different state, and the migration fails in CI. With Prisma 8, the runner checks the database's current schema hash against the migration's `from` hash before doing anything. If they don't match, the migration stops immediately with a clear error. Not halfway through, leaving the database in an unknown state. -What if a migration *does* fail partway through? Because every operation carries a precheck and a postcheck, the migration is [safe to retry](https://www.prisma.io/docs/orm/v8/migrations/rollbacks-and-recovery). Operations whose postchecks already pass are skipped; operations whose prechecks fail produce a clear error. The database never ends up in a state the system can't reason about. +What if a migration *does* fail partway through? Because every operation carries a precheck and a postcheck, the migration is [safe to retry](https://www.prisma.io/docs/orm/migrations/rollbacks-and-recovery). Operations whose postchecks already pass are skipped; operations whose prechecks fail produce a clear error. The database never ends up in a state the system can't reason about. ## Resolving conflicts between branches diff --git a/apps/blog/content/blog/rust-free-prisma-orm-is-ready-for-production/index.mdx b/apps/blog/content/blog/rust-free-prisma-orm-is-ready-for-production/index.mdx index 5988533df5..6d23ea5bd5 100644 --- a/apps/blog/content/blog/rust-free-prisma-orm-is-ready-for-production/index.mdx +++ b/apps/blog/content/blog/rust-free-prisma-orm-is-ready-for-production/index.mdx @@ -130,6 +130,6 @@ Our focus on robustness and stability from the last weeks paid off! This week wa Additionally, you can now create OAuth apps yourself, so you can offer Prisma Postgres to your own users. We're excited to see what you're going to build with it! -If you're ready to put these changes to work, explore [Prisma ORM](https://www.prisma.io/orm), review the [Prisma Client generation docs](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client), and try [Prisma Postgres](https://www.prisma.io/postgres) for the database workflows highlighted in this release. +If you're ready to put these changes to work, explore [Prisma ORM](https://www.prisma.io/orm), review the [Prisma Client generation docs](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/generating-prisma-client), and try [Prisma Postgres](https://www.prisma.io/postgres) for the database workflows highlighted in this release. Let us know your thoughts, questions and feedback [on X](https://pris.ly/x) and join the conversation [on Discord](https://pris.ly/discord). diff --git a/apps/blog/content/blog/rust-to-typescript-update-boosting-prisma-orm-performance/index.mdx b/apps/blog/content/blog/rust-to-typescript-update-boosting-prisma-orm-performance/index.mdx index 0ba80e374c..1f76f847c2 100644 --- a/apps/blog/content/blog/rust-to-typescript-update-boosting-prisma-orm-performance/index.mdx +++ b/apps/blog/content/blog/rust-to-typescript-update-boosting-prisma-orm-performance/index.mdx @@ -127,7 +127,7 @@ You can now use Prisma in environments that support JavaScript or WASM, such as To enable it, use the new `prisma-client` generator and configure the correct driver adapter for your database, for example `@prisma/adapter-pg` for PostgreSQL. -See the [Prisma Client generator documentation](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#prisma-client?utm_source=chatgpt.com) for setup instructions. +See the [Prisma Client generator documentation](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#prisma-client?utm_source=chatgpt.com) for setup instructions. ### If Rust is already fast, why does switching to TypeScript and WebAssembly make Prisma faster? diff --git a/apps/blog/content/blog/ship-risky-schema-changes-without-a-shared-staging-database/index.mdx b/apps/blog/content/blog/ship-risky-schema-changes-without-a-shared-staging-database/index.mdx index 03ada96366..4124c8bd6b 100644 --- a/apps/blog/content/blog/ship-risky-schema-changes-without-a-shared-staging-database/index.mdx +++ b/apps/blog/content/blog/ship-risky-schema-changes-without-a-shared-staging-database/index.mdx @@ -38,7 +38,7 @@ Three Prisma products appear here, each with one job: - **Prisma Compute** (Public Beta) hosts your app and provisions a database for each branch you deploy with `--db`. It provides the isolation. Its CLI is `@prisma/cli`. - **Prisma Postgres** is the database each branch gets. -- **[Prisma 8](https://www.prisma.io/docs/orm/v8)** (Release Candidate) provides the migration toolchain in the examples, via the unified Prisma CLI (`npx prisma@next`). The same workflow also works with Prisma 7's `prisma migrate deploy`. +- **[Prisma 8](https://www.prisma.io/docs/orm)** (Release Candidate) provides the migration toolchain in the examples, via the unified Prisma CLI (`npx prisma@latest`). The same workflow also works with Prisma 7's `prisma migrate deploy`. ::: @@ -127,7 +127,7 @@ Add `displayName` as nullable, so existing code that only knows about `name` kee skill="prisma-next-migrations" before={expandContractBefore} after={expandContractAfter} - terminalCommand="npx prisma@next migration plan --name add_display_name" + terminalCommand="npx prisma@latest migration plan --name add_display_name" terminalLines={expandTerminalLines} /> @@ -147,7 +147,7 @@ override get operations() { } ``` -Apply it to your branch database with `npx prisma@next migrate` and deploy the branch. Old code still reads `name`; new code can start writing `displayName`. +Apply it to your branch database with `npx prisma@latest migrate` and deploy the branch. Old code still reads `name`; new code can start writing `displayName`. ### Step 2: Migrate @@ -166,7 +166,7 @@ model User { ``` ```bash -npx prisma@next migration plan --name require_display_name +npx prisma@latest migration plan --name require_display_name ``` The planner can write the `SET NOT NULL` itself, but only you know what existing rows should contain, so it scaffolds a backfill placeholder in front of the constraint and leaves the query to you. The backfill lives [inside the migration](https://pris.ly/data-migrations-pn) as a `dataTransform`, written with the same type-safe query builder you use in your app, instead of a standalone script that runs outside your migration history. Filled in: @@ -196,7 +196,7 @@ override get operations() { `check` asks "are there rows that still need this?" and `run` performs the change, here copying each row's `name` into `displayName`. Every migration folder carries a snapshot of the contract as it stood at that point in history, and both queries are typed against this migration's snapshot rather than your live schema. That's why the query can reference `name` even though a later migration drops it. -After editing, recompile with `node migration.ts`. The `dataTransform` compiles to the same `precheck` / `execute` / `postcheck` JSON as every other operation: reviewers read your intent in `migration.ts` and the exact SQL in `ops.json`, and production only ever runs the compiled JSON, never your TypeScript. See [Editing a migration](https://www.prisma.io/docs/orm/v8/migrations/editing-a-migration) for the full file, including the wiring that builds the typed `db` handle. +After editing, recompile with `node migration.ts`. The `dataTransform` compiles to the same `precheck` / `execute` / `postcheck` JSON as every other operation: reviewers read your intent in `migration.ts` and the exact SQL in `ops.json`, and production only ever runs the compiled JSON, never your TypeScript. See [Editing a migration](https://www.prisma.io/docs/orm/migrations/editing-a-migration) for the full file, including the wiring that builds the typed `db` handle. Run it against the branch database and check the data. Seed the branch database with realistic data first; an empty database proves the sequence applies cleanly, but only a real-shaped dataset tells you anything about the backfill. Nothing has touched production yet. @@ -211,7 +211,7 @@ Once all code reads `displayName` and the backfill is verified, remove the old c skill="prisma-next-migrations" before={contractContractBefore} after={contractContractAfter} - terminalCommand="npx prisma@next migration plan --name drop_legacy_name" + terminalCommand="npx prisma@latest migration plan --name drop_legacy_name" terminalLines={contractTerminalLines} /> @@ -270,7 +270,7 @@ jobs: PRISMA_SERVICE_TOKEN: ${{ secrets.PRISMA_SERVICE_TOKEN }} - name: Apply migrations to the branch database - run: npx prisma@next migrate --db "$DATABASE_URL" + run: npx prisma@latest migrate --db "$DATABASE_URL" env: DATABASE_URL: ${{ secrets.BRANCH_DB_URL }} @@ -317,7 +317,7 @@ Neon branches copy schema and data from a parent branch by default. Compute bran [Prisma 8 is in Early Access](https://www.prisma.io/blog/prisma-next-early-access-write-your-contract-prompt-your-agent-ship-your-app). It isn't production-ready yet; Prisma 7 remains the right choice for production today. But the per-branch workflow is ready to try now: ```bash -npx prisma@next orm init +npx prisma@latest orm init ``` Write a contract, plan a migration, and read the `migration.ts` and `ops.json` it produces. Then, from a feature branch, deploy to [Compute](https://www.prisma.io/docs/prisma-compute/deploy) with `npx @prisma/cli@latest app deploy --db`. The CLI targets your current Git branch, so that one command gives the branch its own database, ready for the expand-and-contract cycle. diff --git a/apps/blog/content/blog/stop-your-ai-agent-dropping-your-database/index.mdx b/apps/blog/content/blog/stop-your-ai-agent-dropping-your-database/index.mdx index cf4d4bd9d6..dbb7565873 100644 --- a/apps/blog/content/blog/stop-your-ai-agent-dropping-your-database/index.mdx +++ b/apps/blog/content/blog/stop-your-ai-agent-dropping-your-database/index.mdx @@ -28,9 +28,9 @@ We built Prisma 8 (formerly *Prisma Next*) so your agent can manage your databas Most agent-caused data loss traces back to a handful of schema admin commands: the commands that change the structure of your tables and their relationships. -The worst offender historically was [`prisma migrate reset`](https://www.prisma.io/docs/cli/migrate/reset), a command that wipes the database completely. It was meant as a development-time tool for starting from scratch, but older versions of Prisma *suggested* it whenever the database got into a state they couldn't manage. Unsurprisingly, people, and later their agents, deleted their databases. It was, after all, the next step in a process they trusted `prisma` to keep safe. +The worst offender historically was [`prisma migrate reset`](https://www.prisma.io/docs/cli/v7/migrate/reset), a command that wipes the database completely. It was meant as a development-time tool for starting from scratch, but older versions of Prisma *suggested* it whenever the database got into a state they couldn't manage. Unsurprisingly, people, and later their agents, deleted their databases. It was, after all, the next step in a process they trusted `prisma` to keep safe. -In the same vein are commands that update the database to match the schema recorded in the codebase: [`prisma db push`](https://www.prisma.io/docs/cli/db/push), [`drizzle-kit push --force`](https://orm.drizzle.team/docs/drizzle-kit-push), and friends. These are intended for development, but to an inquisitive agent they look like a fine way to update a running production database. Never mind that they will blithely delete any data that no longer matches the schema. +In the same vein are commands that update the database to match the schema recorded in the codebase: [`prisma db push`](https://www.prisma.io/docs/cli/v7/db/push), [`drizzle-kit push --force`](https://orm.drizzle.team/docs/drizzle-kit-push), and friends. These are intended for development, but to an inquisitive agent they look like a fine way to update a running production database. Never mind that they will blithely delete any data that no longer matches the schema. And then there are migrations themselves, a vertigo-inducing pitfall for humans and agents alike, and the place where tools have historically done almost nothing to protect you from your own mistakes. A migration is a file of SQL commands that runs in order. That's it. No protections, no guardrails, no verification. If you mess up, it's on you. @@ -56,11 +56,11 @@ But this isn't enough. The fix isn't a better warning. It's a system where the c ## How Prisma 8 makes schema changes safe -In Prisma 8, your schema is a [**contract**](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract) between your application and the database: it records every table, field, and index your application depends on. +In Prisma 8, your schema is a [**contract**](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract) between your application and the database: it records every table, field, and index your application depends on. Prisma's job is to make sure your database satisfies your contract, and that your application's queries and TypeScript types match it too. -The way you change your database is by changing your contract. Each time you do, you tell Prisma to bring the database up to date, which it does by writing and executing [migrations](https://www.prisma.io/docs/orm/v8/migrations/how-migrations-work). +The way you change your database is by changing your contract. Each time you do, you tell Prisma to bring the database up to date, which it does by writing and executing [migrations](https://www.prisma.io/docs/orm/migrations/how-migrations-work). For an agent, just like a human, that reduces the job to: describe what you want, ask the system to make it true, go back to writing your app. We didn't add warnings to make this safe for agents. We took away the dangerous actions entirely. @@ -72,7 +72,7 @@ Interactively, it asks: *"Apply destructive changes? This cannot be undone."* No ### There is no shadow database -To plan a migration, classic Prisma needed a second, disposable database, the [shadow database](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/shadow-database), where it replayed your entire migration history to work out what your real database should look like. Prisma usually creates and deletes it automatically, but hosted providers often don't allow that, so you supply one yourself through `shadowDatabaseUrl`. A shadow database gets wiped at the start of every run, with no prompt. That's its job. Which means one connection string pasted into the wrong field turns "plan a migration" into "silently erase a real database". The docs can only warn: *"Do not use the exact same values for `url` and `shadowDatabaseUrl` as that might delete all the data in your database."* +To plan a migration, classic Prisma needed a second, disposable database, the [shadow database](https://www.prisma.io/docs/orm/v7/prisma-migrate/understanding-prisma-migrate/shadow-database), where it replayed your entire migration history to work out what your real database should look like. Prisma usually creates and deletes it automatically, but hosted providers often don't allow that, so you supply one yourself through `shadowDatabaseUrl`. A shadow database gets wiped at the start of every run, with no prompt. That's its job. Which means one connection string pasted into the wrong field turns "plan a migration" into "silently erase a real database". The docs can only warn: *"Do not use the exact same values for `url` and `shadowDatabaseUrl` as that might delete all the data in your database."* That's not a hypothetical. In late July 2026, [ten minutes into an agent session](https://x.com/im_irushik/status/2082328630169145526), a developer watched [every table in their production Supabase instance turn up empty](https://x.com/IntCyberDigest/status/2082479318567895195). And Supabase is exactly the kind of hosted provider where the shadow database is configured by hand. @@ -136,7 +136,7 @@ Never "drop the database and try again". ### Runtime guardrails for dangerous queries -Schema changes aren't the only risk. When your application is running, Prisma 8 [middleware](https://www.prisma.io/docs/orm/v8/middleware/how-middleware-works) can check the queries you're executing, whoever wrote them: +Schema changes aren't the only risk. When your application is running, Prisma 8 [middleware](https://www.prisma.io/docs/orm/middleware/how-middleware-works) can check the queries you're executing, whoever wrote them: ```ts middleware: [ @@ -151,7 +151,7 @@ middleware: [ ], ``` -A `DELETE` without a `WHERE`, the classic agent-generated data wipe, errors before it executes. A connection can be marked read-only in policy. [Budgets](https://www.prisma.io/docs/orm/v8/middleware/built-in-budgets) stop runaway queries mid-stream. Together with the [built-in lints](https://www.prisma.io/docs/orm/v8/middleware/built-in-lints), this gives your agent fast feedback loops in development and testing, so it corrects itself before code hits production. +A `DELETE` without a `WHERE`, the classic agent-generated data wipe, errors before it executes. A connection can be marked read-only in policy. [Budgets](https://www.prisma.io/docs/orm/middleware/built-in-budgets) stop runaway queries mid-stream. Together with the [built-in lints](https://www.prisma.io/docs/orm/middleware/built-in-lints), this gives your agent fast feedback loops in development and testing, so it corrects itself before code hits production. ## What about the connection string? @@ -178,7 +178,7 @@ Prisma 8 is available today as a Release Candidate. Some features of Prisma 7 ar To get started, run: ```bash -npx prisma@next orm init +npx prisma@latest orm init ``` Then ask your agent to make a schema change and watch the workflow it follows: edit the contract, plan a migration, run it. That workflow, not a warning, is what stands between your agent and a viral screenshot. diff --git a/apps/blog/content/blog/sveltekit-prisma-kvCOEoeQlC/index.mdx b/apps/blog/content/blog/sveltekit-prisma-kvCOEoeQlC/index.mdx index ba11b3ecd1..91a5933a2f 100644 --- a/apps/blog/content/blog/sveltekit-prisma-kvCOEoeQlC/index.mdx +++ b/apps/blog/content/blog/sveltekit-prisma-kvCOEoeQlC/index.mdx @@ -114,7 +114,7 @@ It’s now time to get your hands dirty! Start by installing Prisma’s CLI as a development dependency with the following command: ```shell -npm install prisma --save-dev +npm install prisma@7.9.1 --save-dev ``` You can now set up Prisma in the project by running the following command: @@ -123,7 +123,7 @@ npx prisma init --datasource-provider sqlite ``` `prisma init` created a new `prisma` directory with a `schema.prisma` file inside it and a `.env` ([dotenv](https://github.com/motdotla/dotenv)) file at the root folder in your project. -The `schema.prisma` defines your database connection and the Prisma Client generator. For this project, you’ll use SQLite as your database provider for an easier setup. The `--datasource-provider sqlite` shorthand automatically sets up Prisma using SQLite. However, you can use another database provider simply by changing the database provider from `sqlite` to your preferred choice and updating the [connection URL](https://www.prisma.io/docs/orm/reference/connection-urls). +The `schema.prisma` defines your database connection and the Prisma Client generator. For this project, you’ll use SQLite as your database provider for an easier setup. The `--datasource-provider sqlite` shorthand automatically sets up Prisma using SQLite. However, you can use another database provider simply by changing the database provider from `sqlite` to your preferred choice and updating the [connection URL](https://www.prisma.io/docs/orm/v7/reference/connection-urls). The Prisma schema looks should resemble this: @@ -275,7 +275,7 @@ Then add this property to your `package.json` file: -Refer [Prisma docs](https://www.prisma.io/docs/orm/prisma-migrate/workflows/seeding#how-to-seed-your-database-in-prisma) for more information on seeding. +Refer [Prisma docs](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/seeding#how-to-seed-your-database-in-prisma) for more information on seeding. ### Create your first database migration @@ -289,7 +289,7 @@ The above command will execute the following: 1. Create a migration called `init` located in the `/prisma/migrations` directory. 2. Create the `dev.db` database file, since it does not exist, and apply the new SQL migration. 3. Install [`@prisma/client`](https://www.npmjs.com/package/@prisma/client) package. -4. [Generate Prisma Client](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client) based on the current schema. +4. [Generate Prisma Client](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/generating-prisma-client) based on the current schema. 5. Seed the database with sample data defined in the previous step. You should see similar output on your terminal to the one below: @@ -325,7 +325,7 @@ Seeding finished. 🌱 The seed command has been executed. ``` -You can browse the data in your database using [Prisma Studio](https://www.prisma.io/docs/orm/reference/prisma-cli-reference#studio). Run the following command: +You can browse the data in your database using [Prisma Studio](https://www.prisma.io/docs/orm/v7/reference/prisma-cli-reference#studio). Run the following command: ```shell npx prisma studio @@ -377,7 +377,7 @@ return { feed: response }; ``` The function above does the following: -1. Queries all published posts, including their authors, using the [`include` option](https://www.prisma.io/docs/orm/reference/prisma-client-reference#include). +1. Queries all published posts, including their authors, using the [`include` option](https://www.prisma.io/docs/orm/v7/reference/prisma-client-reference#include). 2. Assigns the `response` result to the `feed` object response. Currently, the client is still using dummy data from `data.json` instead of the SQLite database. Replace the code in `src/routes/+page.svelte` with the code below to rectify this: @@ -484,7 +484,7 @@ export const load = (async ({ params: { id } }) => { ``` The load function above does the following: -1. Leverages the load function [`data` prop](https://www.prisma.io/docs/orm/reference/prisma-client-reference#include) to get the post `id`. +1. Leverages the load function [`data` prop](https://www.prisma.io/docs/orm/v7/reference/prisma-client-reference#include) to get the post `id`. 2. Queries the database for a single post by its `id`. 3. Returns the `post` object response. diff --git a/apps/blog/content/blog/testing-series-1-8eRB5p0Y8o/index.mdx b/apps/blog/content/blog/testing-series-1-8eRB5p0Y8o/index.mdx index 5747b68f70..639d913a8b 100644 --- a/apps/blog/content/blog/testing-series-1-8eRB5p0Y8o/index.mdx +++ b/apps/blog/content/blog/testing-series-1-8eRB5p0Y8o/index.mdx @@ -92,8 +92,8 @@ Before writing tests, you need a project. Create a new directory, initialize it, ```sh mkdir prisma-testing && cd prisma-testing npm init -y -npm install -D prisma typescript tsx @types/node vitest vitest-mock-extended -npm install @prisma/client @prisma/adapter-pg dotenv +npm install -D prisma@7.9.1 typescript tsx @types/node vitest vitest-mock-extended +npm install @prisma/client@7.9.1 @prisma/adapter-pg dotenv ``` The `prisma-client` generator emits modern ES modules, so mark the project as ESM in `package.json`: @@ -436,7 +436,7 @@ test('getPosts should separate published & un-published posts', async () => { ### Triggering and capturing errors -You may want to test a case where a query throws. A good example is Prisma Client's [`findUniqueOrThrow`](https://www.prisma.io/docs/orm/reference/prisma-client-reference#finduniqueorthrow), which throws if no record is found. Because the client is mocked, you trigger the errored state yourself: +You may want to test a case where a query throws. A good example is Prisma Client's [`findUniqueOrThrow`](https://www.prisma.io/docs/orm/v7/reference/prisma-client-reference#finduniqueorthrow), which throws if no record is found. Because the client is mocked, you trigger the errored state yourself: ```ts // src/script.ts @@ -491,7 +491,7 @@ The [`rejects`](https://vitest.dev/api/expect.html#rejects) modifier resolves th ### Mocking transactions -Another part of Prisma Client you may need to mock is a [`$transaction`](https://www.prisma.io/docs/orm/prisma-client/queries/transactions#the-transaction-api). There are two forms: [sequential operations](https://www.prisma.io/docs/orm/prisma-client/queries/transactions#sequential-prisma-client-operations) and [interactive transactions](https://www.prisma.io/docs/orm/prisma-client/queries/transactions#interactive-transactions). How you mock them depends on your test's goal. +Another part of Prisma Client you may need to mock is a [`$transaction`](https://www.prisma.io/docs/orm/v7/prisma-client/queries/transactions#the-transaction-api). There are two forms: [sequential operations](https://www.prisma.io/docs/orm/v7/prisma-client/queries/transactions#sequential-prisma-client-operations) and [interactive transactions](https://www.prisma.io/docs/orm/v7/prisma-client/queries/transactions#interactive-transactions). How you mock them depends on your test's goal. If your test only cares about the result of a sequential transaction, mock the return value of `$transaction` directly: @@ -674,4 +674,4 @@ In this article, you focused on _mocking_ and _spying_, which play a major role With this foundation, you have the tools to unit test an application. In [part 2: Unit Testing](/testing-series-2-xPhjjmIEsM), you will put them to use against a real service. -Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/testing-series-2-xPhjjmIEsM/index.mdx b/apps/blog/content/blog/testing-series-2-xPhjjmIEsM/index.mdx index 61b4a8b5dd..89566dbede 100644 --- a/apps/blog/content/blog/testing-series-2-xPhjjmIEsM/index.mdx +++ b/apps/blog/content/blog/testing-series-2-xPhjjmIEsM/index.mdx @@ -452,4 +452,4 @@ While only one file was covered here, the same concepts apply to the rest of the You can also revisit [part 1: Mocking Prisma Client](/testing-series-1-8eRB5p0Y8o) for the mock setup used here. -Looking ahead: Prisma 8 is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/testing-series-3-aBUyF8nxAn/index.mdx b/apps/blog/content/blog/testing-series-3-aBUyF8nxAn/index.mdx index ee1e344f66..05fe253b5c 100644 --- a/apps/blog/content/blog/testing-series-3-aBUyF8nxAn/index.mdx +++ b/apps/blog/content/blog/testing-series-3-aBUyF8nxAn/index.mdx @@ -397,4 +397,4 @@ During this article you: In [part 4: End-to-End Testing](/testing-series-4-OVXtDis201), you will test the application from a user's perspective with Playwright. You can also revisit [part 2: Unit Testing](/testing-series-2-xPhjjmIEsM). -Looking ahead: Prisma 8 is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/testing-series-4-OVXtDis201/index.mdx b/apps/blog/content/blog/testing-series-4-OVXtDis201/index.mdx index 18ce78515a..c941745a05 100644 --- a/apps/blog/content/blog/testing-series-4-OVXtDis201/index.mdx +++ b/apps/blog/content/blog/testing-series-4-OVXtDis201/index.mdx @@ -379,4 +379,4 @@ Throughout this article you: In [part 5: CI Pipelines](/testing-series-5-xWogenROXm), you will run your unit, integration, and end-to-end tests automatically with GitHub Actions. You can also revisit [part 3: Integration Testing](/testing-series-3-aBUyF8nxAn). -Looking ahead: Prisma 8 is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/testing-series-5-xWogenROXm/index.mdx b/apps/blog/content/blog/testing-series-5-xWogenROXm/index.mdx index 1d4f7e947a..8d83476446 100644 --- a/apps/blog/content/blog/testing-series-5-xWogenROXm/index.mdx +++ b/apps/blog/content/blog/testing-series-5-xWogenROXm/index.mdx @@ -235,4 +235,4 @@ In this article you learned: Over this series you learned the kinds of tests you can write against applications that use Prisma ORM, how to write them, and how to automate them in CI. You can revisit any part: [part 1: Mocking](/testing-series-1-8eRB5p0Y8o), [part 2: Unit Testing](/testing-series-2-xPhjjmIEsM), [part 3: Integration Testing](/testing-series-3-aBUyF8nxAn), and [part 4: End-to-End Testing](/testing-series-4-OVXtDis201). -Looking ahead: Prisma 8 is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents and now available as a Release Candidate. Until it reaches general availability, Prisma 7 stays the production choice. To try it, run `npm create prisma@latest` or read the [Prisma 8 docs](https://pris.ly/pn-ea). +Looking ahead: [Prisma 8](https://www.prisma.io/docs/orm) is a TypeScript-native rewrite of Prisma ORM, built for AI coding agents, and it is now the current release. Prisma 7 remains fully supported; its docs live at [prisma.io/docs/orm/v7](https://www.prisma.io/docs/orm/v7). To start with Prisma 8, run `npm create prisma@latest` or read the [Prisma 8 docs](https://www.prisma.io/docs/getting-started). diff --git a/apps/blog/content/blog/the-next-evolution-of-prisma-orm/index.mdx b/apps/blog/content/blog/the-next-evolution-of-prisma-orm/index.mdx index 91b763c14f..9926ddd248 100644 --- a/apps/blog/content/blog/the-next-evolution-of-prisma-orm/index.mdx +++ b/apps/blog/content/blog/the-next-evolution-of-prisma-orm/index.mdx @@ -34,7 +34,7 @@ If you’ve been using Prisma, you will have felt the pain. Fixes take longer th Prisma 8 is a rewrite, which allows us to address what’s holding us back in the existing codebase, by rebuilding it end-to-end to be **extensible** and **composable** by default. -And we’re keeping what developers love about Prisma: the **[declarative schema](https://www.prisma.io/docs/orm/v8/data-modeling)** and the **model-first query experience**. +And we’re keeping what developers love about Prisma: the **[declarative schema](https://www.prisma.io/docs/orm/data-modeling)** and the **model-first query experience**. And we’re doing it for the world we’re in now: AI agents are increasingly part of how teams ship software, so Prisma 8 is designed to make **agent-assisted workflows** safer and more predictable. @@ -112,13 +112,13 @@ const orders = await db.orders .all(); ``` -In Prisma 8, [queries](https://www.prisma.io/docs/orm/v8/fundamentals/reading-data) remain easy to read, your editor continues to provide autocompletion, and even as queries grow more complex, they stay manageable. +In Prisma 8, [queries](https://www.prisma.io/docs/orm/fundamentals/reading-data) remain easy to read, your editor continues to provide autocompletion, and even as queries grow more complex, they stay manageable. If you’d like a deeper side-by-side comparison of Prisma ORM and Prisma 8, take a look at [the API comparison doc](https://github.com/prisma/prisma-next/blob/27ae1d164ae7060626aabaefce1af8428031e5ef/specs/2026-02-16-repository-model-client/prisma-orm-comparison.md?plain=1). ## We’re adding a SQL query builder -But an ORM can’t fit every use case. When you need something custom, or you need to tune performance, drop down to the **[type-safe SQL query builder](https://www.prisma.io/docs/orm/v8/fundamentals/advanced-queries)** and write it directly: +But an ORM can’t fit every use case. When you need something custom, or you need to tune performance, drop down to the **[type-safe SQL query builder](https://www.prisma.io/docs/orm/fundamentals/advanced-queries)** and write it directly: ```ts title="sql-builder.ts" db.sql @@ -142,7 +142,7 @@ Your query **builder stays in sync with your Prisma schema**, ensuring full type ## Write `schema.prisma` or TypeScript -The other thing Prisma is known for is its clean, declarative schema language. In Prisma 8 we add support for a [TypeScript alternative](https://www.prisma.io/docs/orm/v8/contract-authoring/typescript-schema-builder), so you can keep your schema in the same language as your application. +The other thing Prisma is known for is its clean, declarative schema language. In Prisma 8 we add support for a [TypeScript alternative](https://www.prisma.io/docs/orm/contract-authoring/typescript-schema-builder), so you can keep your schema in the same language as your application. Both versions are read by your application the same way, determining the shape of queries you can write on your models, their fields and their relationships: @@ -201,7 +201,7 @@ export default defineConfig({ }); ``` -When you install an [extension](https://www.prisma.io/docs/orm/v8/extensions/using-extensions) like `pgvector` above, your schema and your queries gain new capabilities: +When you install an [extension](https://www.prisma.io/docs/orm/extensions/using-extensions) like `pgvector` above, your schema and your queries gain new capabilities: ```prisma tab="Usage in Schema" // Use @pgvector columns in your Prisma schema @@ -338,7 +338,7 @@ But fast feedback is only half the story - you also need enforcement. ## Middleware -[Middleware](https://www.prisma.io/docs/orm/v8/middleware/how-middleware-works) runs in your application and sees every query before it hits the database. It lets you inspect, block, or rewrite queries before execution. +[Middleware](https://www.prisma.io/docs/orm/middleware/how-middleware-works) runs in your application and sees every query before it hits the database. It lets you inspect, block, or rewrite queries before execution. This is where you add real guardrails, for agents and humans alike. @@ -383,7 +383,7 @@ The result is simple: the query you write, the schema you define, and the databa One of Prisma's core promises has always been simple: update your Prisma schema, and your database follows. -Prisma 8 makes migrations safer and more transparent. Instead of a linear list of files, migrations form a **[graph](https://www.prisma.io/docs/orm/v8/migrations/the-migration-graph)** like Git branches, but for your database schema. +Prisma 8 makes migrations safer and more transparent. Instead of a linear list of files, migrations form a **[graph](https://www.prisma.io/docs/orm/migrations/the-migration-graph)** like Git branches, but for your database schema. With Prisma next you will be able to see exactly where your database is and where it's going: diff --git a/apps/blog/content/blog/top-5-myths-about-prisma-orm/index.mdx b/apps/blog/content/blog/top-5-myths-about-prisma-orm/index.mdx index bcc1314f08..32fb57f7f4 100644 --- a/apps/blog/content/blog/top-5-myths-about-prisma-orm/index.mdx +++ b/apps/blog/content/blog/top-5-myths-about-prisma-orm/index.mdx @@ -99,13 +99,13 @@ So, in order to not sacrifice important features that may be needed in more adva ### Customized migrations let developers use any SQL feature -While it's not possible to represent _all_ the features a database may have in the Prisma schema, you can still make use of these by [customizing the migration files](https://www.prisma.io/docs/orm/prisma-migrate/workflows/development-and-production#customizing-migrations) that are generated by Prisma Migrate. +While it's not possible to represent _all_ the features a database may have in the Prisma schema, you can still make use of these by [customizing the migration files](https://www.prisma.io/docs/orm/v7/prisma-migrate/workflows/development-and-production#customizing-migrations) that are generated by Prisma Migrate. To do so, you can simply use the `--create-only` flag whenever you create a new migration and make edits to it before it's applied against the database. ![](/top-5-myths-about-prisma-orm/imgs/25269e1341880f556defb4a52c3a593df68336b1-1047x1200.png) -Using customized migrations, you can freely manipulate your database schema while ensuring that all changes are executed by Prisma Migrate and tracked in its [migration history](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/migration-histories). +Using customized migrations, you can freely manipulate your database schema while ensuring that all changes are executed by Prisma Migrate and tracked in its [migration history](https://www.prisma.io/docs/orm/v7/prisma-migrate/understanding-prisma-migrate/migration-histories). ### Write type-safe SQL in Prisma ORM diff --git a/apps/blog/content/blog/try-the-new-rust-free-version-of-prisma-orm-early-access/index.mdx b/apps/blog/content/blog/try-the-new-rust-free-version-of-prisma-orm-early-access/index.mdx index 102325bd2e..9408b167a4 100644 --- a/apps/blog/content/blog/try-the-new-rust-free-version-of-prisma-orm-early-access/index.mdx +++ b/apps/blog/content/blog/try-the-new-rust-free-version-of-prisma-orm-early-access/index.mdx @@ -55,7 +55,7 @@ With all that knowledge, we embarked on a journey of removing Rust from the arch ## Prisma ORM v6.7.0: A new architecture without Rust engines (Early Access) -Following our previous updates, we're excited to release the new, _Rust-free_ architecture in [Early Access](https://www.prisma.io/docs/orm/more/releases#early-access) for PostgreSQL and SQLite with this week's [v6.7.0](http://github.com/prisma/prisma/releases/6.7.0) release. Please try it out and let us know what you think! +Following our previous updates, we're excited to release the new, _Rust-free_ architecture in [Early Access](https://www.prisma.io/docs/orm/v7/more/releases#early-access) for PostgreSQL and SQLite with this week's [v6.7.0](http://github.com/prisma/prisma/releases/6.7.0) release. Please try it out and let us know what you think! ### Usage with native JavaScript driver packages @@ -123,7 +123,7 @@ For details on that, you can check out our recent [article](https://www.prisma.i ## What's next for Prisma ORM? -Prisma ORM is undergoing major changes at the moment. We've announced our [ORM manifesto](https://www.prisma.io/blog/prisma-orm-manifesto) a few months ago with all details about changes to our OSS governance process. Since then, we've been working hard at making Prisma ORM _simpler_, _more robust_, and _more flexible_ with features like the new [`prisma-client` generator,](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#prisma-client-early-access) a [TypeScript-based configuration file](https://www.prisma.io/docs/orm/reference/prisma-config-reference) (called `prisma.config.ts`, and removing magic behaviors, like generating Prisma Client into `node_modules`). Check out our [roadmap](https://github.com/prisma/prisma/issues/26592) to see what's next! +Prisma ORM is undergoing major changes at the moment. We've announced our [ORM manifesto](https://www.prisma.io/blog/prisma-orm-manifesto) a few months ago with all details about changes to our OSS governance process. Since then, we've been working hard at making Prisma ORM _simpler_, _more robust_, and _more flexible_ with features like the new [`prisma-client` generator,](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#prisma-client-early-access) a [TypeScript-based configuration file](https://www.prisma.io/docs/orm/v7/reference/prisma-config-reference) (called `prisma.config.ts`, and removing magic behaviors, like generating Prisma Client into `node_modules`). Check out our [roadmap](https://github.com/prisma/prisma/issues/26592) to see what's next! ## Try out Prisma ORM without Rust @@ -170,7 +170,7 @@ You can now use Prisma in environments that support JavaScript or WASM, such as To enable it, use the new `prisma-client` generator and configure the correct driver adapter for your database, for example `@prisma/adapter-pg` for PostgreSQL. -See the [Prisma Client generator documentation](https://www.prisma.io/docs/orm/prisma-schema/overview/generators#prisma-client?utm_source=chatgpt.com) for setup instructions. +See the [Prisma Client generator documentation](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators#prisma-client?utm_source=chatgpt.com) for setup instructions. ### If Rust is already fast, why does switching to TypeScript and WebAssembly make Prisma faster? diff --git a/apps/blog/content/blog/type-safe-js-with-jsdoc-typeSaf3js/index.mdx b/apps/blog/content/blog/type-safe-js-with-jsdoc-typeSaf3js/index.mdx index ed9b0b778d..c1e29c9615 100644 --- a/apps/blog/content/blog/type-safe-js-with-jsdoc-typeSaf3js/index.mdx +++ b/apps/blog/content/blog/type-safe-js-with-jsdoc-typeSaf3js/index.mdx @@ -199,8 +199,8 @@ Next, install Prisma CLI as a development dependency and Prisma client: ```shell npm init -y -npm install -D prisma -npm install @prisma/client +npm install -D prisma@7.9.1 +npm install @prisma/client@7.9.1 ``` The [Prisma CLI](https://www.prisma.io/docs/reference/api-reference/command-reference) is as a development dependency used for the following: * Initializing Prisma in your project diff --git a/apps/blog/content/blog/typescript-migrations-in-prisma-next/index.mdx b/apps/blog/content/blog/typescript-migrations-in-prisma-next/index.mdx index 1b6e266ac7..5b61aa3835 100644 --- a/apps/blog/content/blog/typescript-migrations-in-prisma-next/index.mdx +++ b/apps/blog/content/blog/typescript-migrations-in-prisma-next/index.mdx @@ -19,7 +19,7 @@ seriesIndex: 4 > _Editor's note: Prisma 8 was developed under the working name Prisma Next. This post has been updated to use the final name._ -Migrations shouldn't be the scariest part of your deploy. In Prisma 8, [migrations](https://www.prisma.io/docs/orm/v8/migrations/how-migrations-work) are TypeScript files you can read, edit, and re-run with confidence. Every step is verified before it runs and again after. Every failure points directly at the operation that caused it. +Migrations shouldn't be the scariest part of your deploy. In Prisma 8, [migrations](https://www.prisma.io/docs/orm/migrations/how-migrations-work) are TypeScript files you can read, edit, and re-run with confidence. Every step is verified before it runs and again after. Every failure points directly at the operation that caused it. ## This is a SQL migration @@ -177,16 +177,16 @@ You edit the TypeScript. The system runs the JSON. Both get committed, much like ## The workflow -Most migrations don't get written from scratch. They get [planned](https://www.prisma.io/docs/orm/v8/migrations/generating-a-migration) from changes to your [Prisma contract](https://www.prisma.io/docs/orm/v8/contract-authoring/the-data-contract) (the `.prisma` file that describes your database schema). Say you add a `displayName String` field to your `User` model. Then: +Most migrations don't get written from scratch. They get [planned](https://www.prisma.io/docs/orm/migrations/generating-a-migration) from changes to your [Prisma contract](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract) (the `.prisma` file that describes your database schema). Say you add a `displayName String` field to your `User` model. Then: ```text -$ npx prisma@next migration plan +$ npx prisma@latest migration plan ✔ Planned 2 operation(s) │ ├─ Add column "displayName" to "user" [additive] └─ Set NOT NULL on "user"."displayName" [destructive] -$ npx prisma@next migrate --verbose +$ npx prisma@latest migrate --verbose ✔ Applied 1 migration(s) └─ 20260424T0930_add_user_displayname [2 op(s)] @@ -196,12 +196,12 @@ $ npx prisma@next migrate --verbose The planner reads your contract, compares it to the current database, and writes both `migration.ts` and `ops.json`. For most changes (adding a model, adding a field, creating an index), that's all you need. -When you do need to [edit a migration](https://www.prisma.io/docs/orm/v8/migrations/editing-a-migration), for example to backfill data before a constraint, reorder operations, or drop in a custom check, you open `migration.ts`, edit it like any other TypeScript file, and re-run it to regenerate `ops.json`. Your editor handles autocomplete, type checking, and inline docs for every operation. There's no SQL syntax to remember and no second-guessing whether you got the constraint definition right. +When you do need to [edit a migration](https://www.prisma.io/docs/orm/migrations/editing-a-migration), for example to backfill data before a constraint, reorder operations, or drop in a custom check, you open `migration.ts`, edit it like any other TypeScript file, and re-run it to regenerate `ops.json`. Your editor handles autocomplete, type checking, and inline docs for every operation. There's no SQL syntax to remember and no second-guessing whether you got the constraint definition right. Where it gets interesting is when something goes wrong. The runner doesn't just bail with a database error. It names the operation that failed and the check inside it that the database refused to satisfy: ```text -$ npx prisma@next migrate +$ npx prisma@latest migrate ✖ Operation alterNullability.setNotNull.user.displayName failed during precheck: ensure no NULL values in "displayName" (PN-RUN-5001) Why: Migration runner halted before destructive ALTER Fix: Fix the issue and re-run `prisma-next migrate`. Previously applied migrations are preserved. @@ -209,14 +209,14 @@ $ npx prisma@next migrate You know which operation failed (`alterNullability.setNotNull.user.displayName`) and which check failed inside it (`ensure no NULL values in "displayName"`). Both come straight from `ops.json`, and both tell you exactly where to look. From here, you fix it. You might backfill the nulls, drop and re-add the column with a default, or edit the migration to add a backfill step before the `setNotNull`. Then you re-run. -**[Re-running is safe](https://www.prisma.io/docs/orm/v8/migrations/rollbacks-and-recovery).** Before running each operation, the migration runner first evaluates that operation's postcheck. If the postcheck is already true, the runner skips the operation (which makes each operation idempotent). The migration then continues at the first step that hasn't succeeded yet. There's no commenting out lines, no manually unwinding state, and no guessing what's been applied. The single most uncomfortable problem with SQL migrations is solved. +**[Re-running is safe](https://www.prisma.io/docs/orm/migrations/rollbacks-and-recovery).** Before running each operation, the migration runner first evaluates that operation's postcheck. If the postcheck is already true, the runner skips the operation (which makes each operation idempotent). The migration then continues at the first step that hasn't succeeded yet. There's no commenting out lines, no manually unwinding state, and no guessing what's been applied. The single most uncomfortable problem with SQL migrations is solved. **Your development workflow becomes:** 1. Edit your `contract.prisma` 2. Plan a migration: `migration plan` 3. Edit the TypeScript and run `./migration.ts` -4. [Apply the migration](https://www.prisma.io/docs/orm/v8/migrations/applying-a-migration): `prisma-next migrate` +4. [Apply the migration](https://www.prisma.io/docs/orm/migrations/applying-a-migration): `prisma-next migrate` 5. Read the output, iterate The contract describes the database schema you want. `migration.ts` lets you edit the migration easily. The JSON is what runs. The feedback is granular enough to act on. @@ -293,7 +293,7 @@ Most importantly, `migration.ts` combined with `ops.json` is _really_ easy to re But you can try it now: ```bash -npx prisma@next orm init +npx prisma@latest orm init ``` Start a project, write a contract, plan a migration, and see what `migration.ts` and `ops.json` look like for yourself. We'd love your feedback. Join us on [Discord](https://pris.ly/discord) and tell us what works and what doesn't. diff --git a/apps/blog/content/blog/vibe-coding-with-limits-how-to-build-apps-in-the-age-of-ai/index.mdx b/apps/blog/content/blog/vibe-coding-with-limits-how-to-build-apps-in-the-age-of-ai/index.mdx index 8d1cb03e17..1a9960ed51 100644 --- a/apps/blog/content/blog/vibe-coding-with-limits-how-to-build-apps-in-the-age-of-ai/index.mdx +++ b/apps/blog/content/blog/vibe-coding-with-limits-how-to-build-apps-in-the-age-of-ai/index.mdx @@ -82,7 +82,7 @@ It offers the reliability developers need without the operational complexity tha To try out Prisma Postgres, simply run this command in your terminal: ``` -npx prisma init --db +npx prisma@7.9.1 init --db ``` Prisma Postgres also integrates directly with your favorite LLM and AI coding environment via the Model Context Protocol (MCP). diff --git a/apps/blog/content/blog/vibe-coding-with-prisma-mcp-and-nextjs/index.mdx b/apps/blog/content/blog/vibe-coding-with-prisma-mcp-and-nextjs/index.mdx index 59db4e4ab9..82bee82c25 100644 --- a/apps/blog/content/blog/vibe-coding-with-prisma-mcp-and-nextjs/index.mdx +++ b/apps/blog/content/blog/vibe-coding-with-prisma-mcp-and-nextjs/index.mdx @@ -101,7 +101,7 @@ With the stack and context in place, we were ready to move on to building the ho From there, the AI proceeded to scaffold the workspace, by running two commands: - `create-next-app@latest .`: Creates a new Next.js app in the current directory, along with a few other flags to auto select tool options. -- `prisma init --output`: Initializes Prisma ORM with a custom [output path](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client#using-a-custom-output-path) +- `prisma init --output`: Initializes Prisma ORM with a custom [output path](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/generating-prisma-client#using-a-custom-output-path) ```shell npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir @@ -109,8 +109,8 @@ npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir It then added Prisma: ```shell -npm install prisma --save-dev -npm install @prisma/client +npm install prisma@7.9.1 --save-dev +npm install @prisma/client@7.9.1 npx prisma init --output ../src/generated/prisma ``` After intializing Prisma, it prompted the [Prisma MCP Server](https://pris.ly/docs/mcp-server) to create a database. Once created, it connected to the database and that was it! diff --git a/apps/blog/content/blog/why-prisma-orm-checks-types-faster-than-drizzle/index.mdx b/apps/blog/content/blog/why-prisma-orm-checks-types-faster-than-drizzle/index.mdx index 71587e4854..2fe0ccdc1c 100644 --- a/apps/blog/content/blog/why-prisma-orm-checks-types-faster-than-drizzle/index.mdx +++ b/apps/blog/content/blog/why-prisma-orm-checks-types-faster-than-drizzle/index.mdx @@ -354,6 +354,6 @@ You can explore all the benchmark files in our [open-source repo](https://github If you are building a large, complex app where developer velocity and CI performance matter, Prisma ORM’s approach scales further and faster. Most importantly, type performance is developer experience. The faster your editor responds, the quicker your feedback loop and the happier your developers. -If you want to see how that workflow looks in practice, explore [Prisma ORM](https://www.prisma.io/orm), review how [Prisma Client generation works](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client), and compare it with [TypedSQL](https://www.prisma.io/typedsql) for the cases where you need lower-level control. +If you want to see how that workflow looks in practice, explore [Prisma ORM](https://www.prisma.io/orm), review how [Prisma Client generation works](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/generating-prisma-client), and compare it with [TypedSQL](https://www.prisma.io/typedsql) for the cases where you need lower-level control. > We used Drizzle ORM versions `0.44.4` (stable) and `1.0.0-beta.1-2acab7f` and compared them against Prisma ORM `6.15.0`. diff --git a/apps/blog/content/blog/why-prisma-orm-generates-code-into-node-modules-and-why-it-ll-change/index.mdx b/apps/blog/content/blog/why-prisma-orm-generates-code-into-node-modules-and-why-it-ll-change/index.mdx index 569f5232e6..9d1598738f 100644 --- a/apps/blog/content/blog/why-prisma-orm-generates-code-into-node-modules-and-why-it-ll-change/index.mdx +++ b/apps/blog/content/blog/why-prisma-orm-generates-code-into-node-modules-and-why-it-ll-change/index.mdx @@ -19,7 +19,7 @@ Since Prisma ORM v7, Prisma Client is generated into a folder you choose inside ## Where Prisma Client lives today -In Prisma ORM v7, the default generator is [`prisma-client`](https://www.prisma.io/docs/orm/prisma-schema/overview/generators). It requires an explicit `output` path and writes the generated client into your project source tree: +In Prisma ORM v7, the default generator is [`prisma-client`](https://www.prisma.io/docs/orm/v7/prisma-schema/overview/generators). It requires an explicit `output` path and writes the generated client into your project source tree: ```prisma // prisma/schema.prisma diff --git a/apps/blog/content/blog/why-the-prisma-cli-asks-for-your-feedback/index.mdx b/apps/blog/content/blog/why-the-prisma-cli-asks-for-your-feedback/index.mdx index 47892ca29c..05f89b09b9 100644 --- a/apps/blog/content/blog/why-the-prisma-cli-asks-for-your-feedback/index.mdx +++ b/apps/blog/content/blog/why-the-prisma-cli-asks-for-your-feedback/index.mdx @@ -46,7 +46,7 @@ We store the score, any comment you provide, and a random uuid. We do **not**  Participation is entirely optional. If you’d like to opt out, choose whichever method suits you best: - When prompted, leave the input blank and press **Enter**—you will not be asked again -- Run commands with [`--no-hints`](https://www.prisma.io/docs/orm/reference/prisma-cli-reference#options-1) to avoid survey prompts and other tips +- Run commands with [`--no-hints`](https://www.prisma.io/docs/orm/v7/reference/prisma-cli-reference#options-1) to avoid survey prompts and other tips - Set the [`CI` environment variable](https://github.com/watson/ci-info/blob/master/index.js#L36) to any truthy value in order to silence prompts in automated pipelines ## Closing the loop diff --git a/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/PgvectorDemoRunner.tsx b/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/PgvectorDemoRunner.tsx index 966855def7..a212c2b7da 100644 --- a/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/PgvectorDemoRunner.tsx +++ b/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/PgvectorDemoRunner.tsx @@ -67,9 +67,9 @@ export default defineConfig({ title: "Migrate", filename: "terminal", lang: "bash", - source: `bunx prisma@next contract emit -bunx prisma@next migration plan -bunx prisma@next db init`, + source: `bunx prisma@latest contract emit +bunx prisma@latest migration plan +bunx prisma@latest db init`, caption: "migration plan copies the pgvector pack's own baseline migration into your repo; db init applies both spaces. You never run CREATE EXTENSION by hand.", output: [ diff --git a/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/index.mdx b/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/index.mdx index 84c6d6ba44..d39f0a76ad 100644 --- a/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/index.mdx +++ b/apps/blog/content/blog/you-dont-need-a-vector-database-postgres-already-has-pgvector/index.mdx @@ -27,7 +27,7 @@ If your app already runs on Postgres, you probably don't need a dedicated vector The default move is the opposite: the moment semantic search shows up on a roadmap, someone proposes Pinecone, Weaviate, or Qdrant. That means a second data store, a pipeline to keep it consistent with your primary database, and a second set of credentials, backups, and bills, all before the first useful search result. -In this post you'll build a small semantic search demo end to end: a temporary [Prisma Postgres](https://www.prisma.io/docs/postgres) database spawned with `npx create-db`, a schema with a `vector` column, and a type-safe cosine similarity query written with [Prisma 8](https://www.prisma.io/docs/orm/v8), the next-generation Prisma ORM, and its `@prisma/orm-extension-pgvector` extension pack. Every command and every output in this post comes from a real run. +In this post you'll build a small semantic search demo end to end: a temporary [Prisma Postgres](https://www.prisma.io/docs/postgres) database spawned with `npx create-db`, a schema with a `vector` column, and a type-safe cosine similarity query written with [Prisma 8](https://www.prisma.io/docs/orm), the next-generation Prisma ORM, and its `@prisma/orm-extension-pgvector` extension pack. Every command and every output in this post comes from a real run. ## What an embedding is @@ -179,9 +179,9 @@ export default defineConfig({ Three commands take the contract from a `.prisma` file to a live, signed database: ```bash -bunx prisma@next contract emit -bunx prisma@next migration plan -bunx prisma@next db init +bunx prisma@latest contract emit +bunx prisma@latest migration plan +bunx prisma@latest db init ``` `contract emit` compiles the contract to `contract.json` plus a `contract.d.ts` where `Movie.embedding` is typed as `Vector<4>`. diff --git a/apps/blog/content/blog/you-dont-need-elasticsearch-postgres-already-has-full-text-search/index.mdx b/apps/blog/content/blog/you-dont-need-elasticsearch-postgres-already-has-full-text-search/index.mdx index b5347c091d..ccd2ad58c6 100644 --- a/apps/blog/content/blog/you-dont-need-elasticsearch-postgres-already-has-full-text-search/index.mdx +++ b/apps/blog/content/blog/you-dont-need-elasticsearch-postgres-already-has-full-text-search/index.mdx @@ -482,7 +482,7 @@ For most applications, yes. Postgres full-text search handles stemming, boolean It doesn't: stemming maps real word forms to a common stem, but a misspelling like "conection" is not a form of "connection", so the tsquery finds nothing. Pair full-text search with the `pg_trgm` extension, which measures string similarity by shared three-character trigrams. Run the full-text query first, and when it returns nothing, fall back to a trigram `similarity` query for a "did you mean" suggestion. -Yes, through the `fullTextSearchPostgres` preview feature. Enabling it in the generator block adds a `search` filter on string fields and `_relevance` ordering, which cover the common case from typed queries. The docs cover the details in [full-text search with Prisma Client](https://www.prisma.io/docs/orm/prisma-client/queries/full-text-search). For the weighted, headline-generating query this post builds, use Prisma's raw SQL escape hatch (`$queryRaw` or TypedSQL); it composes fine with the rest of your Prisma Client code. +Yes, through the `fullTextSearchPostgres` preview feature. Enabling it in the generator block adds a `search` filter on string fields and `_relevance` ordering, which cover the common case from typed queries. The docs cover the details in [full-text search with Prisma Client](https://www.prisma.io/docs/orm/v7/prisma-client/queries/full-text-search). For the weighted, headline-generating query this post builds, use Prisma's raw SQL escape hatch (`$queryRaw` or TypedSQL); it composes fine with the rest of your Prisma Client code. Full-text search matches the words a document actually contains, normalized by stemming: a search for "pooling" finds "pooled", but not "connection reuse". Vector search with pgvector matches by meaning through embeddings, so "connection reuse" can surface a pooling article that never uses those words, at the cost of running an embedding model. They compose well: full-text search for precise term matches and filters, vectors for conceptual similarity, both in the same Postgres database. diff --git a/apps/blog/public/introducing-create-prisma/imgs/hero.svg b/apps/blog/public/introducing-create-prisma/imgs/hero.svg index 275ffa9fd7..a4e320de77 100644 --- a/apps/blog/public/introducing-create-prisma/imgs/hero.svg +++ b/apps/blog/public/introducing-create-prisma/imgs/hero.svg @@ -44,7 +44,7 @@ - $ npm create prisma@latest + $ npm create prisma@stable diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md index d3c20d61b0..0c3829fc82 100644 --- a/apps/docs/AGENTS.md +++ b/apps/docs/AGENTS.md @@ -11,16 +11,16 @@ Classify every docs page as one of three kinds before writing or moving content: ## Placement rules 1. Reference material lives under `content/docs/cli/`, `content/docs/rest-api/`, or a section's `---Reference---` meta.json block. Never document flags, parameters, or endpoints in full inside a concept or guide page; link to the reference page instead. -2. A product section may keep a thin `cli-reference.mdx` pointer page that links into `cli/v8/*`. `content/docs/compute/cli-reference.mdx` is the canonical example. Full command references live in `cli/v8/`. +2. A product section may keep a thin `cli-reference.mdx` pointer page that links into `cli/*`. `content/docs/compute/cli-reference.mdx` is the canonical example. Full command references live in `cli/`; the Prisma 7 CLI is under `cli/v7/`. 3. The section is named "REST API" (folder `rest-api`). Do not reintroduce "Management API" in titles, nav, prose, or new URLs. Code identifiers (`@prisma/management-api-sdk`, `createManagementApiClient`) keep their names. 4. Sidebar grouping (Build/Deploy/Manage/Reference) is UI config in `src/lib/sidebar-sections.ts`, not content structure. Do not add grouping separators to the root `content/docs/meta.json`. ## Moving or renaming pages -1. Add a redirect in the live region of `next.config.mjs` `redirects()` (near the `/llms/next.txt` entry). Do not add entries to the commented "Prisma 8 URL cutover" staging blocks unless working on that cutover. Run `pnpm audit:redirects:strict` after. +1. Add a redirect in the live region of `next.config.mjs` `redirects()` (near the `/llms/next.txt` entry). Run `pnpm audit:redirects:strict` after. 2. Re-run `npx tsx scripts/add-url-frontmatter.ts` after any file move; the required `url:` frontmatter goes stale silently and no linter catches it. 3. New top-level sections need an entry in `llmsSections` in `src/lib/llms.ts` (see `.claude/skills/docs-agent-ready`). -4. Do not rename the `orm/`, `cli/`, or `guides/` folders or their meta.json titles, and keep `cli/v8/meta.json` title exactly `"v8 (RC)"`: `src/lib/version.ts` path maps and `src/lib/versioned-sidebar-tree.ts` match on those strings and break the version switcher silently. +4. Do not rename the `orm/`, `cli/`, or `guides/` folders or their meta.json titles, and keep the `orm/v7`, `cli/v7`, `guides/v7`, and `(index)/v7` meta.json titles exactly `"v7"`: `src/lib/version.ts` path maps and `src/lib/versioned-sidebar-tree.ts` match on those strings and break the version switcher silently. ## Generated content diff --git a/apps/docs/content/docs/(index)/full-stack-tutorial.mdx b/apps/docs/content/docs/(index)/full-stack-tutorial.mdx index 1ba867af18..f609d46b12 100644 --- a/apps/docs/content/docs/(index)/full-stack-tutorial.mdx +++ b/apps/docs/content/docs/(index)/full-stack-tutorial.mdx @@ -6,9 +6,9 @@ metaTitle: "Tutorial: the full Prisma stack" metaDescription: Scaffold an app with Prisma 8, provision Prisma Postgres, seed and query it, then deploy to Prisma Compute for a live URL. Every step verified. --- -This tutorial takes you through the whole recommended stack in one sitting: scaffold an app with [Prisma 8](/v8), store data in [Prisma Postgres](/postgres), query it over HTTP, and deploy to [Prisma Compute](/compute) for a live URL. About 15 minutes. +This tutorial takes you through the whole recommended stack in one sitting: scaffold an app with [Prisma 8](/prisma-orm), store data in [Prisma Postgres](/postgres), query it over HTTP, and deploy to [Prisma Compute](/compute) for a live URL. About 15 minutes. -It uses the `hono` template so you get a small API you can verify with curl at every step. The same journey works for the other templates; the [framework guides](/guides/v8) cover each one. +It uses the `hono` template so you get a small API you can verify with curl at every step. The same journey works for the other templates; the [framework guides](/guides) cover each one. ## Prerequisites @@ -99,7 +99,7 @@ curl http://localhost:3000/users ] ``` -The route handler in `src/index.ts` is ordinary Hono code calling an ordinary Prisma 8 query. Change the starter contract in `src/prisma/` when you are ready to model your own data; the [fundamentals](/orm/v8/fundamentals/reading-data) cover the query patterns. +The route handler in `src/index.ts` is ordinary Hono code calling an ordinary Prisma 8 query. Change the starter contract in `src/prisma/` when you are ready to model your own data; the [fundamentals](/orm/fundamentals/reading-data) cover the query patterns. ## 4. Deploy to Prisma Compute @@ -135,7 +135,7 @@ The same three users come back, now served from production next to your database ## Next steps -- [Pick your framework](/guides/v8): the same journey for Next.js, Nuxt, Astro, NestJS, TanStack Start, and more. +- [Pick your framework](/guides): the same journey for Next.js, Nuxt, Astro, NestJS, TanStack Start, and more. - [Branching and previews](/compute/branching): every Git branch gets an isolated deployment. -- [Learn the fundamentals](/orm/v8/fundamentals/reading-data): reading, writing, relations, and transactions. +- [Learn the fundamentals](/orm/fundamentals/reading-data): reading, writing, relations, and transactions. - [Deploy on push](/compute/github): connect GitHub so every commit deploys itself. diff --git a/apps/docs/content/docs/(index)/getting-started.mdx b/apps/docs/content/docs/(index)/getting-started.mdx index b8def7cd09..3ed34beb71 100644 --- a/apps/docs/content/docs/(index)/getting-started.mdx +++ b/apps/docs/content/docs/(index)/getting-started.mdx @@ -1,78 +1,86 @@ --- -title: Prisma 7 setup paths -description: Choose the fastest path to start using Prisma ORM 7, Prisma Postgres, or Prisma Compute in a new or existing TypeScript project. +title: Choose a Prisma 8 setup path +description: Choose the fastest path to try Prisma 8 in a new or existing project. url: /getting-started -metaTitle: Prisma 7 getting started -metaDescription: Choose the fastest Prisma 7 setup path. Quickstarts and existing-project guides for Prisma ORM 7, Prisma Postgres, and Prisma Compute, plus an agent prompt. +metaTitle: Prisma 8 getting started +metaDescription: Choose a Prisma 8 quickstart for a new project or add Prisma 8 to an existing app. --- -Prisma 7 is the current generally available release of Prisma ORM. Scaffold a new Prisma 7 app with `npx create-prisma@stable`, or add it to an existing project with `npx prisma@latest init`. This page collects the Prisma 7 starting points: start a new project, add Prisma to an existing one, then deploy. - -:::note - -Starting a new project? [Prisma 8](/v8) is the recommended path for new apps. It is the next major version of Prisma ORM, now available as a Release Candidate. To start with Prisma 8, see the [getting started page](/). - -::: +Start with a quickstart if you want Prisma 8 to create the app. Use the existing-project path if you already have an app and database. ## Start a new project -The recommended path is the [Quickstart with Prisma Postgres](/prisma-orm/quickstart/prisma-postgres): it provisions a managed PostgreSQL database for you and gets you from install to first query in about five minutes. +```npm +npx create-prisma@latest +``` -Working with a specific database instead? +The [create-prisma reference](/prisma-orm/create-prisma) lists every template and flag. -- [Quickstart with PostgreSQL](/prisma-orm/quickstart/postgresql) -- [Quickstart with SQLite](/prisma-orm/quickstart/sqlite) for a lightweight local setup -- [Quickstart with MySQL](/prisma-orm/quickstart/mysql) -- [Quickstart with MongoDB](/prisma-orm/quickstart/mongodb) + + }> + 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 replica set, apply the first migration, and run the first query. + + -## Add Prisma to an existing project + -Use these guides if you already have an application or database and want to add Prisma ORM: +```text +Create a new [framework] application with Prisma 8, seed it, and run it locally. -- [Add Prisma ORM to an existing PostgreSQL project](/prisma-orm/add-to-existing-project/postgresql) -- [Add Prisma ORM to an existing MySQL project](/prisma-orm/add-to-existing-project/mysql) -- [Add Prisma ORM to an existing SQLite project](/prisma-orm/add-to-existing-project/sqlite) -- [Add Prisma ORM to an existing MongoDB project](/prisma-orm/add-to-existing-project/mongodb) -- [Add Prisma ORM to an existing Prisma Postgres project](/prisma-orm/add-to-existing-project/prisma-postgres) +If I have not told you which framework, stop and ask before scaffolding. Valid --template values: next, hono, nuxt, astro, nest, svelte, tanstack-start, elysia. -## Deploy to Prisma Compute +1. Scaffold the app: `npx create-prisma@latest create my-app --template [framework] --provider postgres --yes`. +2. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `npx create-db@latest` and show me the claim URL it prints. Export it as `DATABASE_URL` in the shell; the generated scripts read the environment variable, not `.env`. +3. From the project directory, apply the starter contract: `npm run db:init`. Sample users are seeded automatically on the app's first query; there is no separate seed script. +4. Edit the starter contract under `src/prisma/` into a small schema for my use case, then run `npm run contract:emit` and plan and apply the migration: `npx prisma@latest migration plan`, then `npx prisma@latest migrate --yes`. Migration planning diffs the emitted contract, so the emit step is required. +5. Update the seed script under `src/prisma/` and the app routes to query the new schema, start `npm run dev` in the background (with `DATABASE_URL` exported), and verify with a request against the running app. For the `nest` template, if routes return 500s with `reading 'findAll'` in the logs, add explicit `@Inject()` tokens as shown in https://www.prisma.io/docs/guides/frameworks/nestjs.md. -Once your app runs locally, [Prisma Compute](/compute) (currently in Public Beta) runs it next to your Prisma Postgres database: +Use the installed Prisma 8 skills and the current Prisma docs: https://www.prisma.io/docs/llms.txt (append `.md` to any docs URL for a markdown version). +``` -1. Sign in with `npx @prisma/cli@latest auth login`. -2. Run `npx @prisma/cli@latest app deploy` from your app directory to get a live URL, adding `--env .env` so environment variables like `DATABASE_URL` reach the deployment. -3. `--env .env` applies to that one deployment. Persist variables for future deployments with `npx @prisma/cli@latest project env add --file .env --role production`. See [environment variables](/compute/environment-variables). -4. Keep deploying from the CLI, or [connect GitHub](/compute/github) to deploy on push. + -`app deploy` is part of the earlier beta CLI (`@prisma/cli@latest`). The Prisma 8 RC CLI (`prisma@next`) that the [Compute docs](/compute) describe deploys through a git push, the Console, or [Prisma Composer](/composer) instead. Both CLIs talk to the same platform. For the git-push path, follow the [deploy quickstart](/prisma-compute/deploy). +## Add to an existing project -## Use with your agent +```npm +npx prisma@latest orm init +``` -To hand the full Prisma 7 stack to your coding agent, copy this prompt. The commands below install Prisma 7, not Prisma 8: + + }> + Add Prisma 8 to an existing PostgreSQL app and infer a starter contract from the live schema. + + }> + Add Prisma 8 to an existing MongoDB app and model the collections you want to query first. + + ```text -Set up the Prisma 7 stack: Prisma ORM 7, Prisma Postgres, and Prisma Compute. +Add Prisma 8 to this existing project. -If I have not told you which framework template to use, stop and ask. +This flow is for PostgreSQL. If the project uses MongoDB, follow https://www.prisma.io/docs/prisma-orm/add-to-existing-project/mongodb.md instead; for other databases, stop and tell me. -1. Scaffold a new app non-interactively: `npx create-prisma@stable --name my-app --template [next|hono|nuxt|astro|nest|svelte|tanstack-start|elysia|turborepo] --provider postgresql --no-deploy`. Or add Prisma 7 to an existing app with `npx prisma@latest init --db`, which provisions a Prisma Postgres database; before that, check `npx @prisma/cli@latest auth whoami` and stop and ask me to run `auth login` if I am not signed in, because provisioning can open a browser. -2. From the project directory, define a small schema in `prisma/schema.prisma`, then run `npx prisma migrate dev --name init` and `npx prisma generate`. If migrate dev asks to reset the database, stop and ask me first. -3. Update the seed and app code to query the schema, and verify locally with the dev script. -4. Deploy with Prisma Compute: check `npx @prisma/cli@latest auth whoami` first. If I am not signed in, stop and ask me to run `npx @prisma/cli@latest auth login`, because that step opens a browser. Then run `npx @prisma/cli@latest app deploy --create-project my-app --env .env` so DATABASE_URL reaches the deployment, and verify the deployed URL with curl. +1. Run `npx prisma@latest orm init`. It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs Prisma 8 skills for you. +2. Set `DATABASE_URL` in `.env` to my database. If I did not give you one, create a Prisma Postgres database with `npx create-db@latest`, put its connection string in `.env`, and show me the claim URL it prints so I can keep the database. +3. If the database already has tables, infer the contract from it: `npx prisma@latest contract infer`, then `npx prisma@latest contract emit`, then sign it with `npx prisma@latest db sign`. If the database is empty, keep the starter contract and run `npx prisma@latest db init`. +4. Write one query with the generated `db` client in an existing code path, run it, and show me the returned rows. -Current docs: https://www.prisma.io/docs/getting-started.md and https://www.prisma.io/docs/llms.txt. +Follow https://www.prisma.io/docs/prisma-orm/add-to-existing-project/postgresql.md and the installed Prisma 8 skills. ``` -## Next steps - -After setup, these pages are usually the next ones people need: +## After setup -- [Prisma Client overview](/orm/prisma-client) -- [Prisma Migrate getting started](/orm/prisma-migrate/getting-started) -- [Prisma schema overview](/orm/prisma-schema/overview) -- [Open Prisma Studio](/studio/getting-started) to inspect and edit data visually -- [Review pricing](https://www.prisma.io/pricing) if you're evaluating Prisma Postgres for a team +- Use the generated app scripts for the first run. +- Open `prisma-next.md` or the installed Prisma 8 skills when you want agent-ready guidance inside the project. +- Change the starter contract when you are ready to model your own data. +- Open the [Prisma 8 overview](/orm) when you want the concepts behind the setup. diff --git a/apps/docs/content/docs/(index)/index.mdx b/apps/docs/content/docs/(index)/index.mdx index 617884f6cc..3d758af604 100644 --- a/apps/docs/content/docs/(index)/index.mdx +++ b/apps/docs/content/docs/(index)/index.mdx @@ -8,7 +8,7 @@ full: true -Prisma is a complete TypeScript stack with one workflow: **build** your app and run all of it on your machine, then **deploy** it to the Prisma platform with one command. Jump straight to the [full-stack tutorial](/full-stack-tutorial), [Prisma 8](/v8) or [Prisma 7](/getting-started) docs. +Prisma is a complete TypeScript stack with one workflow: **build** your app and run all of it on your machine, then **deploy** it to the Prisma platform with one command. Jump straight to the [full-stack tutorial](/full-stack-tutorial), [Prisma 8](/getting-started) or [Prisma 7](/v7/getting-started) docs. @@ -38,8 +38,8 @@ Prisma is a complete TypeScript stack with one workflow: **build** your app and - - One CLI serves the whole stack: `npx prisma@next` drives the ORM and the Prisma platform, from migrations and local dev to deploys, databases, and buckets, for you and your coding agent. + + One CLI serves the whole stack: `npx prisma@latest` drives the ORM and the Prisma platform, from migrations and local dev to deploys, databases, and buckets, for you and your coding agent. @@ -47,27 +47,27 @@ Prisma is a complete TypeScript stack with one workflow: **build** your app and - - - - - - - - - - + + + + + + + + + + -If you're using Express or another Node.js server, follow the [existing-project path](/v8/add-to-existing-project/postgresql) instead. +If you're using Express or another Node.js server, follow the [existing-project path](/prisma-orm/add-to-existing-project/postgresql) instead. - + - } /> - } /> + } /> + } /> @@ -84,24 +84,24 @@ If you're using Express or another Node.js server, follow the [existing-project icon={} > -}> +}> ```text Add Prisma 8 to this existing project. -This flow is for PostgreSQL. If the project uses MongoDB, follow https://www.prisma.io/docs/v8/add-to-existing-project/mongodb.md instead; for other databases, stop and tell me. +This flow is for PostgreSQL. If the project uses MongoDB, follow https://www.prisma.io/docs/prisma-orm/add-to-existing-project/mongodb.md instead; for other databases, stop and tell me. -1. Run `npx prisma@next orm init`. It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs Prisma 8 skills for you. +1. Run `npx prisma@latest orm init`. It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs Prisma 8 skills for you. 2. Set `DATABASE_URL` in `.env` to my database. If I did not give you one, create a Prisma Postgres database with `npx create-db@latest`, put its connection string in `.env`, and show me the claim URL it prints so I can keep the database. -3. If the database already has tables, infer the contract from it: `npx prisma@next contract infer`, then `npx prisma@next contract emit`, then sign it with `npx prisma@next db sign`. If the database is empty, keep the starter contract and run `npx prisma@next db init`. +3. If the database already has tables, infer the contract from it: `npx prisma@latest contract infer`, then `npx prisma@latest contract emit`, then sign it with `npx prisma@latest db sign`. If the database is empty, keep the starter contract and run `npx prisma@latest db init`. 4. Write one query with the generated `db` client in an existing code path, run it, and show me the returned rows. -Follow https://www.prisma.io/docs/v8/add-to-existing-project/postgresql.md and the installed Prisma 8 skills. +Follow https://www.prisma.io/docs/prisma-orm/add-to-existing-project/postgresql.md and the installed Prisma 8 skills. ``` -}> +}> ```text Create a new [framework] application with Prisma 8 against my existing PostgreSQL database. @@ -110,25 +110,25 @@ If I have not given you a connection string, stop and ask; do not invent one. Va 1. Scaffold: `npx create-prisma@latest create my-app --template [framework] --provider postgres --yes`. 2. Export my connection string as `DATABASE_URL` in the shell; the generated scripts read the environment variable, not `.env`. From the project directory: `npm run db:init`, then start `npm run dev` in the background and verify the sample query returns data. Sample users are seeded automatically on the app's first query; there is no separate seed script. -3. Evolve the starter contract under `src/prisma/` into my schema, then run `npm run contract:emit`, `npx prisma@next migration plan`, and `npx prisma@next migrate --yes`. +3. Evolve the starter contract under `src/prisma/` into my schema, then run `npm run contract:emit`, `npx prisma@latest migration plan`, and `npx prisma@latest migrate --yes`. Do not provision any hosted database. Use the installed Prisma 8 skills and https://www.prisma.io/docs/llms.txt for current docs. ``` -}> +}> ```text Add Prisma ORM 7 to this project with my existing database. If I have not given you a database connection string and none exists in the project, stop and ask. -1. Run `npx prisma@latest init` (Prisma 7). For an existing database, set DATABASE_URL in `.env` and introspect it with `npx prisma db pull`; for a new schema, define models in `prisma/schema.prisma` and run `npx prisma migrate dev --name init`. If migrate dev asks to reset the database, stop and ask me first. +1. Run `npx prisma@7.9.1 init` (Prisma 7). For an existing database, set DATABASE_URL in `.env` and introspect it with `npx prisma db pull`; for a new schema, define models in `prisma/schema.prisma` and run `npx prisma migrate dev --name init`. If migrate dev asks to reset the database, stop and ask me first. 2. Install the driver adapter for the database (Prisma 7 requires one), e.g. `npm install @prisma/adapter-pg` for PostgreSQL, and pass it to `new PrismaClient({ adapter })`. Generate the client with `npx prisma generate` and write one query in an existing code path. 3. Run the query (e.g. with `npx tsx`) and show me the output, the schema, and the query you added. -Current docs: https://www.prisma.io/docs/orm.md and https://www.prisma.io/docs/llms.txt. +Current docs: https://www.prisma.io/docs/orm/v7.md and https://www.prisma.io/docs/llms.txt. ``` @@ -163,7 +163,7 @@ Current docs: https://www.prisma.io/docs/prisma-compute/deploy.md. -If you're using MongoDB, follow the [MongoDB quickstart](/v8/quickstart/mongodb) or [add Prisma 8 to an existing MongoDB app](/v8/add-to-existing-project/mongodb). If you work with [Kysely](/prisma-postgres/quickstart/kysely), [Drizzle](/prisma-postgres/quickstart/drizzle-orm), or [TypeORM](/prisma-postgres/quickstart/typeorm), follow the Prisma Postgres quickstart for that tool. +If you're using MongoDB, follow the [MongoDB quickstart](/prisma-orm/quickstart/mongodb) or [add Prisma 8 to an existing MongoDB app](/prisma-orm/add-to-existing-project/mongodb). If you work with [Kysely](/prisma-postgres/quickstart/kysely), [Drizzle](/prisma-postgres/quickstart/drizzle-orm), or [TypeORM](/prisma-postgres/quickstart/typeorm), follow the Prisma Postgres quickstart for that tool. @@ -172,7 +172,7 @@ If you're using MongoDB, follow the [MongoDB quickstart](/v8/quickstart/mongodb) - } /> + } /> } /> } /> } /> diff --git a/apps/docs/content/docs/(index)/meta.json b/apps/docs/content/docs/(index)/meta.json index 63a4b9018f..d6581dd01e 100644 --- a/apps/docs/content/docs/(index)/meta.json +++ b/apps/docs/content/docs/(index)/meta.json @@ -4,18 +4,14 @@ "pages": [ "---Start---", "index", - "prisma-compute/deploy", - "full-stack-tutorial", - "---Prisma 8---", - "v8/index", - "v8/getting-started", - "v8/quickstart", - "v8/add-to-existing-project", - "v8/prisma-postgres", - "---Prisma 7---", "getting-started", + "full-stack-tutorial", + "prisma-compute/deploy", + "---Prisma ORM---", "...prisma-orm", "---Prisma Postgres---", - "...prisma-postgres" + "...prisma-postgres", + "---Prisma 7---", + "v7" ] } diff --git a/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx b/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx index 81c3d00424..42115d10c4 100644 --- a/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx +++ b/apps/docs/content/docs/(index)/prisma-compute/deploy.mdx @@ -92,7 +92,7 @@ Now run the app on your machine. No account or credentials are involved: ```npm npm run build -npx prisma@next composer dev module.ts +npx prisma@latest composer dev module.ts ``` `composer dev` prints the service's local URL; `curl` it and you get `Hello from Prisma Compute`. See [Local development](/local-development) for the local database, storage, and log workflow. @@ -113,7 +113,7 @@ Verify the port before deploying by running it locally: ```npm npm run build -npx prisma@next composer dev module.ts +npx prisma@latest composer dev module.ts ``` Every service should appear in the startup output with a local URL. Then continue to [Deploy](#2-deploy). @@ -123,7 +123,7 @@ Every service should appear in the startup output with a local URL. Then continu Sign in once. This is the only interactive step, because it opens your browser: ```npm -npx prisma@next auth login +npx prisma@latest auth login ``` The session is stored on your machine and every later command reads it, including commands a coding agent runs in your directory. Confirm it any time with `auth whoami`. In CI or a headless environment, set `PRISMA_SERVICE_TOKEN` and `PRISMA_WORKSPACE_ID` instead; see [Deploying](/composer/deploying#credentials). @@ -132,7 +132,7 @@ The session is stored on your machine and every later command reads it, includin ```npm npm run build -npx prisma@next composer deploy module.ts +npx prisma@latest composer deploy module.ts ``` The CLI creates a project named after your root module, provisions the services on Compute and any databases on Prisma Postgres, wires the dependencies, and starts everything. @@ -160,10 +160,10 @@ You can also inspect everything in the [Console](https://pris.ly/pdp): projects, Re-deploying is idempotent: build again, deploy again, and the platform applies the difference instead of recreating everything. Production and previews are separated by stages: ```npm -npx prisma@next composer deploy module.ts # production -npx prisma@next composer deploy module.ts --stage staging # a persistent staging environment -npx prisma@next composer deploy module.ts --stage pr-42 # one environment per PR -npx prisma@next composer destroy module.ts --stage pr-42 # tear the environment down +npx prisma@latest composer deploy module.ts # production +npx prisma@latest composer deploy module.ts --stage staging # a persistent staging environment +npx prisma@latest composer deploy module.ts --stage pr-42 # one environment per PR +npx prisma@latest composer destroy module.ts --stage pr-42 # tear the environment down ``` A stage is a complete, isolated copy of the app: its own services, databases, and configuration, sharing only the code with production. In platform terms it is a [preview branch](/compute/branching) of the same project. See [Deploying](/composer/deploying) for CI, deploy state, and teardown in full. @@ -173,14 +173,14 @@ A stage is a complete, isolated copy of the app: its own services, databases, an You can let a coding agent do the work. Sign in once yourself ([step 2](#2-deploy)). The browser sign-in is the one step an agent can't do for you. After that, anything running in your environment inherits the session, including your agent. Paste this into your agent and fill in the blanks: ```text -Build [what you want] as a Prisma Composer app and deploy it to Prisma Compute using `npx prisma@next`. +Build [what you want] as a Prisma Composer app and deploy it to Prisma Compute using `npx prisma@latest`. Notes: - First install the Composer skill so you use the real API: `npx skills add prisma/composer`. -- Before deploying, run `npx prisma@next auth whoami`; if I am not signed in, stop and ask me to run `npx prisma@next auth login` (it opens a browser). +- Before deploying, run `npx prisma@latest auth whoami`; if I am not signed in, stop and ask me to run `npx prisma@latest auth login` (it opens a browser). - Composer needs Node.js 22.18 or newer, and server code targets Bun. Read the port with `service.port()` and bind 0.0.0.0. For a Next.js service, use the nextjs build adapter and set `output: "standalone"`. -- Composer does not build; produce one self-contained entry file per service (for example `bun build --target=bun`), then run it locally with `npx prisma@next composer dev module.ts` and verify each service's local URL responds. -- Deploy with `npx prisma@next composer deploy module.ts` and verify the printed public URL with curl. +- Composer does not build; produce one self-contained entry file per service (for example `bun build --target=bun`), then run it locally with `npx prisma@latest composer dev module.ts` and verify each service's local URL responds. +- Deploy with `npx prisma@latest composer deploy module.ts` and verify the printed public URL with curl. - To give a service a database, declare `deps: { db: postgres() }` and build the client from the injected `db.url`; do not read connection strings from process.env. - Current docs: https://www.prisma.io/docs/composer.md and https://www.prisma.io/docs/prisma-compute/deploy.md ``` @@ -188,7 +188,7 @@ Notes: For example: ```text -Build a Bun API with a /todos endpoint backed by an in-memory list as a Prisma Composer app and deploy it to Prisma Compute using `npx prisma@next`. +Build a Bun API with a /todos endpoint backed by an in-memory list as a Prisma Composer app and deploy it to Prisma Compute using `npx prisma@latest`. ``` ## What's next 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 index d0d0a4e667..84c814653c 100644 --- 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 @@ -1,13 +1,4 @@ { "title": "Add to Existing Project", - "pages": [ - "prisma-postgres", - "sqlite", - "postgresql", - "mysql", - "sql-server", - "planetscale", - "cockroachdb", - "mongodb" - ] + "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 2a5fc660c0..10e121f29b 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,326 +1,174 @@ --- title: MongoDB -description: Add Prisma ORM to an existing TypeScript project with MongoDB and learn database introspection and querying +description: Add Prisma 8 to an existing MongoDB project. url: /prisma-orm/add-to-existing-project/mongodb -metaTitle: How to add Prisma ORM to an existing project using MongoDB (15 min) -metaDescription: Add Prisma ORM to an existing TypeScript project with MongoDB and learn database introspection and querying. +metaTitle: Add Prisma 8 to an existing MongoDB project +metaDescription: Add Prisma 8 to an existing MongoDB project. --- -[MongoDB](https://www.mongodb.com/) is a popular document-based NoSQL database known for its flexibility, scalability, and developer-friendly features. In this guide, you will learn how to add Prisma ORM to an existing TypeScript project, connect it to MongoDB, introspect your existing database schema, and start querying with type-safe Prisma Client. +To add Prisma 8 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. -:::warning[MongoDB support for Prisma ORM v7] +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 24 or newer. If you want Prisma 8 to create a new app for you, use the [MongoDB quickstart](/prisma-orm/quickstart/mongodb). -**MongoDB support for Prisma ORM v7 is coming in the near future.** In the meantime, please use **Prisma ORM v6.19** (the latest v6 release) when working with MongoDB. +:::note[Using Prisma 7?] -This guide uses Prisma ORM v6.19 to ensure full compatibility with MongoDB. +Prisma 8 is the current release of Prisma ORM. Prisma 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). ::: -:::tip +For local development, use a replica set. MongoDB Atlas already gives you that. -If you're migrating to Prisma ORM from Mongoose, see our [Migrate from Mongoose guide](/guides/switch-to-prisma-orm/from-mongoose). +## 1. Make sure you can run the example script -::: - -## Prerequisites - -In order to successfully complete this guide, you need: - -- [Node.js](https://nodejs.org/en/) installed on your machine (see [system requirements](/guides/upgrade-prisma-orm/v6#minimum-supported-nodejs-versions) for officially supported versions) -- An existing TypeScript project with a `package.json` file -- Access to a MongoDB 4.2+ server with a replica set deployment. We recommend using [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). - -:::warning - -The MongoDB database connector uses transactions to support nested writes. Transactions **require** a [replica set](https://www.mongodb.com/docs/manual/tutorial/deploy-replica-set/) deployment. The easiest way to deploy a replica set is with [Atlas](https://www.mongodb.com/docs/atlas/getting-started/). It's free to get started. - -::: - -Make sure you have your database [connection URL](/orm/reference/connection-urls) (that includes your authentication credentials) at hand! - -:::note - -If your project contains multiple directories with `package.json` files (e.g., `frontend`, `backend`, etc.), note that Prisma ORM is specifically designed for use in the API/backend layer. To set up Prisma, navigate to the appropriate backend directory containing the relevant `package.json` file and configure Prisma there. +If your project already runs TypeScript scripts, you can skip this step. -::: - -## 1. Set up Prisma ORM - -Navigate to your existing project directory and install the required dependencies: +Otherwise, install the script tooling: ```npm -npm install prisma@6.19 @types/node --save-dev -npm install @prisma/client@6.19 dotenv +npm install --save-dev tsx typescript ``` -Here's what each package does: +Later, `orm init` will also add the Node.js types it needs and make sure the generated Prisma 8 files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma 8 leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app. -- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db pull`, and `prisma generate` -- **`@prisma/client`** - The Prisma Client library for querying your database -- **`dotenv`** - Loads environment variables from your `.env` file +## 2. Initialize Prisma 8 -:::info[Why Prisma v6.19?] - -This is the latest stable version of Prisma ORM v6 that fully supports MongoDB. MongoDB support for Prisma ORM v7 is coming soon. - -You can also install `prisma@6` and `@prisma/client@6` to automatically get the latest v6 release. - -::: - -## 2. Initialize Prisma ORM - -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +From the root of your existing project, run: ```npm -npx prisma init --datasource-provider mongodb --output ../generated/prisma +npx prisma@latest orm init --target mongodb ``` -This command does a few things: +This is the existing-project path. It preselects MongoDB, adds Prisma 8 files and package scripts to the app you already have, and does not scaffold a new framework project. -- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection configuration -- Creates a `.env` file in the root directory for environment variables -- Creates a `prisma.config.ts` file for Prisma configuration +It also adds `prisma-next.md` and project-level Prisma 8 skills for Cursor, Claude Code, Codex, and Windsurf so your agent can read the Prisma 8 usage, upgrade, and extension-author guidance from the project. -The generated `prisma.config.ts` file looks like this: +When Prisma 8 asks the remaining setup questions: -```typescript title="prisma.config.ts" -import { defineConfig, env } from "prisma/config"; +- choose `PSL` +- keep the default schema path, `prisma/contract.prisma` -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - engine: "classic", - datasource: { - url: env("DATABASE_URL"), - }, -}); -``` +## 3. Set your database connection string -Add `dotenv` to `prisma.config.ts` so that Prisma can load environment variables from your `.env` file: - -```typescript title="prisma.config.ts" -import "dotenv/config"; // [!code ++] -import { defineConfig, env } from "prisma/config"; - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - engine: "classic", - datasource: { - url: env("DATABASE_URL"), - }, -}); -``` - -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: - -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} - -datasource db { - provider = "mongodb" - url = env("DATABASE_URL") -} -``` - -## 3. Connect your database - -Update the `.env` file with your MongoDB connection URL: +Update `.env` with the connection string for the MongoDB deployment your app already uses: ```text title=".env" -DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/mydb" +DATABASE_URL="mongodb://127.0.0.1:27017/app?replicaSet=rs0" ``` -For MongoDB Atlas, the connection URL format is: +## 4. Describe the collections you want Prisma 8 to know about -``` -mongodb+srv://USERNAME:PASSWORD@CLUSTER.mongodb.net/DATABASE -``` - -Self-hosted MongoDB connection URL format: - -``` -mongodb://USERNAME:PASSWORD@HOST:PORT/DATABASE -``` +This is the key adoption step for MongoDB, because you decide which part of the existing database Prisma 8 should model first. -Connection URL components: +PostgreSQL has `contract infer`. MongoDB does not, so this step is manual. -- **`USERNAME`**: Your database user name -- **`PASSWORD`**: Your database user password -- **`HOST`**: The host where [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod/#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos/#mongodb-binary-bin.mongos) is running -- **`PORT`**: The port where your database server is running (typically `27017`) -- **`DATABASE`**: The name of your database +Open `prisma/contract.prisma` and make it match the collections you want Prisma 8 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: -:::tip +```prisma title="prisma/contract.prisma" +// use prisma-next -For MongoDB Atlas, you can manually append the database name to the connection URL, as Atlas doesn't include it by default. +model User { + id ObjectId @id @map("_id") + email String @unique + name String? + posts Post[] + @@map("users") +} -::: +model Post { + id ObjectId @id @map("_id") + title String + content String? + author User @relation(fields: [authorId], references: [id]) + authorId ObjectId + @@map("posts") +} +``` -### Troubleshooting connection issues +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. -- **Authentication failed** — If you see a `SCRAM failure: Authentication failed` error, [add `?authSource=admin`](https://github.com/prisma/prisma/discussions/9994#discussioncomment-1562283) to the end of your connection string. -- **Empty database name** — If you see an `Error code 8000 (AtlasError): empty database name not allowed` error, append the database name to your connection URL. See this [GitHub issue](https://github.com/prisma/web/issues/5562) for details. +## 5. Emit the generated artifacts -## 4. Introspect your database +Once the contract looks right, this step turns it into the generated files the runtime and query APIs use. -Run the following command to introspect your existing database: +Run: ```npm -npx prisma db pull +npx prisma@latest contract emit ``` -This command: +This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed. -- Reads the `DATABASE_URL` from your `.env` file -- Connects to your MongoDB database -- Samples documents in your collections to infer the schema -- Generates Prisma models in your `schema.prisma` file +## 6. Run a simple high-level query -![Introspect your database with Prisma ORM](/img/getting-started/prisma-db-pull-generate-schema.png) +With the emitted artifacts in place, you can test the higher-level API first and confirm Prisma 8 can read the existing collections. -:::info +Create a `script.ts` file: -**MongoDB introspection limitations:** Prisma introspects MongoDB by sampling documents. You may need to manually: +```typescript title="script.ts" +import "dotenv/config"; +import { db } from "./prisma/db"; -- Add relation fields using the `@relation` attribute -- Adjust field types if the sampling didn't capture all variations -- Add indexes and constraints not detected during introspection +async function main() { + const user = await db.orm.users.where({ email: "existing@example.com" }).first(); + console.log(user); -::: + await db.close(); +} -## 5. Generate Prisma ORM types +main().catch((error) => { + console.error(error); + process.exit(1); +}); +``` -Generate Prisma Client based on your introspected schema: +Run it: ```npm -npx prisma generate +npx tsx script.ts ``` -This creates a type-safe Prisma Client tailored to your database schema in the `generated/prisma` directory. +## 7. Run a simple low-level query -## 6. Instantiate Prisma Client +After the ORM example, this step shows the lower-level MongoDB pipeline builder against the same existing collections. -Create a utility file to instantiate Prisma Client: +Replace `script.ts` with this version: -```typescript title="lib/prisma.ts" +```typescript title="script.ts" import "dotenv/config"; -import { PrismaClient } from "../generated/prisma/client"; - -const prisma = new PrismaClient(); - -export { prisma }; -``` +import { db } from "./prisma/db"; -## 7. Query your database - -Now you can use Prisma Client to query your database. Create a `script.ts` file: +async function main() { + const runtime = await db.runtime(); + const plan = db.query + .from("users") + .match((fields) => fields.email.eq("existing@example.com")) + .project("email", "name") + .build(); -```typescript title="script.ts" -import { prisma } from "./lib/prisma"; + const rows = await runtime.execute(plan); + console.log(rows); -async function main() { - // Example: Fetch all records from a collection - // Replace 'user' with your actual model name - const allUsers = await prisma.user.findMany(); - console.log("All users:", JSON.stringify(allUsers, null, 2)); + await db.close(); } -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); +main().catch((error) => { + console.error(error); + process.exit(1); +}); ``` -Run the script: +Run it again: ```npm npx tsx script.ts ``` -## 8. Evolve your schema - -MongoDB doesn't support migrations like relational databases. Instead, use `db push` to sync schema changes: - -### 8.1. Update your Prisma schema file - -Modify your Prisma schema file with the changes you want. For example, add a new model: - -```prisma title="prisma/schema.prisma" -model Post { // [!code ++] - id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] - title String // [!code ++] - content String? // [!code ++] - published Boolean @default(false) // [!code ++] - authorId String @db.ObjectId // [!code ++] - author User @relation(fields: [authorId], references: [id]) // [!code ++] -} // [!code ++] - -model User { // [!code ++] - id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] - email String @unique // [!code ++] - name String? // [!code ++] - posts Post[] // [!code ++] -} // [!code ++] -``` - -:::info - -In MongoDB, the `id` field is mapped to `_id` and uses `@db.ObjectId` type. Relations use `String` type with `@db.ObjectId` annotation. +## 8. Next steps -::: - -### 8.2. Push the changes to your database +When you change `prisma/contract.prisma`, emit the contract again: ```npm -npx prisma db push +npx prisma@latest contract emit ``` -This command: - -- Applies schema changes to your MongoDB database -- Automatically regenerates Prisma Client - -:::info[Why `db push` instead of migrations?] - -MongoDB uses a flexible schema model. Prisma Migrate (which creates migration files) is not supported for MongoDB. Always use `prisma db push` to sync your schema changes. - -::: - -## 9. Explore your data - -You can use [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), the MongoDB shell, or MongoDB Compass to view and manage your data. - -:::warning - -[Prisma Studio](/studio) does not currently support MongoDB. Support may be added in a future release. See [Databases supported by Prisma Studio](/studio#supported-databases) for more information. - -::: - -## Next steps - -You've successfully set up Prisma ORM. Here's what you can explore next: - -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more -- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) - -## More info - -- [MongoDB database connector](/orm/core-concepts/supported-databases/mongodb) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) +You do not need a migration just to read collections that already exist. Use [migration plan](/cli/migration-plan) when you want Prisma 8 to own a schema change. 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 9490cc72a9..1f4e5f4c25 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,246 +1,174 @@ --- title: PostgreSQL -description: 'Add Prisma ORM to an existing TypeScript project with PostgreSQL and learn database introspection, baselining, and querying' +description: Add Prisma 8 to an existing PostgreSQL project. url: /prisma-orm/add-to-existing-project/postgresql -metaTitle: How to add Prisma ORM to an existing project using PostgreSQL (15 min) -metaDescription: 'Add Prisma ORM to an existing TypeScript project with PostgreSQL and learn database introspection, baselining, and querying.' +metaTitle: Add Prisma 8 to an existing PostgreSQL project +metaDescription: Add Prisma 8 to an existing PostgreSQL project. --- -[PostgreSQL](https://www.postgresql.org/) is a popular open-source relational database known for its reliability, feature robustness, and performance. In this guide, you will learn how to add Prisma ORM to an existing TypeScript project, connect it to PostgreSQL, introspect your existing database schema, and start querying with type-safe Prisma Client. +To add Prisma 8 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. -## Prerequisites +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 24 or newer. If you want Prisma 8 to create a new app for you, use the [PostgreSQL quickstart](/prisma-orm/quickstart/postgresql). -## 1. Set up Prisma ORM +:::note[Using Prisma 7?] -Navigate to your existing project directory and install the required dependencies: +Prisma 8 is the current release of Prisma ORM. Prisma 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). -```npm -npm install prisma @types/node @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv -``` - -Here's what each package does: +::: -- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db pull`, and `prisma generate` -- **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database -- **`pg`** - The node-postgres database driver -- **`@types/pg`** - TypeScript type definitions for node-postgres -- **`dotenv`** - Loads environment variables from your `.env` file +## 1. Make sure you can run the example script -## 2. Initialize Prisma ORM +If your project already runs TypeScript scripts, you can skip this step. -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Otherwise, install the script tooling: ```npm -npx prisma init --datasource-provider postgresql --output ../generated/prisma +npm install --save-dev tsx typescript ``` -This command does a few things: +Later, `orm init` will also add the Node.js types it needs and make sure the generated Prisma 8 files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma 8 leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app. -- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection configuration -- Creates a `.env` file in the root directory for environment variables -- Creates a `prisma.config.ts` file for Prisma configuration +## 2. Initialize Prisma 8 -The generated `prisma.config.ts` file looks like this: +From the root of your existing project, run: -```typescript title="prisma.config.ts" -import "dotenv/config"; -import { defineConfig, env } from "prisma/config"; - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - datasource: { - url: env("DATABASE_URL"), - }, -}); +```npm +npx prisma@latest orm init --target postgres ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +This is the existing-project path. It preselects PostgreSQL, adds Prisma 8 files and package scripts to the app you already have, and does not scaffold a new framework project. -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} +It also adds `prisma-next.md` and project-level Prisma 8 skills for Cursor, Claude Code, Codex, and Windsurf so your agent can read the Prisma 8 usage, upgrade, and extension-author guidance from the project. -datasource db { - provider = "postgresql" -} -``` +When Prisma 8 asks the remaining setup questions: -## 3. Connect your database +- choose `PSL` +- keep the default schema path, `prisma/contract.prisma` -Update the `.env` file with your PostgreSQL connection URL: +## 3. Set your database connection string + +Update `.env` with the connection string for the database your app already uses: ```text title=".env" -DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public" +DATABASE_URL="postgres://username:password@host:5432/database?sslmode=require" ``` -The [format of the connection URL](/orm/reference/connection-urls) for PostgreSQL looks as follows: +## 4. Infer a starter contract from the live database -``` -postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA -``` +This step gives you a starting contract by reading the schema that already exists in PostgreSQL. -## 4. Introspect your database - -Run the following command to introspect your existing database: +Run: ```npm -npx prisma db pull +npx prisma@latest contract infer --output ./prisma/contract.prisma ``` -This command reads the `DATABASE_URL` environment variable, connects to your database, and introspects the database schema. It then translates the database schema from SQL into a data model in your Prisma schema. - -![Introspect your database with Prisma ORM](/img/getting-started/prisma-db-pull-generate-schema.png) - -After introspection, your Prisma schema will contain models that represent your existing database tables. +The command writes a first draft of `prisma/contract.prisma`. -## 5. Baseline your database +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 8 to know about first, and make the file easier to read. -To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/prisma-migrate/getting-started). +## 5. Emit the generated artifacts -First, create a `migrations` directory: +Once the contract looks right, this step turns it into the generated files the runtime and CLI use. -```bash -mkdir -p prisma/migrations/0_init -``` - -Next, generate the migration file with `prisma migrate diff`: +After you are happy with the contract, run: ```npm -npx prisma migrate diff --from-empty --to-schema prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql +npx prisma@latest contract emit ``` -Review the generated migration file to ensure it matches your database schema. +This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed. -Then, mark the migration as applied: +## 6. Sign the database -```npm -npx prisma migrate resolve --applied 0_init -``` - -You now have a baseline for your current database schema. - -## 6. Generate Prisma ORM types - -Generate Prisma Client based on your introspected schema: +Record that the live database matches the emitted contract: ```npm -npx prisma generate +npx prisma@latest db sign ``` -This creates a type-safe Prisma Client tailored to your database schema in the `generated/prisma` directory. - -## 7. Instantiate Prisma Client +This step matters in two common cases: -Create a utility file to instantiate Prisma Client. You need to pass an instance of the Prisma ORM driver adapter adapter to the `PrismaClient` constructor: +- the database has never been signed by Prisma 8 before +- the database was signed earlier, but under an older contract hash -```typescript title="lib/prisma.ts" -import "dotenv/config"; -import { PrismaPg } from "@prisma/adapter-pg"; -import { PrismaClient } from "../generated/prisma/client"; +## 7. Run a simple high-level query -const connectionString = `${process.env.DATABASE_URL}`; +With the database signed, you can test the higher-level API first and confirm Prisma 8 is reading the existing schema correctly. -const adapter = new PrismaPg({ connectionString }); -const prisma = new PrismaClient({ adapter }); +Create a `script.ts` file: -export { prisma }; -``` +```typescript title="script.ts" +import "dotenv/config"; +import { db } from "./prisma/db"; -## 8. Query your database +async function main() { + const runtime = await db.connect({ url: process.env.DATABASE_URL! }); -Now you can use Prisma Client to query your database. Create a `script.ts` file: + const users = await db.orm.User + .select("id", "email", "name") + .take(2) + .all(); -```typescript title="script.ts" -import { prisma } from "./lib/prisma"; + console.log(users); -async function main() { - // Example: Fetch all records from a table - // Replace 'user' with your actual model name - const allUsers = await prisma.user.findMany(); - console.log("All users:", JSON.stringify(allUsers, null, 2)); + await runtime.close(); } -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); +main().catch((error) => { + console.error(error); + process.exit(1); +}); ``` -Run the script: +Run it: ```npm npx tsx script.ts ``` -## 9. Evolve your schema - -To make changes to your database schema: +## 8. Run a simple low-level query -### 9.1. Update your Prisma schema file +After the ORM example, this step shows the lower-level SQL builder against the same existing schema. -Update your Prisma schema file to reflect the changes you want to make to your database schema. For example, add a new model: +Replace `script.ts` with this version: -```prisma title="prisma/schema.prisma" -model Post { // [!code ++] - id Int @id @default(autoincrement()) // [!code ++] - title String // [!code ++] - content String? // [!code ++] - published Boolean @default(false) // [!code ++] - authorId Int // [!code ++] - author User @relation(fields: [authorId], references: [id]) // [!code ++] -} // [!code ++] +```typescript title="script.ts" +import "dotenv/config"; +import { db } from "./prisma/db"; -model User { // [!code ++] - id Int @id @default(autoincrement()) // [!code ++] - email String @unique // [!code ++] - name String? // [!code ++] - posts Post[] // [!code ++] -} // [!code ++] -``` +async function main() { + const runtime = await db.connect({ url: process.env.DATABASE_URL! }); -### 9.2. Create and apply a migration: + const plan = db.sql.user + .select("id", "email", "name") + .limit(2) + .build(); -```npm -npx prisma migrate dev --name your_migration_name -``` + const rows = await db.runtime().execute(plan); + console.log(rows); -This command will: + await runtime.close(); +} -- Create a new SQL migration file -- Apply the migration to your database -- Regenerate Prisma Client +main().catch((error) => { + console.error(error); + process.exit(1); +}); +``` -## 10. Explore your data with Prisma Studio +Run it again: -```shell -npx prisma studio +```npm +npx tsx script.ts ``` -## Next steps - -You've successfully set up Prisma ORM. Here's what you can explore next: +## 9. Next steps -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more -- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) +When you change `prisma/contract.prisma`, emit the contract again: -## More info +```npm +npx prisma@latest contract emit +``` -- [PostgreSQL database connector](/orm/core-concepts/supported-databases/postgresql) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) -- [Prisma Migrate](/orm/prisma-migrate) +Use [db update](/cli/db-update) for a direct development update, or [migration plan](/cli/migration-plan) when you want a checked-in migration. diff --git a/apps/docs/content/docs/(index)/prisma-orm/create-prisma.mdx b/apps/docs/content/docs/(index)/prisma-orm/create-prisma.mdx new file mode 100644 index 0000000000..55b621e7f9 --- /dev/null +++ b/apps/docs/content/docs/(index)/prisma-orm/create-prisma.mdx @@ -0,0 +1,100 @@ +--- +title: create-prisma +description: Scaffold a new Prisma 8 app with create-prisma, with Prisma Composer, Prisma Postgres, and a deploy path built in. +url: /prisma-orm/create-prisma +metaTitle: Scaffold a Prisma 8 app with create-prisma +metaDescription: Use npx create-prisma@latest to create a Prisma 8 app from a framework template, pick PostgreSQL or MongoDB, choose PSL or TypeScript contract authoring, and deploy to Prisma. +--- + +`create-prisma` creates a new Prisma 8 project from an app template. It installs Prisma 8, 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 8 to an existing PostgreSQL project](/prisma-orm/add-to-existing-project/postgresql) or [Add Prisma 8 to an existing MongoDB project](/prisma-orm/add-to-existing-project/mongodb) instead. + +:::note[Using Prisma 7?] + +`create-prisma@latest` scaffolds Prisma 8. To scaffold a Prisma 7 app, run `npm create prisma@stable` and follow the [Prisma 7 setup paths](/v7/getting-started). + +::: + +## Create a project + +Run the CLI with your package manager and answer the prompts: + +```npm +npx create-prisma@latest my-app +``` + +The prompts cover the project name, the app template, the database provider, the contract authoring style, the package manager, and whether to deploy right away. Generated Node.js projects expect Node.js 24 LTS or newer. + +The last prompt is: + +```text +Deploy to Prisma now? +``` + +Choose no to deploy later with the generated `deploy` script. When more than one Prisma workspace session is available, the CLI asks which workspace receives the deployment; pass `--workspace ` to pick one without a prompt, or omit it to use the active workspace. Choosing another workspace also updates the Prisma CLI's active workspace session. + +## Skip the prompts + +Pass flags when you already know the project shape. `--yes` accepts the defaults for anything you leave out: + +```npm +npx create-prisma@latest my-app --template next --provider postgres --yes +``` + +`create` is the default subcommand, so `npx create-prisma@latest create my-app ...` is the same command. + +| Flag | What it does | +| --- | --- | +| `` or `--name ` | The project name and directory. | +| `--template ` | Chooses the app template (see below). | +| `--provider postgres\|postgresql\|mongo\|mongodb` | Chooses the database: PostgreSQL relational models or MongoDB document models. | +| `--authoring psl\|typescript` | Chooses the [contract authoring](/orm/contract-authoring/the-data-contract) style. | +| `--package-manager npm\|pnpm\|yarn\|bun\|deno` | Chooses the package manager used to install dependencies. | +| `--deploy` / `--no-deploy` | Deploys the generated app to Prisma immediately, or skips that step. | +| `--workspace ` | The Prisma workspace to deploy into. | +| `--yes` | Skips prompts and accepts the default choices. | +| `--force` | Allows scaffolding into a non-empty directory. | +| `--verbose` | Shows the full command output during setup. | + +## Templates + +| `--template` | App | +| --- | --- | +| `minimal` | A minimal server with one query | +| `next` | Next.js | +| `hono` | Hono | +| `elysia` | Elysia | +| `nest` | NestJS | +| `svelte` | SvelteKit | +| `astro` | Astro | +| `nuxt` | Nuxt | +| `tanstack-start` | TanStack Start | + +Every template supports PostgreSQL and MongoDB, PSL or TypeScript contract authoring, and npm, pnpm, Yarn, and Bun. Each [framework guide](/guides) walks the generated app from the first query to a deploy. + +Deno is supported for local minimal PostgreSQL apps: + +```bash +deno run -A npm:create-prisma@latest my-deno-app --template minimal --provider postgres --package-manager deno --no-deploy +``` + +Prisma Compute does not support Deno deployments yet, so Deno projects stop at a verified local run. + +## Start the app + +Review `DATABASE_URL` in `.env`, then initialize the database and start the dev server: + +```bash +cd my-app +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@latest migration plan` and `npx prisma@latest migrate`. The [quickstart](/prisma-orm/quickstart/postgresql) covers that loop in detail, and the [MongoDB quickstart](/prisma-orm/quickstart/mongodb) covers the replica set setup MongoDB needs. + +## Telemetry + +Published builds may send anonymous usage telemetry. It never includes project names, file paths, or database URLs. Disable it by setting `DO_NOT_TRACK`, `CREATE_PRISMA_DISABLE_TELEMETRY`, or `CREATE_PRISMA_TELEMETRY_DISABLED` in your environment. + +The CLI is open source at [prisma/create-prisma](https://github.com/prisma/create-prisma). diff --git a/apps/docs/content/docs/(index)/prisma-orm/index.mdx b/apps/docs/content/docs/(index)/prisma-orm/index.mdx new file mode 100644 index 0000000000..19273615d9 --- /dev/null +++ b/apps/docs/content/docs/(index)/prisma-orm/index.mdx @@ -0,0 +1,102 @@ +--- +title: Introduction to Prisma 8 +description: 'Prisma 8 is the current release of Prisma ORM.' +url: /prisma-orm +metaTitle: Introduction to Prisma 8 +metaDescription: 'Start here for Prisma 8, the TypeScript-native rebuild of Prisma ORM. Quickstarts, framework guides, and agent prompts.' +--- + +Prisma 8 is a ground-up rebuild of Prisma ORM, from the runtime and query APIs to the migration flow and project setup. + +:::note[Using Prisma 7?] + +Prisma 8 is the current release of Prisma ORM. Prisma 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). + +::: + +Prisma 8 is the recommended starting point for new projects. + +```npm +npx 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. + + + }> + Scaffold, provision Prisma Postgres, query, and deploy to Prisma Compute in one sitting. + + }> + Pick a new-project quickstart or add Prisma 8 to an existing app. + + + +## Use with your agent + +Copy this prompt, replace the placeholders, and hand it to your coding agent. The scaffold installs [Prisma 8 skills](/ai/tools/skills) into `.claude/skills/` and `.agents/skills/`: + + + +```text +Create a new [framework] application with Prisma 8, seed it, and run it locally. + +If I have not told you which framework, stop and ask before scaffolding. Valid --template values: next, hono, nuxt, astro, nest, svelte, tanstack-start, elysia. + +1. Scaffold the app: `npx create-prisma@latest create my-app --template [framework] --provider postgres --yes`. +2. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `npx create-db@latest` and show me the claim URL it prints. Export it as `DATABASE_URL` in the shell and write it to `.env` in the project directory; the generated scripts read the environment variable, and the deploy step reads `.env`. +3. From the project directory, apply the starter contract: `npm run db:init`. Sample users are seeded automatically on the app's first query; there is no separate seed script. +4. Edit the starter contract under `src/prisma/` into a small schema for my use case, then run `npm run contract:emit` and plan and apply the migration: `npx prisma@latest migration plan`, then `npx prisma@latest migrate --yes`. Migration planning diffs the emitted contract, so the emit step is required. +5. Update the seed script under `src/prisma/` and the app routes to query the new schema, start `npm run dev` in the background (with `DATABASE_URL` exported), and verify with a request against the running app. For the `nest` template, if routes return 500s with `reading 'findAll'` in the logs, add explicit `@Inject()` tokens as shown in https://www.prisma.io/docs/guides/frameworks/nestjs.md. +6. Deploy with Prisma Compute. First apply the framework's deploy requirement from the guide at https://www.prisma.io/docs/guides/frameworks/[guide].md, where [guide] is the template name except: template `next` → guide `nextjs`, `nest` → `nestjs`, `svelte` → `sveltekit`. The requirements: Next.js needs `output: "standalone"` in `next.config.ts` (without it the deployed app returns 504s), TanStack Start needs the nitro build plugin, Astro needs the `@astrojs/node` adapter plus `--env HOST=0.0.0.0`, and Elysia needs `--framework bun --entry src/index.ts` on the deploy command. If the template is `svelte`, skip this step; Compute does not support SvelteKit yet. Check `npx @prisma/cli@latest auth whoami`. If I am not signed in, stop and ask me to run `npx @prisma/cli@latest auth login`, because that step opens a browser. Then run `npx @prisma/cli@latest app deploy --create-project my-app --env .env` so DATABASE_URL reaches the deployment, and verify the deployed URL with curl. + +Use the installed Prisma 8 skills and the current Prisma docs: https://www.prisma.io/docs/llms.txt (append `.md` to any docs URL for a markdown version). +``` + + + +## Add Prisma 8 to your framework + +Each guide runs the same journey for a specific framework: scaffold, connect Prisma Postgres, query, and deploy where the framework is supported on Compute. + + + + + + + + + + + + + + +## Learn the fundamentals + +Once you are connected, the Fundamentals section teaches the everyday query patterns. + + + }> + Filter with where, project with select, sort, and paginate. + + }> + Create, update, delete, upsert, and the bulk write variants. + + }> + Read related records with include on PostgreSQL and MongoDB. + + }> + Make several writes succeed or fail together. + + }> + The SQL builder and the MongoDB pipeline builder for shapes the ORM can't express. + + + +## Learn the concepts + + + }> + Learn the core ideas behind contracts, emitted artifacts, runtime clients, query styles, and migrations. + + diff --git a/apps/docs/content/docs/(index)/prisma-orm/meta.json b/apps/docs/content/docs/(index)/prisma-orm/meta.json index 1ee958a0a6..2fb7230510 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/meta.json +++ b/apps/docs/content/docs/(index)/prisma-orm/meta.json @@ -1,5 +1,10 @@ { "title": "Prisma ORM", "defaultOpen": true, - "pages": ["quickstart", "add-to-existing-project"] + "pages": [ + "index", + "create-prisma", + "quickstart", + "add-to-existing-project" + ] } 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 c7c3975061..3a7edc76ec 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/meta.json @@ -1,13 +1,4 @@ { "title": "Quickstart", - "pages": [ - "prisma-postgres", - "sqlite", - "postgresql", - "mysql", - "sql-server", - "planetscale", - "cockroachdb", - "mongodb" - ] + "pages": ["postgresql", "mongodb"] } 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 447d9263ad..05c5191dec 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx @@ -1,332 +1,80 @@ --- title: MongoDB -description: Create a new TypeScript project from scratch by connecting Prisma ORM to MongoDB and generating a Prisma Client for database access +description: Create a new Prisma 8 project with MongoDB using create-prisma@latest. url: /prisma-orm/quickstart/mongodb -metaTitle: 'Quickstart: Prisma ORM with MongoDB (10 min)' -metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to MongoDB and generating a Prisma Client for database access. +metaTitle: 'Quickstart: Prisma 8 with MongoDB' +metaDescription: 'Scaffold a Prisma 8 project with MongoDB, apply the starter migration, and run your first query.' --- -[MongoDB](https://www.mongodb.com) is a popular NoSQL document database. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to MongoDB using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database. +Create a Prisma 8 app with MongoDB, apply the first migration, and run your first query against seeded data. -:::warning[MongoDB support for Prisma ORM v7] +:::note[Using Prisma 7?] -**MongoDB support for Prisma ORM v7 is coming in the near future.** In the meantime, please use **Prisma ORM v6.19** (the latest v6 release) when working with MongoDB. - -This guide uses Prisma ORM v6.19 to ensure full compatibility with MongoDB. +Prisma 8 is the current release of Prisma ORM. Prisma 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). ::: -## Prerequisites - -- Node.js installed in your system [with the supported version](/guides/upgrade-prisma-orm/v6#minimum-supported-nodejs-versions) -- A [MongoDB](https://www.mongodb.com/) database accessible via connection string - -## 1. Create a new project - -```shell -mkdir hello-prisma -cd hello-prisma -``` - -Initialize a TypeScript project: - -```npm -npm init -y -npm install typescript tsx @types/node --save-dev -npx tsc --init -``` - - -## 2. Install required dependencies - -Install the packages needed for this quickstart: - -```npm -npm install prisma@6.19 @types/node --save-dev -``` +## Quick start ```npm -npm install @prisma/client@6.19 dotenv +npx create-prisma@latest --provider mongodb ``` -:::info[Why Prisma v6.19?] - -This is the latest stable version of Prisma ORM v6 that fully supports MongoDB. MongoDB support for Prisma ORM v7 is coming soon. You can also install `prisma@6` and `@prisma/client@6` to automatically get the latest v6 release. +Run this from a Node.js 24 or newer environment. The command preselects MongoDB and prompts you for the contract authoring style (PSL or TypeScript) and your package manager. -::: +Setup gives you the app template, a starter contract, `prisma-next.md`, project-level Prisma 8 skills for your coding agent, and package scripts for the database steps below. Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. -Here's what each package does: - -- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db push`, and `prisma generate` -- **`@prisma/client`** - The Prisma Client library for querying your database -- **`dotenv`** - Loads environment variables from your `.env` file - -:::note - -MongoDB doesn't require driver adapters since Prisma ORM connects directly to MongoDB. - -::: +Prisma 8 needs a MongoDB replica set. MongoDB Atlas already gives you one; for local development, run a single-node replica set named `rs0` on port 27017 to match the generated connection string. -## 3. Configure ESM support +## 1. Set the database connection -Update `tsconfig.json` for ESM compatibility: +The scaffold writes a `.env` with a local replica-set connection string: -```json title="tsconfig.json" -{ - "compilerOptions": { - "module": "ESNext", - "moduleResolution": "bundler", - "target": "ES2023", - "strict": true, - "esModuleInterop": true, - "ignoreDeprecations": "6.0" - } -} +```text title=".env" +DATABASE_URL="mongodb://localhost:27017/mydb?replicaSet=rs0&directConnection=true" ``` -Update `package.json` to enable ESM: +The generated scripts read environment variables directly rather than `.env`, and the CLI and the app use different variable names: the CLI commands read `MONGODB_URL`, and the app reads `DATABASE_URL`. Export both in the shell you work in: -```json title="package.json" -{ - "type": "module" // [!code ++] -} +```bash +export MONGODB_URL="mongodb://localhost:27017/mydb?replicaSet=rs0&directConnection=true" +export DATABASE_URL="$MONGODB_URL" ``` -## 4. Initialize Prisma ORM - -You can now invoke the Prisma CLI by prefixing it with `npx`: +If you use MongoDB Atlas, use the connection string from your Atlas cluster instead. -```npm -npx prisma -``` +## 2. Create the migration plan -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Create the first migration plan from the starter contract. ```npm -npx prisma init --datasource-provider mongodb --output ../generated/prisma -``` - -This command does a few things: - -- Creates a `prisma/` directory with a `schema.prisma` file for your database connection and schema models -- Creates a `.env` file in the root directory for environment variables -- Creates a `prisma.config.ts` file for Prisma configuration - -:::note - -Prisma Client will be generated in the `generated/prisma/` directory when you run `npx prisma generate` later in this guide. - -::: - -The generated `prisma.config.ts` file looks like this: - -```typescript title="prisma.config.ts" -import { defineConfig, env } from "prisma/config"; - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - engine: "classic", - datasource: { - url: env("DATABASE_URL"), - }, -}); -``` - -Add `dotenv` to `prisma.config.ts` so that Prisma can load environment variables from your `.env` file: - -```typescript title="prisma.config.ts" -import "dotenv/config"; // [!code ++] -import { defineConfig, env } from "prisma/config"; - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - engine: "classic", - datasource: { - url: env("DATABASE_URL"), - }, -}); -``` - -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: - -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} - -datasource db { - provider = "mongodb" - url = env("DATABASE_URL") -} +npm run migration:plan -- --name init ``` -Update your `.env` file with your MongoDB connection string: +The output reports the planned operations: creating the `users` and `posts` collections and a unique index on `users.email`. -```text title=".env" -DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/mydb" -``` - -:::tip - -Replace `username`, `password`, `cluster`, and `mydb` with your actual MongoDB credentials and database name. You can get your connection string from [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) or your MongoDB deployment. - -::: - -## 5. Define your data model - -Open `prisma/schema.prisma` and add the following models: - -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} - -datasource db { - provider = "mongodb" - url = env("DATABASE_URL") -} - -model User { // [!code ++] - id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] - email String @unique // [!code ++] - name String? // [!code ++] - posts Post[] // [!code ++] -} // [!code ++] +## 3. Apply the migration -model Post { // [!code ++] - id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] - title String // [!code ++] - content String? // [!code ++] - published Boolean @default(false) // [!code ++] - author User @relation(fields: [authorId], references: [id]) // [!code ++] - authorId String @db.ObjectId // [!code ++] -} // [!code ++] -``` - -## 6. Push your schema to MongoDB - -MongoDB doesn't support migrations like relational databases. Instead, use `db push` to sync your schema: +Apply the planned migration to MongoDB. ```npm -npx prisma db push -``` - -This command: - -- Creates the collections in MongoDB based on your schema -- Automatically generates Prisma Client - -:::info - -Unlike relational databases, MongoDB uses a flexible schema. The `db push` command ensures your Prisma schema is reflected in your database without creating migration files. - -::: - -## 7. Instantiate Prisma Client - -Now that you have all the dependencies installed, you can instantiate Prisma Client: - -```typescript title="lib/prisma.ts" -import "dotenv/config"; -import { PrismaClient } from "../generated/prisma/client"; - -const prisma = new PrismaClient(); - -export { prisma }; +npm run migrate ``` -## 8. Write your first query - -Create a `script.ts` file to test your setup: - -```typescript title="script.ts" -import { prisma } from "./lib/prisma"; +The output ends with a summary like `Applied 1 migration(s) (3 operation(s)) across 1 contract space(s)`. If it fails with a connection error, confirm your MongoDB deployment is a replica set and `MONGODB_URL` is exported in this shell. -async function main() { - // Create a new user with a post - const user = await prisma.user.create({ - data: { - name: "Alice", - email: "alice@prisma.io", - posts: { - create: { - title: "Hello World", - content: "This is my first post!", - published: true, - }, - }, - }, - include: { - posts: true, - }, - }); - console.log("Created user:", user); +## 4. Run the app - // Fetch all users with their posts - const allUsers = await prisma.user.findMany({ - include: { - posts: true, - }, - }); - console.log("All users:", JSON.stringify(allUsers, null, 2)); -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -Run the script: +Start the app and confirm the sample query runs successfully. ```npm -npx tsx script.ts +npm run dev ``` -You should see the created user and all users printed to the console! - -## 9. Explore your data - -You can use [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), the MongoDB shell, or MongoDB Compass to view and manage your data. - -:::warning - -[Prisma Studio](/studio) does not currently support MongoDB. Support may be added in a future release. See [Databases supported by Prisma Studio](/studio#supported-databases) for more information. - -::: +Use the URL or terminal output shown by your template. You should see the seeded users returned from MongoDB. ## Next steps -You've successfully set up Prisma ORM. Here's what you can explore next: - -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more -- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) - - - -## Troubleshooting - -- **Authentication failed** — If you see a `SCRAM failure: Authentication failed` error, [add `?authSource=admin`](https://github.com/prisma/prisma/discussions/9994#discussioncomment-1562283) to the end of your connection string. -- **Empty database name** — If you see an `Error code 8000 (AtlasError): empty database name not allowed` error, append the database name to your connection URL. See this [GitHub issue](https://github.com/prisma/web/issues/5562) for details. - -## More info - -- [MongoDB database connector](/orm/core-concepts/supported-databases/mongodb) -- [MongoDB data modeling patterns](/orm/core-concepts/supported-databases/mongodb#type-mapping-between-mongodb-and-the-prisma-schema) -- [MongoDB deployment considerations](/orm/core-concepts/supported-databases/mongodb#differences-to-connectors-for-relational-databases) +- 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. +- Read the [Prisma 8 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 c72cc980f3..64f983d4b6 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx +++ b/apps/docs/content/docs/(index)/prisma-orm/quickstart/postgresql.mdx @@ -1,289 +1,75 @@ --- title: PostgreSQL -description: Create a new TypeScript project from scratch by connecting Prisma ORM to PostgreSQL and generating a Prisma Client for database access +description: Create a new Prisma 8 project with PostgreSQL using create-prisma@latest. url: /prisma-orm/quickstart/postgresql -metaTitle: 'Quickstart: Prisma ORM with PostgreSQL (10 min)' -metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to PostgreSQL and generating a Prisma Client for database access. +metaTitle: 'Quickstart: Prisma 8 with PostgreSQL' +metaDescription: 'Scaffold a Prisma 8 project with PostgreSQL, initialize the database, and run your first query.' --- -[PostgreSQL](https://www.postgresql.org) is a powerful, open-source relational database. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to PostgreSQL using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database. +Create a Prisma 8 app with PostgreSQL and run your first query against seeded data. -## Prerequisites +:::note[Using Prisma 7?] -You also need: - -- A [PostgreSQL](https://www.postgresql.org/) database server running and accessible -- Database connection details (host, port, username, password, database name) - -:::tip[Need a PostgreSQL database?] - -If you don't already have a PostgreSQL database, follow the quickstart to set up a production-ready [Prisma Postgres](/prisma-orm/quickstart/prisma-postgres) database with Prisma ORM in a new project. +Prisma 8 is the current release of Prisma ORM. Prisma 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). ::: -## 1. Create a new project - -```shell -mkdir hello-prisma -cd hello-prisma -``` - -Initialize a TypeScript project: - -```npm -npm init -y -npm install typescript tsx @types/node --save-dev -npx tsc --init -``` - - -## 2. Install required dependencies - -Install the packages needed for this quickstart: +## Quick start ```npm -npm install prisma @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv -``` - -Here's what each package does: - -- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma migrate`, and `prisma generate` -- **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database -- **`pg`** - The node-postgres database driver -- **`@types/pg`** - TypeScript type definitions for node-postgres -- **`dotenv`** - Loads environment variables from your `.env` file - -## 3. Configure ESM support - -Update `tsconfig.json` for ESM compatibility: - -```json title="tsconfig.json" -{ - "compilerOptions": { - "module": "ESNext", - "moduleResolution": "bundler", - "target": "ES2023", - "strict": true, - "esModuleInterop": true, - "ignoreDeprecations": "6.0" - } -} +npx create-prisma@latest --provider postgres ``` -Update `package.json` to enable ESM: - -```json title="package.json" -{ - "type": "module" // [!code ++] -} -``` +Run this from a Node.js 24 or newer environment. The command preselects PostgreSQL and prompts you for the contract authoring style (PSL or TypeScript) and your package manager. -## 4. Initialize Prisma ORM +Setup gives you the app template, a starter contract, `prisma-next.md`, project-level Prisma 8 skills for your coding agent, and package scripts for the database steps below. Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. -You can now invoke the Prisma CLI by prefixing it with `npx`: +From here you have two paths: let [Prisma Composer](/composer) run a local Prisma Postgres database for you, or connect a PostgreSQL database you provide. -```npm -npx prisma -``` +## Path A: Run with a local database -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Composer builds the app, starts a local Prisma Postgres database, and applies the starter contract for you. No connection string needed. ```npm -npx prisma init --datasource-provider postgresql --output ../generated/prisma -``` - -This command does a few things: - -- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection and schema models -- Creates a `.env` file in the root directory for environment variables -- Creates a `prisma.config.ts` file for Prisma configuration - -The generated `prisma.config.ts` file looks like this: - -```typescript title="prisma.config.ts" -import "dotenv/config"; -import { defineConfig, env } from "prisma/config"; - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - datasource: { - url: env("DATABASE_URL"), - }, -}); +npm run dev:composer ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +Open the URL the command prints. You should see the seeded users returned from PostgreSQL. -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} +## Path B: Connect your own database -datasource db { - provider = "postgresql" -} -``` +### 1. Set the database connection -Update your `.env` file with your PostgreSQL connection string: +Export `DATABASE_URL` in the shell you run the commands from. The generated scripts read the variable from the environment, not from `.env`. -```text title=".env" -DATABASE_URL="postgresql://username:password@localhost:5432/mydb?schema=public" +```bash +export DATABASE_URL="postgresql://username:password@host:5432/database?sslmode=require" ``` -Replace the placeholders with your actual database credentials: - -- `username`: Your PostgreSQL username -- `password`: Your PostgreSQL password -- `localhost:5432`: Your PostgreSQL host and port -- `mydb`: Your database name - -## 5. Define your data model - -Open `prisma/schema.prisma` and add the following models: +If you don't have a PostgreSQL database yet, `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. -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} +### 2. Initialize the database -datasource db { - provider = "postgresql" -} - -model User { // [!code ++] - id Int @id @default(autoincrement()) // [!code ++] - email String @unique // [!code ++] - name String? // [!code ++] - posts Post[] // [!code ++] -} // [!code ++] - -model Post { // [!code ++] - id Int @id @default(autoincrement()) // [!code ++] - title String // [!code ++] - content String? // [!code ++] - published Boolean @default(false) // [!code ++] - author User @relation(fields: [authorId], references: [id]) // [!code ++] - authorId Int // [!code ++] -} // [!code ++] -``` - -## 6. Create and apply your first migration - -Create your first migration to set up the database tables: - -```npm -npx prisma migrate dev --name init -``` - -This command creates the database tables based on your schema. - -Now run the following command to generate the Prisma Client: +From the generated project directory, run `db:init` to apply the starter contract to PostgreSQL and sign the database. ```npm -npx prisma generate +npm run db:init ``` -## 7. Instantiate Prisma Client - -Now that you have all the dependencies installed, you can instantiate Prisma Client. You need to pass an instance of the Prisma ORM driver adapter to the `PrismaClient` constructor: - -```typescript title="lib/prisma.ts" -import "dotenv/config"; -import { PrismaPg } from "@prisma/adapter-pg"; -import { PrismaClient } from "../generated/prisma/client"; - -const connectionString = `${process.env.DATABASE_URL}`; - -const adapter = new PrismaPg({ connectionString }); -const prisma = new PrismaClient({ adapter }); - -export { prisma }; -``` +The output ends with a summary like `Applied 5 operation(s) across 1 space(s), database signed`. -## 8. Write your first query +### 3. Run the app -Create a `script.ts` file to test your setup: - -```typescript title="script.ts" -import { prisma } from "./lib/prisma"; - -async function main() { - // Create a new user with a post - const user = await prisma.user.create({ - data: { - name: "Alice", - email: "alice@prisma.io", - posts: { - create: { - title: "Hello World", - content: "This is my first post!", - published: true, - }, - }, - }, - include: { - posts: true, - }, - }); - console.log("Created user:", user); - - // Fetch all users with their posts - const allUsers = await prisma.user.findMany({ - include: { - posts: true, - }, - }); - console.log("All users:", JSON.stringify(allUsers, null, 2)); -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -Run the script: +Start the app and confirm the sample query runs successfully. ```npm -npx tsx script.ts +npm run dev ``` -You should see the created user and all users printed to the console! - -## 9. Explore your data with Prisma Studio - -Prisma Studio is a visual editor for your database. Launch it with: - -```shell -npx prisma studio -``` +Use the URL or terminal output shown by your template. You should see the seeded users returned from PostgreSQL. If the response is `Could not query users yet`, `DATABASE_URL` is not set in the environment the app runs in; export it in the same shell and restart. ## Next steps -You've successfully set up Prisma ORM. Here's what you can explore next: - -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more -- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) - - - -## More info - -- [PostgreSQL database connector](/orm/core-concepts/supported-databases/postgresql) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- 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. +- Read the [Prisma 8 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 7260c7b790..508b2e6a8b 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 @@ -1,468 +1,62 @@ --- title: From the CLI -description: Start building a Prisma application with a Prisma Postgres database from the CLI +description: Start a Prisma 8 app with Prisma Postgres from the command line. url: /prisma-postgres/from-the-cli -metaTitle: From the CLI -metaDescription: Start building a Prisma application with a Prisma Postgres database from the CLI +metaTitle: Prisma 8 with Prisma Postgres from the CLI +metaDescription: Start a Prisma 8 app with Prisma Postgres from the command line. --- -This page provides a step-by-step guide for Prisma Postgres after setting it up with `prisma init` and `npx create-db`: +Use the CLI when you want Prisma 8 and Prisma Postgres set up without leaving the terminal. -1. Set up a TypeScript app with Prisma ORM -1. Migrate the schema of your database -1. Query your database from TypeScript - -## Prerequisites - -This guide assumes you initialized Prisma with `prisma init` and created a Prisma Postgres database with `npx create-db`: +## Start a new app ```npm -npx prisma@latest init -npx create-db +npx create-prisma@latest ``` +Choose PostgreSQL when prompted. Setup adds `prisma-next.md`, installs project-level Prisma 8 skills for your coding agent, and writes the generated scripts used below. -Once these commands have terminated: - -- The `prisma/` folder was created with an empty `schema.prisma` file. -- The `DATABASE_URL` env var was set in a `.env` file. -- The `prisma.config.ts` file was created with the default configuration. -- You have a Prisma Postgres connection string to paste into `.env`. - -## 1. Organize your project directory - -:::note - -If you ran the `prisma init` command inside a folder where you want your project to live, you can skip this step and [proceed to the next section](/prisma-postgres/from-the-cli#2-set-up-your-project). - -::: - -If you ran the command outside your intended project directory (e.g., in your home folder or another location), you need to move the generated `prisma` folder and the `.env` file into a dedicated project directory. - -Create a new folder (e.g. `hello-prisma`) where you want your project to live and move the necessary files into it: - -```bash -mkdir hello-prisma -mv .env ./hello-prisma/ -mv prisma ./hello-prisma/ -``` - -Navigate into your project folder: - -```bash -cd ./hello-prisma -``` - -Now that your project is in the correct location, continue with the setup. +## Create the database -## 2. Set up your project - -### 2.1. Set up TypeScript - -Initialize a TypeScript project and add the Prisma CLI as a development dependency: - -```npm -npm init -y -``` - -```npm -npm install typescript tsx @types/node @types/pg -D -``` - -This creates a `package.json` file with an initial setup for your TypeScript app. - -Next, initialize TypeScript with a `tsconfig.json` file in the project: +Create a Prisma Postgres database from the terminal and export its connection string. The generated scripts read the environment variable, not `.env`: ```npm -npx tsc --init -``` - -### 2.2. Configure ESM support - -Update `tsconfig.json` for ESM compatibility: - -```json title="tsconfig.json" -{ - "compilerOptions": { - "module": "ESNext", - "moduleResolution": "bundler", - "target": "ES2023", - "strict": true, - "esModuleInterop": true, - "ignoreDeprecations": "6.0" - } -} +npx create-db@latest ``` -Update `package.json` to enable ESM: - -```json title="package.json" -{ - "type": "module" // [!code ++] -} -``` - -### 2.3. Set up Prisma ORM - -Install the required dependencies to use Prisma Postgres: - -```npm -npm install prisma --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv -``` - -Here's what each package does: - -- **`prisma`** - The Prisma CLI for running commands like `prisma migrate` and `prisma generate` -- **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database -- **`pg`** - The node-postgres database driver -- **`@types/pg`** - TypeScript type definitions for node-postgres -- **`dotenv`** - Loads environment variables from your `.env` file - -### 2.4. Review the generated prisma.config.ts - -The `prisma init` command automatically created a `prisma.config.ts` file that looks like this: - -```typescript title="prisma.config.ts" -import "dotenv/config"; -import { defineConfig, env } from "prisma/config"; - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - datasource: { - url: env("DATABASE_URL"), - }, -}); -``` - -### 2.5. Create a script to query the database - -Create an `index.ts` file in the root directory, this will be used to query your application with Prisma ORM: - ```bash -touch index.ts +export DATABASE_URL="" ``` -## 3. Migrate the database schema - -Update your `prisma/schema.prisma` file to include the `User` and `Post` models: +The command also prints a claim URL; open it within 24 hours to keep the database in your account. -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} +## Initialize the database -datasource db { - provider = "postgresql" -} - -model User { - id Int @id @default(autoincrement()) - email String @unique - name String? - posts Post[] -} - -model Post { - id Int @id @default(autoincrement()) - title String - content String? - published Boolean @default(false) - author User @relation(fields: [authorId], references: [id]) - authorId Int -} -``` - -After adding the models, migrate your database using [Prisma Migrate](/orm/prisma-migrate): +From the generated project directory, run: ```npm -npx prisma migrate dev --name init +npm run db:init ``` -This command creates the database tables based on your schema. +## Run the app -Now run the following command to generate the Prisma Client: +Sample users are seeded automatically on the app's first query. ```npm -npx prisma generate -``` - -## 4. Send queries with Prisma ORM - -### 4.1. Instantiate Prisma Client - -Create a `lib/prisma.ts` file to instantiate Prisma Client with the driver adapter: - -```typescript title="lib/prisma.ts" -import "dotenv/config"; -import { PrismaPg } from "@prisma/adapter-pg"; -import { PrismaClient } from "../generated/prisma/client"; - -const connectionString = `${process.env.DATABASE_URL}`; - -const adapter = new PrismaPg({ connectionString }); -const prisma = new PrismaClient({ adapter }); - -export { prisma }; +npm run dev ``` -:::tip - -If you need to query your database via HTTP from an edge runtime (Cloudflare Workers, Vercel Edge Functions, etc.), use the [Prisma Postgres serverless driver](/postgres/database/serverless-driver#use-with-prisma-orm). - -::: - -### 4.2. Write your first query - -Paste the following boilerplate into `index.ts`: +## Add Prisma 8 to an existing app -```ts title="index.ts" -import { prisma } from "./lib/prisma"; - -async function main() { - // ... you will write your Prisma ORM queries here -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -This code contains a `main` function that's invoked at the end of the script. It also instantiates `PrismaClient` which you'll use to send queries to your database. - -### 4.3. Create a new `User` record - -Let's start with a small query to create a new `User` record in the database and log the resulting object to the console. Add the following code to your `index.ts` file: - -```ts title="index.ts" -import { prisma } from "./lib/prisma"; - -async function main() { - const user = await prisma.user.create({ - // [!code ++] - data: { - // [!code ++] - name: "Alice", // [!code ++] - email: "alice@prisma.io", // [!code ++] - }, // [!code ++] - }); // [!code ++] - console.log(user); // [!code ++] -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -Next, execute the script with the following command: - -```npm -npx tsx index.ts -``` - -```text no-copy -{ id: 1, email: 'alice@prisma.io', name: 'Alice' } -``` - -Great job, you just created your first database record with Prisma Postgres! 🎉 - -### 4.4. Retrieve all `User` records - -Prisma ORM offers various queries to read data from your database. In this section, you'll use the `findMany` query that returns _all_ the records in the database for a given model. - -Delete the previous Prisma ORM query and add the new `findMany` query instead: - -```ts title="index.ts" -import { prisma } from "./lib/prisma"; - -async function main() { - const users = await prisma.user.findMany(); // [!code ++] - console.log(users); // [!code ++] -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -Execute the script again: - -```npm -npx tsx index.ts -``` - -```text no-copy -[{ id: 1, email: 'alice@prisma.io', name: 'Alice' }] -``` - -Notice how the single `User` object is now enclosed with square brackets in the console. That's because the `findMany` returned an array with a single object inside. - -### 4.5. Explore relation queries - -One of the main features of Prisma ORM is the ease of working with [relations](/orm/prisma-schema/data-model/relations). In this section, you'll learn how to create a `User` and a `Post` record in a nested write query. Afterwards, you'll see how you can retrieve the relation from the database using the `include` option. - -First, adjust your script to include the nested query: - -```ts title="index.ts" -import { prisma } from "./lib/prisma"; - -async function main() { - const user = await prisma.user.create({ - // [!code ++] - data: { - // [!code ++] - name: "Bob", // [!code ++] - email: "bob@prisma.io", // [!code ++] - posts: { - // [!code ++] - create: [ - // [!code ++] - { - // [!code ++] - title: "Hello World", // [!code ++] - published: true, // [!code ++] - }, // [!code ++] - { - // [!code ++] - title: "My second post", // [!code ++] - content: "This is still a draft", // [!code ++] - }, // [!code ++] - ], // [!code ++] - }, // [!code ++] - }, // [!code ++] - }); // [!code ++] - console.log(user); // [!code ++] -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -Run the query by executing the script again: - -```npm -npx tsx index.ts -``` - -```text no-copy -{ id: 2, email: 'bob@prisma.io', name: 'Bob' } -``` - -In order to also retrieve the `Post` records that belong to a `User`, you can use the `include` option via the `posts` relation field: - -```ts title="index.ts" -import { prisma } from "./lib/prisma"; - -async function main() { - const usersWithPosts = await prisma.user.findMany({ - // [!code ++] - include: { - // [!code ++] - posts: true, // [!code ++] - }, // [!code ++] - }); // [!code ++] - console.dir(usersWithPosts, { depth: null }); // [!code ++] -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -Run the script again to see the results of the nested read query: - -```npm -npx tsx index.ts -``` - -```text no-copy -[ - { id: 1, email: 'alice@prisma.io', name: 'Alice', posts: [] }, - { - id: 2, - email: 'bob@prisma.io', - name: 'Bob', - posts: [ - { - id: 1, - title: 'Hello World', - content: null, - published: true, - authorId: 2 - }, - { - id: 2, - title: 'My second post', - content: 'This is still a draft', - published: false, - authorId: 2 - } - ] - } -] -``` - -This time, you're seeing two `User` objects being printed. Both of them have a `posts` field (which is empty for `"Alice"` and populated with two `Post` objects for `"Bob"`) that represents the `Post` records associated with them. - -## Next steps - -You just got your feet wet with a basic Prisma Postgres setup. Check out the official [Quickstart](/prisma-orm/quickstart/prisma-postgres). - -### View and edit data in Prisma Studio - -Prisma ORM comes with a built-in GUI to view and edit the data in your database. You can open it using the following command: +If the app already exists, run Prisma 8 from the project root: ```npm -npx prisma studio --config ./prisma.config.ts +npx prisma@latest orm init ``` -With Prisma Postgres, you can also directly use Prisma Studio inside the [Console](https://console.prisma.io) by selecting the **Studio** tab in your project. - -### Build a fullstack app with Next.js - -Learn how to use Prisma Postgres in a fullstack app: - -- [Build a fullstack app with Next.js 15](/guides/frameworks/nextjs) -- [Next.js 15 example app](https://github.com/prisma/nextjs-prisma-postgres-demo) (including authentication) - -### Explore ready-to-run examples +Choose PostgreSQL and set `DATABASE_URL` to your Prisma Postgres connection string. Init adds `prisma-next.md`, package scripts, and the Prisma 8 skills for your coding agent. Then follow the [PostgreSQL existing-project guide](/prisma-orm/add-to-existing-project/postgresql). -Check out the [`prisma-examples`](https://github.com/prisma/prisma-examples/) repository on GitHub to see how Prisma ORM can be used with your favorite library. The repo contains examples with Express, NestJS, GraphQL as well as fullstack examples with Next.js and Vue.js, and a lot more. +## Import an existing database -These examples use SQLite by default but you can follow the instructions in the project README to switch to Prisma Postgres in a few simple steps. +- Use [Import from PostgreSQL](/prisma-postgres/import-from-existing-database-postgresql) when your source database is PostgreSQL. +- Use [Import from MySQL](/prisma-postgres/import-from-existing-database-mysql) when your source database is MySQL. 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 030c2da1fe..f2d67b456c 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 @@ -1,206 +1,70 @@ --- title: Import from MySQL -description: Learn how to import data from an existing MySQL database into Prisma Postgres +description: 'Import an existing MySQL database into Prisma Postgres, then use it with Prisma 8.' url: /prisma-postgres/import-from-existing-database-mysql -metaTitle: Import from existing MySQL database into Prisma Postgres -metaDescription: Learn how to import data from an existing MySQL database into Prisma Postgres. +metaTitle: Import from MySQL into Prisma Postgres for Prisma 8 +metaDescription: 'Import MySQL data into Prisma Postgres, then connect Prisma 8 to the imported database.' --- -This guide provides step-by-step instructions for importing data from an existing MySQL database into Prisma Postgres. - -You can accomplish this migration in four steps: - -1. Create a new Prisma Postgres database. -1. Connect directly to a Prisma Postgres instance using a [direct connection](/postgres/database/connecting-to-your-database). -1. Migrate your MySQL data to Prisma Postgres using [pgloader](https://pgloader.io/). -1. Configure your Prisma project for Prisma Postgres. +Move an existing MySQL database into Prisma Postgres, then connect Prisma 8 to it. ## Prerequisites -- The connection URL to your existing MySQL database. -- A [Prisma Data Platform](https://console.prisma.io) account. -- Node.js 18+ installed. -- [pgloader](https://pgloader.io/) installed. - -:::info[Make sure your PostgreSQL tools match the Prisma Postgres version] - -Prisma Postgres runs PostgreSQL 17. Your `pgloader` and any other PostgreSQL tools you use need to be compatible with PostgreSQL 17. - -::: - -We recommend attempting this migration in a separate git development branch. - -## 1. Create a new Prisma Postgres database +You need: -Follow these steps to create a new Prisma Postgres database: +- the connection URL for the MySQL database you are importing from +- a Prisma Data Platform account +- `pgloader` +- Node.js 24 or newer -1. Log in to [Prisma Data Platform](https://console.prisma.io/) and open the Console. -1. In a [workspace](/console/concepts#workspace) of your choice, click the **New project** button. -1. Type a name for your project in the **Name** field, e.g. **hello-ppg**. -1. In the **Prisma Postgres** section, click the **Get started** button. -1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**. -1. Click the **Create project** button. +## 1. Create a Prisma Postgres database -Once your database is** **provisioned, find your direct Prisma Postgres connection string: +Create a Prisma Postgres database from Console or with the CLI. Copy the direct connection string. You will use it for the import and for `DATABASE_URL`. -1. Navigate to your active Prisma Postgres instance. -1. Click the **Connection Strings** tab in the project's sidenav. -1. Click the **Create connection string** button. -1. In the popup, provide a **Name** for the connection string and click **Create**. -1. Copy the connection string starting with `postgres://`, this is your direct connection string. - -Save the connection string, as you'll need it in step 3. - -## 2. Prepare your direct connection string - -In this step, you'll use the [direct connection string](/postgres/database/connecting-to-your-database) you obtained in step 1 to connect to your Prisma Postgres instance. - -Your direct connection string should look like this: - -```text -postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require -``` +## 2. Create a pgloader config -You'll use this connection string in the next step when configuring pgloader. - -## 3. Migrate your MySQL data to Prisma Postgres using pgloader - -Now that you have an active connection to your Prisma Postgres instance, you'll use [pgloader](https://pgloader.io/) to export data from your MySQL database to Prisma Postgres. - -Open a separate terminal window and create a `config.load` file: - -```bash -touch config.load -``` - -Open the `config.load` file in your preferred text editor and copy-paste the following configuration: +Create `config.load`: ```text title="config.load" LOAD DATABASE - FROM mysql://username:password@host:PORT/database_name - INTO postgres://__USER__:__PASSWORD__@db.prisma.io:5432/?sslmode=require + FROM mysql://USER:PASSWORD@HOST:PORT/DATABASE + INTO postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require -WITH quote identifiers, -- preserve table/column name case by quoting them +WITH quote identifiers, include drop, create tables, create indexes, reset sequences -ALTER SCHEMA 'database_name' RENAME TO 'public'; +ALTER SCHEMA 'DATABASE' RENAME TO 'public'; ``` -Make sure to update the following details in the `config.load` file: +## 3. Import into Prisma Postgres -- `FROM` url (MySQL database URL): - - Replace `username`, `password`, `host`, `PORT`, and `database_name` with the actual connection details for your MySQL database. - - Ensure that your connection string includes `useSSL=true` if SSL is required, for example: `mysql://username:password@host:PORT/database_name?useSSL=true`. Note that when using PlanetScale, appending `sslaccept=strict` will not work. -- `INTO` url (Postgres database URL): - - Update this with your direct connection string from above, replacing the `__USER__` and `__PASSWORD__` placeholders. -- Update the `database_name` in `ALTER SCHEMA 'database_name' RENAME TO 'public';` to exactly match the `database_name` in your MySQL connection string. +Run pgloader: -After saving the configuration file with your updated credentials, in the same terminal window, execute the following command: - -```bash +```shell pgloader config.load ``` -You should see a log similar to this, which confirms the successful migration of your data: - -```bash -LOG report summary reset - table name errors rows bytes total time -------------------------- --------- --------- --------- -------------- - fetch meta data 0 9 2.546s - Create Schemas 0 0 0.325s - Create SQL Types 0 0 0.635s - Create tables 0 6 5.695s - Set Table OIDs 0 3 0.328s -------------------------- --------- --------- --------- -------------- - public.post 0 8 0.5 kB 4.255s - public."user" 0 4 0.1 kB 2.775s -public._prisma_migrations 0 1 0.2 kB 4.278s -------------------------- --------- --------- --------- -------------- - COPY Threads Completion 0 4 5.095s - Index Build Completion 0 5 9.601s - Create Indexes 0 5 4.116s - Reset Sequences 0 2 4.540s - Primary Keys 0 3 2.917s - Create Foreign Keys 0 1 1.121s - Create Triggers 0 0 0.651s - Install Comments 0 0 0.000s -------------------------- --------- --------- --------- -------------- - Total import time ✓ 13 0.8 kB 28.042s -``` - -If you see output like this, it means your data has been successfully exported to your Prisma Postgres instance. +## 4. Add Prisma 8 - -You can also use [Prisma Studio](/guides/postgres/viewing-data#viewing-and-editing-data-in-prisma-studio) to verify whether the migration was successful: +From your app root, initialize Prisma 8: ```npm -npx prisma studio +npx prisma@latest orm init ``` -## 4. Configure your Prisma project for Prisma Postgres - -After migrating your data, you need to set up your Prisma project to work with Prisma Postgres. The steps differ depending on whether you were already using Prisma ORM. - -### If you **were not** previously using Prisma ORM - -Initialize Prisma in your project by running `npx prisma init` in your project directory. This creates a `prisma` folder with a `schema.prisma` file and `.env` file (if not already present). - -In the generated `.env` file, update `DATABASE_URL` to match your Prisma Postgres direct connection string that you received in [step 1](/prisma-postgres/import-from-existing-database-mysql#1-create-a-new-prisma-postgres-database): - -```text title=".env" no-copy -DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require" -``` - -[Introspect](/orm/prisma-schema/introspection) your newly migrated database by running: - -```npm -npx prisma db pull -``` - -This command updates your `schema.prisma` file with models representing your migrated tables, so you can start using [Prisma Client](/orm/prisma-client/setup-and-configuration/introduction) to query your data or [Prisma Migrate](/orm/prisma-migrate/getting-started) to manage future changes. - -Congratulations! You've successfully migrated your MySQL database to Prisma Postgres and configured your Prisma project. Your migration tutorial is now complete. - -:::note - -For a comprehensive guide on getting started with Prisma and Prisma Postgres, see [start from scratch with Prisma and Prisma Postgres](/prisma-orm/quickstart/prisma-postgres). - -::: - -### If you **were** already using Prisma ORM - -In your `schema.prisma` file, change the `provider` in the `datasource` block from `mysql` to `postgresql`: - -```prisma title="schema.prisma" -datasource db { - provider = "mysql" // [!code --] - provider = "postgres" // [!code ++] -} -``` - -In the generated `.env` file, update `DATABASE_URL` to match your Prisma Postgres direct connection string that you received in [step 1](/prisma-postgres/import-from-existing-database-mysql#1-create-a-new-prisma-postgres-database): - -```text title=".env" no-copy -DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require" -``` - -Introspect your newly migrated Prisma Postgres database and generate Prisma Client: +Choose PostgreSQL, set `DATABASE_URL` to the Prisma Postgres connection string, then infer and emit the contract: ```npm -npx prisma db pull +npx prisma@latest contract infer --output ./prisma/contract.prisma +npx prisma@latest contract emit +npx prisma@latest db sign ``` -This command refreshes your Prisma models based on the new database schema. - -If you were using [Prisma Migrate](/orm/prisma-migrate/getting-started) before: - -- Delete your existing `migrations` folder in the `prisma` directory. -- [Baseline your database](/orm/prisma-migrate/workflows/baselining#baselining-a-database) to begin creating new migrations. - -Congratulations! You've successfully migrated your MySQL database to Prisma Postgres and configured your Prisma project. Your migration tutorial is now complete. +## Next steps -If you encounter any issues during the migration, please don't hesitate to reach out to us on [Discord](https://pris.ly/discord?utm_source=docs&utm_medium=conclusion) or via [X](https://pris.ly/x?utm_source=docs&utm_medium=conclusion). +- 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 8 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/import-from-existing-database-postgresql.mdx b/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx index fa4ee25009..2d44851c7f 100644 --- a/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx +++ b/apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx @@ -1,189 +1,60 @@ --- title: Import from PostgreSQL -description: Learn how to import data from an existing PostgreSQL database into Prisma Postgres +description: 'Import an existing PostgreSQL database into Prisma Postgres, then use it with Prisma 8.' url: /prisma-postgres/import-from-existing-database-postgresql -metaTitle: Import from existing Postgres database into Prisma Postgres -metaDescription: Learn how to import data from an existing database into Prisma Postgres. +metaTitle: Import from PostgreSQL into Prisma Postgres for Prisma 8 +metaDescription: 'Import PostgreSQL data into Prisma Postgres, then connect Prisma 8 to the imported database.' --- -This guide provides step-by-step instructions for importing data from an existing PostgreSQL database into Prisma Postgres. - -You can accomplish this migration in three steps: - -1. Create a new Prisma Postgres database. -1. Export your existing data via `pg_dump`. -1. Import the previously exported data into Prisma Postgres via `pg_restore`. - -In the third step, you will be using a [direct connection](/postgres/database/connecting-to-your-database) to securely connect to your Prisma Postgres database to run `pg_restore`. +Move an existing PostgreSQL database into Prisma Postgres, then connect Prisma 8 to it. ## Prerequisites -- The connection URL to your existing PostgreSQL database -- A [Prisma Data Platform](https://console.prisma.io) account -- Node.js 18+ installed -- PostgreSQL CLI Tools (`pg_dump`, `pg_restore`) for creating and restoring backups - -:::info[Make sure your PostgreSQL tools match the Prisma Postgres version] - -Prisma Postgres runs PostgreSQL 17. Your `pg_dump` and `pg_restore` tools need to be version 17 to ensure compatibility. You can check your version by running `pg_dump --version` or `pg_restore --version`. - -::: - -## 1. Create a new Prisma Postgres database - -Follow these steps to create a new Prisma Postgres database: - -1. Log in to [Prisma Data Platform](https://console.prisma.io/) and open the Console. -1. In a [workspace](/console/concepts#workspace) of your choice, click the **New project** button. -1. Type a name for your project in the **Name** field, e.g. **hello-ppg**. -1. In the **Prisma Postgres** section, click the **Get started** button. -1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**. -1. Click the **Create project** button. - -Once your database is provisioned, obtain your direct connection string: - -1. Navigate to your active Prisma Postgres instance. -1. Click the **Connection Strings** tab in the project's sidenav. -1. Click the **Create connection string** button. -1. In the popup, provide a **Name** for the connection string and click **Create**. -1. Copy the connection string starting with `postgres://`, this is your direct connection string. - -Save the connection string, as you'll need it in step 3. - -## 2. Export data from your existing database - -In this step, you're going to export the data from your existing database and store it in a `.bak` file on your local machine. - -Make sure to have the connection URL for your existing database ready, it should be [structured](/orm/reference/connection-urls) like this: - -```text -postgresql://USER:PASSWORD@HOST:PORT/DATABASE -``` - -Expand below for provider-specific instructions that help you determine the right connection string: - - - - - - - - Make sure to select non-pooled connection string by switching off the **Connection pooling** toggle. - - The `sslmode` has to be set to `require` and appended to your Neon database URL for the command to work. - - The connection URL should look similar to this: +You need: - ```text - postgresql://USER:PASSWORD@YOUR-NEON-HOST/DATABASE?sslmode=require - ``` - - +- the connection URL for the PostgreSQL database you are importing from +- a Prisma Data Platform account +- PostgreSQL 17 CLI tools, including `pg_dump` and `pg_restore` +- Node.js 24 or newer - - Use a database connection URL that uses [Supavisor session mode](https://supabase.com/docs/guides/database/connecting-to-postgres#supavisor-session-mode). - - The connection URL should look similar to this: - ```text - postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres - ``` +## 1. Create a Prisma Postgres database - +Create a Prisma Postgres database from Console or with the CLI. Copy the direct connection string. You will use it for the restore and for `DATABASE_URL`. - +## 2. Export from PostgreSQL -Next, run the following command to export the data of your PostgreSQL database (replace the `__DATABASE_URL__` placeholder with your actual database connection URL): +Run `pg_dump` against the source database: -```bash -pg_dump \ - -Fc \ - -v \ - -d __DATABASE_URL__ \ - -n public \ - -f db_dump.bak +```shell +pg_dump -Fc -v -d "postgresql://USER:PASSWORD@HOST:PORT/DATABASE" -n public -f db_dump.bak ``` -Here's a quick overview of the CLI options that were used for this command: +## 3. Restore into Prisma Postgres -- `-Fc`: Uses the custom format for backups, recommended for `pg_restore` -- `-v`: Runs `pg_dump` in verbose mode -- `-d`: Specifies the database connection string -- `-n`: Specifies the target PostgreSQL schema -- `-f`: Specifies the output name for the backup file +Restore the dump with the direct Prisma Postgres connection string: -Running this command will create a backup file named `db_dump.bak` which you will use to restore the data into your Prisma Postgres database in the next step. - -## 3. Import data into Prisma Postgres - -In this section, you'll use your [direct connection string](/postgres/database/connecting-to-your-database) to connect to your Prisma Postgres instance and import data via `pg_restore`. - -Your direct connection string from step 1 should look like this: - -```text -postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require -``` - -Use the backup file from **Step 2** to restore data into your Prisma Postgres database with `pg_restore` by running this command (replace `__USER__`, `__PASSWORD__` with the values from your direct connection string): - -```bash -pg_restore \ - -h db.prisma.io \ - -p 5432 \ - -U __USER__ \ - -d postgres \ - -v \ - ./db_dump.bak \ -&& echo "-complete-" +```shell +pg_restore -d "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require" -v ./db_dump.bak ``` -When prompted, enter the `__PASSWORD__` from your direct connection string. +## 4. Add Prisma 8 -You can also use the full connection string format: - -```bash -pg_restore \ - -d "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require" \ - -v \ - ./db_dump.bak \ -&& echo "-complete-" -``` - -Once the command completes execution, you will have successfully imported the data from your existing PostgreSQL database into Prisma Postgres 🎉 - -To validate that the import worked, you can use [Prisma Studio](/guides/postgres/viewing-data#viewing-and-editing-data-in-prisma-studio). Either open it in the [Platform Console](https://console.prisma.io) by clicking the **Studio** tab in the left-hand sidenav in your project or run this command to launch Prisma Studio locally: +From your app root, initialize Prisma 8: ```npm -npx prisma studio -``` - -## 4. Update your application code to query Prisma Postgres - -### Scenario A: You are already using Prisma ORM - -If you're already using Prisma ORM, you need to update your database connection URL to point to your new Prisma Postgres instance. - -Update the `DATABASE_URL` in your `.env` file to match your Prisma Postgres direct connection string from step 1: - -```text title=".env" -DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require" +npx prisma@latest orm init ``` -Then, re-generate Prisma Client so that the updated environment variable takes effect: +Choose PostgreSQL, set `DATABASE_URL` to the Prisma Postgres connection string, then infer and emit the contract: ```npm -npx prisma generate +npx prisma@latest contract infer --output ./prisma/contract.prisma +npx prisma@latest contract emit +npx prisma@latest db sign ``` -Once this is done, you can run your application and it should work as before. - -:::tip - -For a complete guide on setting up Prisma ORM with Prisma Postgres from scratch, including driver adapter configuration and best practices, see the [Prisma ORM with Prisma Postgres quickstart](/prisma-orm/quickstart/prisma-postgres). - -::: - -### Scenario B: You are not yet using Prisma ORM - -If you are not yet using Prisma ORM, you'll need to go through the following steps to use Prisma Postgres from your application: - -1. Install the Prisma CLI and other required dependencies in your project -1. Introspect the database to generate a Prisma schema -1. Generate Prisma Client -1. Update the queries in your application to use Prisma ORM +## Next steps -You can find the detailed step-by-step instructions for this process in this guide: [Add Prisma ORM to an existing project](/prisma-orm/add-to-existing-project/prisma-postgres). +- Review the inferred contract before you rely on it in application code. +- Use the [PostgreSQL existing-project guide](/prisma-orm/add-to-existing-project/postgresql) for the first Prisma 8 query. +- Use the [full Prisma Postgres import guide](/prisma-postgres/import-from-existing-database-postgresql) for deeper migration details. diff --git a/apps/docs/content/docs/(index)/prisma-postgres/quickstart/meta.json b/apps/docs/content/docs/(index)/prisma-postgres/quickstart/meta.json index 36716edce9..0d9ae98fa4 100644 --- a/apps/docs/content/docs/(index)/prisma-postgres/quickstart/meta.json +++ b/apps/docs/content/docs/(index)/prisma-postgres/quickstart/meta.json @@ -1,4 +1,9 @@ { "title": "Quickstart", - "pages": ["prisma-next", "prisma-orm", "kysely", "drizzle-orm", "typeorm"] + "pages": [ + "prisma-orm", + "kysely", + "drizzle-orm", + "typeorm" + ] } diff --git a/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-next.mdx b/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-next.mdx deleted file mode 100644 index 4417f56dfc..0000000000 --- a/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-next.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Prisma 8 -description: Create a Prisma 8 app with Prisma Postgres. -url: /prisma-postgres/quickstart/prisma-next -metaTitle: 'Quickstart: Prisma 8 with Prisma Postgres' -metaDescription: Create a Prisma 8 app, create a Prisma Postgres database, initialize it, and run your first query. -badge: release-candidate ---- - -Create a Prisma 8 app backed by Prisma Postgres. - -## Quick start - -```npm -npx create-prisma@latest -``` - -Run this from a Node.js 24 or newer environment. When prompted, choose PostgreSQL. - -Setup adds a starter contract, creates `prisma-next.md`, installs project-level Prisma 8 skills for your coding agent, and adds package scripts for the database steps below. Choose the minimal template if you want the fastest first run, or a framework template when you want the first query wired into an app route or page. - -## 1. Create the database - -Create a Prisma Postgres database from the terminal and export its connection string. The generated scripts read the environment variable, not `.env`: - -```npm -npx create-db@latest -``` - -```bash -export DATABASE_URL="" -``` - -The command also prints a claim URL; open it within 24 hours to keep the database in your account. - -## 2. Initialize the database - -From the generated project directory, run `db:init` to apply the starter schema to Prisma Postgres and sign the database. - -```npm -npm run db:init -``` - -Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. - -## 3. Run the app - -Start the app and confirm the sample query runs successfully. - -```npm -npm run dev -``` - -Use the URL or terminal output shown by your template to confirm the sample query runs successfully. - -## Next steps - -- Open the generated contract and change the starter model. -- Use [Import from PostgreSQL](/v8/prisma-postgres/import-from-existing-database-postgresql) or [Import from MySQL](/v8/prisma-postgres/import-from-existing-database-mysql) when you want to move an existing database to Prisma Postgres. -- Use the [PostgreSQL existing-project guide](/v8/add-to-existing-project/postgresql) when your app already has a Prisma Postgres database. 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 e6a5430f12..1ad4ddc6ef 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 @@ -1,264 +1,59 @@ --- -title: Prisma ORM -description: Create a new TypeScript project from scratch by connecting Prisma ORM to Prisma Postgres and generating a Prisma Client for database access +title: Prisma 8 +description: Create a Prisma 8 app with Prisma Postgres. url: /prisma-postgres/quickstart/prisma-orm -metaTitle: 'Quickstart: Prisma Postgres with Prisma ORM (5 min)' -metaDescription: Set up Prisma Postgres in a new TypeScript project with Prisma ORM. Create the database, connect, and run your first type-safe queries. +metaTitle: 'Quickstart: Prisma 8 with Prisma Postgres' +metaDescription: 'Create a Prisma 8 app, create a Prisma Postgres database, initialize it, and run your first query.' --- -[Prisma Postgres](/postgres) is a fully managed PostgreSQL database that scales to zero and integrates smoothly with both Prisma ORM and Prisma Studio. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to Prisma Postgres using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database. +Create a Prisma 8 app backed by Prisma Postgres. -## Prerequisites - -## 1. Create a new project - -## 2. Install required dependencies - -Install the packages needed for this quickstart: - -```npm -npm install prisma @types/node --save-dev -npm install @prisma/client @prisma/adapter-pg dotenv -``` - -Here's what each package does: - -- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma migrate`, and `prisma generate` -- **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database -- **`dotenv`** - Loads environment variables from your `.env` file - -## 3. Configure ESM support - -Update `tsconfig.json` for ESM compatibility: - -```json title="tsconfig.json" -{ - "compilerOptions": { - "module": "ESNext", - "moduleResolution": "bundler", - "target": "ES2023", - "strict": true, - "esModuleInterop": true, - "ignoreDeprecations": "6.0" - } -} -``` - -Update `package.json` to enable ESM: - -```json title="package.json" -{ - "type": "module" // [!code ++] -} -``` - -## 4. Initialize Prisma ORM - -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +## Quick start ```npm -npx prisma init --output ../generated/prisma +npx create-prisma@latest ``` -:::info - -`prisma init` creates the Prisma scaffolding and a local `DATABASE_URL`. In the next step, replace that value with a direct `postgres://...` connection string from Prisma Postgres. - -::: +Run this from a Node.js 24 or newer environment. When prompted, choose PostgreSQL. -This command does a few things: +Setup adds a starter contract, creates `prisma-next.md`, installs project-level Prisma 8 skills for your coding agent, and adds package scripts for the database steps below. Choose the minimal template if you want the fastest first run, or a framework template when you want the first query wired into an app route or page. -- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection and schema models -- Creates a `.env` file in the root directory for environment variables -- Generates the Prisma Client in the `generated/prisma/` directory -- Creates a `prisma.config.ts` file for Prisma configuration - -The generated `prisma.config.ts` file looks like this: - -```typescript title="prisma.config.ts" -import "dotenv/config"; -import { defineConfig, env } from "prisma/config"; - -export default defineConfig({ - schema: "prisma/schema.prisma", - migrations: { - path: "prisma/migrations", - }, - datasource: { - url: env("DATABASE_URL"), - }, -}); -``` +## 1. Create the database -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: - -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} - -datasource db { - provider = "postgresql" -} -``` - -Create a Prisma Postgres database and replace the generated `DATABASE_URL` in your `.env` file with the `postgres://...` connection string from the CLI output: +Create a Prisma Postgres database from the terminal and export its connection string. The generated scripts read the environment variable, not `.env`: ```npm -npx create-db +npx create-db@latest ``` -## 5. Define your data model - -Open `prisma/schema.prisma` and add the following models: - -```prisma title="prisma/schema.prisma" -generator client { - provider = "prisma-client" - output = "../generated/prisma" -} - -datasource db { - provider = "postgresql" -} - -model User { // [!code ++] - id Int @id @default(autoincrement()) // [!code ++] - email String @unique // [!code ++] - name String? // [!code ++] - posts Post[] // [!code ++] -} // [!code ++] - -model Post { // [!code ++] - id Int @id @default(autoincrement()) // [!code ++] - title String // [!code ++] - content String? // [!code ++] - published Boolean @default(false) // [!code ++] - author User @relation(fields: [authorId], references: [id]) // [!code ++] - authorId Int // [!code ++] -} // [!code ++] +```bash +export DATABASE_URL="" ``` -## 6. Create and apply your first migration - -Create your first migration to set up the database tables: - -```npm -npx prisma migrate dev --name init -``` +The command also prints a claim URL; open it within 24 hours to keep the database in your account. -This command creates the database tables based on your schema. +## 2. Initialize the database -Now run the following command to generate the Prisma Client: +From the generated project directory, run `db:init` to apply the starter schema to Prisma Postgres and sign the database. ```npm -npx prisma generate +npm run db:init ``` -## 7. Instantiate Prisma Client - -Now that you have all the dependencies installed, you can instantiate Prisma Client. You need to pass an instance of the Prisma ORM driver adapter adapter to the `PrismaClient` constructor: - -```typescript title="lib/prisma.ts" -import "dotenv/config"; -import { PrismaPg } from "@prisma/adapter-pg"; -import { PrismaClient } from "../generated/prisma/client"; - -const connectionString = `${process.env.DATABASE_URL}`; - -const adapter = new PrismaPg({ connectionString }); -const prisma = new PrismaClient({ adapter }); - -export { prisma }; -``` - -:::tip - -If you need to query your database via HTTP from an edge runtime (Cloudflare Workers, Vercel Edge Functions, etc.), use the [Prisma Postgres serverless driver](/postgres/database/serverless-driver#use-with-prisma-orm). - -::: +Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. -## 8. Write your first query +## 3. Run the app -Create a `script.ts` file to test your setup: - -```typescript title="script.ts" -import { prisma } from "./lib/prisma"; - -async function main() { - // Create a new user with a post - const user = await prisma.user.create({ - data: { - name: "Alice", - email: "alice@prisma.io", - posts: { - create: { - title: "Hello World", - content: "This is my first post!", - published: true, - }, - }, - }, - include: { - posts: true, - }, - }); - console.log("Created user:", user); - - // Fetch all users with their posts - const allUsers = await prisma.user.findMany({ - include: { - posts: true, - }, - }); - console.log("All users:", JSON.stringify(allUsers, null, 2)); -} - -main() - .then(async () => { - await prisma.$disconnect(); - }) - .catch(async (e) => { - console.error(e); - await prisma.$disconnect(); - process.exit(1); - }); -``` - -Run the script: +Start the app and confirm the sample query runs successfully. ```npm -npx tsx script.ts +npm run dev ``` -You should see the created user and all users printed to the console! - -## 9. Explore your data with Prisma Studio - -```shell -npx prisma studio -``` +Use the URL or terminal output shown by your template to confirm the sample query runs successfully. ## Next steps -You've successfully set up Prisma ORM. Here's what you can explore next: - -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more -- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) - -:::info[Deploy to Compute] - -Want to run this app in the cloud? Deploy it to [Prisma Compute](/compute), which runs your app next to your Prisma Postgres database. Follow [Deploy your first app](/prisma-compute/deploy). - -::: - -## More info - -- [Prisma Postgres documentation](/postgres) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- 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. diff --git a/apps/docs/content/docs/(index)/v7/getting-started.mdx b/apps/docs/content/docs/(index)/v7/getting-started.mdx new file mode 100644 index 0000000000..47510de520 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/getting-started.mdx @@ -0,0 +1,78 @@ +--- +title: Prisma 7 setup paths +description: 'Choose the fastest path to start using Prisma ORM 7, Prisma Postgres, or Prisma Compute in a new or existing TypeScript project.' +url: /v7/getting-started +metaTitle: Prisma 7 getting started +metaDescription: 'Choose the fastest Prisma 7 setup path. Quickstarts and existing-project guides for Prisma ORM 7, Prisma Postgres, and Prisma Compute, plus an agent prompt.' +--- + +Prisma 7 remains fully supported; [Prisma 8](/getting-started) is the current release of Prisma ORM. Scaffold a new Prisma 7 app with `npx create-prisma@stable`, or add it to an existing project with `npx prisma@7.9.1 init`. This page collects the Prisma 7 starting points: start a new project, add Prisma to an existing one, then deploy. + +:::note + +Starting a new project? [Prisma 8](/prisma-orm) is the recommended path for new apps. It is the current major version of Prisma ORM. To start with Prisma 8, see the [getting started page](/). + +::: + +## Start a new project + +The recommended path is the [Quickstart with Prisma Postgres](/v7/prisma-orm/quickstart/prisma-postgres): it provisions a managed PostgreSQL database for you and gets you from install to first query in about five minutes. + +Working with a specific database instead? + +- [Quickstart with PostgreSQL](/v7/prisma-orm/quickstart/postgresql) +- [Quickstart with SQLite](/v7/prisma-orm/quickstart/sqlite) for a lightweight local setup +- [Quickstart with MySQL](/v7/prisma-orm/quickstart/mysql) +- [Quickstart with MongoDB](/v7/prisma-orm/quickstart/mongodb) + +## Add Prisma to an existing project + +Use these guides if you already have an application or database and want to add Prisma ORM: + +- [Add Prisma ORM to an existing PostgreSQL project](/v7/prisma-orm/add-to-existing-project/postgresql) +- [Add Prisma ORM to an existing MySQL project](/v7/prisma-orm/add-to-existing-project/mysql) +- [Add Prisma ORM to an existing SQLite project](/v7/prisma-orm/add-to-existing-project/sqlite) +- [Add Prisma ORM to an existing MongoDB project](/v7/prisma-orm/add-to-existing-project/mongodb) +- [Add Prisma ORM to an existing Prisma Postgres project](/v7/prisma-orm/add-to-existing-project/prisma-postgres) + +## Deploy to Prisma Compute + +Once your app runs locally, [Prisma Compute](/compute) (currently in Public Beta) runs it next to your Prisma Postgres database: + +1. Sign in with `npx @prisma/cli@latest auth login`. +2. Run `npx @prisma/cli@latest app deploy` from your app directory to get a live URL, adding `--env .env` so environment variables like `DATABASE_URL` reach the deployment. +3. `--env .env` applies to that one deployment. Persist variables for future deployments with `npx @prisma/cli@latest project env add --file .env --role production`. See [environment variables](/compute/environment-variables). +4. Keep deploying from the CLI, or [connect GitHub](/compute/github) to deploy on push. + +`app deploy` is part of the earlier beta CLI (`@prisma/cli@latest`). The Prisma 8 CLI (`prisma@latest`) that the [Compute docs](/compute) describe deploys through a git push, the Console, or [Prisma Composer](/composer) instead. Both CLIs talk to the same platform. For the git-push path, follow the [deploy quickstart](/prisma-compute/deploy). + +## Use with your agent + +To hand the full Prisma 7 stack to your coding agent, copy this prompt. The commands below install Prisma 7, not Prisma 8: + + + +```text +Set up the Prisma 7 stack: Prisma ORM 7, Prisma Postgres, and Prisma Compute. + +If I have not told you which framework template to use, stop and ask. + +1. Scaffold a new app non-interactively: `npx create-prisma@stable --name my-app --template [next|hono|nuxt|astro|nest|svelte|tanstack-start|elysia|turborepo] --provider postgresql --no-deploy`. Or add Prisma 7 to an existing app with `npx prisma@7.9.1 init --db`, which provisions a Prisma Postgres database; before that, check `npx @prisma/cli@latest auth whoami` and stop and ask me to run `auth login` if I am not signed in, because provisioning can open a browser. +2. From the project directory, define a small schema in `prisma/schema.prisma`, then run `npx prisma migrate dev --name init` and `npx prisma generate`. If migrate dev asks to reset the database, stop and ask me first. +3. Update the seed and app code to query the schema, and verify locally with the dev script. +4. Deploy with Prisma Compute: check `npx @prisma/cli@latest auth whoami` first. If I am not signed in, stop and ask me to run `npx @prisma/cli@latest auth login`, because that step opens a browser. Then run `npx @prisma/cli@latest app deploy --create-project my-app --env .env` so DATABASE_URL reaches the deployment, and verify the deployed URL with curl. + +Current docs: https://www.prisma.io/docs/v7/getting-started.md and https://www.prisma.io/docs/llms.txt. +``` + + + +## Next steps + +After setup, these pages are usually the next ones people need: + +- [Prisma Client overview](/orm/v7/prisma-client) +- [Prisma Migrate getting started](/orm/v7/prisma-migrate/getting-started) +- [Prisma schema overview](/orm/v7/prisma-schema/overview) +- [Open Prisma Studio](/studio/getting-started) to inspect and edit data visually +- [Review pricing](https://www.prisma.io/pricing) if you're evaluating Prisma Postgres for a team diff --git a/apps/docs/content/docs/(index)/v7/meta.json b/apps/docs/content/docs/(index)/v7/meta.json new file mode 100644 index 0000000000..2ac405c8bd --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/meta.json @@ -0,0 +1,10 @@ +{ + "title": "v7", + "pages": [ + "getting-started", + "---Prisma ORM---", + "...prisma-orm", + "---Prisma Postgres---", + "...prisma-postgres" + ] +} diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/cockroachdb.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/cockroachdb.mdx similarity index 84% rename from apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/cockroachdb.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/cockroachdb.mdx index 30a0cd3f2f..dcc00fac22 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/cockroachdb.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/cockroachdb.mdx @@ -1,7 +1,7 @@ --- title: CockroachDB description: 'Add Prisma ORM to an existing TypeScript project with CockroachDB and learn database introspection, baselining, and querying' -url: /prisma-orm/add-to-existing-project/cockroachdb +url: /v7/prisma-orm/add-to-existing-project/cockroachdb metaTitle: How to add Prisma ORM to an existing project using CockroachDB (15 min) metaDescription: 'Add Prisma ORM to an existing TypeScript project with CockroachDB and learn database introspection, baselining, and querying.' --- @@ -15,22 +15,22 @@ metaDescription: 'Add Prisma ORM to an existing TypeScript project with Cockroac Navigate to your existing project directory and install the required dependencies: ```npm -npm install prisma @types/node @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install prisma@7.9.1 @types/node @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` Here's what each package does: - **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db pull`, and `prisma generate` - **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database (CockroachDB is PostgreSQL-compatible) +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database (CockroachDB is PostgreSQL-compatible) - **`pg`** - The node-postgres database driver - **`@types/pg`** - TypeScript type definitions for node-postgres - **`dotenv`** - Loads environment variables from your `.env` file ## 2. Initialize Prisma ORM -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider cockroachdb --output ../generated/prisma @@ -59,7 +59,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -80,7 +80,7 @@ Update the `.env` file with your CockroachDB connection URL: DATABASE_URL="postgresql://user:password@host:26257/mydb?sslmode=require" ``` -The [format of the connection URL](/orm/reference/connection-urls) for CockroachDB looks as follows: +The [format of the connection URL](/orm/v7/reference/connection-urls) for CockroachDB looks as follows: ``` postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require @@ -102,7 +102,7 @@ After introspection, your Prisma schema will contain models that represent your ## 5. Baseline your database -To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/prisma-migrate/getting-started). +To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/v7/prisma-migrate/getting-started). First, create a `migrations` directory: @@ -236,16 +236,16 @@ Explore the options suggested by [CockroachDB](https://www.cockroachlabs.com/blo You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [CockroachDB database connector](/orm/core-concepts/supported-databases/postgresql#cockroachdb) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) -- [Prisma Migrate](/orm/prisma-migrate) +- [CockroachDB database connector](/orm/v7/core-concepts/supported-databases/postgresql#cockroachdb) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) +- [Prisma Migrate](/orm/v7/prisma-migrate) diff --git a/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/meta.json b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/meta.json new file mode 100644 index 0000000000..d0d0a4e667 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/meta.json @@ -0,0 +1,13 @@ +{ + "title": "Add to Existing Project", + "pages": [ + "prisma-postgres", + "sqlite", + "postgresql", + "mysql", + "sql-server", + "planetscale", + "cockroachdb", + "mongodb" + ] +} diff --git a/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/mongodb.mdx new file mode 100644 index 0000000000..cdf73e0c58 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/mongodb.mdx @@ -0,0 +1,326 @@ +--- +title: MongoDB +description: Add Prisma ORM to an existing TypeScript project with MongoDB and learn database introspection and querying +url: /v7/prisma-orm/add-to-existing-project/mongodb +metaTitle: How to add Prisma ORM to an existing project using MongoDB (15 min) +metaDescription: Add Prisma ORM to an existing TypeScript project with MongoDB and learn database introspection and querying. +--- + +[MongoDB](https://www.mongodb.com/) is a popular document-based NoSQL database known for its flexibility, scalability, and developer-friendly features. In this guide, you will learn how to add Prisma ORM to an existing TypeScript project, connect it to MongoDB, introspect your existing database schema, and start querying with type-safe Prisma Client. + +:::warning[MongoDB support for Prisma ORM v7] + +**MongoDB support for Prisma ORM v7 is coming in the near future.** In the meantime, please use **Prisma ORM v6.19** (the latest v6 release) when working with MongoDB. + +This guide uses Prisma ORM v6.19 to ensure full compatibility with MongoDB. + +::: + +:::tip + +If you're migrating to Prisma ORM from Mongoose, see our [Migrate from Mongoose guide](/guides/switch-to-prisma-orm/from-mongoose). + +::: + +## Prerequisites + +In order to successfully complete this guide, you need: + +- [Node.js](https://nodejs.org/en/) installed on your machine (see [system requirements](/guides/upgrade-prisma-orm/v6#minimum-supported-nodejs-versions) for officially supported versions) +- An existing TypeScript project with a `package.json` file +- Access to a MongoDB 4.2+ server with a replica set deployment. We recommend using [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). + +:::warning + +The MongoDB database connector uses transactions to support nested writes. Transactions **require** a [replica set](https://www.mongodb.com/docs/manual/tutorial/deploy-replica-set/) deployment. The easiest way to deploy a replica set is with [Atlas](https://www.mongodb.com/docs/atlas/getting-started/). It's free to get started. + +::: + +Make sure you have your database [connection URL](/orm/v7/reference/connection-urls) (that includes your authentication credentials) at hand! + +:::note + +If your project contains multiple directories with `package.json` files (e.g., `frontend`, `backend`, etc.), note that Prisma ORM is specifically designed for use in the API/backend layer. To set up Prisma, navigate to the appropriate backend directory containing the relevant `package.json` file and configure Prisma there. + +::: + +## 1. Set up Prisma ORM + +Navigate to your existing project directory and install the required dependencies: + +```npm +npm install prisma@6.19 @types/node --save-dev +npm install @prisma/client@6.19 dotenv +``` + +Here's what each package does: + +- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db pull`, and `prisma generate` +- **`@prisma/client`** - The Prisma Client library for querying your database +- **`dotenv`** - Loads environment variables from your `.env` file + +:::info[Why Prisma v6.19?] + +This is the latest stable version of Prisma ORM v6 that fully supports MongoDB. MongoDB support for Prisma ORM v7 is coming soon. + +You can also install `prisma@6` and `@prisma/client@6` to automatically get the latest v6 release. + +::: + +## 2. Initialize Prisma ORM + +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: + +```npm +npx prisma init --datasource-provider mongodb --output ../generated/prisma +``` + +This command does a few things: + +- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection configuration +- Creates a `.env` file in the root directory for environment variables +- Creates a `prisma.config.ts` file for Prisma configuration + +The generated `prisma.config.ts` file looks like this: + +```typescript title="prisma.config.ts" +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + engine: "classic", + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +Add `dotenv` to `prisma.config.ts` so that Prisma can load environment variables from your `.env` file: + +```typescript title="prisma.config.ts" +import "dotenv/config"; // [!code ++] +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + engine: "classic", + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "mongodb" + url = env("DATABASE_URL") +} +``` + +## 3. Connect your database + +Update the `.env` file with your MongoDB connection URL: + +```text title=".env" +DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/mydb" +``` + +For MongoDB Atlas, the connection URL format is: + +``` +mongodb+srv://USERNAME:PASSWORD@CLUSTER.mongodb.net/DATABASE +``` + +Self-hosted MongoDB connection URL format: + +``` +mongodb://USERNAME:PASSWORD@HOST:PORT/DATABASE +``` + +Connection URL components: + +- **`USERNAME`**: Your database user name +- **`PASSWORD`**: Your database user password +- **`HOST`**: The host where [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod/#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos/#mongodb-binary-bin.mongos) is running +- **`PORT`**: The port where your database server is running (typically `27017`) +- **`DATABASE`**: The name of your database + +:::tip + +For MongoDB Atlas, you can manually append the database name to the connection URL, as Atlas doesn't include it by default. + +::: + +### Troubleshooting connection issues + +- **Authentication failed** — If you see a `SCRAM failure: Authentication failed` error, [add `?authSource=admin`](https://github.com/prisma/prisma/discussions/9994#discussioncomment-1562283) to the end of your connection string. +- **Empty database name** — If you see an `Error code 8000 (AtlasError): empty database name not allowed` error, append the database name to your connection URL. See this [GitHub issue](https://github.com/prisma/web/issues/5562) for details. + +## 4. Introspect your database + +Run the following command to introspect your existing database: + +```npm +npx prisma db pull +``` + +This command: + +- Reads the `DATABASE_URL` from your `.env` file +- Connects to your MongoDB database +- Samples documents in your collections to infer the schema +- Generates Prisma models in your `schema.prisma` file + +![Introspect your database with Prisma ORM](/img/getting-started/prisma-db-pull-generate-schema.png) + +:::info + +**MongoDB introspection limitations:** Prisma introspects MongoDB by sampling documents. You may need to manually: + +- Add relation fields using the `@relation` attribute +- Adjust field types if the sampling didn't capture all variations +- Add indexes and constraints not detected during introspection + +::: + +## 5. Generate Prisma ORM types + +Generate Prisma Client based on your introspected schema: + +```npm +npx prisma generate +``` + +This creates a type-safe Prisma Client tailored to your database schema in the `generated/prisma` directory. + +## 6. Instantiate Prisma Client + +Create a utility file to instantiate Prisma Client: + +```typescript title="lib/prisma.ts" +import "dotenv/config"; +import { PrismaClient } from "../generated/prisma/client"; + +const prisma = new PrismaClient(); + +export { prisma }; +``` + +## 7. Query your database + +Now you can use Prisma Client to query your database. Create a `script.ts` file: + +```typescript title="script.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + // Example: Fetch all records from a collection + // Replace 'user' with your actual model name + const allUsers = await prisma.user.findMany(); + console.log("All users:", JSON.stringify(allUsers, null, 2)); +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Run the script: + +```npm +npx tsx script.ts +``` + +## 8. Evolve your schema + +MongoDB doesn't support migrations like relational databases. Instead, use `db push` to sync schema changes: + +### 8.1. Update your Prisma schema file + +Modify your Prisma schema file with the changes you want. For example, add a new model: + +```prisma title="prisma/schema.prisma" +model Post { // [!code ++] + id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] + title String // [!code ++] + content String? // [!code ++] + published Boolean @default(false) // [!code ++] + authorId String @db.ObjectId // [!code ++] + author User @relation(fields: [authorId], references: [id]) // [!code ++] +} // [!code ++] + +model User { // [!code ++] + id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] + email String @unique // [!code ++] + name String? // [!code ++] + posts Post[] // [!code ++] +} // [!code ++] +``` + +:::info + +In MongoDB, the `id` field is mapped to `_id` and uses `@db.ObjectId` type. Relations use `String` type with `@db.ObjectId` annotation. + +::: + +### 8.2. Push the changes to your database + +```npm +npx prisma db push +``` + +This command: + +- Applies schema changes to your MongoDB database +- Automatically regenerates Prisma Client + +:::info[Why `db push` instead of migrations?] + +MongoDB uses a flexible schema model. Prisma Migrate (which creates migration files) is not supported for MongoDB. Always use `prisma db push` to sync your schema changes. + +::: + +## 9. Explore your data + +You can use [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), the MongoDB shell, or MongoDB Compass to view and manage your data. + +:::warning + +[Prisma Studio](/studio) does not currently support MongoDB. Support may be added in a future release. See [Databases supported by Prisma Studio](/studio#supported-databases) for more information. + +::: + +## Next steps + +You've successfully set up Prisma ORM. Here's what you can explore next: + +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more +- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) + +## More info + +- [MongoDB database connector](/orm/v7/core-concepts/supported-databases/mongodb) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mysql.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/mysql.mdx similarity index 87% rename from apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mysql.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/mysql.mdx index 520e472c73..b8b823f67e 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mysql.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/mysql.mdx @@ -1,7 +1,7 @@ --- title: MySQL description: 'Add Prisma ORM to an existing TypeScript project with MySQL and learn database introspection, baselining, and querying' -url: /prisma-orm/add-to-existing-project/mysql +url: /v7/prisma-orm/add-to-existing-project/mysql metaTitle: How to add Prisma ORM to an existing project using MySQL (15 min) metaDescription: 'Add Prisma ORM to an existing TypeScript project with MySQL and learn database introspection, baselining, and querying.' --- @@ -15,8 +15,8 @@ metaDescription: 'Add Prisma ORM to an existing TypeScript project with MySQL an Navigate to your existing project directory and install the required dependencies: ```npm -npm install prisma @types/node --save-dev -npm install @prisma/client @prisma/adapter-mariadb dotenv +npm install prisma@7.9.1 @types/node --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-mariadb dotenv ``` Here's what each package does: @@ -28,7 +28,7 @@ Here's what each package does: ## 2. Initialize Prisma ORM -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider mysql --output ../generated/prisma @@ -57,7 +57,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -106,7 +106,7 @@ After introspection, your Prisma schema will contain models that represent your ## 5. Baseline your database -To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/prisma-migrate/getting-started). +To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/v7/prisma-migrate/getting-started). First, create a `migrations` directory: @@ -242,15 +242,15 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [MySQL database connector](/orm/core-concepts/supported-databases/mysql) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) -- [Prisma Migrate](/orm/prisma-migrate) +- [MySQL database connector](/orm/v7/core-concepts/supported-databases/mysql) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) +- [Prisma Migrate](/orm/v7/prisma-migrate) diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/planetscale.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/planetscale.mdx similarity index 87% rename from apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/planetscale.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/planetscale.mdx index b672746e46..98e8879370 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/planetscale.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/planetscale.mdx @@ -1,7 +1,7 @@ --- title: PlanetScale description: Add Prisma ORM to an existing TypeScript project with PlanetScale and learn database introspection and querying -url: /prisma-orm/add-to-existing-project/planetscale +url: /v7/prisma-orm/add-to-existing-project/planetscale metaTitle: How to add Prisma ORM to an existing project using PlanetScale MySQL (15 min) metaDescription: Add Prisma ORM to an existing TypeScript project with PlanetScale MySQL and learn database introspection and querying. --- @@ -17,20 +17,20 @@ Navigate to your existing project directory and install the required dependencie ### MySQL ```npm -npm install prisma @types/node --save-dev -npm install @prisma/client @prisma/adapter-planetscale undici dotenv +npm install prisma@7.9.1 @types/node --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-planetscale undici dotenv ``` ### Postgres ```npm -npm install prisma @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install prisma@7.9.1 @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` ## 2. Initialize Prisma ORM -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ### MySQL @@ -67,7 +67,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" tab="MySQL" generator client { @@ -264,15 +264,15 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [PlanetScale database connector](/orm/core-concepts/supported-databases/mysql#planetscale) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) +- [PlanetScale database connector](/orm/v7/core-concepts/supported-databases/mysql#planetscale) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) - [PlanetScale branching workflow](https://planetscale.com/docs/concepts/branching) diff --git a/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/postgresql.mdx new file mode 100644 index 0000000000..0e61f438fc --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/postgresql.mdx @@ -0,0 +1,246 @@ +--- +title: PostgreSQL +description: 'Add Prisma ORM to an existing TypeScript project with PostgreSQL and learn database introspection, baselining, and querying' +url: /v7/prisma-orm/add-to-existing-project/postgresql +metaTitle: How to add Prisma ORM to an existing project using PostgreSQL (15 min) +metaDescription: 'Add Prisma ORM to an existing TypeScript project with PostgreSQL and learn database introspection, baselining, and querying.' +--- + +[PostgreSQL](https://www.postgresql.org/) is a popular open-source relational database known for its reliability, feature robustness, and performance. In this guide, you will learn how to add Prisma ORM to an existing TypeScript project, connect it to PostgreSQL, introspect your existing database schema, and start querying with type-safe Prisma Client. + +## Prerequisites + +## 1. Set up Prisma ORM + +Navigate to your existing project directory and install the required dependencies: + +```npm +npm install prisma@7.9.1 @types/node @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv +``` + +Here's what each package does: + +- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db pull`, and `prisma generate` +- **`@prisma/client`** - The Prisma Client library for querying your database +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database +- **`pg`** - The node-postgres database driver +- **`@types/pg`** - TypeScript type definitions for node-postgres +- **`dotenv`** - Loads environment variables from your `.env` file + +## 2. Initialize Prisma ORM + +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: + +```npm +npx prisma init --datasource-provider postgresql --output ../generated/prisma +``` + +This command does a few things: + +- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection configuration +- Creates a `.env` file in the root directory for environment variables +- Creates a `prisma.config.ts` file for Prisma configuration + +The generated `prisma.config.ts` file looks like this: + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "postgresql" +} +``` + +## 3. Connect your database + +Update the `.env` file with your PostgreSQL connection URL: + +```text title=".env" +DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public" +``` + +The [format of the connection URL](/orm/v7/reference/connection-urls) for PostgreSQL looks as follows: + +``` +postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA +``` + +## 4. Introspect your database + +Run the following command to introspect your existing database: + +```npm +npx prisma db pull +``` + +This command reads the `DATABASE_URL` environment variable, connects to your database, and introspects the database schema. It then translates the database schema from SQL into a data model in your Prisma schema. + +![Introspect your database with Prisma ORM](/img/getting-started/prisma-db-pull-generate-schema.png) + +After introspection, your Prisma schema will contain models that represent your existing database tables. + +## 5. Baseline your database + +To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/v7/prisma-migrate/getting-started). + +First, create a `migrations` directory: + +```bash +mkdir -p prisma/migrations/0_init +``` + +Next, generate the migration file with `prisma migrate diff`: + +```npm +npx prisma migrate diff --from-empty --to-schema prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql +``` + +Review the generated migration file to ensure it matches your database schema. + +Then, mark the migration as applied: + +```npm +npx prisma migrate resolve --applied 0_init +``` + +You now have a baseline for your current database schema. + +## 6. Generate Prisma ORM types + +Generate Prisma Client based on your introspected schema: + +```npm +npx prisma generate +``` + +This creates a type-safe Prisma Client tailored to your database schema in the `generated/prisma` directory. + +## 7. Instantiate Prisma Client + +Create a utility file to instantiate Prisma Client. You need to pass an instance of the Prisma ORM driver adapter adapter to the `PrismaClient` constructor: + +```typescript title="lib/prisma.ts" +import "dotenv/config"; +import { PrismaPg } from "@prisma/adapter-pg"; +import { PrismaClient } from "../generated/prisma/client"; + +const connectionString = `${process.env.DATABASE_URL}`; + +const adapter = new PrismaPg({ connectionString }); +const prisma = new PrismaClient({ adapter }); + +export { prisma }; +``` + +## 8. Query your database + +Now you can use Prisma Client to query your database. Create a `script.ts` file: + +```typescript title="script.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + // Example: Fetch all records from a table + // Replace 'user' with your actual model name + const allUsers = await prisma.user.findMany(); + console.log("All users:", JSON.stringify(allUsers, null, 2)); +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Run the script: + +```npm +npx tsx script.ts +``` + +## 9. Evolve your schema + +To make changes to your database schema: + +### 9.1. Update your Prisma schema file + +Update your Prisma schema file to reflect the changes you want to make to your database schema. For example, add a new model: + +```prisma title="prisma/schema.prisma" +model Post { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + title String // [!code ++] + content String? // [!code ++] + published Boolean @default(false) // [!code ++] + authorId Int // [!code ++] + author User @relation(fields: [authorId], references: [id]) // [!code ++] +} // [!code ++] + +model User { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + email String @unique // [!code ++] + name String? // [!code ++] + posts Post[] // [!code ++] +} // [!code ++] +``` + +### 9.2. Create and apply a migration: + +```npm +npx prisma migrate dev --name your_migration_name +``` + +This command will: + +- Create a new SQL migration file +- Apply the migration to your database +- Regenerate Prisma Client + +## 10. Explore your data with Prisma Studio + +```shell +npx prisma studio +``` + +## Next steps + +You've successfully set up Prisma ORM. Here's what you can explore next: + +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more +- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) + +## More info + +- [PostgreSQL database connector](/orm/v7/core-concepts/supported-databases/postgresql) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) +- [Prisma Migrate](/orm/v7/prisma-migrate) diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/prisma-postgres.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/prisma-postgres.mdx similarity index 86% rename from apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/prisma-postgres.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/prisma-postgres.mdx index 0d8208f946..72e24a2bbb 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/prisma-postgres.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/prisma-postgres.mdx @@ -1,7 +1,7 @@ --- title: Prisma Postgres description: 'Add Prisma ORM to an existing TypeScript project with Prisma Postgres and learn database introspection, baselining, and querying' -url: /prisma-orm/add-to-existing-project/prisma-postgres +url: /v7/prisma-orm/add-to-existing-project/prisma-postgres metaTitle: How to add Prisma ORM to an existing project using Prisma Postgres (15 min) metaDescription: 'Add Prisma ORM to an existing TypeScript project with Prisma Postgres and learn database introspection, baselining, and querying.' --- @@ -15,22 +15,22 @@ metaDescription: 'Add Prisma ORM to an existing TypeScript project with Prisma P Navigate to your existing project directory and install the required dependencies: ```npm -npm install prisma @types/node @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install prisma@7.9.1 @types/node @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` Here's what each package does: - **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db pull`, and `prisma generate` - **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database - **`pg`** - The node-postgres database driver - **`@types/pg`** - TypeScript type definitions for node-postgres - **`dotenv`** - Loads environment variables from your `.env` file ## 2. Initialize Prisma ORM -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider postgresql --output ../generated/prisma @@ -59,7 +59,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -98,7 +98,7 @@ After introspection, your Prisma schema will contain models that represent your ## 5. Baseline your database -To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/prisma-migrate/getting-started). +To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/v7/prisma-migrate/getting-started). First, create a `migrations` directory: @@ -234,15 +234,15 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info - [Prisma Postgres documentation](/postgres) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) -- [Prisma Migrate](/orm/prisma-migrate) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) +- [Prisma Migrate](/orm/v7/prisma-migrate) diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/sql-server.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/sql-server.mdx similarity index 87% rename from apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/sql-server.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/sql-server.mdx index 300431b0f5..1f57ef44a3 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/sql-server.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/sql-server.mdx @@ -1,7 +1,7 @@ --- title: SQL Server description: 'Add Prisma ORM to an existing TypeScript project with SQL Server and learn database introspection, baselining, and querying' -url: /prisma-orm/add-to-existing-project/sql-server +url: /v7/prisma-orm/add-to-existing-project/sql-server metaTitle: How to add Prisma ORM to an existing project using SQL Server (15 min) metaDescription: 'Add Prisma ORM to an existing TypeScript project with SQL Server and learn database introspection, baselining, and querying.' --- @@ -15,8 +15,8 @@ metaDescription: 'Add Prisma ORM to an existing TypeScript project with SQL Serv Navigate to your existing project directory and install the required dependencies: ```npm -npm install prisma @types/node @types/mssql --save-dev -npm install @prisma/client @prisma/adapter-mssql dotenv +npm install prisma@7.9.1 @types/node @types/mssql --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-mssql dotenv ``` Here's what each package does: @@ -29,7 +29,7 @@ Here's what each package does: ## 2. Initialize Prisma ORM -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider sqlserver --output ../generated/prisma @@ -58,7 +58,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -106,7 +106,7 @@ After introspection, your Prisma schema will contain models that represent your ## 5. Baseline your database -To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/prisma-migrate/getting-started). +To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/v7/prisma-migrate/getting-started). First, create a `migrations` directory: @@ -250,15 +250,15 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [SQL Server database connector](/orm/core-concepts/supported-databases/sql-server) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) -- [Prisma Migrate](/orm/prisma-migrate) +- [SQL Server database connector](/orm/v7/core-concepts/supported-databases/sql-server) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) +- [Prisma Migrate](/orm/v7/prisma-migrate) diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/sqlite.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/sqlite.mdx similarity index 92% rename from apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/sqlite.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/sqlite.mdx index 813fb56ee2..87f1e976ba 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/sqlite.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/add-to-existing-project/sqlite.mdx @@ -1,7 +1,7 @@ --- title: SQLite description: 'Add Prisma ORM to an existing TypeScript project with SQLite and learn database introspection, baselining, and querying' -url: /prisma-orm/add-to-existing-project/sqlite +url: /v7/prisma-orm/add-to-existing-project/sqlite metaTitle: How to add Prisma ORM to an existing project using SQLite (15 min) metaDescription: 'Add Prisma ORM to an existing TypeScript project with SQLite and learn database introspection, baselining, and querying.' --- @@ -15,8 +15,8 @@ metaDescription: 'Add Prisma ORM to an existing TypeScript project with SQLite a Navigate to your existing project directory and install the required dependencies: ```npm -npm install prisma @types/node @types/better-sqlite3 --save-dev -npm install @prisma/client @prisma/adapter-better-sqlite3 dotenv +npm install prisma@7.9.1 @types/node @types/better-sqlite3 --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-better-sqlite3 dotenv ``` Here's what each package does: @@ -29,7 +29,7 @@ Here's what each package does: ## 2. Initialize Prisma ORM -Set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider sqlite --output ../generated/prisma @@ -58,7 +58,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -101,7 +101,7 @@ After introspection, your Prisma schema will contain models that represent your ## 5. Baseline your database -To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/prisma-migrate/getting-started). +To use Prisma Migrate with your existing database, you need to [baseline your database](/orm/v7/prisma-migrate/getting-started). First, create a `migrations` directory: @@ -266,7 +266,7 @@ This command: ## Next steps -- [SQLite database connector](/orm/core-concepts/supported-databases/sqlite) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database introspection](/orm/prisma-schema/introspection) -- [Prisma Migrate](/orm/prisma-migrate) +- [SQLite database connector](/orm/v7/core-concepts/supported-databases/sqlite) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database introspection](/orm/v7/prisma-schema/introspection) +- [Prisma Migrate](/orm/v7/prisma-migrate) diff --git a/apps/docs/content/docs/(index)/v7/prisma-orm/meta.json b/apps/docs/content/docs/(index)/v7/prisma-orm/meta.json new file mode 100644 index 0000000000..1ee958a0a6 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Prisma ORM", + "defaultOpen": true, + "pages": ["quickstart", "add-to-existing-project"] +} diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/cockroachdb.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/cockroachdb.mdx similarity index 86% rename from apps/docs/content/docs/(index)/prisma-orm/quickstart/cockroachdb.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/cockroachdb.mdx index dcaa0c9ae4..c40ef346c7 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/cockroachdb.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/cockroachdb.mdx @@ -1,7 +1,7 @@ --- title: CockroachDB description: Create a new TypeScript project from scratch by connecting Prisma ORM to CockroachDB and generating a Prisma Client for database access -url: /prisma-orm/quickstart/cockroachdb +url: /v7/prisma-orm/quickstart/cockroachdb metaTitle: 'Quickstart: Prisma ORM with CockroachDB (10 min)' metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to CockroachDB and generating a Prisma Client for database access. --- @@ -36,15 +36,15 @@ npx tsc --init Install the packages needed for this quickstart: ```npm -npm install prisma @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install prisma@7.9.1 @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` Here's what each package does: - **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma migrate`, and `prisma generate` - **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database (CockroachDB is PostgreSQL-compatible) +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database (CockroachDB is PostgreSQL-compatible) - **`pg`** - The node-postgres database driver - **`@types/pg`** - TypeScript type definitions for node-postgres - **`dotenv`** - Loads environment variables from your `.env` file @@ -82,7 +82,7 @@ You can now invoke the Prisma CLI by prefixing it with `npx`: npx prisma ``` -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider cockroachdb --output ../generated/prisma @@ -111,7 +111,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -265,16 +265,16 @@ Explore the options suggested by [CockroachDB](https://www.cockroachlabs.com/blo You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [CockroachDB database connector](/orm/core-concepts/supported-databases/postgresql#cockroachdb) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- [CockroachDB database connector](/orm/v7/core-concepts/supported-databases/postgresql#cockroachdb) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) diff --git a/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/meta.json b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/meta.json new file mode 100644 index 0000000000..c7c3975061 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/meta.json @@ -0,0 +1,13 @@ +{ + "title": "Quickstart", + "pages": [ + "prisma-postgres", + "sqlite", + "postgresql", + "mysql", + "sql-server", + "planetscale", + "cockroachdb", + "mongodb" + ] +} diff --git a/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/mongodb.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/mongodb.mdx new file mode 100644 index 0000000000..fbccb75498 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/mongodb.mdx @@ -0,0 +1,332 @@ +--- +title: MongoDB +description: Create a new TypeScript project from scratch by connecting Prisma ORM to MongoDB and generating a Prisma Client for database access +url: /v7/prisma-orm/quickstart/mongodb +metaTitle: 'Quickstart: Prisma ORM with MongoDB (10 min)' +metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to MongoDB and generating a Prisma Client for database access. +--- + +[MongoDB](https://www.mongodb.com) is a popular NoSQL document database. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to MongoDB using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database. + +:::warning[MongoDB support for Prisma ORM v7] + +**MongoDB support for Prisma ORM v7 is coming in the near future.** In the meantime, please use **Prisma ORM v6.19** (the latest v6 release) when working with MongoDB. + +This guide uses Prisma ORM v6.19 to ensure full compatibility with MongoDB. + +::: + +## Prerequisites + +- Node.js installed in your system [with the supported version](/guides/upgrade-prisma-orm/v6#minimum-supported-nodejs-versions) +- A [MongoDB](https://www.mongodb.com/) database accessible via connection string + +## 1. Create a new project + +```shell +mkdir hello-prisma +cd hello-prisma +``` + +Initialize a TypeScript project: + +```npm +npm init -y +npm install typescript tsx @types/node --save-dev +npx tsc --init +``` + + +## 2. Install required dependencies + +Install the packages needed for this quickstart: + +```npm +npm install prisma@6.19 @types/node --save-dev +``` + +```npm +npm install @prisma/client@6.19 dotenv +``` + +:::info[Why Prisma v6.19?] + +This is the latest stable version of Prisma ORM v6 that fully supports MongoDB. MongoDB support for Prisma ORM v7 is coming soon. You can also install `prisma@6` and `@prisma/client@6` to automatically get the latest v6 release. + +::: + +Here's what each package does: + +- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db push`, and `prisma generate` +- **`@prisma/client`** - The Prisma Client library for querying your database +- **`dotenv`** - Loads environment variables from your `.env` file + +:::note + +MongoDB doesn't require driver adapters since Prisma ORM connects directly to MongoDB. + +::: + +## 3. Configure ESM support + +Update `tsconfig.json` for ESM compatibility: + +```json title="tsconfig.json" +{ + "compilerOptions": { + "module": "ESNext", + "moduleResolution": "bundler", + "target": "ES2023", + "strict": true, + "esModuleInterop": true, + "ignoreDeprecations": "6.0" + } +} +``` + +Update `package.json` to enable ESM: + +```json title="package.json" +{ + "type": "module" // [!code ++] +} +``` + +## 4. Initialize Prisma ORM + +You can now invoke the Prisma CLI by prefixing it with `npx`: + +```npm +npx prisma +``` + +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: + +```npm +npx prisma init --datasource-provider mongodb --output ../generated/prisma +``` + +This command does a few things: + +- Creates a `prisma/` directory with a `schema.prisma` file for your database connection and schema models +- Creates a `.env` file in the root directory for environment variables +- Creates a `prisma.config.ts` file for Prisma configuration + +:::note + +Prisma Client will be generated in the `generated/prisma/` directory when you run `npx prisma generate` later in this guide. + +::: + +The generated `prisma.config.ts` file looks like this: + +```typescript title="prisma.config.ts" +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + engine: "classic", + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +Add `dotenv` to `prisma.config.ts` so that Prisma can load environment variables from your `.env` file: + +```typescript title="prisma.config.ts" +import "dotenv/config"; // [!code ++] +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + engine: "classic", + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "mongodb" + url = env("DATABASE_URL") +} +``` + +Update your `.env` file with your MongoDB connection string: + +```text title=".env" +DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/mydb" +``` + +:::tip + +Replace `username`, `password`, `cluster`, and `mydb` with your actual MongoDB credentials and database name. You can get your connection string from [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) or your MongoDB deployment. + +::: + +## 5. Define your data model + +Open `prisma/schema.prisma` and add the following models: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "mongodb" + url = env("DATABASE_URL") +} + +model User { // [!code ++] + id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] + email String @unique // [!code ++] + name String? // [!code ++] + posts Post[] // [!code ++] +} // [!code ++] + +model Post { // [!code ++] + id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++] + title String // [!code ++] + content String? // [!code ++] + published Boolean @default(false) // [!code ++] + author User @relation(fields: [authorId], references: [id]) // [!code ++] + authorId String @db.ObjectId // [!code ++] +} // [!code ++] +``` + +## 6. Push your schema to MongoDB + +MongoDB doesn't support migrations like relational databases. Instead, use `db push` to sync your schema: + +```npm +npx prisma db push +``` + +This command: + +- Creates the collections in MongoDB based on your schema +- Automatically generates Prisma Client + +:::info + +Unlike relational databases, MongoDB uses a flexible schema. The `db push` command ensures your Prisma schema is reflected in your database without creating migration files. + +::: + +## 7. Instantiate Prisma Client + +Now that you have all the dependencies installed, you can instantiate Prisma Client: + +```typescript title="lib/prisma.ts" +import "dotenv/config"; +import { PrismaClient } from "../generated/prisma/client"; + +const prisma = new PrismaClient(); + +export { prisma }; +``` + +## 8. Write your first query + +Create a `script.ts` file to test your setup: + +```typescript title="script.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + // Create a new user with a post + const user = await prisma.user.create({ + data: { + name: "Alice", + email: "alice@prisma.io", + posts: { + create: { + title: "Hello World", + content: "This is my first post!", + published: true, + }, + }, + }, + include: { + posts: true, + }, + }); + console.log("Created user:", user); + + // Fetch all users with their posts + const allUsers = await prisma.user.findMany({ + include: { + posts: true, + }, + }); + console.log("All users:", JSON.stringify(allUsers, null, 2)); +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Run the script: + +```npm +npx tsx script.ts +``` + +You should see the created user and all users printed to the console! + +## 9. Explore your data + +You can use [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), the MongoDB shell, or MongoDB Compass to view and manage your data. + +:::warning + +[Prisma Studio](/studio) does not currently support MongoDB. Support may be added in a future release. See [Databases supported by Prisma Studio](/studio#supported-databases) for more information. + +::: + +## Next steps + +You've successfully set up Prisma ORM. Here's what you can explore next: + +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more +- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) + + + +## Troubleshooting + +- **Authentication failed** — If you see a `SCRAM failure: Authentication failed` error, [add `?authSource=admin`](https://github.com/prisma/prisma/discussions/9994#discussioncomment-1562283) to the end of your connection string. +- **Empty database name** — If you see an `Error code 8000 (AtlasError): empty database name not allowed` error, append the database name to your connection URL. See this [GitHub issue](https://github.com/prisma/web/issues/5562) for details. + +## More info + +- [MongoDB database connector](/orm/v7/core-concepts/supported-databases/mongodb) +- [MongoDB data modeling patterns](/orm/v7/core-concepts/supported-databases/mongodb#type-mapping-between-mongodb-and-the-prisma-schema) +- [MongoDB deployment considerations](/orm/v7/core-concepts/supported-databases/mongodb#differences-to-connectors-for-relational-databases) diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/mysql.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/mysql.mdx similarity index 88% rename from apps/docs/content/docs/(index)/prisma-orm/quickstart/mysql.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/mysql.mdx index 8ab025505f..c15a127f40 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/mysql.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/mysql.mdx @@ -1,7 +1,7 @@ --- title: MySQL description: Create a new TypeScript project from scratch by connecting Prisma ORM to MySQL and generating a Prisma Client for database access -url: /prisma-orm/quickstart/mysql +url: /v7/prisma-orm/quickstart/mysql metaTitle: 'Quickstart: Prisma ORM with MySQL (10 min)' metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to MySQL and generating a Prisma Client for database access. --- @@ -42,8 +42,8 @@ npx tsc --init Install the packages needed for this quickstart: ```npm -npm install prisma @types/node --save-dev -npm install @prisma/client @prisma/adapter-mariadb dotenv +npm install prisma@7.9.1 @types/node --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-mariadb dotenv ``` Here's what each package does: @@ -86,7 +86,7 @@ You can now invoke the Prisma CLI by prefixing it with `npx`: npx prisma ``` -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider mysql --output ../generated/prisma @@ -115,7 +115,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -280,16 +280,16 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [MySQL database connector](/orm/core-concepts/supported-databases/mysql) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- [MySQL database connector](/orm/v7/core-concepts/supported-databases/mysql) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/planetscale.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/planetscale.mdx similarity index 90% rename from apps/docs/content/docs/(index)/prisma-orm/quickstart/planetscale.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/planetscale.mdx index c5465990f5..fc484f4781 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/planetscale.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/planetscale.mdx @@ -1,7 +1,7 @@ --- title: PlanetScale description: Create a new TypeScript project from scratch by connecting Prisma ORM to PlanetScale and generating a Prisma Client for database access -url: /prisma-orm/quickstart/planetscale +url: /v7/prisma-orm/quickstart/planetscale metaTitle: 'Quickstart: Prisma ORM with PlanetScale MySQL (10 min)' metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to PlanetScale MySQL and generating a Prisma Client for database access. --- @@ -40,15 +40,15 @@ Install the packages needed for this quickstart: ### MySQL ```npm -npm install prisma --save-dev -npm install @prisma/client @prisma/adapter-planetscale undici dotenv +npm install prisma@7.9.1 --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-planetscale undici dotenv ``` ### Postgres ```npm -npm install prisma @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install prisma@7.9.1 @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` ## 3. Configure ESM support @@ -84,7 +84,7 @@ You can now invoke the Prisma CLI by prefixing it with `npx`: npx prisma ``` -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ### MySQL @@ -121,7 +121,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" tab="MySQL" generator client { @@ -372,16 +372,16 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) - [PlanetScale documentation](https://planetscale.com/docs) diff --git a/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/postgresql.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/postgresql.mdx new file mode 100644 index 0000000000..e5481c61f8 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/postgresql.mdx @@ -0,0 +1,289 @@ +--- +title: PostgreSQL +description: Create a new TypeScript project from scratch by connecting Prisma ORM to PostgreSQL and generating a Prisma Client for database access +url: /v7/prisma-orm/quickstart/postgresql +metaTitle: 'Quickstart: Prisma ORM with PostgreSQL (10 min)' +metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to PostgreSQL and generating a Prisma Client for database access. +--- + +[PostgreSQL](https://www.postgresql.org) is a powerful, open-source relational database. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to PostgreSQL using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database. + +## Prerequisites + +You also need: + +- A [PostgreSQL](https://www.postgresql.org/) database server running and accessible +- Database connection details (host, port, username, password, database name) + +:::tip[Need a PostgreSQL database?] + +If you don't already have a PostgreSQL database, follow the quickstart to set up a production-ready [Prisma Postgres](/v7/prisma-orm/quickstart/prisma-postgres) database with Prisma ORM in a new project. + +::: + +## 1. Create a new project + +```shell +mkdir hello-prisma +cd hello-prisma +``` + +Initialize a TypeScript project: + +```npm +npm init -y +npm install typescript tsx @types/node --save-dev +npx tsc --init +``` + + +## 2. Install required dependencies + +Install the packages needed for this quickstart: + +```npm +npm install prisma@7.9.1 @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv +``` + +Here's what each package does: + +- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma migrate`, and `prisma generate` +- **`@prisma/client`** - The Prisma Client library for querying your database +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database +- **`pg`** - The node-postgres database driver +- **`@types/pg`** - TypeScript type definitions for node-postgres +- **`dotenv`** - Loads environment variables from your `.env` file + +## 3. Configure ESM support + +Update `tsconfig.json` for ESM compatibility: + +```json title="tsconfig.json" +{ + "compilerOptions": { + "module": "ESNext", + "moduleResolution": "bundler", + "target": "ES2023", + "strict": true, + "esModuleInterop": true, + "ignoreDeprecations": "6.0" + } +} +``` + +Update `package.json` to enable ESM: + +```json title="package.json" +{ + "type": "module" // [!code ++] +} +``` + +## 4. Initialize Prisma ORM + +You can now invoke the Prisma CLI by prefixing it with `npx`: + +```npm +npx prisma +``` + +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: + +```npm +npx prisma init --datasource-provider postgresql --output ../generated/prisma +``` + +This command does a few things: + +- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection and schema models +- Creates a `.env` file in the root directory for environment variables +- Creates a `prisma.config.ts` file for Prisma configuration + +The generated `prisma.config.ts` file looks like this: + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "postgresql" +} +``` + +Update your `.env` file with your PostgreSQL connection string: + +```text title=".env" +DATABASE_URL="postgresql://username:password@localhost:5432/mydb?schema=public" +``` + +Replace the placeholders with your actual database credentials: + +- `username`: Your PostgreSQL username +- `password`: Your PostgreSQL password +- `localhost:5432`: Your PostgreSQL host and port +- `mydb`: Your database name + +## 5. Define your data model + +Open `prisma/schema.prisma` and add the following models: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "postgresql" +} + +model User { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + email String @unique // [!code ++] + name String? // [!code ++] + posts Post[] // [!code ++] +} // [!code ++] + +model Post { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + title String // [!code ++] + content String? // [!code ++] + published Boolean @default(false) // [!code ++] + author User @relation(fields: [authorId], references: [id]) // [!code ++] + authorId Int // [!code ++] +} // [!code ++] +``` + +## 6. Create and apply your first migration + +Create your first migration to set up the database tables: + +```npm +npx prisma migrate dev --name init +``` + +This command creates the database tables based on your schema. + +Now run the following command to generate the Prisma Client: + +```npm +npx prisma generate +``` + +## 7. Instantiate Prisma Client + +Now that you have all the dependencies installed, you can instantiate Prisma Client. You need to pass an instance of the Prisma ORM driver adapter to the `PrismaClient` constructor: + +```typescript title="lib/prisma.ts" +import "dotenv/config"; +import { PrismaPg } from "@prisma/adapter-pg"; +import { PrismaClient } from "../generated/prisma/client"; + +const connectionString = `${process.env.DATABASE_URL}`; + +const adapter = new PrismaPg({ connectionString }); +const prisma = new PrismaClient({ adapter }); + +export { prisma }; +``` + +## 8. Write your first query + +Create a `script.ts` file to test your setup: + +```typescript title="script.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + // Create a new user with a post + const user = await prisma.user.create({ + data: { + name: "Alice", + email: "alice@prisma.io", + posts: { + create: { + title: "Hello World", + content: "This is my first post!", + published: true, + }, + }, + }, + include: { + posts: true, + }, + }); + console.log("Created user:", user); + + // Fetch all users with their posts + const allUsers = await prisma.user.findMany({ + include: { + posts: true, + }, + }); + console.log("All users:", JSON.stringify(allUsers, null, 2)); +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Run the script: + +```npm +npx tsx script.ts +``` + +You should see the created user and all users printed to the console! + +## 9. Explore your data with Prisma Studio + +Prisma Studio is a visual editor for your database. Launch it with: + +```shell +npx prisma studio +``` + +## Next steps + +You've successfully set up Prisma ORM. Here's what you can explore next: + +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more +- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) + + + +## More info + +- [PostgreSQL database connector](/orm/v7/core-concepts/supported-databases/postgresql) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/prisma-postgres.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/prisma-postgres.mdx similarity index 87% rename from apps/docs/content/docs/(index)/prisma-orm/quickstart/prisma-postgres.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/prisma-postgres.mdx index 7d6d5fe0e9..7287c771ca 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/prisma-postgres.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/prisma-postgres.mdx @@ -1,7 +1,7 @@ --- title: Prisma Postgres description: Create a new TypeScript project from scratch by connecting Prisma ORM to Prisma Postgres and generating a Prisma Client for database access -url: /prisma-orm/quickstart/prisma-postgres +url: /v7/prisma-orm/quickstart/prisma-postgres metaTitle: 'Quickstart: Prisma ORM with Prisma Postgres (5 min)' metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to Prisma Postgres and generating a Prisma Client for database access. --- @@ -33,15 +33,15 @@ npx tsc --init Install the packages needed for this quickstart: ```npm -npm install prisma @types/pg --save-dev -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install prisma@7.9.1 @types/pg --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` Here's what each package does: - **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma migrate`, and `prisma generate` - **`@prisma/client`** - The Prisma Client library for querying your database -- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database - **`pg`** - The node-postgres database driver - **`@types/pg`** - TypeScript type definitions for node-postgres - **`dotenv`** - Loads environment variables from your `.env` file @@ -79,7 +79,7 @@ You can now invoke the Prisma CLI by prefixing it with `npx`: npx prisma ``` -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --output ../generated/prisma @@ -110,7 +110,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -266,10 +266,10 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) :::info[Deploy to Compute] @@ -281,5 +281,5 @@ Want to run this app in the cloud? Deploy it to [Prisma Compute](/compute), whic ## More info - [Prisma Postgres documentation](/postgres) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/sql-server.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/sql-server.mdx similarity index 86% rename from apps/docs/content/docs/(index)/prisma-orm/quickstart/sql-server.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/sql-server.mdx index c209822b7d..d24db18ec3 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/sql-server.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/sql-server.mdx @@ -1,7 +1,7 @@ --- title: SQL Server description: Create a new TypeScript project from scratch by connecting Prisma ORM to SQL Server and generating a Prisma Client for database access -url: /prisma-orm/quickstart/sql-server +url: /v7/prisma-orm/quickstart/sql-server metaTitle: 'Quickstart: Prisma ORM with SQL Server (10 min)' metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to SQL Server and generating a Prisma Client for database access. --- @@ -13,8 +13,8 @@ metaDescription: Create a new TypeScript project from scratch by connecting Pris You also need: - A [Microsoft SQL Server](https://learn.microsoft.com/en-us/sql/?view=sql-server-ver16) database - - [Microsoft SQL Server on Linux for Docker](/orm/core-concepts/supported-databases/sql-server#local-setup) - - [Microsoft SQL Server on Windows (local)](/orm/core-concepts/supported-databases/sql-server#local-setup) + - [Microsoft SQL Server on Linux for Docker](/orm/v7/core-concepts/supported-databases/sql-server#local-setup) + - [Microsoft SQL Server on Windows (local)](/orm/v7/core-concepts/supported-databases/sql-server#local-setup) - Database connection details (host, port, username, password, database name) ## 1. Create a new project @@ -37,8 +37,8 @@ npx tsc --init Install the packages needed for this quickstart: ```npm -npm install prisma @types/node @types/mssql --save-dev -npm install @prisma/client @prisma/adapter-mssql dotenv +npm install prisma@7.9.1 @types/node @types/mssql --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-mssql dotenv ``` Here's what each package does: @@ -82,7 +82,7 @@ You can now invoke the Prisma CLI by prefixing it with `npx`: npx prisma ``` -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider sqlserver --output ../generated/prisma @@ -111,7 +111,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -286,16 +286,16 @@ npx prisma studio You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [SQL Server database connector](/orm/core-concepts/supported-databases/sql-server) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- [SQL Server database connector](/orm/v7/core-concepts/supported-databases/sql-server) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) diff --git a/apps/docs/content/docs/(index)/prisma-orm/quickstart/sqlite.mdx b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/sqlite.mdx similarity index 89% rename from apps/docs/content/docs/(index)/prisma-orm/quickstart/sqlite.mdx rename to apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/sqlite.mdx index 890b76ec4d..d00c53ce24 100644 --- a/apps/docs/content/docs/(index)/prisma-orm/quickstart/sqlite.mdx +++ b/apps/docs/content/docs/(index)/v7/prisma-orm/quickstart/sqlite.mdx @@ -1,7 +1,7 @@ --- title: SQLite description: Create a new TypeScript project from scratch by connecting Prisma ORM to SQLite and generating a Prisma Client for database access -url: /prisma-orm/quickstart/sqlite +url: /v7/prisma-orm/quickstart/sqlite metaTitle: 'Quickstart: Prisma ORM with SQLite (5 min)' metaDescription: Create a new TypeScript project from scratch by connecting Prisma ORM to SQLite and generating a Prisma Client for database access. --- @@ -34,11 +34,11 @@ npx tsc --init Install the packages needed for this quickstart: ```npm -npm install prisma @types/node @types/better-sqlite3 -D +npm install prisma@7.9.1 @types/node @types/better-sqlite3 -D ``` ```npm -npm install @prisma/client @prisma/adapter-better-sqlite3 dotenv +npm install @prisma/client@7.9.1 @prisma/adapter-better-sqlite3 dotenv ``` :::note[pnpm users with SQLite] @@ -86,7 +86,7 @@ You can now invoke the Prisma CLI by prefixing it with `npx`: npx prisma ``` -Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/prisma-schema/overview) file with the following command: +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: ```npm npx prisma init --datasource-provider sqlite --output ../generated/prisma @@ -115,7 +115,7 @@ export default defineConfig({ }); ``` -The generated schema uses [the ESM-first `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client) with a custom output path: +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: ```prisma title="prisma/schema.prisma" generator client { @@ -299,16 +299,16 @@ This command: You've successfully set up Prisma ORM. Here's what you can explore next: -- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations -- **Database migrations**: Learn about [Prisma Migrate](/orm/prisma-migrate) for evolving your database schema -- **Performance optimization**: Discover [query optimization techniques](/orm/prisma-client/queries/advanced/query-optimization-performance) -- **Build a full application**: Check out our [framework guides](/guides) to integrate Prisma ORM with Next.js, Express, and more +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more - **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) ## More info -- [SQLite database connector](/orm/core-concepts/supported-databases/sqlite) -- [Prisma Config reference](/orm/reference/prisma-config-reference) -- [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) +- [SQLite database connector](/orm/v7/core-concepts/supported-databases/sqlite) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) diff --git a/apps/docs/content/docs/(index)/v7/prisma-postgres/from-the-cli.mdx b/apps/docs/content/docs/(index)/v7/prisma-postgres/from-the-cli.mdx new file mode 100644 index 0000000000..cc20c6434f --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-postgres/from-the-cli.mdx @@ -0,0 +1,468 @@ +--- +title: From the CLI +description: Start building a Prisma application with a Prisma Postgres database from the CLI +url: /v7/prisma-postgres/from-the-cli +metaTitle: From the CLI +metaDescription: Start building a Prisma application with a Prisma Postgres database from the CLI +--- + +This page provides a step-by-step guide for Prisma Postgres after setting it up with `prisma init` and `npx create-db`: + +1. Set up a TypeScript app with Prisma ORM +1. Migrate the schema of your database +1. Query your database from TypeScript + +## Prerequisites + +This guide assumes you initialized Prisma with `prisma init` and created a Prisma Postgres database with `npx create-db`: + +```npm +npx prisma@7.9.1 init +npx create-db +``` + + +Once these commands have terminated: + +- The `prisma/` folder was created with an empty `schema.prisma` file. +- The `DATABASE_URL` env var was set in a `.env` file. +- The `prisma.config.ts` file was created with the default configuration. +- You have a Prisma Postgres connection string to paste into `.env`. + +## 1. Organize your project directory + +:::note + +If you ran the `prisma init` command inside a folder where you want your project to live, you can skip this step and [proceed to the next section](/v7/prisma-postgres/from-the-cli#2-set-up-your-project). + +::: + +If you ran the command outside your intended project directory (e.g., in your home folder or another location), you need to move the generated `prisma` folder and the `.env` file into a dedicated project directory. + +Create a new folder (e.g. `hello-prisma`) where you want your project to live and move the necessary files into it: + +```bash +mkdir hello-prisma +mv .env ./hello-prisma/ +mv prisma ./hello-prisma/ +``` + +Navigate into your project folder: + +```bash +cd ./hello-prisma +``` + +Now that your project is in the correct location, continue with the setup. + +## 2. Set up your project + +### 2.1. Set up TypeScript + +Initialize a TypeScript project and add the Prisma CLI as a development dependency: + +```npm +npm init -y +``` + +```npm +npm install typescript tsx @types/node @types/pg -D +``` + +This creates a `package.json` file with an initial setup for your TypeScript app. + +Next, initialize TypeScript with a `tsconfig.json` file in the project: + +```npm +npx tsc --init +``` + +### 2.2. Configure ESM support + +Update `tsconfig.json` for ESM compatibility: + +```json title="tsconfig.json" +{ + "compilerOptions": { + "module": "ESNext", + "moduleResolution": "bundler", + "target": "ES2023", + "strict": true, + "esModuleInterop": true, + "ignoreDeprecations": "6.0" + } +} +``` + +Update `package.json` to enable ESM: + +```json title="package.json" +{ + "type": "module" // [!code ++] +} +``` + +### 2.3. Set up Prisma ORM + +Install the required dependencies to use Prisma Postgres: + +```npm +npm install prisma@7.9.1 --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv +``` + +Here's what each package does: + +- **`prisma`** - The Prisma CLI for running commands like `prisma migrate` and `prisma generate` +- **`@prisma/client`** - The Prisma Client library for querying your database +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database +- **`pg`** - The node-postgres database driver +- **`@types/pg`** - TypeScript type definitions for node-postgres +- **`dotenv`** - Loads environment variables from your `.env` file + +### 2.4. Review the generated prisma.config.ts + +The `prisma init` command automatically created a `prisma.config.ts` file that looks like this: + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +### 2.5. Create a script to query the database + +Create an `index.ts` file in the root directory, this will be used to query your application with Prisma ORM: + +```bash +touch index.ts +``` + +## 3. Migrate the database schema + +Update your `prisma/schema.prisma` file to include the `User` and `Post` models: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "postgresql" +} + +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? + posts Post[] +} + +model Post { + id Int @id @default(autoincrement()) + title String + content String? + published Boolean @default(false) + author User @relation(fields: [authorId], references: [id]) + authorId Int +} +``` + +After adding the models, migrate your database using [Prisma Migrate](/orm/v7/prisma-migrate): + +```npm +npx prisma migrate dev --name init +``` + +This command creates the database tables based on your schema. + +Now run the following command to generate the Prisma Client: + +```npm +npx prisma generate +``` + +## 4. Send queries with Prisma ORM + +### 4.1. Instantiate Prisma Client + +Create a `lib/prisma.ts` file to instantiate Prisma Client with the driver adapter: + +```typescript title="lib/prisma.ts" +import "dotenv/config"; +import { PrismaPg } from "@prisma/adapter-pg"; +import { PrismaClient } from "../generated/prisma/client"; + +const connectionString = `${process.env.DATABASE_URL}`; + +const adapter = new PrismaPg({ connectionString }); +const prisma = new PrismaClient({ adapter }); + +export { prisma }; +``` + +:::tip + +If you need to query your database via HTTP from an edge runtime (Cloudflare Workers, Vercel Edge Functions, etc.), use the [Prisma Postgres serverless driver](/postgres/database/serverless-driver#use-with-prisma-orm). + +::: + +### 4.2. Write your first query + +Paste the following boilerplate into `index.ts`: + +```ts title="index.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + // ... you will write your Prisma ORM queries here +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +This code contains a `main` function that's invoked at the end of the script. It also instantiates `PrismaClient` which you'll use to send queries to your database. + +### 4.3. Create a new `User` record + +Let's start with a small query to create a new `User` record in the database and log the resulting object to the console. Add the following code to your `index.ts` file: + +```ts title="index.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + const user = await prisma.user.create({ + // [!code ++] + data: { + // [!code ++] + name: "Alice", // [!code ++] + email: "alice@prisma.io", // [!code ++] + }, // [!code ++] + }); // [!code ++] + console.log(user); // [!code ++] +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Next, execute the script with the following command: + +```npm +npx tsx index.ts +``` + +```text no-copy +{ id: 1, email: 'alice@prisma.io', name: 'Alice' } +``` + +Great job, you just created your first database record with Prisma Postgres! 🎉 + +### 4.4. Retrieve all `User` records + +Prisma ORM offers various queries to read data from your database. In this section, you'll use the `findMany` query that returns _all_ the records in the database for a given model. + +Delete the previous Prisma ORM query and add the new `findMany` query instead: + +```ts title="index.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + const users = await prisma.user.findMany(); // [!code ++] + console.log(users); // [!code ++] +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Execute the script again: + +```npm +npx tsx index.ts +``` + +```text no-copy +[{ id: 1, email: 'alice@prisma.io', name: 'Alice' }] +``` + +Notice how the single `User` object is now enclosed with square brackets in the console. That's because the `findMany` returned an array with a single object inside. + +### 4.5. Explore relation queries + +One of the main features of Prisma ORM is the ease of working with [relations](/orm/v7/prisma-schema/data-model/relations). In this section, you'll learn how to create a `User` and a `Post` record in a nested write query. Afterwards, you'll see how you can retrieve the relation from the database using the `include` option. + +First, adjust your script to include the nested query: + +```ts title="index.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + const user = await prisma.user.create({ + // [!code ++] + data: { + // [!code ++] + name: "Bob", // [!code ++] + email: "bob@prisma.io", // [!code ++] + posts: { + // [!code ++] + create: [ + // [!code ++] + { + // [!code ++] + title: "Hello World", // [!code ++] + published: true, // [!code ++] + }, // [!code ++] + { + // [!code ++] + title: "My second post", // [!code ++] + content: "This is still a draft", // [!code ++] + }, // [!code ++] + ], // [!code ++] + }, // [!code ++] + }, // [!code ++] + }); // [!code ++] + console.log(user); // [!code ++] +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Run the query by executing the script again: + +```npm +npx tsx index.ts +``` + +```text no-copy +{ id: 2, email: 'bob@prisma.io', name: 'Bob' } +``` + +In order to also retrieve the `Post` records that belong to a `User`, you can use the `include` option via the `posts` relation field: + +```ts title="index.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + const usersWithPosts = await prisma.user.findMany({ + // [!code ++] + include: { + // [!code ++] + posts: true, // [!code ++] + }, // [!code ++] + }); // [!code ++] + console.dir(usersWithPosts, { depth: null }); // [!code ++] +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Run the script again to see the results of the nested read query: + +```npm +npx tsx index.ts +``` + +```text no-copy +[ + { id: 1, email: 'alice@prisma.io', name: 'Alice', posts: [] }, + { + id: 2, + email: 'bob@prisma.io', + name: 'Bob', + posts: [ + { + id: 1, + title: 'Hello World', + content: null, + published: true, + authorId: 2 + }, + { + id: 2, + title: 'My second post', + content: 'This is still a draft', + published: false, + authorId: 2 + } + ] + } +] +``` + +This time, you're seeing two `User` objects being printed. Both of them have a `posts` field (which is empty for `"Alice"` and populated with two `Post` objects for `"Bob"`) that represents the `Post` records associated with them. + +## Next steps + +You just got your feet wet with a basic Prisma Postgres setup. Check out the official [Quickstart](/v7/prisma-orm/quickstart/prisma-postgres). + +### View and edit data in Prisma Studio + +Prisma ORM comes with a built-in GUI to view and edit the data in your database. You can open it using the following command: + +```npm +npx prisma studio --config ./prisma.config.ts +``` + +With Prisma Postgres, you can also directly use Prisma Studio inside the [Console](https://console.prisma.io) by selecting the **Studio** tab in your project. + +### Build a fullstack app with Next.js + +Learn how to use Prisma Postgres in a fullstack app: + +- [Build a fullstack app with Next.js 15](/guides/v7/frameworks/nextjs) +- [Next.js 15 example app](https://github.com/prisma/nextjs-prisma-postgres-demo) (including authentication) + +### Explore ready-to-run examples + +Check out the [`prisma-examples`](https://github.com/prisma/prisma-examples/) repository on GitHub to see how Prisma ORM can be used with your favorite library. The repo contains examples with Express, NestJS, GraphQL as well as fullstack examples with Next.js and Vue.js, and a lot more. + +These examples use SQLite by default but you can follow the instructions in the project README to switch to Prisma Postgres in a few simple steps. diff --git a/apps/docs/content/docs/(index)/v7/prisma-postgres/import-from-existing-database-mysql.mdx b/apps/docs/content/docs/(index)/v7/prisma-postgres/import-from-existing-database-mysql.mdx new file mode 100644 index 0000000000..269f7782d6 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-postgres/import-from-existing-database-mysql.mdx @@ -0,0 +1,206 @@ +--- +title: Import from MySQL +description: Learn how to import data from an existing MySQL database into Prisma Postgres +url: /v7/prisma-postgres/import-from-existing-database-mysql +metaTitle: Import from existing MySQL database into Prisma Postgres +metaDescription: Learn how to import data from an existing MySQL database into Prisma Postgres. +--- + +This guide provides step-by-step instructions for importing data from an existing MySQL database into Prisma Postgres. + +You can accomplish this migration in four steps: + +1. Create a new Prisma Postgres database. +1. Connect directly to a Prisma Postgres instance using a [direct connection](/postgres/database/connecting-to-your-database). +1. Migrate your MySQL data to Prisma Postgres using [pgloader](https://pgloader.io/). +1. Configure your Prisma project for Prisma Postgres. + +## Prerequisites + +- The connection URL to your existing MySQL database. +- A [Prisma Data Platform](https://console.prisma.io) account. +- Node.js 18+ installed. +- [pgloader](https://pgloader.io/) installed. + +:::info[Make sure your PostgreSQL tools match the Prisma Postgres version] + +Prisma Postgres runs PostgreSQL 17. Your `pgloader` and any other PostgreSQL tools you use need to be compatible with PostgreSQL 17. + +::: + +We recommend attempting this migration in a separate git development branch. + +## 1. Create a new Prisma Postgres database + +Follow these steps to create a new Prisma Postgres database: + +1. Log in to [Prisma Data Platform](https://console.prisma.io/) and open the Console. +1. In a [workspace](/console/concepts#workspace) of your choice, click the **New project** button. +1. Type a name for your project in the **Name** field, e.g. **hello-ppg**. +1. In the **Prisma Postgres** section, click the **Get started** button. +1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**. +1. Click the **Create project** button. + +Once your database is** **provisioned, find your direct Prisma Postgres connection string: + +1. Navigate to your active Prisma Postgres instance. +1. Click the **Connection Strings** tab in the project's sidenav. +1. Click the **Create connection string** button. +1. In the popup, provide a **Name** for the connection string and click **Create**. +1. Copy the connection string starting with `postgres://`, this is your direct connection string. + +Save the connection string, as you'll need it in step 3. + +## 2. Prepare your direct connection string + +In this step, you'll use the [direct connection string](/postgres/database/connecting-to-your-database) you obtained in step 1 to connect to your Prisma Postgres instance. + +Your direct connection string should look like this: + +```text +postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require +``` + +You'll use this connection string in the next step when configuring pgloader. + +## 3. Migrate your MySQL data to Prisma Postgres using pgloader + +Now that you have an active connection to your Prisma Postgres instance, you'll use [pgloader](https://pgloader.io/) to export data from your MySQL database to Prisma Postgres. + +Open a separate terminal window and create a `config.load` file: + +```bash +touch config.load +``` + +Open the `config.load` file in your preferred text editor and copy-paste the following configuration: + +```text title="config.load" +LOAD DATABASE + FROM mysql://username:password@host:PORT/database_name + INTO postgres://__USER__:__PASSWORD__@db.prisma.io:5432/?sslmode=require + +WITH quote identifiers, -- preserve table/column name case by quoting them + include drop, + create tables, + create indexes, + reset sequences + +ALTER SCHEMA 'database_name' RENAME TO 'public'; +``` + +Make sure to update the following details in the `config.load` file: + +- `FROM` url (MySQL database URL): + - Replace `username`, `password`, `host`, `PORT`, and `database_name` with the actual connection details for your MySQL database. + - Ensure that your connection string includes `useSSL=true` if SSL is required, for example: `mysql://username:password@host:PORT/database_name?useSSL=true`. Note that when using PlanetScale, appending `sslaccept=strict` will not work. +- `INTO` url (Postgres database URL): + - Update this with your direct connection string from above, replacing the `__USER__` and `__PASSWORD__` placeholders. +- Update the `database_name` in `ALTER SCHEMA 'database_name' RENAME TO 'public';` to exactly match the `database_name` in your MySQL connection string. + +After saving the configuration file with your updated credentials, in the same terminal window, execute the following command: + +```bash +pgloader config.load +``` + +You should see a log similar to this, which confirms the successful migration of your data: + +```bash +LOG report summary reset + table name errors rows bytes total time +------------------------- --------- --------- --------- -------------- + fetch meta data 0 9 2.546s + Create Schemas 0 0 0.325s + Create SQL Types 0 0 0.635s + Create tables 0 6 5.695s + Set Table OIDs 0 3 0.328s +------------------------- --------- --------- --------- -------------- + public.post 0 8 0.5 kB 4.255s + public."user" 0 4 0.1 kB 2.775s +public._prisma_migrations 0 1 0.2 kB 4.278s +------------------------- --------- --------- --------- -------------- + COPY Threads Completion 0 4 5.095s + Index Build Completion 0 5 9.601s + Create Indexes 0 5 4.116s + Reset Sequences 0 2 4.540s + Primary Keys 0 3 2.917s + Create Foreign Keys 0 1 1.121s + Create Triggers 0 0 0.651s + Install Comments 0 0 0.000s +------------------------- --------- --------- --------- -------------- + Total import time ✓ 13 0.8 kB 28.042s +``` + +If you see output like this, it means your data has been successfully exported to your Prisma Postgres instance. + + +You can also use [Prisma Studio](/guides/postgres/viewing-data#viewing-and-editing-data-in-prisma-studio) to verify whether the migration was successful: + +```npm +npx prisma studio +``` + +## 4. Configure your Prisma project for Prisma Postgres + +After migrating your data, you need to set up your Prisma project to work with Prisma Postgres. The steps differ depending on whether you were already using Prisma ORM. + +### If you **were not** previously using Prisma ORM + +Initialize Prisma in your project by running `npx prisma init` in your project directory. This creates a `prisma` folder with a `schema.prisma` file and `.env` file (if not already present). + +In the generated `.env` file, update `DATABASE_URL` to match your Prisma Postgres direct connection string that you received in [step 1](/v7/prisma-postgres/import-from-existing-database-mysql#1-create-a-new-prisma-postgres-database): + +```text title=".env" no-copy +DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require" +``` + +[Introspect](/orm/v7/prisma-schema/introspection) your newly migrated database by running: + +```npm +npx prisma db pull +``` + +This command updates your `schema.prisma` file with models representing your migrated tables, so you can start using [Prisma Client](/orm/v7/prisma-client/setup-and-configuration/introduction) to query your data or [Prisma Migrate](/orm/v7/prisma-migrate/getting-started) to manage future changes. + +Congratulations! You've successfully migrated your MySQL database to Prisma Postgres and configured your Prisma project. Your migration tutorial is now complete. + +:::note + +For a comprehensive guide on getting started with Prisma and Prisma Postgres, see [start from scratch with Prisma and Prisma Postgres](/v7/prisma-orm/quickstart/prisma-postgres). + +::: + +### If you **were** already using Prisma ORM + +In your `schema.prisma` file, change the `provider` in the `datasource` block from `mysql` to `postgresql`: + +```prisma title="schema.prisma" +datasource db { + provider = "mysql" // [!code --] + provider = "postgres" // [!code ++] +} +``` + +In the generated `.env` file, update `DATABASE_URL` to match your Prisma Postgres direct connection string that you received in [step 1](/v7/prisma-postgres/import-from-existing-database-mysql#1-create-a-new-prisma-postgres-database): + +```text title=".env" no-copy +DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require" +``` + +Introspect your newly migrated Prisma Postgres database and generate Prisma Client: + +```npm +npx prisma db pull +``` + +This command refreshes your Prisma models based on the new database schema. + +If you were using [Prisma Migrate](/orm/v7/prisma-migrate/getting-started) before: + +- Delete your existing `migrations` folder in the `prisma` directory. +- [Baseline your database](/orm/v7/prisma-migrate/workflows/baselining#baselining-a-database) to begin creating new migrations. + +Congratulations! You've successfully migrated your MySQL database to Prisma Postgres and configured your Prisma project. Your migration tutorial is now complete. + +If you encounter any issues during the migration, please don't hesitate to reach out to us on [Discord](https://pris.ly/discord?utm_source=docs&utm_medium=conclusion) or via [X](https://pris.ly/x?utm_source=docs&utm_medium=conclusion). diff --git a/apps/docs/content/docs/(index)/v7/prisma-postgres/import-from-existing-database-postgresql.mdx b/apps/docs/content/docs/(index)/v7/prisma-postgres/import-from-existing-database-postgresql.mdx new file mode 100644 index 0000000000..8296cc722f --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-postgres/import-from-existing-database-postgresql.mdx @@ -0,0 +1,189 @@ +--- +title: Import from PostgreSQL +description: Learn how to import data from an existing PostgreSQL database into Prisma Postgres +url: /v7/prisma-postgres/import-from-existing-database-postgresql +metaTitle: Import from existing Postgres database into Prisma Postgres +metaDescription: Learn how to import data from an existing database into Prisma Postgres. +--- + +This guide provides step-by-step instructions for importing data from an existing PostgreSQL database into Prisma Postgres. + +You can accomplish this migration in three steps: + +1. Create a new Prisma Postgres database. +1. Export your existing data via `pg_dump`. +1. Import the previously exported data into Prisma Postgres via `pg_restore`. + +In the third step, you will be using a [direct connection](/postgres/database/connecting-to-your-database) to securely connect to your Prisma Postgres database to run `pg_restore`. + +## Prerequisites + +- The connection URL to your existing PostgreSQL database +- A [Prisma Data Platform](https://console.prisma.io) account +- Node.js 18+ installed +- PostgreSQL CLI Tools (`pg_dump`, `pg_restore`) for creating and restoring backups + +:::info[Make sure your PostgreSQL tools match the Prisma Postgres version] + +Prisma Postgres runs PostgreSQL 17. Your `pg_dump` and `pg_restore` tools need to be version 17 to ensure compatibility. You can check your version by running `pg_dump --version` or `pg_restore --version`. + +::: + +## 1. Create a new Prisma Postgres database + +Follow these steps to create a new Prisma Postgres database: + +1. Log in to [Prisma Data Platform](https://console.prisma.io/) and open the Console. +1. In a [workspace](/console/concepts#workspace) of your choice, click the **New project** button. +1. Type a name for your project in the **Name** field, e.g. **hello-ppg**. +1. In the **Prisma Postgres** section, click the **Get started** button. +1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**. +1. Click the **Create project** button. + +Once your database is provisioned, obtain your direct connection string: + +1. Navigate to your active Prisma Postgres instance. +1. Click the **Connection Strings** tab in the project's sidenav. +1. Click the **Create connection string** button. +1. In the popup, provide a **Name** for the connection string and click **Create**. +1. Copy the connection string starting with `postgres://`, this is your direct connection string. + +Save the connection string, as you'll need it in step 3. + +## 2. Export data from your existing database + +In this step, you're going to export the data from your existing database and store it in a `.bak` file on your local machine. + +Make sure to have the connection URL for your existing database ready, it should be [structured](/orm/v7/reference/connection-urls) like this: + +```text +postgresql://USER:PASSWORD@HOST:PORT/DATABASE +``` + +Expand below for provider-specific instructions that help you determine the right connection string: + + + + + + + - Make sure to select non-pooled connection string by switching off the **Connection pooling** toggle. + - The `sslmode` has to be set to `require` and appended to your Neon database URL for the command to work. + - The connection URL should look similar to this: + + ```text + postgresql://USER:PASSWORD@YOUR-NEON-HOST/DATABASE?sslmode=require + ``` + + + + - Use a database connection URL that uses [Supavisor session mode](https://supabase.com/docs/guides/database/connecting-to-postgres#supavisor-session-mode). + - The connection URL should look similar to this: + ```text + postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres + ``` + + + + + +Next, run the following command to export the data of your PostgreSQL database (replace the `__DATABASE_URL__` placeholder with your actual database connection URL): + +```bash +pg_dump \ + -Fc \ + -v \ + -d __DATABASE_URL__ \ + -n public \ + -f db_dump.bak +``` + +Here's a quick overview of the CLI options that were used for this command: + +- `-Fc`: Uses the custom format for backups, recommended for `pg_restore` +- `-v`: Runs `pg_dump` in verbose mode +- `-d`: Specifies the database connection string +- `-n`: Specifies the target PostgreSQL schema +- `-f`: Specifies the output name for the backup file + +Running this command will create a backup file named `db_dump.bak` which you will use to restore the data into your Prisma Postgres database in the next step. + +## 3. Import data into Prisma Postgres + +In this section, you'll use your [direct connection string](/postgres/database/connecting-to-your-database) to connect to your Prisma Postgres instance and import data via `pg_restore`. + +Your direct connection string from step 1 should look like this: + +```text +postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require +``` + +Use the backup file from **Step 2** to restore data into your Prisma Postgres database with `pg_restore` by running this command (replace `__USER__`, `__PASSWORD__` with the values from your direct connection string): + +```bash +pg_restore \ + -h db.prisma.io \ + -p 5432 \ + -U __USER__ \ + -d postgres \ + -v \ + ./db_dump.bak \ +&& echo "-complete-" +``` + +When prompted, enter the `__PASSWORD__` from your direct connection string. + +You can also use the full connection string format: + +```bash +pg_restore \ + -d "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require" \ + -v \ + ./db_dump.bak \ +&& echo "-complete-" +``` + +Once the command completes execution, you will have successfully imported the data from your existing PostgreSQL database into Prisma Postgres 🎉 + +To validate that the import worked, you can use [Prisma Studio](/guides/postgres/viewing-data#viewing-and-editing-data-in-prisma-studio). Either open it in the [Platform Console](https://console.prisma.io) by clicking the **Studio** tab in the left-hand sidenav in your project or run this command to launch Prisma Studio locally: + +```npm +npx prisma studio +``` + +## 4. Update your application code to query Prisma Postgres + +### Scenario A: You are already using Prisma ORM + +If you're already using Prisma ORM, you need to update your database connection URL to point to your new Prisma Postgres instance. + +Update the `DATABASE_URL` in your `.env` file to match your Prisma Postgres direct connection string from step 1: + +```text title=".env" +DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require" +``` + +Then, re-generate Prisma Client so that the updated environment variable takes effect: + +```npm +npx prisma generate +``` + +Once this is done, you can run your application and it should work as before. + +:::tip + +For a complete guide on setting up Prisma ORM with Prisma Postgres from scratch, including driver adapter configuration and best practices, see the [Prisma ORM with Prisma Postgres quickstart](/v7/prisma-orm/quickstart/prisma-postgres). + +::: + +### Scenario B: You are not yet using Prisma ORM + +If you are not yet using Prisma ORM, you'll need to go through the following steps to use Prisma Postgres from your application: + +1. Install the Prisma CLI and other required dependencies in your project +1. Introspect the database to generate a Prisma schema +1. Generate Prisma Client +1. Update the queries in your application to use Prisma ORM + +You can find the detailed step-by-step instructions for this process in this guide: [Add Prisma ORM to an existing project](/v7/prisma-orm/add-to-existing-project/prisma-postgres). diff --git a/apps/docs/content/docs/(index)/v8/prisma-postgres/meta.json b/apps/docs/content/docs/(index)/v7/prisma-postgres/meta.json similarity index 79% rename from apps/docs/content/docs/(index)/v8/prisma-postgres/meta.json rename to apps/docs/content/docs/(index)/v7/prisma-postgres/meta.json index 42fcedfea9..35ff24fc9c 100644 --- a/apps/docs/content/docs/(index)/v8/prisma-postgres/meta.json +++ b/apps/docs/content/docs/(index)/v7/prisma-postgres/meta.json @@ -1,6 +1,8 @@ { "title": "Prisma Postgres", + "defaultOpen": true, "pages": [ + "quickstart", "import-from-existing-database-postgresql", "import-from-existing-database-mysql", "from-the-cli" diff --git a/apps/docs/content/docs/(index)/v7/prisma-postgres/quickstart/meta.json b/apps/docs/content/docs/(index)/v7/prisma-postgres/quickstart/meta.json new file mode 100644 index 0000000000..a62046e024 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-postgres/quickstart/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Quickstart", + "pages": [ + "prisma-orm" + ] +} diff --git a/apps/docs/content/docs/(index)/v7/prisma-postgres/quickstart/prisma-orm.mdx b/apps/docs/content/docs/(index)/v7/prisma-postgres/quickstart/prisma-orm.mdx new file mode 100644 index 0000000000..4590195737 --- /dev/null +++ b/apps/docs/content/docs/(index)/v7/prisma-postgres/quickstart/prisma-orm.mdx @@ -0,0 +1,264 @@ +--- +title: Prisma ORM +description: Create a new TypeScript project from scratch by connecting Prisma ORM to Prisma Postgres and generating a Prisma Client for database access +url: /v7/prisma-postgres/quickstart/prisma-orm +metaTitle: 'Quickstart: Prisma Postgres with Prisma ORM (5 min)' +metaDescription: 'Set up Prisma Postgres in a new TypeScript project with Prisma ORM. Create the database, connect, and run your first type-safe queries.' +--- + +[Prisma Postgres](/postgres) is a fully managed PostgreSQL database that scales to zero and integrates smoothly with both Prisma ORM and Prisma Studio. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to Prisma Postgres using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database. + +## Prerequisites + +## 1. Create a new project + +## 2. Install required dependencies + +Install the packages needed for this quickstart: + +```npm +npm install prisma@7.9.1 @types/node --save-dev +npm install @prisma/client@7.9.1 @prisma/adapter-pg dotenv +``` + +Here's what each package does: + +- **`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma migrate`, and `prisma generate` +- **`@prisma/client`** - The Prisma Client library for querying your database +- **`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/v7/core-concepts/supported-databases/postgresql#using-driver-adapters) that connects Prisma Client to your database +- **`dotenv`** - Loads environment variables from your `.env` file + +## 3. Configure ESM support + +Update `tsconfig.json` for ESM compatibility: + +```json title="tsconfig.json" +{ + "compilerOptions": { + "module": "ESNext", + "moduleResolution": "bundler", + "target": "ES2023", + "strict": true, + "esModuleInterop": true, + "ignoreDeprecations": "6.0" + } +} +``` + +Update `package.json` to enable ESM: + +```json title="package.json" +{ + "type": "module" // [!code ++] +} +``` + +## 4. Initialize Prisma ORM + +Next, set up your Prisma ORM project by creating your [Prisma Schema](/orm/v7/prisma-schema/overview) file with the following command: + +```npm +npx prisma init --output ../generated/prisma +``` + +:::info + +`prisma init` creates the Prisma scaffolding and a local `DATABASE_URL`. In the next step, replace that value with a direct `postgres://...` connection string from Prisma Postgres. + +::: + +This command does a few things: + +- Creates a `prisma/` directory with a `schema.prisma` file containing your database connection and schema models +- Creates a `.env` file in the root directory for environment variables +- Generates the Prisma Client in the `generated/prisma/` directory +- Creates a `prisma.config.ts` file for Prisma configuration + +The generated `prisma.config.ts` file looks like this: + +```typescript title="prisma.config.ts" +import "dotenv/config"; +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +The generated schema uses [the ESM-first `prisma-client` generator](/orm/v7/prisma-schema/overview/generators#prisma-client) with a custom output path: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "postgresql" +} +``` + +Create a Prisma Postgres database and replace the generated `DATABASE_URL` in your `.env` file with the `postgres://...` connection string from the CLI output: + +```npm +npx create-db +``` + +## 5. Define your data model + +Open `prisma/schema.prisma` and add the following models: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" +} + +datasource db { + provider = "postgresql" +} + +model User { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + email String @unique // [!code ++] + name String? // [!code ++] + posts Post[] // [!code ++] +} // [!code ++] + +model Post { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + title String // [!code ++] + content String? // [!code ++] + published Boolean @default(false) // [!code ++] + author User @relation(fields: [authorId], references: [id]) // [!code ++] + authorId Int // [!code ++] +} // [!code ++] +``` + +## 6. Create and apply your first migration + +Create your first migration to set up the database tables: + +```npm +npx prisma migrate dev --name init +``` + +This command creates the database tables based on your schema. + +Now run the following command to generate the Prisma Client: + +```npm +npx prisma generate +``` + +## 7. Instantiate Prisma Client + +Now that you have all the dependencies installed, you can instantiate Prisma Client. You need to pass an instance of the Prisma ORM driver adapter adapter to the `PrismaClient` constructor: + +```typescript title="lib/prisma.ts" +import "dotenv/config"; +import { PrismaPg } from "@prisma/adapter-pg"; +import { PrismaClient } from "../generated/prisma/client"; + +const connectionString = `${process.env.DATABASE_URL}`; + +const adapter = new PrismaPg({ connectionString }); +const prisma = new PrismaClient({ adapter }); + +export { prisma }; +``` + +:::tip + +If you need to query your database via HTTP from an edge runtime (Cloudflare Workers, Vercel Edge Functions, etc.), use the [Prisma Postgres serverless driver](/postgres/database/serverless-driver#use-with-prisma-orm). + +::: + +## 8. Write your first query + +Create a `script.ts` file to test your setup: + +```typescript title="script.ts" +import { prisma } from "./lib/prisma"; + +async function main() { + // Create a new user with a post + const user = await prisma.user.create({ + data: { + name: "Alice", + email: "alice@prisma.io", + posts: { + create: { + title: "Hello World", + content: "This is my first post!", + published: true, + }, + }, + }, + include: { + posts: true, + }, + }); + console.log("Created user:", user); + + // Fetch all users with their posts + const allUsers = await prisma.user.findMany({ + include: { + posts: true, + }, + }); + console.log("All users:", JSON.stringify(allUsers, null, 2)); +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Run the script: + +```npm +npx tsx script.ts +``` + +You should see the created user and all users printed to the console! + +## 9. Explore your data with Prisma Studio + +```shell +npx prisma studio +``` + +## Next steps + +You've successfully set up Prisma ORM. Here's what you can explore next: + +- **Learn more about Prisma Client**: Explore the [Prisma Client API](/orm/v7/prisma-client/setup-and-configuration/introduction) for advanced querying, filtering, and relations +- **Database migrations**: Learn about [Prisma Migrate](/orm/v7/prisma-migrate) for evolving your database schema +- **Performance optimization**: Discover [query optimization techniques](/orm/v7/prisma-client/queries/advanced/query-optimization-performance) +- **Build a full application**: Check out our [framework guides](/guides/v7) to integrate Prisma ORM with Next.js, Express, and more +- **Join the community**: Connect with other developers on [Discord](https://pris.ly/discord) + +:::info[Deploy to Compute] + +Want to run this app in the cloud? Deploy it to [Prisma Compute](/compute), which runs your app next to your Prisma Postgres database. Follow [Deploy your first app](/prisma-compute/deploy). + +::: + +## More info + +- [Prisma Postgres documentation](/postgres) +- [Prisma Config reference](/orm/v7/reference/prisma-config-reference) +- [Database connection management](/orm/v7/prisma-client/setup-and-configuration/databases-connections) diff --git a/apps/docs/content/docs/(index)/v8/add-to-existing-project/meta.json b/apps/docs/content/docs/(index)/v8/add-to-existing-project/meta.json deleted file mode 100644 index 84c814653c..0000000000 --- a/apps/docs/content/docs/(index)/v8/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)/v8/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/v8/add-to-existing-project/mongodb.mdx deleted file mode 100644 index 0423f15461..0000000000 --- a/apps/docs/content/docs/(index)/v8/add-to-existing-project/mongodb.mdx +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: MongoDB -description: Add Prisma 8 to an existing MongoDB project. -url: /v8/add-to-existing-project/mongodb -metaTitle: Add Prisma 8 to an existing MongoDB project -metaDescription: Add Prisma 8 to an existing MongoDB project. ---- - -To add Prisma 8 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 24 or newer. If you want Prisma 8 to create a new app for you, use the [MongoDB quickstart](/v8/quickstart/mongodb). - -:::note[The Prisma 8 Release Candidate is available] - -Prisma 8 Release Candidate is now live and the recommended version of the Prisma ORM. Cutting-edge and the future of the Prisma ORM. We’d love for you to try it, explore what’s new, and [share your feedback in Discord](https://pris.ly/discord). - -If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started). - -::: - -For local development, use a replica set. MongoDB Atlas already gives you that. - -## 1. Make sure you can run the example script - -If your project already runs TypeScript scripts, you can skip this step. - -Otherwise, install the script tooling: - -```npm -npm install --save-dev tsx typescript -``` - -Later, `orm init` will also add the Node.js types it needs and make sure the generated Prisma 8 files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma 8 leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app. - -## 2. Initialize Prisma 8 - -From the root of your existing project, run: - -```npm -npx prisma@next orm init --target mongodb -``` - -This is the existing-project path. It preselects MongoDB, adds Prisma 8 files and package scripts to the app you already have, and does not scaffold a new framework project. - -It also adds `prisma-next.md` and project-level Prisma 8 skills for Cursor, Claude Code, Codex, and Windsurf so your agent can read the Prisma 8 usage, upgrade, and extension-author guidance from the project. - -When Prisma 8 asks the remaining setup questions: - -- choose `PSL` -- keep the default schema path, `prisma/contract.prisma` - -## 3. Set your database connection string - -Update `.env` with the connection string for the MongoDB deployment your app already uses: - -```text title=".env" -DATABASE_URL="mongodb://127.0.0.1:27017/app?replicaSet=rs0" -``` - -## 4. Describe the collections you want Prisma 8 to know about - -This is the key adoption step for MongoDB, because you decide which part of the existing database Prisma 8 should model first. - -PostgreSQL has `contract infer`. MongoDB does not, so this step is manual. - -Open `prisma/contract.prisma` and make it match the collections you want Prisma 8 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: - -```prisma title="prisma/contract.prisma" -// use prisma-next - -model User { - id ObjectId @id @map("_id") - email String @unique - name String? - posts Post[] - @@map("users") -} - -model Post { - id ObjectId @id @map("_id") - title String - content String? - author User @relation(fields: [authorId], references: [id]) - authorId ObjectId - @@map("posts") -} -``` - -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. - -## 5. Emit the generated artifacts - -Once the contract looks right, this step turns it into the generated files the runtime and query APIs use. - -Run: - -```npm -npx prisma@next contract emit -``` - -This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed. - -## 6. Run a simple high-level query - -With the emitted artifacts in place, you can test the higher-level API first and confirm Prisma 8 can read the existing collections. - -Create a `script.ts` file: - -```typescript title="script.ts" -import "dotenv/config"; -import { db } from "./prisma/db"; - -async function main() { - const user = await db.orm.users.where({ email: "existing@example.com" }).first(); - console.log(user); - - await db.close(); -} - -main().catch((error) => { - console.error(error); - process.exit(1); -}); -``` - -Run it: - -```npm -npx tsx script.ts -``` - -## 7. Run a simple low-level query - -After the ORM example, this step shows the lower-level MongoDB pipeline builder against the same existing collections. - -Replace `script.ts` with this version: - -```typescript title="script.ts" -import "dotenv/config"; -import { db } from "./prisma/db"; - -async function main() { - const runtime = await db.runtime(); - const plan = db.query - .from("users") - .match((fields) => fields.email.eq("existing@example.com")) - .project("email", "name") - .build(); - - const rows = await runtime.execute(plan); - console.log(rows); - - await db.close(); -} - -main().catch((error) => { - console.error(error); - process.exit(1); -}); -``` - -Run it again: - -```npm -npx tsx script.ts -``` - -## 8. Next steps - -When you change `prisma/contract.prisma`, emit the contract again: - -```npm -npx prisma@next contract emit -``` - -You do not need a migration just to read collections that already exist. Use [migration plan](/cli/v8/migration-plan) when you want Prisma 8 to own a schema change. diff --git a/apps/docs/content/docs/(index)/v8/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/(index)/v8/add-to-existing-project/postgresql.mdx deleted file mode 100644 index 70bce04943..0000000000 --- a/apps/docs/content/docs/(index)/v8/add-to-existing-project/postgresql.mdx +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: PostgreSQL -description: Add Prisma 8 to an existing PostgreSQL project. -url: /v8/add-to-existing-project/postgresql -metaTitle: Add Prisma 8 to an existing PostgreSQL project -metaDescription: Add Prisma 8 to an existing PostgreSQL project. ---- - -To add Prisma 8 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. - -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 24 or newer. If you want Prisma 8 to create a new app for you, use the [PostgreSQL quickstart](/v8/quickstart/postgresql). - -:::note[The Prisma 8 Release Candidate is available] - -Prisma 8 is the next major version of Prisma ORM, now available as a Release Candidate. It’s the cutting-edge version of Prisma ORM and will become the future of Prisma, so we’d love for you to try it, explore what’s new, and [share your feedback in Discord](https://pris.ly/discord). - -If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started). - -::: - -## 1. Make sure you can run the example script - -If your project already runs TypeScript scripts, you can skip this step. - -Otherwise, install the script tooling: - -```npm -npm install --save-dev tsx typescript -``` - -Later, `orm init` will also add the Node.js types it needs and make sure the generated Prisma 8 files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma 8 leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app. - -## 2. Initialize Prisma 8 - -From the root of your existing project, run: - -```npm -npx prisma@next orm init --target postgres -``` - -This is the existing-project path. It preselects PostgreSQL, adds Prisma 8 files and package scripts to the app you already have, and does not scaffold a new framework project. - -It also adds `prisma-next.md` and project-level Prisma 8 skills for Cursor, Claude Code, Codex, and Windsurf so your agent can read the Prisma 8 usage, upgrade, and extension-author guidance from the project. - -When Prisma 8 asks the remaining setup questions: - -- choose `PSL` -- keep the default schema path, `prisma/contract.prisma` - -## 3. Set your database connection string - -Update `.env` with the connection string for the database your app already uses: - -```text title=".env" -DATABASE_URL="postgres://username:password@host:5432/database?sslmode=require" -``` - -## 4. Infer a starter contract from the live database - -This step gives you a starting contract by reading the schema that already exists in PostgreSQL. - -Run: - -```npm -npx prisma@next contract infer --output ./prisma/contract.prisma -``` - -The command writes a first draft of `prisma/contract.prisma`. - -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 8 to know about first, and make the file easier to read. - -## 5. Emit the generated artifacts - -Once the contract looks right, this step turns it into the generated files the runtime and CLI use. - -After you are happy with the contract, run: - -```npm -npx prisma@next contract emit -``` - -This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed. - -## 6. Sign the database - -Record that the live database matches the emitted contract: - -```npm -npx prisma@next db sign -``` - -This step matters in two common cases: - -- the database has never been signed by Prisma 8 before -- the database was signed earlier, but under an older contract hash - -## 7. Run a simple high-level query - -With the database signed, you can test the higher-level API first and confirm Prisma 8 is reading the existing schema correctly. - -Create a `script.ts` file: - -```typescript title="script.ts" -import "dotenv/config"; -import { db } from "./prisma/db"; - -async function main() { - const runtime = await db.connect({ url: process.env.DATABASE_URL! }); - - const users = await db.orm.User - .select("id", "email", "name") - .take(2) - .all(); - - console.log(users); - - await runtime.close(); -} - -main().catch((error) => { - console.error(error); - process.exit(1); -}); -``` - -Run it: - -```npm -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. - -Replace `script.ts` with this version: - -```typescript title="script.ts" -import "dotenv/config"; -import { db } from "./prisma/db"; - -async function main() { - const runtime = await db.connect({ url: process.env.DATABASE_URL! }); - - const plan = db.sql.user - .select("id", "email", "name") - .limit(2) - .build(); - - const rows = await db.runtime().execute(plan); - console.log(rows); - - await runtime.close(); -} - -main().catch((error) => { - console.error(error); - process.exit(1); -}); -``` - -Run it again: - -```npm -npx tsx script.ts -``` - -## 9. Next steps - -When you change `prisma/contract.prisma`, emit the contract again: - -```npm -npx prisma@next contract emit -``` - -Use [db update](/cli/v8/db-update) for a direct development update, or [migration plan](/cli/v8/migration-plan) when you want a checked-in migration. diff --git a/apps/docs/content/docs/(index)/v8/getting-started.mdx b/apps/docs/content/docs/(index)/v8/getting-started.mdx deleted file mode 100644 index 41e4d069ef..0000000000 --- a/apps/docs/content/docs/(index)/v8/getting-started.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Choose a Prisma 8 setup path -description: Choose the fastest path to try Prisma 8 in a new or existing project. -url: /v8/getting-started -metaTitle: Prisma 8 getting started -metaDescription: Choose a Prisma 8 quickstart for a new project or add Prisma 8 to an existing app. -badge: release-candidate ---- - -Start with a quickstart if you want Prisma 8 to create the app. Use the existing-project path if you already have an app and database. - -## Start a new project - -```npm -npx create-prisma@latest -``` - - - }> - 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 replica set, apply the first migration, and run the first query. - - - - - -```text -Create a new [framework] application with Prisma 8, seed it, and run it locally. - -If I have not told you which framework, stop and ask before scaffolding. Valid --template values: next, hono, nuxt, astro, nest, svelte, tanstack-start, elysia. - -1. Scaffold the app: `npx create-prisma@latest create my-app --template [framework] --provider postgres --yes`. -2. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `npx create-db@latest` and show me the claim URL it prints. Export it as `DATABASE_URL` in the shell; the generated scripts read the environment variable, not `.env`. -3. From the project directory, apply the starter contract: `npm run db:init`. Sample users are seeded automatically on the app's first query; there is no separate seed script. -4. Edit the starter contract under `src/prisma/` into a small schema for my use case, then run `npm run contract:emit` and plan and apply the migration: `npx prisma@next migration plan`, then `npx prisma@next migrate --yes`. Migration planning diffs the emitted contract, so the emit step is required. -5. Update the seed script under `src/prisma/` and the app routes to query the new schema, start `npm run dev` in the background (with `DATABASE_URL` exported), and verify with a request against the running app. For the `nest` template, if routes return 500s with `reading 'findAll'` in the logs, add explicit `@Inject()` tokens as shown in https://www.prisma.io/docs/guides/v8/frameworks/nestjs.md. - -Use the installed Prisma 8 skills and the current Prisma docs: https://www.prisma.io/docs/llms.txt (append `.md` to any docs URL for a markdown version). -``` - - - -## Add to an existing project - -```npm -npx prisma@next orm init -``` - - - }> - Add Prisma 8 to an existing PostgreSQL app and infer a starter contract from the live schema. - - }> - Add Prisma 8 to an existing MongoDB app and model the collections you want to query first. - - - - - -```text -Add Prisma 8 to this existing project. - -This flow is for PostgreSQL. If the project uses MongoDB, follow https://www.prisma.io/docs/v8/add-to-existing-project/mongodb.md instead; for other databases, stop and tell me. - -1. Run `npx prisma@next orm init`. It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs Prisma 8 skills for you. -2. Set `DATABASE_URL` in `.env` to my database. If I did not give you one, create a Prisma Postgres database with `npx create-db@latest`, put its connection string in `.env`, and show me the claim URL it prints so I can keep the database. -3. If the database already has tables, infer the contract from it: `npx prisma@next contract infer`, then `npx prisma@next contract emit`, then sign it with `npx prisma@next db sign`. If the database is empty, keep the starter contract and run `npx prisma@next db init`. -4. Write one query with the generated `db` client in an existing code path, run it, and show me the returned rows. - -Follow https://www.prisma.io/docs/v8/add-to-existing-project/postgresql.md and the installed Prisma 8 skills. -``` - - - -## After setup - -- Use the generated app scripts for the first run. -- Open `prisma-next.md` or the installed Prisma 8 skills when you want agent-ready guidance inside the project. -- Change the starter contract when you are ready to model your own data. -- Open the [Prisma 8 overview](/orm/v8) when you want the concepts behind the setup. diff --git a/apps/docs/content/docs/(index)/v8/index.mdx b/apps/docs/content/docs/(index)/v8/index.mdx deleted file mode 100644 index e5ffa1a69c..0000000000 --- a/apps/docs/content/docs/(index)/v8/index.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Introduction to Prisma 8 -description: Prisma 8 is the next major version of Prisma ORM, available as a Release Candidate. -url: /v8 -metaTitle: Introduction to Prisma 8 -metaDescription: Start here for Prisma 8, the TypeScript-native rebuild of Prisma ORM, now a Release Candidate. Quickstarts, framework guides, and agent prompts. -badge: release-candidate ---- - -Prisma 8 is a ground-up rebuild of Prisma ORM, from the runtime and query APIs to the migration flow and project setup. - -:::note[The Prisma 8 Release Candidate is available] - -Prisma 8 is the next major version of Prisma ORM, now available as a Release Candidate. It’s the cutting-edge version of Prisma ORM and will become the future of Prisma, so we’d love for you to try it, explore what’s new, and [share your feedback in Discord](https://pris.ly/discord). - -If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started). - -::: - -Prisma 8 is the recommended starting point for new projects. - -```npm -npx create-prisma@latest -``` - -Start with the setup page when you want a guided first run. - - - }> - Scaffold, provision Prisma Postgres, query, and deploy to Prisma Compute in one sitting. - - }> - Pick a new-project quickstart or add Prisma 8 to an existing app. - - - -## Use with your agent - -Copy this prompt, replace the placeholders, and hand it to your coding agent. The scaffold installs [Prisma 8 skills](/ai/tools/skills) into `.claude/skills/` and `.agents/skills/`: - - - -```text -Create a new [framework] application with Prisma 8, seed it, and run it locally. - -If I have not told you which framework, stop and ask before scaffolding. Valid --template values: next, hono, nuxt, astro, nest, svelte, tanstack-start, elysia. - -1. Scaffold the app: `npx create-prisma@latest create my-app --template [framework] --provider postgres --yes`. -2. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `npx create-db@latest` and show me the claim URL it prints. Export it as `DATABASE_URL` in the shell and write it to `.env` in the project directory; the generated scripts read the environment variable, and the deploy step reads `.env`. -3. From the project directory, apply the starter contract: `npm run db:init`. Sample users are seeded automatically on the app's first query; there is no separate seed script. -4. Edit the starter contract under `src/prisma/` into a small schema for my use case, then run `npm run contract:emit` and plan and apply the migration: `npx prisma@next migration plan`, then `npx prisma@next migrate --yes`. Migration planning diffs the emitted contract, so the emit step is required. -5. Update the seed script under `src/prisma/` and the app routes to query the new schema, start `npm run dev` in the background (with `DATABASE_URL` exported), and verify with a request against the running app. For the `nest` template, if routes return 500s with `reading 'findAll'` in the logs, add explicit `@Inject()` tokens as shown in https://www.prisma.io/docs/guides/v8/frameworks/nestjs.md. -6. Deploy with Prisma Compute. First apply the framework's deploy requirement from the guide at https://www.prisma.io/docs/guides/v8/frameworks/[guide].md, where [guide] is the template name except: template `next` → guide `nextjs`, `nest` → `nestjs`, `svelte` → `sveltekit`. The requirements: Next.js needs `output: "standalone"` in `next.config.ts` (without it the deployed app returns 504s), TanStack Start needs the nitro build plugin, Astro needs the `@astrojs/node` adapter plus `--env HOST=0.0.0.0`, and Elysia needs `--framework bun --entry src/index.ts` on the deploy command. If the template is `svelte`, skip this step; Compute does not support SvelteKit yet. Check `npx @prisma/cli@latest auth whoami`. If I am not signed in, stop and ask me to run `npx @prisma/cli@latest auth login`, because that step opens a browser. Then run `npx @prisma/cli@latest app deploy --create-project my-app --env .env` so DATABASE_URL reaches the deployment, and verify the deployed URL with curl. - -Use the installed Prisma 8 skills and the current Prisma docs: https://www.prisma.io/docs/llms.txt (append `.md` to any docs URL for a markdown version). -``` - - - -## Add Prisma 8 to your framework - -Each guide runs the same journey for a specific framework: scaffold, connect Prisma Postgres, query, and deploy where the framework is supported on Compute. - - - - - - - - - - - - - - -## Learn the fundamentals - -Once you are connected, the Fundamentals section teaches the everyday query patterns. - - - }> - Filter with where, project with select, sort, and paginate. - - }> - Create, update, delete, upsert, and the bulk write variants. - - }> - Read related records with include on PostgreSQL and MongoDB. - - }> - Make several writes succeed or fail together. - - }> - The SQL builder and the MongoDB pipeline builder for shapes the ORM can't express. - - - -## Learn the concepts - - - }> - Learn the core ideas behind contracts, emitted artifacts, runtime clients, query styles, and migrations. - - diff --git a/apps/docs/content/docs/(index)/v8/prisma-postgres/from-the-cli.mdx b/apps/docs/content/docs/(index)/v8/prisma-postgres/from-the-cli.mdx deleted file mode 100644 index 5f0715752c..0000000000 --- a/apps/docs/content/docs/(index)/v8/prisma-postgres/from-the-cli.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: From the CLI -description: Start a Prisma 8 app with Prisma Postgres from the command line. -url: /v8/prisma-postgres/from-the-cli -metaTitle: Prisma 8 with Prisma Postgres from the CLI -metaDescription: Start a Prisma 8 app with Prisma Postgres from the command line. -badge: release-candidate ---- - -Use the CLI when you want Prisma 8 and Prisma Postgres set up without leaving the terminal. - -## Start a new app - -```npm -npx create-prisma@latest -``` - -Choose PostgreSQL when prompted. Setup adds `prisma-next.md`, installs project-level Prisma 8 skills for your coding agent, and writes the generated scripts used below. - -## Create the database - -Create a Prisma Postgres database from the terminal and export its connection string. The generated scripts read the environment variable, not `.env`: - -```npm -npx create-db@latest -``` - -```bash -export DATABASE_URL="" -``` - -The command also prints a claim URL; open it within 24 hours to keep the database in your account. - -## Initialize the database - -From the generated project directory, run: - -```npm -npm run db:init -``` - -## Run the app - -Sample users are seeded automatically on the app's first query. - -```npm -npm run dev -``` - -## Add Prisma 8 to an existing app - -If the app already exists, run Prisma 8 from the project root: - -```npm -npx prisma@next orm init -``` - -Choose PostgreSQL and set `DATABASE_URL` to your Prisma Postgres connection string. Init adds `prisma-next.md`, package scripts, and the Prisma 8 skills for your coding agent. Then follow the [PostgreSQL existing-project guide](/v8/add-to-existing-project/postgresql). - -## Import an existing database - -- Use [Import from PostgreSQL](/v8/prisma-postgres/import-from-existing-database-postgresql) when your source database is PostgreSQL. -- Use [Import from MySQL](/v8/prisma-postgres/import-from-existing-database-mysql) when your source database is MySQL. diff --git a/apps/docs/content/docs/(index)/v8/prisma-postgres/import-from-existing-database-mysql.mdx b/apps/docs/content/docs/(index)/v8/prisma-postgres/import-from-existing-database-mysql.mdx deleted file mode 100644 index a00af0ccf4..0000000000 --- a/apps/docs/content/docs/(index)/v8/prisma-postgres/import-from-existing-database-mysql.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Import from MySQL -description: Import an existing MySQL database into Prisma Postgres, then use it with Prisma 8. -url: /v8/prisma-postgres/import-from-existing-database-mysql -metaTitle: Import from MySQL into Prisma Postgres for Prisma 8 -metaDescription: Import MySQL data into Prisma Postgres, then connect Prisma 8 to the imported database. -badge: release-candidate ---- - -Move an existing MySQL database into Prisma Postgres, then connect Prisma 8 to it. - -## Prerequisites - -You need: - -- the connection URL for the MySQL database you are importing from -- a Prisma Data Platform account -- `pgloader` -- Node.js 24 or newer - -## 1. Create a Prisma Postgres database - -Create a Prisma Postgres database from Console or with the CLI. Copy the direct connection string. You will use it for the import and for `DATABASE_URL`. - -## 2. Create a pgloader config - -Create `config.load`: - -```text title="config.load" -LOAD DATABASE - FROM mysql://USER:PASSWORD@HOST:PORT/DATABASE - INTO postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require - -WITH quote identifiers, - include drop, - create tables, - create indexes, - reset sequences - -ALTER SCHEMA 'DATABASE' RENAME TO 'public'; -``` - -## 3. Import into Prisma Postgres - -Run pgloader: - -```shell -pgloader config.load -``` - -## 4. Add Prisma 8 - -From your app root, initialize Prisma 8: - -```npm -npx prisma@next orm init -``` - -Choose PostgreSQL, set `DATABASE_URL` to the Prisma Postgres connection string, then infer and emit the contract: - -```npm -npx prisma@next contract infer --output ./prisma/contract.prisma -npx prisma@next contract emit -npx prisma@next db sign -``` - -## Next steps - -- Review table and column names in the inferred contract. -- Use the [PostgreSQL existing-project guide](/v8/add-to-existing-project/postgresql) for the first Prisma 8 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)/v8/prisma-postgres/import-from-existing-database-postgresql.mdx b/apps/docs/content/docs/(index)/v8/prisma-postgres/import-from-existing-database-postgresql.mdx deleted file mode 100644 index 9a2e12cec5..0000000000 --- a/apps/docs/content/docs/(index)/v8/prisma-postgres/import-from-existing-database-postgresql.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Import from PostgreSQL -description: Import an existing PostgreSQL database into Prisma Postgres, then use it with Prisma 8. -url: /v8/prisma-postgres/import-from-existing-database-postgresql -metaTitle: Import from PostgreSQL into Prisma Postgres for Prisma 8 -metaDescription: Import PostgreSQL data into Prisma Postgres, then connect Prisma 8 to the imported database. -badge: release-candidate ---- - -Move an existing PostgreSQL database into Prisma Postgres, then connect Prisma 8 to it. - -## Prerequisites - -You need: - -- the connection URL for the PostgreSQL database you are importing from -- a Prisma Data Platform account -- PostgreSQL 17 CLI tools, including `pg_dump` and `pg_restore` -- Node.js 24 or newer - -## 1. Create a Prisma Postgres database - -Create a Prisma Postgres database from Console or with the CLI. Copy the direct connection string. You will use it for the restore and for `DATABASE_URL`. - -## 2. Export from PostgreSQL - -Run `pg_dump` against the source database: - -```shell -pg_dump -Fc -v -d "postgresql://USER:PASSWORD@HOST:PORT/DATABASE" -n public -f db_dump.bak -``` - -## 3. Restore into Prisma Postgres - -Restore the dump with the direct Prisma Postgres connection string: - -```shell -pg_restore -d "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require" -v ./db_dump.bak -``` - -## 4. Add Prisma 8 - -From your app root, initialize Prisma 8: - -```npm -npx prisma@next orm init -``` - -Choose PostgreSQL, set `DATABASE_URL` to the Prisma Postgres connection string, then infer and emit the contract: - -```npm -npx prisma@next contract infer --output ./prisma/contract.prisma -npx prisma@next contract emit -npx prisma@next db sign -``` - -## Next steps - -- Review the inferred contract before you rely on it in application code. -- Use the [PostgreSQL existing-project guide](/v8/add-to-existing-project/postgresql) for the first Prisma 8 query. -- Use the [full Prisma Postgres import guide](/prisma-postgres/import-from-existing-database-postgresql) for deeper migration details. diff --git a/apps/docs/content/docs/(index)/v8/quickstart/meta.json b/apps/docs/content/docs/(index)/v8/quickstart/meta.json deleted file mode 100644 index 3a7edc76ec..0000000000 --- a/apps/docs/content/docs/(index)/v8/quickstart/meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Quickstart", - "pages": ["postgresql", "mongodb"] -} diff --git a/apps/docs/content/docs/(index)/v8/quickstart/mongodb.mdx b/apps/docs/content/docs/(index)/v8/quickstart/mongodb.mdx deleted file mode 100644 index 25712e2e9d..0000000000 --- a/apps/docs/content/docs/(index)/v8/quickstart/mongodb.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: MongoDB -description: Create a new Prisma 8 project with MongoDB using create-prisma@latest. -url: /v8/quickstart/mongodb -metaTitle: 'Quickstart: Prisma 8 with MongoDB' -metaDescription: Scaffold a Prisma 8 project with MongoDB, apply the starter migration, and run your first query. ---- - -Create a Prisma 8 app with MongoDB, apply the first migration, and run your first query against seeded data. - -:::note[The Prisma 8 Release Candidate is available] - -Prisma 8 is the next major version of Prisma ORM, now available as a Release Candidate. It’s the cutting-edge version of Prisma ORM and will become the future of Prisma, so we’d love for you to try it, explore what’s new, and [share your feedback in Discord](https://pris.ly/discord). - -If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started). - -::: - -## Quick start - -```npm -npx create-prisma@latest --provider mongodb -``` - -Run this from a Node.js 24 or newer environment. The command preselects MongoDB and prompts you for the contract authoring style (PSL or TypeScript) and your package manager. - -Setup gives you the app template, a starter contract, `prisma-next.md`, project-level Prisma 8 skills for your coding agent, and package scripts for the database steps below. Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. - -Prisma 8 needs a MongoDB replica set. MongoDB Atlas already gives you one; for local development, run a single-node replica set named `rs0` on port 27017 to match the generated connection string. - -## 1. Set the database connection - -The scaffold writes a `.env` with a local replica-set connection string: - -```text title=".env" -DATABASE_URL="mongodb://localhost:27017/mydb?replicaSet=rs0&directConnection=true" -``` - -The generated scripts read environment variables directly rather than `.env`, and the CLI and the app use different variable names: the CLI commands read `MONGODB_URL`, and the app reads `DATABASE_URL`. Export both in the shell you work in: - -```bash -export MONGODB_URL="mongodb://localhost:27017/mydb?replicaSet=rs0&directConnection=true" -export DATABASE_URL="$MONGODB_URL" -``` - -If you use MongoDB Atlas, use the connection string from your Atlas cluster instead. - -## 2. Create the migration plan - -Create the first migration plan from the starter contract. - -```npm -npm run migration:plan -- --name init -``` - -The output reports the planned operations: creating the `users` and `posts` collections and a unique index on `users.email`. - -## 3. Apply the migration - -Apply the planned migration to MongoDB. - -```npm -npm run migrate -``` - -The output ends with a summary like `Applied 1 migration(s) (3 operation(s)) across 1 contract space(s)`. If it fails with a connection error, confirm your MongoDB deployment is a replica set and `MONGODB_URL` is exported in this shell. - -## 4. Run the app - -Start the app and confirm the sample query runs successfully. - -```npm -npm run dev -``` - -Use the URL or terminal output shown by your template. You should see the seeded users returned from MongoDB. - -## Next steps - -- Open `src/prisma/contract.prisma` or `src/prisma/contract.ts` and change the starter model. -- Use the [MongoDB existing-project guide](/v8/add-to-existing-project/mongodb) if you already have an app and database. -- Read the [Prisma 8 overview](/orm/v8) when you want the concepts behind contracts, query APIs, and migrations. diff --git a/apps/docs/content/docs/(index)/v8/quickstart/postgresql.mdx b/apps/docs/content/docs/(index)/v8/quickstart/postgresql.mdx deleted file mode 100644 index 52a84824ad..0000000000 --- a/apps/docs/content/docs/(index)/v8/quickstart/postgresql.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: PostgreSQL -description: Create a new Prisma 8 project with PostgreSQL using create-prisma@latest. -url: /v8/quickstart/postgresql -metaTitle: 'Quickstart: Prisma 8 with PostgreSQL' -metaDescription: Scaffold a Prisma 8 project with PostgreSQL, initialize the database, and run your first query. ---- - -Create a Prisma 8 app with PostgreSQL and run your first query against seeded data. - -:::note[The Prisma 8 Release Candidate is available] - -Prisma 8 is the next major version of Prisma ORM, now available as a Release Candidate. It’s the cutting-edge version of Prisma ORM and will become the future of Prisma, so we’d love for you to try it, explore what’s new, and [share your feedback in Discord](https://pris.ly/discord). - -If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started). - -::: - -## Quick start - -```npm -npx create-prisma@latest --provider postgres -``` - -Run this from a Node.js 24 or newer environment. The command preselects PostgreSQL and prompts you for the contract authoring style (PSL or TypeScript) and your package manager. - -Setup gives you the app template, a starter contract, `prisma-next.md`, project-level Prisma 8 skills for your coding agent, and package scripts for the database steps below. Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step. - -From here you have two paths: let [Prisma Composer](/composer) run a local Prisma Postgres database for you, or connect a PostgreSQL database you provide. - -## Path A: Run with a local database - -Composer builds the app, starts a local Prisma Postgres database, and applies the starter contract for you. No connection string needed. - -```npm -npm run dev:composer -``` - -Open the URL the command prints. You should see the seeded users returned from PostgreSQL. - -## Path B: Connect your own database - -### 1. Set the database connection - -Export `DATABASE_URL` in the shell you run the commands from. The generated scripts read the variable from the environment, not from `.env`. - -```bash -export DATABASE_URL="postgresql://username:password@host:5432/database?sslmode=require" -``` - -If you don't have a PostgreSQL database yet, `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. - -### 2. Initialize the database - -From the generated project directory, run `db:init` to apply the starter contract to PostgreSQL and sign the database. - -```npm -npm run db:init -``` - -The output ends with a summary like `Applied 5 operation(s) across 1 space(s), database signed`. - -### 3. Run the app - -Start the app and confirm the sample query runs successfully. - -```npm -npm run dev -``` - -Use the URL or terminal output shown by your template. You should see the seeded users returned from PostgreSQL. If the response is `Could not query users yet`, `DATABASE_URL` is not set in the environment the app runs in; export it in the same shell and restart. - -## Next steps - -- Open `src/prisma/contract.prisma` or `src/prisma/contract.ts` and change the starter model. -- Use the [PostgreSQL existing-project guide](/v8/add-to-existing-project/postgresql) if you already have an app and database. -- Read the [Prisma 8 overview](/orm/v8) when you want the concepts behind contracts, query APIs, and migrations. diff --git a/apps/docs/content/docs/accelerate/getting-started.mdx b/apps/docs/content/docs/accelerate/getting-started.mdx index dc6c35708a..83e76ccb70 100644 --- a/apps/docs/content/docs/accelerate/getting-started.mdx +++ b/apps/docs/content/docs/accelerate/getting-started.mdx @@ -11,7 +11,7 @@ metaDescription: Learn how to get up and running with Prisma Accelerate. To get started with Accelerate, you will need the following: - A [Prisma Data Platform account](https://console.prisma.io) -- A project that uses [Prisma Client](/orm/prisma-client/setup-and-configuration/introduction) `4.16.1` or higher. If your project is using interactive transactions, you need to use `5.1.1` or higher. (We always recommend using the latest version of Prisma.) +- A project that uses [Prisma Client](/orm/v7/prisma-client/setup-and-configuration/introduction) `4.16.1` or higher. If your project is using interactive transactions, you need to use `5.1.1` or higher. (We always recommend using the latest version of Prisma.) - A hosted PostgreSQL, MySQL/MariaDB, PlanetScale, CockroachDB, or MongoDB database ## 1. Enable Accelerate @@ -75,7 +75,7 @@ If you are using Prisma with PostgreSQL, there is no need for `directUrl`, as Pr :::info -💡 Accelerate requires [Prisma Client](/orm/prisma-client/setup-and-configuration/introduction) version `4.16.1` or higher and [`@prisma/extension-accelerate`](https://www.npmjs.com/package/@prisma/extension-accelerate) version `1.0.0` or higher. +💡 Accelerate requires [Prisma Client](/orm/v7/prisma-client/setup-and-configuration/introduction) version `4.16.1` or higher and [`@prisma/extension-accelerate`](https://www.npmjs.com/package/@prisma/extension-accelerate) version `1.0.0` or higher. 💡 Accelerate extension [`@prisma/extension-accelerate`](https://www.npmjs.com/package/@prisma/extension-accelerate) version `2.0.0` and above requires Node.js version `18` or higher. @@ -149,7 +149,7 @@ If VS Code does not recognize the `$extends` method, refer to [this section](/ac #### Using the Accelerate extension with other extensions -Since [extensions are applied one after another](/orm/prisma-client/client-extensions#conflicts-in-combined-extensions), make sure you apply them in the correct order. Extensions cannot share behavior and the last extension applied takes precedence. +Since [extensions are applied one after another](/orm/v7/prisma-client/client-extensions#conflicts-in-combined-extensions), make sure you apply them in the correct order. Extensions cannot share behavior and the last extension applied takes precedence. If you are using [Query Insights](/query-insights) in your application, make sure you apply it _before_ the Accelerate extension. For example: diff --git a/apps/docs/content/docs/accelerate/more/faq.mdx b/apps/docs/content/docs/accelerate/more/faq.mdx index f3ff6627cd..dc5c7911ee 100644 --- a/apps/docs/content/docs/accelerate/more/faq.mdx +++ b/apps/docs/content/docs/accelerate/more/faq.mdx @@ -106,7 +106,7 @@ Accelerate's global cache feature may not be a good fit for your app if: - Your application data _always_ needs to be up-to-date on retrieval, making it difficult to establish a reasonable cache strategy. -Even without using Accelerate's global cache, you can still greatly benefit from Accelerate by using its connection pool, especially in serverless or edge functions, where it is difficult to manage and scale database connections. You can learn more about the serverless challenge [here](/orm/prisma-client/setup-and-configuration/databases-connections#the-serverless-challenge). +Even without using Accelerate's global cache, you can still greatly benefit from Accelerate by using its connection pool, especially in serverless or edge functions, where it is difficult to manage and scale database connections. You can learn more about the serverless challenge [here](/orm/v7/prisma-client/setup-and-configuration/databases-connections#the-serverless-challenge). ## Can I use Accelerate with other ORMs/query builders/drivers? @@ -126,11 +126,11 @@ In the rare event of a service disruption, falling back to a direct connection w If there is a service disruption, it's recommended to verify on the [status page](https://pris.ly/data-platform-status). You can reach out to one of Prisma's [support channels](/console/more/support) for assistance. -> **Note:** Additionally, it's worth noting that some edge function runtime environments may not support direct connections with Prisma ORM. For further details, refer to our [Edge functions documentation](/orm/prisma-client/deployment/edge/overview). +> **Note:** Additionally, it's worth noting that some edge function runtime environments may not support direct connections with Prisma ORM. For further details, refer to our [Edge functions documentation](/orm/v7/prisma-client/deployment/edge/overview). ## Are each of the queries within an interactive transaction counted separately for billing? -Yes, [interactive transactions](/orm/prisma-client/queries/transactions#interactive-transactions) are billed based on the individual operations within the transaction. There is no charge for the start, commit, or rollback of the transaction itself. For example, in the following query, there are two billable queries: +Yes, [interactive transactions](/orm/v7/prisma-client/queries/transactions#interactive-transactions) are billed based on the individual operations within the transaction. There is no charge for the start, commit, or rollback of the transaction itself. For example, in the following query, there are two billable queries: ```ts await prisma.$transaction(async (tx) => { @@ -139,7 +139,7 @@ await prisma.$transaction(async (tx) => { }); ``` -However, when using the [`$transaction` API for sequential client operations](/orm/prisma-client/queries/transactions#sequential-operations), regardless of the number of queries within the array, it counts as only one billable query. For example: +However, when using the [`$transaction` API for sequential client operations](/orm/v7/prisma-client/queries/transactions#sequential-operations), regardless of the number of queries within the array, it counts as only one billable query. For example: ```ts await prisma.$transaction([ @@ -148,7 +148,7 @@ await prisma.$transaction([ ]); ``` -If you don't need [interactive transactions](/orm/prisma-client/queries/transactions#interactive-transactions), you can save costs and improve performance by using [sequential operations transactions](/orm/prisma-client/queries/transactions#sequential-operations). Sequential operations transactions perform better on Accelerate because they execute in one round-trip to the database, while interactive transactions require separate round-trips for start, commit, and each individual operation on the transaction. +If you don't need [interactive transactions](/orm/v7/prisma-client/queries/transactions#interactive-transactions), you can save costs and improve performance by using [sequential operations transactions](/orm/v7/prisma-client/queries/transactions#sequential-operations). Sequential operations transactions perform better on Accelerate because they execute in one round-trip to the database, while interactive transactions require separate round-trips for start, commit, and each individual operation on the transaction. ## Can I increase my Accelerate query duration and response size limits? diff --git a/apps/docs/content/docs/accelerate/more/known-limitations.mdx b/apps/docs/content/docs/accelerate/more/known-limitations.mdx index f80c34dcc0..e6a6c1d34f 100644 --- a/apps/docs/content/docs/accelerate/more/known-limitations.mdx +++ b/apps/docs/content/docs/accelerate/more/known-limitations.mdx @@ -10,11 +10,11 @@ Below are descriptions of known limitations when using Accelerate. If you encoun ## Cannot cache raw queries -At the moment, it is not possible to cache the responses of [raw queries](/orm/prisma-client/using-raw-sql/raw-queries). +At the moment, it is not possible to cache the responses of [raw queries](/orm/v7/prisma-client/using-raw-sql/raw-queries). ## Not compatible with the fluent API -Client Extensions (which are used in Accelerate) currently do not correctly forward the [fluent API](/orm/prisma-client/queries/relation-queries#fluent-api) types. We hope to get a fix into Client Extensions soon. +Client Extensions (which are used in Accelerate) currently do not correctly forward the [fluent API](/orm/v7/prisma-client/queries/relation-queries#fluent-api) types. We hope to get a fix into Client Extensions soon. ## Not compatible with extremely heavy or long-running queries diff --git a/apps/docs/content/docs/accelerate/more/troubleshoot.mdx b/apps/docs/content/docs/accelerate/more/troubleshoot.mdx index e3125a12ac..93cb193c5b 100644 --- a/apps/docs/content/docs/accelerate/more/troubleshoot.mdx +++ b/apps/docs/content/docs/accelerate/more/troubleshoot.mdx @@ -12,7 +12,7 @@ When working with Accelerate, you may encounter errors often highlighted by spec This error is triggered when the response size from a database query exceeds the configured query response size limit. We've implemented this restriction to safeguard your application performance, as retrieving data over 5MB can significantly slow down your application due to multiple network layers. Typically, transmitting more than 5MB of data is common when conducting ETL (Extract, Transform, Load) operations. However, for other scenarios such as transactional queries, real-time data fetching for user interfaces, bulk data updates, or aggregating large datasets for analytics outside of ETL contexts, it should generally be avoided. These use cases, while essential, can often be optimized to work within the configured query response size limit, ensuring smoother performance and a better user experience. -### Possible causes for [`P6009`](/orm/reference/error-reference#p6009-responsesizelimitexceeded) +### Possible causes for [`P6009`](/orm/v7/reference/error-reference#p6009-responsesizelimitexceeded) #### Transmitting images/files in response @@ -22,9 +22,9 @@ This error may arise if images or files stored within your table are being fetch #### Over-fetching of data -In certain cases, a large number of records or fields are unintentionally fetched, which results in exceeding the configured query response size limit. This could happen when the [`where`](/orm/reference/prisma-client-reference#where) clause in the query is incorrect or entirely missing. +In certain cases, a large number of records or fields are unintentionally fetched, which results in exceeding the configured query response size limit. This could happen when the [`where`](/orm/v7/reference/prisma-client-reference#where) clause in the query is incorrect or entirely missing. -**Suggested solution:** Configure the query response size limit to be larger. If the limit is still exceeded, double-check that the `where` clause is filtering data as expected. To prevent fetching too many records, consider using [pagination](/orm/prisma-client/queries/pagination). Additionally, use the [`select`](/orm/reference/prisma-client-reference#select) clause to return only the necessary fields, reducing the response size. +**Suggested solution:** Configure the query response size limit to be larger. If the limit is still exceeded, double-check that the `where` clause is filtering data as expected. To prevent fetching too many records, consider using [pagination](/orm/v7/prisma-client/queries/pagination). Additionally, use the [`select`](/orm/v7/reference/prisma-client-reference#select) clause to return only the necessary fields, reducing the response size. #### Fetching a large volume of data @@ -38,7 +38,7 @@ This error occurs when a database query fails to return a response within the co > The time for Accelerate's cross-region networking is excluded from the configured query timeout limit. -### Possible causes for [`P6004`](/orm/reference/error-reference#p6004-querytimeout) +### Possible causes for [`P6004`](/orm/v7/reference/error-reference#p6004-querytimeout) This error could be caused by numerous reasons. Some of the prominent ones are: @@ -66,7 +66,7 @@ Users often rely on CPU and memory usage metrics to gauge database load, which c Moreover, it's crucial to periodically scrutinize and refine essential queries and verify that tables are properly indexed. This proactive approach minimizes the vulnerability of these queries to slowdowns caused by competing workloads. -### Considerations for [`P6009`](/orm/reference/error-reference#p6009-responsesizelimitexceeded) and [`P6004`](/orm/reference/error-reference#p6004-querytimeout) errors +### Considerations for [`P6009`](/orm/v7/reference/error-reference#p6009-responsesizelimitexceeded) and [`P6004`](/orm/v7/reference/error-reference#p6004-querytimeout) errors For runtimes that support Prisma ORM natively, you could consider creating two `PrismaClient` Instances. One with the Accelerate connection string (prefixed with `prisma://`) and the other one with the direct database connection string (prefixed with `postgres://`, `mysql://` etc). The main idea behind this approach is to bypass Accelerate for certain specific queries. @@ -99,7 +99,7 @@ This setup allows you to strategically direct certain operations through the dir This error indicates that Prisma Accelerate cannot establish a connection to your database, potentially due to several reasons. -### Possible causes for [`P6008`](/orm/reference/error-reference#p6008-connectionerrorenginestarterror) +### Possible causes for [`P6008`](/orm/v7/reference/error-reference#p6008-connectionerrorenginestarterror) #### Database Not Publicly accessible @@ -129,7 +129,7 @@ If the database is taking too long to respond to the connection request, Prisma This error occurs when Prisma Accelerate detects a high volume of requests that surpasses allowable thresholds. It acts as a protective measure to safeguard both Prisma Accelerate and your underlying database from excessive load. -### Possible causes for [`P5011`](/orm/reference/error-reference#p5011-too-many-requests) +### Possible causes for [`P5011`](/orm/v7/reference/error-reference#p5011-too-many-requests) #### Aggressive retry loops diff --git a/apps/docs/content/docs/accelerate/reference/api-reference.mdx b/apps/docs/content/docs/accelerate/reference/api-reference.mdx index bb62e68278..8d915d9564 100644 --- a/apps/docs/content/docs/accelerate/reference/api-reference.mdx +++ b/apps/docs/content/docs/accelerate/reference/api-reference.mdx @@ -58,14 +58,14 @@ await prisma.user.findMany({ The following is a list of all read query operations that support `cacheStrategy`: -- [`findUnique()`](/orm/reference/prisma-client-reference#findunique) -- [`findUniqueOrThrow()`](/orm/reference/prisma-client-reference#finduniqueorthrow) -- [`findFirst()`](/orm/reference/prisma-client-reference#findfirst) -- [`findFirstOrThrow()`](/orm/reference/prisma-client-reference#findfirstorthrow) -- [`findMany()`](/orm/reference/prisma-client-reference#findmany) -- [`count()`](/orm/reference/prisma-client-reference#count) -- [`aggregate()`](/orm/reference/prisma-client-reference#aggregate) -- [`groupBy()`](/orm/reference/prisma-client-reference#groupby) +- [`findUnique()`](/orm/v7/reference/prisma-client-reference#findunique) +- [`findUniqueOrThrow()`](/orm/v7/reference/prisma-client-reference#finduniqueorthrow) +- [`findFirst()`](/orm/v7/reference/prisma-client-reference#findfirst) +- [`findFirstOrThrow()`](/orm/v7/reference/prisma-client-reference#findfirstorthrow) +- [`findMany()`](/orm/v7/reference/prisma-client-reference#findmany) +- [`count()`](/orm/v7/reference/prisma-client-reference#count) +- [`aggregate()`](/orm/v7/reference/prisma-client-reference#aggregate) +- [`groupBy()`](/orm/v7/reference/prisma-client-reference#groupby) The `cacheStrategy` parameter is not supported on any write operations, such as `create()`. @@ -229,4 +229,4 @@ const prisma = new PrismaClient().$extends(withAccelerate({ fetch: myFetch })); Prisma Accelerate-related errors start with `P6xxx`. -You can find the full error code reference for Prisma Accelerate [here](/orm/reference/error-reference#prisma-accelerate). +You can find the full error code reference for Prisma Accelerate [here](/orm/v7/reference/error-reference#prisma-accelerate). diff --git a/apps/docs/content/docs/ai/index.mdx b/apps/docs/content/docs/ai/index.mdx index 4099f57c23..b5b988da42 100644 --- a/apps/docs/content/docs/ai/index.mdx +++ b/apps/docs/content/docs/ai/index.mdx @@ -13,7 +13,7 @@ In the era of AI, where code is increasingly written by agents, ensuring clarity Run the following command to bootstrap your database with a prompt: ```npm -npx prisma init --prompt "Create a habit tracker application" +npx prisma@7.9.1 init --prompt "Create a habit tracker application" ``` ## AI Coding Tools diff --git a/apps/docs/content/docs/ai/prompts/astro.mdx b/apps/docs/content/docs/ai/prompts/astro.mdx index e27e70f25e..99f810f416 100644 --- a/apps/docs/content/docs/ai/prompts/astro.mdx +++ b/apps/docs/content/docs/ai/prompts/astro.mdx @@ -88,10 +88,10 @@ export default prisma ```bash # Dev dependencies -npm install prisma tsx --save-dev +npm install prisma@7.9.1 tsx --save-dev # Production dependencies -npm install @prisma/extension-accelerate @prisma/client +npm install @prisma/extension-accelerate @prisma/client@7.9.1 ``` ## CORRECT PRISMA INITIALIZATION diff --git a/apps/docs/content/docs/ai/prompts/nextjs.mdx b/apps/docs/content/docs/ai/prompts/nextjs.mdx index f181e6af18..6416972613 100644 --- a/apps/docs/content/docs/ai/prompts/nextjs.mdx +++ b/apps/docs/content/docs/ai/prompts/nextjs.mdx @@ -168,10 +168,10 @@ export default prisma ```bash # Dev dependencies -npm install prisma tsx --save-dev +npm install prisma@7.9.1 tsx --save-dev # Production dependencies -npm install @prisma/adapter-pg @prisma/client dotenv +npm install @prisma/adapter-pg @prisma/client@7.9.1 dotenv ``` ## CORRECT PRISMA INITIALIZATION @@ -428,11 +428,11 @@ User should follow these steps (AI should provide these instructions): 1. **Install dependencies**: ```npm - npm install prisma tsx --save-dev + npm install prisma@7.9.1 tsx --save-dev ``` ```npm - npm install @prisma/adapter-pg @prisma/client dotenv + npm install @prisma/adapter-pg @prisma/client@7.9.1 dotenv ``` 2. **Initialize Prisma, then create Prisma Postgres:** diff --git a/apps/docs/content/docs/ai/prompts/nuxt.mdx b/apps/docs/content/docs/ai/prompts/nuxt.mdx index f3ea49c45c..d34fee7378 100644 --- a/apps/docs/content/docs/ai/prompts/nuxt.mdx +++ b/apps/docs/content/docs/ai/prompts/nuxt.mdx @@ -174,10 +174,10 @@ export { prisma } ```bash # Production dependencies -npm install @prisma/client @prisma/adapter-pg pg dotenv +npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv # Dev dependencies -npm install -D prisma @types/pg tsx +npm install -D prisma@7.9.1 @types/pg tsx ``` ## CORRECT PRISMA INITIALIZATION @@ -440,11 +440,11 @@ User should follow these steps (AI should provide these instructions): 2. **Install dependencies**: ```bash - npm install @prisma/client @prisma/adapter-pg pg dotenv + npm install @prisma/client@7.9.1 @prisma/adapter-pg pg dotenv ``` ```bash - npm install -D prisma @types/pg tsx + npm install -D prisma@7.9.1 @types/pg tsx ``` 3. **Initialize Prisma AND create Prisma Postgres database** (⚠️ USER MUST RUN MANUALLY): diff --git a/apps/docs/content/docs/ai/prompts/prisma-7.mdx b/apps/docs/content/docs/ai/prompts/prisma-7.mdx index 1c31d71088..1b35fa0834 100644 --- a/apps/docs/content/docs/ai/prompts/prisma-7.mdx +++ b/apps/docs/content/docs/ai/prompts/prisma-7.mdx @@ -72,8 +72,8 @@ alwaysApply: false ## 1) Dependencies - Upgrade/install: - - Dev: `prisma@latest`, `tsx`, `dotenv` (skip if Bun). - - Runtime: `@prisma/client@latest`. + - Dev: `prisma@7.9.1`, `tsx`, `dotenv` (skip if Bun). + - Runtime: `@prisma/client@7.9.1`. - **One** database adapter that matches the datasource: - Postgres: `@prisma/adapter-pg` - SQLite: `@prisma/adapter-better-sqlite3` diff --git a/apps/docs/content/docs/ai/prompts/turborepo.mdx b/apps/docs/content/docs/ai/prompts/turborepo.mdx index 8a4e28fd09..d78001ac1f 100644 --- a/apps/docs/content/docs/ai/prompts/turborepo.mdx +++ b/apps/docs/content/docs/ai/prompts/turborepo.mdx @@ -122,8 +122,8 @@ At repo root: npm install turbo --save-dev # Prisma v7 -npm install prisma tsx --save-dev -npm install @prisma/client dotenv +npm install prisma@7.9.1 tsx --save-dev +npm install @prisma/client@7.9.1 dotenv ``` If using Prisma Postgres: diff --git a/apps/docs/content/docs/ai/tools/skills.mdx b/apps/docs/content/docs/ai/tools/skills.mdx index e52ce03563..abd1737d62 100644 --- a/apps/docs/content/docs/ai/tools/skills.mdx +++ b/apps/docs/content/docs/ai/tools/skills.mdx @@ -16,7 +16,7 @@ Prisma ships skills from three repositories, matched to what you are building: | You are working with | Skills repository | Install command | | --- | --- | --- | | Prisma ORM v7, Prisma Postgres, Prisma Compute | [prisma/skills](https://github.com/prisma/skills) | `npx skills add prisma/skills` | -| [Prisma 8](/orm/v8) | [prisma/prisma](https://github.com/prisma/prisma) (`skills/`) | `npx skills add prisma/prisma/skills` | +| [Prisma 8](/orm) | [prisma/prisma](https://github.com/prisma/prisma) (`skills/`) | `npx skills add prisma/prisma/skills` | | [Prisma Composer](/composer) | [prisma/composer](https://github.com/prisma/composer) (`skills/`) | `npx skills add prisma/composer` | ## Install @@ -33,7 +33,7 @@ Or install only the ones you need: npx skills add prisma/skills --skill prisma-client-api ``` -If you use the Prisma 8 CLI, [`prisma agent install`](/cli/v8/agent) wraps the same registry: with no flags it installs every `prisma/skills` skill for Claude Code and Codex, and `agent status` shows what is installed. +If you use the Prisma 8 CLI, [`prisma agent install`](/cli/agent) wraps the same registry: with no flags it installs every `prisma/skills` skill for Claude Code and Codex, and `agent status` shows what is installed. :::note @@ -63,9 +63,9 @@ Covers ESM module configuration, required driver adapters, the new `prisma.confi ### `prisma-mongodb-upgrade` -Helps you move a MongoDB project from Prisma v6 to [Prisma 8](/orm/v8). +Helps you move a MongoDB project from Prisma v6 to [Prisma 8](/orm). -Covers the migration mechanics: schema-to-contract mapping, client API changes, the migration lifecycle, and cutover verification. Use this when your agent needs to make that move: it maps your schema and queries across and guides the cutover, following the [MongoDB upgrade guide](/guides/v8/upgrade-prisma-orm/mongodb). +Covers the migration mechanics: schema-to-contract mapping, client API changes, the migration lifecycle, and cutover verification. Use this when your agent needs to make that move: it maps your schema and queries across and guides the cutover, following the [MongoDB upgrade guide](/guides/upgrade-prisma-orm/mongodb). ### `prisma-database-setup` @@ -99,7 +99,7 @@ Covers `SqlDriverAdapter`, `Transaction`, savepoint hooks, argument and result m ## Available skills for Prisma 8 -[Prisma 8](/orm/v8) ships its own skills from the [prisma/prisma](https://github.com/prisma/prisma) repository, versioned with the product. Projects scaffolded with `create-prisma` or [`orm init`](/cli/v8/init) install them automatically for every agent runtime the installer supports (Claude Code, Cursor, Codex, Windsurf); skip that step with `orm init --skip-skills`. Add them to an existing project with: +[Prisma 8](/orm) ships its own skills from the [prisma/prisma](https://github.com/prisma/prisma) repository, versioned with the product. Projects scaffolded with `create-prisma` or [`orm init`](/cli/init) install them automatically for every agent runtime the installer supports (Claude Code, Cursor, Codex, Windsurf); skip that step with `orm init --skip-skills`. Add them to an existing project with: ```npm npx skills add prisma/prisma/skills diff --git a/apps/docs/content/docs/ai/tools/tabnine.mdx b/apps/docs/content/docs/ai/tools/tabnine.mdx index 8e6121f20b..5b90aafbd7 100644 --- a/apps/docs/content/docs/ai/tools/tabnine.mdx +++ b/apps/docs/content/docs/ai/tools/tabnine.mdx @@ -22,14 +22,14 @@ AI editors like Tabnine are powerful tools that can drastically improve develope - Data modeling and database schema design - Constructing and optimizing database queries - Generating CRUD functionality and other boilerplate code -- Generating plain SQL queries that can be used with [TypedSQL](/orm/prisma-client/using-raw-sql/typedsql) +- Generating plain SQL queries that can be used with [TypedSQL](/orm/v7/prisma-client/using-raw-sql/typedsql) - Generating code for unit and integrations tests - Guiding through major refactorings - Generating seeding scripts ### Leveraging the Prisma schema -Because Prisma has its own [schema](/orm/prisma-schema/overview), Tabnine can understand the basic shape of your data and help you write code for the other parts of your stack. +Because Prisma has its own [schema](/orm/v7/prisma-schema/overview), Tabnine can understand the basic shape of your data and help you write code for the other parts of your stack. We therefore recommend that you start out by defining your Prisma schema and then use Tabnine to build the application layer around it (including API calls, DTOs, business logic, 3rd party integrations, ...). @@ -287,7 +287,7 @@ export default User; ### How Tabnine helps -While Prisma provides a high-level API for querying, sometimes a developer may need to drop down to raw SQL for more low-level control of a query. In these cases, they can use [TypedSQL](/orm/prisma-client/using-raw-sql/typedsql) which provides full type safety for raq SQL queries in Prisma ORM. +While Prisma provides a high-level API for querying, sometimes a developer may need to drop down to raw SQL for more low-level control of a query. In these cases, they can use [TypedSQL](/orm/v7/prisma-client/using-raw-sql/typedsql) which provides full type safety for raq SQL queries in Prisma ORM. One common use case are aggregation queries, such as calculating percentages of different subscription statuses in the schema example above. diff --git a/apps/docs/content/docs/ai/tutorials/linktree-clone.mdx b/apps/docs/content/docs/ai/tutorials/linktree-clone.mdx index b732764a4c..d02b61c3e0 100644 --- a/apps/docs/content/docs/ai/tutorials/linktree-clone.mdx +++ b/apps/docs/content/docs/ai/tutorials/linktree-clone.mdx @@ -688,7 +688,7 @@ Add this to your `package.json` scripts section: } ``` -📖 **Reference:** [Deploy to Vercel - Build Configuration](/orm/prisma-client/deployment/serverless/deploy-to-vercel#build-configuration) +📖 **Reference:** [Deploy to Vercel - Build Configuration](/orm/v7/prisma-client/deployment/serverless/deploy-to-vercel#build-configuration) ### Step 2: Clean Up Development Files diff --git a/apps/docs/content/docs/ai/tutorials/typefully-clone.mdx b/apps/docs/content/docs/ai/tutorials/typefully-clone.mdx index 290b916f21..3828f6817d 100644 --- a/apps/docs/content/docs/ai/tutorials/typefully-clone.mdx +++ b/apps/docs/content/docs/ai/tutorials/typefully-clone.mdx @@ -498,8 +498,8 @@ Now let's add a database to save favorite tweets! We'll use Prisma ORM with Pris ### Install Dependencies ```npm -npm install prisma tsx --save-dev -npm install @prisma/adapter-pg @prisma/client dotenv +npm install prisma@7.9.1 tsx --save-dev +npm install @prisma/adapter-pg @prisma/client@7.9.1 dotenv ``` ### Initialize Prisma diff --git a/apps/docs/content/docs/cli/v8/agent.mdx b/apps/docs/content/docs/cli/agent.mdx similarity index 90% rename from apps/docs/content/docs/cli/v8/agent.mdx rename to apps/docs/content/docs/cli/agent.mdx index 7fd1dcbad2..e22c8632b7 100644 --- a/apps/docs/content/docs/cli/v8/agent.mdx +++ b/apps/docs/content/docs/cli/agent.mdx @@ -1,7 +1,7 @@ --- title: agent description: Install Prisma skills for AI coding agents. -url: /cli/v8/agent +url: /cli/agent metaTitle: agent | Prisma 8 CLI metaDescription: Learn how to install and inspect Prisma agent skills with the unified Prisma CLI. --- @@ -11,13 +11,13 @@ Use `agent` commands to install and inspect [Prisma agent skills](/ai/tools/skil ## Usage ```npm -npx prisma@next agent install +npx prisma@latest agent install ``` With no flags, `agent install` installs every skill in the registry into the current project, for Claude Code and Codex. Narrow it with `--skill` and `--agent`: ```npm -npx prisma@next agent install --skill prisma-compute --agent claude-code +npx prisma@latest agent install --skill prisma-compute --agent claude-code ``` ## Commands @@ -43,7 +43,7 @@ npx prisma@next agent install --skill prisma-compute --agent claude-code `agent install` covers the `prisma/skills` registry. Two skill sets live with their own products instead: -- **Prisma 8 skills** ([prisma/prisma](https://github.com/prisma/prisma)): installed automatically by [`orm init`](/cli/v8/init), or by hand with `npx skills add prisma/prisma/skills`. +- **Prisma 8 skills** ([prisma/prisma](https://github.com/prisma/prisma)): installed automatically by [`orm init`](/cli/init), or by hand with `npx skills add prisma/prisma/skills`. - **The Composer skill** ([prisma/composer](https://github.com/prisma/composer)): installed with `npx skills add prisma/composer`. See [Agent Skills](/ai/tools/skills) for the full catalog of what each skill teaches your agent. diff --git a/apps/docs/content/docs/cli/v8/auth.mdx b/apps/docs/content/docs/cli/auth.mdx similarity index 81% rename from apps/docs/content/docs/cli/v8/auth.mdx rename to apps/docs/content/docs/cli/auth.mdx index 77d9055044..a3441c6db9 100644 --- a/apps/docs/content/docs/cli/v8/auth.mdx +++ b/apps/docs/content/docs/cli/auth.mdx @@ -1,7 +1,7 @@ --- title: auth -description: Sign in to your Prisma account from the CLI, sign out, and manage workspace sessions. -url: /cli/v8/auth +description: 'Sign in to your Prisma account from the CLI, sign out, and manage workspace sessions.' +url: /cli/auth metaTitle: auth | Prisma 8 CLI metaDescription: Learn how to authenticate the unified Prisma CLI with your Prisma account and manage workspace sessions. --- @@ -11,8 +11,8 @@ Use `auth` commands to manage authentication for the platform commands. Signing ## Usage ```npm -npx prisma@next auth login -npx prisma@next auth whoami +npx prisma@latest auth login +npx prisma@latest auth whoami ``` ## Commands @@ -26,4 +26,4 @@ npx prisma@next auth whoami | `auth workspace use [id-or-name]`| Make one of your workspace sessions current | | `auth workspace logout ` | End one workspace session | -`auth login` signs you in through the browser. Afterward, anything running in that environment inherits the session, including coding agents. For CI, set [`PRISMA_SERVICE_TOKEN`](/cli/v8/configuration#platform-environment-variables) instead. +`auth login` signs you in through the browser. Afterward, anything running in that environment inherits the session, including coding agents. For CI, set [`PRISMA_SERVICE_TOKEN`](/cli/configuration#platform-environment-variables) instead. diff --git a/apps/docs/content/docs/cli/v8/branch.mdx b/apps/docs/content/docs/cli/branch.mdx similarity index 92% rename from apps/docs/content/docs/cli/v8/branch.mdx rename to apps/docs/content/docs/cli/branch.mdx index fe7fab209b..d7e8094922 100644 --- a/apps/docs/content/docs/cli/v8/branch.mdx +++ b/apps/docs/content/docs/cli/branch.mdx @@ -1,7 +1,7 @@ --- title: branch description: List platform branches for a project. -url: /cli/v8/branch +url: /cli/branch metaTitle: branch | Prisma 8 CLI metaDescription: Learn how to inspect Prisma platform branches with the unified Prisma CLI. --- @@ -11,7 +11,7 @@ Use `branch` commands to inspect the platform branches of a project. The command ## Usage ```npm -npx prisma@next branch list +npx prisma@latest branch list ``` ## Commands diff --git a/apps/docs/content/docs/cli/v8/bucket.mdx b/apps/docs/content/docs/cli/bucket.mdx similarity index 91% rename from apps/docs/content/docs/cli/v8/bucket.mdx rename to apps/docs/content/docs/cli/bucket.mdx index 300d652012..e8c0537a66 100644 --- a/apps/docs/content/docs/cli/v8/bucket.mdx +++ b/apps/docs/content/docs/cli/bucket.mdx @@ -1,7 +1,7 @@ --- title: bucket description: Create and manage object-store buckets. -url: /cli/v8/bucket +url: /cli/bucket metaTitle: bucket | Prisma 8 CLI metaDescription: Learn how to create and manage object-store buckets and their access keys with the unified Prisma CLI. --- @@ -11,8 +11,8 @@ Use `bucket` commands to manage object-store buckets in a project. ## Usage ```npm -npx prisma@next bucket list -npx prisma@next bucket create --name my-bucket +npx prisma@latest bucket list +npx prisma@latest bucket create --name my-bucket ``` ## Commands diff --git a/apps/docs/content/docs/cli/v8/build.mdx b/apps/docs/content/docs/cli/build.mdx similarity index 78% rename from apps/docs/content/docs/cli/v8/build.mdx rename to apps/docs/content/docs/cli/build.mdx index 647147380c..f8886f5ffe 100644 --- a/apps/docs/content/docs/cli/v8/build.mdx +++ b/apps/docs/content/docs/cli/build.mdx @@ -1,7 +1,7 @@ --- title: build description: Stream logs for builds created by a git push or the Console. -url: /cli/v8/build +url: /cli/build metaTitle: build | Prisma 8 CLI metaDescription: Learn how to inspect Prisma Compute builds and stream build logs with the unified Prisma CLI. --- @@ -11,7 +11,7 @@ Use `build` commands to inspect builds created by a Git push or the [Console](ht ## Usage ```npm -npx prisma@next build logs --follow +npx prisma@latest build logs --follow ``` ## Commands @@ -20,4 +20,4 @@ npx prisma@next build logs --follow | ---------------------- | ----------------------------------------------------------------------------- | | `build logs ` | Stream logs for a build. `--follow` keeps streaming while the build runs. `--cursor ` resumes from a cursor a previous run reported | -Builds are started by a push to a connected repository or from the Console, not by a CLI command. See [`git`](/cli/v8/git) for connecting a repository, and [Deployments](/compute/deployments) for how builds become deployments. +Builds are started by a push to a connected repository or from the Console, not by a CLI command. See [`git`](/cli/git) for connecting a repository, and [Deployments](/compute/deployments) for how builds become deployments. diff --git a/apps/docs/content/docs/cli/v8/composer.mdx b/apps/docs/content/docs/cli/composer.mdx similarity index 86% rename from apps/docs/content/docs/cli/v8/composer.mdx rename to apps/docs/content/docs/cli/composer.mdx index 4d5bdb7711..c6ec0167a6 100644 --- a/apps/docs/content/docs/cli/v8/composer.mdx +++ b/apps/docs/content/docs/cli/composer.mdx @@ -1,20 +1,20 @@ --- title: composer -description: Deploy, tear down, and locally run Composer applications. -url: /cli/v8/composer +description: 'Deploy, tear down, and locally run Composer applications.' +url: /cli/composer metaTitle: composer | Prisma 8 CLI -metaDescription: Complete reference for the prisma composer command group, including deploy, destroy, dev, and log, their flags, credentials, and the in-process control API. +metaDescription: 'Complete reference for the prisma composer command group, including deploy, destroy, dev, and log, their flags, credentials, and the in-process control API.' --- -Use `composer` commands to deploy and run [Prisma Composer](/composer) applications. Composer ships as the `composer` command group of the unified Prisma CLI, published as `prisma@next` during the Prisma 8 RC. +Use `composer` commands to deploy and run [Prisma Composer](/composer) applications. Composer ships as the `composer` command group of the unified Prisma CLI, published as `prisma@latest`. Every command takes an `` argument: the module whose default export is the application root, typically `module.ts`. All four commands stream the underlying pipeline's own output to the terminal. ## Usage ```npm -npx prisma@next composer deploy module.ts -npx prisma@next composer dev module.ts +npx prisma@latest composer deploy module.ts +npx prisma@latest composer dev module.ts ``` ## Commands @@ -42,8 +42,8 @@ The `deploy` command does not build your application. Run your build command bef | `--build-id ` | Join the deploy record your CI already created rather than letting the target create one | ```npm -npx prisma@next composer deploy module.ts -npx prisma@next composer deploy module.ts --stage feat-auth +npx prisma@latest composer deploy module.ts +npx prisma@latest composer deploy module.ts --stage feat-auth ``` ## `composer destroy` @@ -57,8 +57,8 @@ Tears down the application's deployed resources. Requires an explicit target: `- | `--production` | Tear down the project-level production environment | ```npm -npx prisma@next composer destroy module.ts --stage feat-auth -npx prisma@next composer destroy module.ts --production +npx prisma@latest composer destroy module.ts --stage feat-auth +npx prisma@latest composer destroy module.ts --production ``` ## `composer dev` @@ -71,8 +71,8 @@ Brings the application up entirely on this machine. Runs credential-free against | `--fresh` | Destroy the dev stack and wipe the dev state directory before starting | ```npm -npx prisma@next composer dev module.ts -npx prisma@next composer dev module.ts --fresh +npx prisma@latest composer dev module.ts +npx prisma@latest composer dev module.ts --fresh ``` ## `composer log` @@ -86,8 +86,8 @@ Tails the merged logs of the locally running application. The command only reads | `--tail ` | How many trailing history lines to show before live output (default 20; `0` for live-only) | ```npm -npx prisma@next composer log module.ts -npx prisma@next composer log module.ts catalog.service +npx prisma@latest composer log module.ts +npx prisma@latest composer log module.ts catalog.service ``` ## Global flags diff --git a/apps/docs/content/docs/cli/v8/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx similarity index 87% rename from apps/docs/content/docs/cli/v8/configuration.mdx rename to apps/docs/content/docs/cli/configuration.mdx index a86eecbcbd..ea4c1d7727 100644 --- a/apps/docs/content/docs/cli/v8/configuration.mdx +++ b/apps/docs/content/docs/cli/configuration.mdx @@ -1,9 +1,9 @@ --- title: Configuration description: Configure Prisma 8 CLI commands with prisma.config.ts and global flags. -url: /cli/v8/configuration +url: /cli/configuration metaTitle: Prisma 8 CLI configuration -metaDescription: Learn how Prisma 8 CLI commands find config, read database URLs, and format output. +metaDescription: 'Learn how Prisma 8 CLI commands find config, read database URLs, and format output.' --- Prisma 8 CLI commands read `prisma.config.ts` in your project root. The file has one section per part of the CLI. The Prisma 8 data commands read the `orm` section. @@ -29,10 +29,10 @@ export default defineConfig({ For MongoDB projects, import the section helper from `@prisma/orm-mongo/config` instead. -[`orm init`](/cli/v8/init) writes this file for you. Pass `--config` when your config file is not at `./prisma.config.ts`: +[`orm init`](/cli/init) writes this file for you. Pass `--config` when your config file is not at `./prisma.config.ts`: ```npm -npx prisma@next contract emit --config ./config/prisma.config.ts +npx prisma@latest contract emit --config ./config/prisma.config.ts ``` ## Emit-only config @@ -79,7 +79,7 @@ Re-run `contract emit` after changing extension packs, then update the matching Database commands accept `--db `. If you omit it, Prisma 8 uses the database connection from `prisma.config.ts`. ```npm -npx prisma@next db verify --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" ``` ## Environment variables @@ -91,7 +91,7 @@ npx prisma@next db verify --db "$DATABASE_URL" ## Platform environment variables -The [platform commands](/cli/v8#platform-commands) read these: +The [platform commands](/cli#platform-commands) read these: | Variable | Description | | ---------------------- | ------------------------------------------------------------------- | @@ -105,10 +105,10 @@ The [platform commands](/cli/v8#platform-commands) read these: Use the default text output when running commands locally. Use `--json` in CI or automation: ```npm -npx prisma@next db verify --db "$DATABASE_URL" --json +npx prisma@latest db verify --db "$DATABASE_URL" --json ``` -Use `--no-interactive` for scripts that must never pause for user input. Use `--confirm ` to grant a consent prompt non-interactively. For example, [`db update`](/cli/v8/db-update) asks for the database name before a destructive change. +Use `--no-interactive` for scripts that must never pause for user input. Use `--confirm ` to grant a consent prompt non-interactively. For example, [`db update`](/cli/db-update) asks for the database name before a destructive change. ## JSON output diff --git a/apps/docs/content/docs/cli/v8/contract-emit.mdx b/apps/docs/content/docs/cli/contract-emit.mdx similarity index 71% rename from apps/docs/content/docs/cli/v8/contract-emit.mdx rename to apps/docs/content/docs/cli/contract-emit.mdx index 3e0d76db0b..ad81381fe9 100644 --- a/apps/docs/content/docs/cli/v8/contract-emit.mdx +++ b/apps/docs/content/docs/cli/contract-emit.mdx @@ -1,7 +1,7 @@ --- title: contract emit description: Emit Prisma 8 contract artifacts. -url: /cli/v8/contract-emit +url: /cli/contract-emit metaTitle: contract emit | Prisma 8 CLI metaDescription: Learn how to emit contract.json and contract.d.ts for Prisma 8. --- @@ -13,7 +13,7 @@ The command is offline. It does not need a database connection. ## Usage ```npm -npx prisma@next contract emit +npx prisma@latest contract emit ``` ## Options @@ -36,16 +36,16 @@ Do not edit these files by hand. Re-run `contract emit` after changing the contr ## Examples ```npm -npx prisma@next contract emit -npx prisma@next contract emit --output-path ./generated -npx prisma@next contract emit --json +npx prisma@latest contract emit +npx prisma@latest contract emit --output-path ./generated +npx prisma@latest contract emit --json ``` ## Next steps After emitting, choose the database workflow: -- use [`db init`](/cli/v8/db-init) for first-time bootstrap -- use [`db update`](/cli/v8/db-update) for direct reconciliation -- use [`migration plan`](/cli/v8/migration-plan) for checked-in migrations -- use [`db verify`](/cli/v8/db-verify) to check drift +- use [`db init`](/cli/db-init) for first-time bootstrap +- use [`db update`](/cli/db-update) for direct reconciliation +- use [`migration plan`](/cli/migration-plan) for checked-in migrations +- use [`db verify`](/cli/db-verify) to check drift diff --git a/apps/docs/content/docs/cli/v8/contract-infer.mdx b/apps/docs/content/docs/cli/contract-infer.mdx similarity index 75% rename from apps/docs/content/docs/cli/v8/contract-infer.mdx rename to apps/docs/content/docs/cli/contract-infer.mdx index dfad83e0d4..8a9d1bd40b 100644 --- a/apps/docs/content/docs/cli/v8/contract-infer.mdx +++ b/apps/docs/content/docs/cli/contract-infer.mdx @@ -1,7 +1,7 @@ --- title: contract infer description: Infer a starter contract from an existing database. -url: /cli/v8/contract-infer +url: /cli/contract-infer metaTitle: contract infer | Prisma 8 CLI metaDescription: Learn how to infer a Prisma 8 PSL contract from a live database schema. --- @@ -13,7 +13,7 @@ Use it when you are adding Prisma 8 to an existing database and want an initial ## Usage ```npm -npx prisma@next contract infer --db "$DATABASE_URL" +npx prisma@latest contract infer --db "$DATABASE_URL" ``` ## Options @@ -28,9 +28,9 @@ npx prisma@next contract infer --db "$DATABASE_URL" ## Examples ```npm -npx prisma@next contract infer --db "$DATABASE_URL" -npx prisma@next contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma -npx prisma@next contract infer --db "$DATABASE_URL" --json +npx prisma@latest contract infer --db "$DATABASE_URL" +npx prisma@latest contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma +npx prisma@latest contract infer --db "$DATABASE_URL" --json ``` ## What to review @@ -46,9 +46,9 @@ Inference gives you a starting point, not a finished design. Review: The command stops at `contract.prisma`. Follow it with the emit and sign steps: ```npm -npx prisma@next contract emit -npx prisma@next db sign --db "$DATABASE_URL" -npx prisma@next db verify --db "$DATABASE_URL" +npx prisma@latest contract emit +npx prisma@latest db sign --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" ``` `db sign` is the handoff point where you record that the existing database matches the reviewed contract. diff --git a/apps/docs/content/docs/cli/v8/db-init.mdx b/apps/docs/content/docs/cli/db-init.mdx similarity index 64% rename from apps/docs/content/docs/cli/v8/db-init.mdx rename to apps/docs/content/docs/cli/db-init.mdx index 11f1538900..151845a794 100644 --- a/apps/docs/content/docs/cli/v8/db-init.mdx +++ b/apps/docs/content/docs/cli/db-init.mdx @@ -1,7 +1,7 @@ --- title: db init description: Initialize a database from the current Prisma 8 contract. -url: /cli/v8/db-init +url: /cli/db-init metaTitle: db init | Prisma 8 CLI metaDescription: Learn how to create missing database structures from a Prisma 8 contract and sign the database. --- @@ -13,7 +13,7 @@ It creates everything the contract declares and the database does not have yet, ## Usage ```npm -npx prisma@next db init --db "$DATABASE_URL" +npx prisma@latest db init --db "$DATABASE_URL" ``` ## Options @@ -22,7 +22,7 @@ npx prisma@next db init --db "$DATABASE_URL" | --- | --- | | `--db ` | Connects to the database. | | `--dry-run` | Shows planned operations without applying them. | -| `--advance-ref ` | Advances the named [ref](/cli/v8/migration-ref) to the post-command contract hash. | +| `--advance-ref ` | Advances the named [ref](/cli/migration-ref) to the post-command contract hash. | | `--config ` | Read this config file instead of `./prisma.config.ts`. | | `--json` | Prints a machine-readable result. | @@ -33,21 +33,21 @@ npx prisma@next db init --db "$DATABASE_URL" Run a dry run first when you are not working with a disposable local database: ```npm -npx prisma@next db init --db "$DATABASE_URL" --dry-run +npx prisma@latest db init --db "$DATABASE_URL" --dry-run ``` ## Examples ```npm -npx prisma@next contract emit -npx prisma@next db init --db "$DATABASE_URL" -npx prisma@next db verify --db "$DATABASE_URL" +npx prisma@latest contract emit +npx prisma@latest db init --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" ``` ```npm -npx prisma@next db init --db "$DATABASE_URL" --dry-run --json +npx prisma@latest db init --db "$DATABASE_URL" --dry-run --json ``` ## When to use db update instead -Use [`db update`](/cli/v8/db-update) when the database already exists and you want Prisma 8 to reconcile it with a changed contract. Use [`migration plan`](/cli/v8/migration-plan) when you want a reviewable migration package in version control. +Use [`db update`](/cli/db-update) when the database already exists and you want Prisma 8 to reconcile it with a changed contract. Use [`migration plan`](/cli/migration-plan) when you want a reviewable migration package in version control. diff --git a/apps/docs/content/docs/cli/v8/db-schema.mdx b/apps/docs/content/docs/cli/db-schema.mdx similarity index 66% rename from apps/docs/content/docs/cli/v8/db-schema.mdx rename to apps/docs/content/docs/cli/db-schema.mdx index a731768743..046685478e 100644 --- a/apps/docs/content/docs/cli/v8/db-schema.mdx +++ b/apps/docs/content/docs/cli/db-schema.mdx @@ -1,7 +1,7 @@ --- title: db schema description: Inspect a live database schema. -url: /cli/v8/db-schema +url: /cli/db-schema metaTitle: db schema | Prisma 8 CLI metaDescription: Learn how to inspect a live database schema with Prisma 8. --- @@ -13,7 +13,7 @@ Use it when you need to inspect what Prisma 8 sees in the database before inferr ## Usage ```npm -npx prisma@next db schema --db "$DATABASE_URL" +npx prisma@latest db schema --db "$DATABASE_URL" ``` ## Options @@ -27,10 +27,10 @@ npx prisma@next db schema --db "$DATABASE_URL" ## Examples ```npm -npx prisma@next db schema --db "$DATABASE_URL" -npx prisma@next db schema --db "$DATABASE_URL" --json > schema.json +npx prisma@latest db schema --db "$DATABASE_URL" +npx prisma@latest db schema --db "$DATABASE_URL" --json > schema.json ``` ## Related commands -Use [`contract infer`](/cli/v8/contract-infer) when you want to turn a live schema into a starter PSL contract. Use [`db verify`](/cli/v8/db-verify) when you want to compare the live schema with the emitted contract. +Use [`contract infer`](/cli/contract-infer) when you want to turn a live schema into a starter PSL contract. Use [`db verify`](/cli/db-verify) when you want to compare the live schema with the emitted contract. diff --git a/apps/docs/content/docs/cli/v8/db-sign.mdx b/apps/docs/content/docs/cli/db-sign.mdx similarity index 90% rename from apps/docs/content/docs/cli/v8/db-sign.mdx rename to apps/docs/content/docs/cli/db-sign.mdx index fa97783617..88b4a10e50 100644 --- a/apps/docs/content/docs/cli/v8/db-sign.mdx +++ b/apps/docs/content/docs/cli/db-sign.mdx @@ -1,7 +1,7 @@ --- title: db sign description: Sign a database with the current Prisma 8 contract. -url: /cli/v8/db-sign +url: /cli/db-sign metaTitle: db sign | Prisma 8 CLI metaDescription: Learn how to sign a database once it matches the current Prisma 8 contract. --- @@ -13,7 +13,7 @@ It is idempotent and safe to run in CI or a deployment pipeline. Use it after im ## Usage ```npm -npx prisma@next db sign --db "$DATABASE_URL" +npx prisma@latest db sign --db "$DATABASE_URL" ``` ## Options @@ -37,9 +37,9 @@ npx prisma@next db sign --db "$DATABASE_URL" ## Example ```npm -npx prisma@next contract emit -npx prisma@next db sign --db "$DATABASE_URL" -npx prisma@next db verify --db "$DATABASE_URL" +npx prisma@latest contract emit +npx prisma@latest db sign --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" ``` ## When to use it diff --git a/apps/docs/content/docs/cli/v8/db-update.mdx b/apps/docs/content/docs/cli/db-update.mdx similarity index 74% rename from apps/docs/content/docs/cli/v8/db-update.mdx rename to apps/docs/content/docs/cli/db-update.mdx index 271ce3a264..878b301907 100644 --- a/apps/docs/content/docs/cli/v8/db-update.mdx +++ b/apps/docs/content/docs/cli/db-update.mdx @@ -1,7 +1,7 @@ --- title: db update description: Update a database to match the current Prisma 8 contract. -url: /cli/v8/db-update +url: /cli/db-update metaTitle: db update | Prisma 8 CLI metaDescription: Learn how to reconcile a database with the current Prisma 8 contract. --- @@ -13,7 +13,7 @@ Use it for direct reconciliation when you do not need a checked-in migration pac ## Usage ```npm -npx prisma@next db update --db "$DATABASE_URL" +npx prisma@latest db update --db "$DATABASE_URL" ``` ## Options @@ -23,7 +23,7 @@ npx prisma@next db update --db "$DATABASE_URL" | `--db ` | Connects to the database. | | `--dry-run` | Shows planned operations without applying them. | | `--to ` | Updates to a specific contract (hash, prefix, ref name, migration directory name, or `./path`). | -| `--advance-ref ` | Advances the named [ref](/cli/v8/migration-ref) to the post-command contract hash. | +| `--advance-ref ` | Advances the named [ref](/cli/migration-ref) to the post-command contract hash. | | `--config ` | Read this config file instead of `./prisma.config.ts`. | | `--json` | Prints a machine-readable result. | @@ -32,22 +32,22 @@ npx prisma@next db update --db "$DATABASE_URL" An operation that would destroy data is applied only with your consent: the command asks you to type the database name. In a CI job or a run with `--no-interactive`, where the command cannot ask, pass the consent as `--confirm ` instead: ```npm -npx prisma@next db update --db "$DATABASE_URL" --no-interactive --confirm appdb +npx prisma@latest db update --db "$DATABASE_URL" --no-interactive --confirm appdb ``` ## Recommended flow ```npm -npx prisma@next contract emit -npx prisma@next db update --db "$DATABASE_URL" --dry-run -npx prisma@next db update --db "$DATABASE_URL" -npx prisma@next db verify --db "$DATABASE_URL" +npx prisma@latest contract emit +npx prisma@latest db update --db "$DATABASE_URL" --dry-run +npx prisma@latest db update --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" ``` Use `--dry-run` before applying changes in shared environments. ## When to use migrations instead -For reviewable database changes in version control, use [`migration plan`](/cli/v8/migration-plan) and [`migrate`](/cli/v8/migration-apply). +For reviewable database changes in version control, use [`migration plan`](/cli/migration-plan) and [`migrate`](/cli/migration-apply). Use `db update` for local development, preview environments, and workflows where direct reconciliation is acceptable. diff --git a/apps/docs/content/docs/cli/v8/db-verify.mdx b/apps/docs/content/docs/cli/db-verify.mdx similarity index 83% rename from apps/docs/content/docs/cli/v8/db-verify.mdx rename to apps/docs/content/docs/cli/db-verify.mdx index 19c6ecab90..24e88d723c 100644 --- a/apps/docs/content/docs/cli/v8/db-verify.mdx +++ b/apps/docs/content/docs/cli/db-verify.mdx @@ -1,7 +1,7 @@ --- title: db verify description: Verify a database against the current Prisma 8 contract. -url: /cli/v8/db-verify +url: /cli/db-verify metaTitle: db verify | Prisma 8 CLI metaDescription: Learn how to verify that a database marker and live schema match the Prisma 8 contract. --- @@ -13,7 +13,7 @@ Use it in CI and deployment checks before application code that depends on a con ## Usage ```npm -npx prisma@next db verify --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" ``` ## Options @@ -38,16 +38,16 @@ npx prisma@next db verify --db "$DATABASE_URL" ## Examples ```npm -npx prisma@next db verify --db "$DATABASE_URL" -npx prisma@next db verify --db "$DATABASE_URL" --strict -npx prisma@next db verify --db "$DATABASE_URL" --schema-only -npx prisma@next db verify --db "$DATABASE_URL" --marker-only +npx prisma@latest db verify --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" --strict +npx prisma@latest db verify --db "$DATABASE_URL" --schema-only +npx prisma@latest db verify --db "$DATABASE_URL" --marker-only ``` Use JSON output in automation: ```npm -npx prisma@next db verify --db "$DATABASE_URL" --json +npx prisma@latest db verify --db "$DATABASE_URL" --json ``` ## What failures mean diff --git a/apps/docs/content/docs/cli/v8/feedback.mdx b/apps/docs/content/docs/cli/feedback.mdx similarity index 82% rename from apps/docs/content/docs/cli/v8/feedback.mdx rename to apps/docs/content/docs/cli/feedback.mdx index 8b10deeb7e..1c7c9834e2 100644 --- a/apps/docs/content/docs/cli/v8/feedback.mdx +++ b/apps/docs/content/docs/cli/feedback.mdx @@ -1,7 +1,7 @@ --- title: feedback description: Send feedback to the Prisma CLI team. -url: /cli/v8/feedback +url: /cli/feedback metaTitle: feedback | Prisma 8 CLI metaDescription: Learn how to send feedback to the Prisma CLI team straight from the terminal. --- @@ -11,7 +11,7 @@ metaDescription: Learn how to send feedback to the Prisma CLI team straight from ## Usage ```npm -npx prisma@next feedback "The service logs command saved my afternoon" +npx prisma@latest feedback "The service logs command saved my afternoon" ``` The message can be up to 4000 characters. Feedback is anonymous unless you add `--email
` so the team can reply. diff --git a/apps/docs/content/docs/cli/v8/git.mdx b/apps/docs/content/docs/cli/git.mdx similarity index 94% rename from apps/docs/content/docs/cli/v8/git.mdx rename to apps/docs/content/docs/cli/git.mdx index 736f011cbf..f7d94e8b9d 100644 --- a/apps/docs/content/docs/cli/v8/git.mdx +++ b/apps/docs/content/docs/cli/git.mdx @@ -1,7 +1,7 @@ --- title: git description: Connect a GitHub repository for push-to-deploy. -url: /cli/v8/git +url: /cli/git metaTitle: git | Prisma 8 CLI metaDescription: Learn how to connect and disconnect a GitHub repository for Prisma Compute push-to-deploy with the unified Prisma CLI. --- @@ -11,7 +11,7 @@ Use `git` commands to manage the GitHub repository connection. See [GitHub integ ## Usage ```npm -npx prisma@next git connect +npx prisma@latest git connect ``` ## Commands diff --git a/apps/docs/content/docs/cli/v8/global-flags.mdx b/apps/docs/content/docs/cli/global-flags.mdx similarity index 77% rename from apps/docs/content/docs/cli/v8/global-flags.mdx rename to apps/docs/content/docs/cli/global-flags.mdx index d41fe2c4f5..5f76abda95 100644 --- a/apps/docs/content/docs/cli/v8/global-flags.mdx +++ b/apps/docs/content/docs/cli/global-flags.mdx @@ -1,9 +1,9 @@ --- title: Global flags description: Flags accepted by every command in the unified Prisma CLI. -url: /cli/v8/global-flags +url: /cli/global-flags metaTitle: Global flags | Prisma 8 CLI -metaDescription: Reference for the global flags every Prisma 8 CLI command accepts, including output format, log level, prompts, and config path. +metaDescription: 'Reference for the global flags every Prisma 8 CLI command accepts, including output format, log level, prompts, and config path.' --- All commands in the unified Prisma CLI accept these flags. @@ -23,6 +23,6 @@ All commands in the unified Prisma CLI accept these flags. | `-h`, `--help` | Print help for a command. | | `--version` | Print the CLI version and exit. | -Use `npx prisma@next --help` when you need the exact command help from the installed version. +Use `npx prisma@latest --help` when you need the exact command help from the installed version. -The output modes and the JSON envelope these flags select are documented on [Configuration](/cli/v8/configuration#output-modes). +The output modes and the JSON envelope these flags select are documented on [Configuration](/cli/configuration#output-modes). diff --git a/apps/docs/content/docs/cli/index.mdx b/apps/docs/content/docs/cli/index.mdx index 6e1444c750..721af667c7 100644 --- a/apps/docs/content/docs/cli/index.mdx +++ b/apps/docs/content/docs/cli/index.mdx @@ -1,68 +1,99 @@ --- title: Overview -description: 'The Prisma CLI is the command-line interface for Prisma ORM. Use it to initialize projects, generate Prisma Client, manage databases, run migrations, and more' -metaTitle: Prisma CLI Reference | Commands for ORM, Migrate & Database -metaDescription: 'Complete Prisma CLI reference. Initialize projects, generate Prisma Client, run migrations, manage databases, and use Prisma Studio. Install with npm.' +description: Prisma CLI reference url: /cli +metaTitle: Prisma 8 CLI reference +metaDescription: 'Learn the Prisma 8 CLI commands for contracts, databases, migrations, and refs in the unified Prisma CLI.' --- -The Prisma CLI provides commands for: +Prisma 8 ships with a new, unified Prisma CLI. One binary contains the commands for the platform and ORM including [Prisma Composer](/composer), [Prisma Compute](/compute), and more. -- **Project setup**: Initialize new Prisma projects -- **Code generation**: Generate Prisma Client and other artifacts -- **Database management**: Pull schemas, push changes, seed data -- **Migrations**: Create, apply, and manage database migrations -- **Development tools**: Local database servers, schema validation, formatting +:::note[Using Prisma 7?] -## Installation +Prisma 8 is the current release of Prisma ORM. Prisma 7 remains fully supported; its docs live at [/orm/v7](/orm/v7) and its setup paths at [/v7/getting-started](/v7/getting-started). -The Prisma CLI is available as an npm package. Install it as a development dependency: +::: + +The Prisma 8 CLI ships in the `prisma` package. Run it without installing: ```npm -npm install prisma --save-dev +npx prisma@latest --help +npx prisma@latest contract emit ``` -:::info +With `prisma` installed in your project, these commands become plain `prisma contract emit` and so on. -This page documents the Prisma 7 CLI that ships in the `prisma` package. Prisma 8 introduces a new, unified Prisma CLI that also includes commands for [Prisma Composer](/composer) and [Prisma Compute](/compute). The Prisma 8 RC publishes it as `prisma@next`. See the [Prisma 8 CLI reference](/cli/v8), the [Composer commands](/cli/v8/composer), and the [platform commands](/cli/v8#platform-commands). +For a full app scaffold, use a [Prisma 8 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. -::: +## Platform commands + +The platform commands manage everything your app runs on. With [`service`](/cli/service), [`git`](/cli/git), and [`composer`](/cli/composer) you deploy apps to [Prisma Compute](/compute) and manage their deployments, logs, and domains. With [`postgres`](/cli/postgres) you spin up and manage [Prisma Postgres](/postgres) databases. With [`bucket`](/cli/bucket) you create blob-storage buckets and their access keys. [`auth`](/cli/auth), [`project`](/cli/project), and [`branch`](/cli/branch) handle the account, project, and branch plumbing around them. Each command group has its own page in this section; deployments are created by a git push, the [Console](https://pris.ly/pdp), or [Composer](/composer), never by a standalone `deploy` command. -## Usage +## Common workflows -```bash -prisma [command] +There are two main entry points. Platform users deploy apps, create databases, and provision buckets with the [platform commands](#platform-commands). ORM users manage their schema, contracts, and migrations with the ORM and migration commands. + +### Deploy an app + +Sign in, write the committed compute config, and connect the repository; every push then deploys: + +```npm +npx prisma@latest auth login +npx prisma@latest init +npx prisma@latest git connect ``` -## Commands - -| Command | Description | -| -------------------------------- | ---------------------------------------------------- | -| [`init`](/cli/init) | Set up Prisma for your app | -| [`dev`](/cli/dev) | Start a local Prisma Postgres server for development | -| [`generate`](/cli/generate) | Generate artifacts (e.g. Prisma Client) | -| [`db`](/cli/db) | Manage your database schema and lifecycle | -| [`migrate`](/cli/migrate) | Migrate your database | -| [`studio`](/cli/studio) | Browse your data with Prisma Studio | -| [`validate`](/cli/validate) | Validate your Prisma schema | -| [`format`](/cli/format) | Format your Prisma schema | -| [`version`](/cli/version) | Display Prisma version info | -| [`debug`](/cli/debug) | Display Prisma debug info | +Follow a deploy with [`build logs`](/cli/build) and manage the result with [`service`](/cli/service). -## Global flags +### Create a database + +```npm +npx prisma@latest postgres create mydb +npx prisma@latest postgres connection create mydb +``` -These flags are available for all commands: +`postgres create` prints a one-time connection URL; `postgres connection create` mints another when you need one. See [`postgres`](/cli/postgres). -| Flag | Description | -| ------------------- | ----------------------------------- | -| `--help`, `-h` | Show help information for a command | -| `--preview-feature` | Run Preview Prisma commands | +### Create a bucket + +```npm +npx prisma@latest bucket create --name my-bucket +npx prisma@latest bucket key create +``` -## Using a HTTP proxy +`bucket key create` prints the key's one-time credentials. See [`bucket`](/cli/bucket). -Prisma CLI supports custom HTTP proxies. This is useful when behind a corporate firewall. +### Start in an existing project -Set one of these environment variables: +```npm +npx prisma@latest orm init --target postgres --authoring psl +npx prisma@latest contract emit +npx prisma@latest db init --db "$DATABASE_URL" +``` + +### Adopt an existing database + +```npm +npx prisma@latest contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma +npx prisma@latest contract emit +npx prisma@latest db sign --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" +``` + +### Use checked-in migrations + +```npm +npx prisma@latest contract emit +npx prisma@latest migration plan --name add-users +npx prisma@latest migration status --db "$DATABASE_URL" +npx prisma@latest migrate --db "$DATABASE_URL" +npx prisma@latest db verify --db "$DATABASE_URL" +``` + +## Other commands + +A few commands ship without dedicated pages yet. `format` formats your PSL contract source in place, and `lsp` starts the Prisma 8 language server (spawned by editors, not run interactively). The `migration` group also has read-only inspection commands: `migration list` (on-disk migrations per contract space; `--space`, `--ascii`, `--legend`), `migration log` (executed history from the database ledger; `--db`, `--utc`, `--ascii`), `migration graph` (graph topology; `--space`, `--dot` for Graphviz output, `--ascii`, `--legend`), and `migration check [target]` (artifact and graph integrity; `--space`). Run any of them with `--help` for the details. + +## Global flags -- `HTTP_PROXY` or `http_proxy`: Proxy URL for HTTP traffic (e.g., `http://localhost:8080`) -- `HTTPS_PROXY` or `https_proxy`: Proxy URL for HTTPS traffic (e.g., `https://localhost:8080`) +Every command accepts the same set of output, prompt, and config flags. They are documented on [Global flags](/cli/global-flags). diff --git a/apps/docs/content/docs/cli/init.mdx b/apps/docs/content/docs/cli/init.mdx index 151eb15b1b..091f6ebc04 100644 --- a/apps/docs/content/docs/cli/init.mdx +++ b/apps/docs/content/docs/cli/init.mdx @@ -1,165 +1,76 @@ --- -title: init -description: Set up a new Prisma project in the current directory -metaTitle: prisma init | Create New Prisma Project -metaDescription: 'Bootstrap a new Prisma project with prisma init. Creates schema.prisma, prisma.config.ts, .env. Choose datasource provider or provision Prisma Postgres.' +title: orm init +description: Initialize Prisma 8 files in a project. url: /cli/init +metaTitle: orm init | Prisma 8 CLI +metaDescription: Learn how to initialize Prisma 8 files in an existing project with the orm init command. --- -The `prisma init` command bootstraps a fresh Prisma project within the current directory. +`orm init` scaffolds the Prisma 8 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. -## Usage - -```bash -prisma init [options] -``` - -The command creates a `prisma` directory containing a `schema.prisma` file. By default, the project is configured for [local Prisma Postgres](/local-development/postgres), but you can choose a different database using the `--datasource-provider` option. - -## Options - -| Option | Description | -| ----------------------- | --------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Display help message | -| `--db` | Provision a fully managed Prisma Postgres database on the Prisma Data Platform | -| `--datasource-provider` | Define the datasource provider: `postgresql`, `mysql`, `sqlite`, `sqlserver`, `mongodb`, or `cockroachdb` | -| `--generator-provider` | Define the generator provider to use (default: `prisma-client`) | -| `--preview-feature` | Define a preview feature to use (can be specified multiple times) | -| `--output` | Define Prisma Client generator output path | -| `--url` | Define a custom datasource URL | - -## Flags - -| Flag | Description | -| -------------- | ----------------------------------------------- | -| `--with-model` | Add an example model to the created schema file | - -## Examples - -### Set up a new Prisma project (default) - -Sets up a new project configured for local Prisma Postgres: +Use a [Prisma 8 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 8 files. -```npm -npx prisma init -``` - -### Specify a datasource provider - -Set up a new project with MySQL as the datasource provider: - -```npm -npx prisma init --datasource-provider mysql -``` - -### Specify a generator provider +## Usage -Set up a project with the legacy `prisma-client-js` generator instead of the default `prisma-client` generator: +Run it interactively for a guided setup: ```npm -npx prisma init --generator-provider prisma-client-js +npx prisma@latest orm init ``` -### Specify preview features - -Set up a project with specific preview features enabled: +Or supply `--target` and `--authoring` for a fully scriptable run (CI, AI coding agents, automation): ```npm -npx prisma init --preview-feature metrics +npx prisma@latest orm init --yes --target postgres --authoring psl ``` -Multiple preview features: +## Options -```npm -npx prisma init --preview-feature views --preview-feature metrics -``` +| Option | What it does | +| --- | --- | +| `--target ` | Sets the database target. Use `postgres` or `mongodb`. | +| `--authoring