diff --git a/.claude/skills/prisma-docs-voice/SKILL.md b/.claude/skills/prisma-docs-voice/SKILL.md new file mode 100644 index 0000000000..b939020147 --- /dev/null +++ b/.claude/skills/prisma-docs-voice/SKILL.md @@ -0,0 +1,53 @@ +--- +name: prisma-docs-voice +description: Use when the operator wants Prisma docs, educational content, tutorials, guides, FAQs, or support-style responses reviewed, edited, or rewritten for accuracy, clarity, usefulness, calm tone, and product correctness without hype. Also use when writing or reviewing Prisma Next docs, where it fact-checks against the Prisma Next repo and follows the Prisma Next user-docs spec. +--- + +# Prisma Docs Voice + +Use this skill for docs and educational writing, plus support-style communication that should sound clear and calm rather than promotional. + +## Usage guide + +Use this skill for prompts like: + +- `Does this docs page talk about Accelerate correctly?` +- `Rewrite this guide intro so it is clearer and less hyped.` +- `Check this quickstart for vague claims and missing caveats.` +- `Turn this product note into a helpful support-style response.` +- `Review this docs PR for accuracy, tone, and usefulness.` +- `Write the Prisma Next data-modeling page.` +- `Review this Prisma Next docs PR for accuracy against the repo.` + +## Foundation first + +- If `prisma-product-messaging` is available, consult it first. +- Use that skill for product naming, messaging hierarchy, and uncertainty handling. +- Then read `references/docs-guidance.md`. +- For Prisma Next work (writing or reviewing anything under `/docs/orm/next` or `/docs/next`, or any page describing Prisma Next behavior), read `references/prisma-next.md` before writing. It is the branch that governs source of truth, information architecture, fact-checking, and redirect tracking. + +## Workflow + +1. Identify whether the draft is docs, educational content, FAQ, support-style communication, or Prisma Next docs. +2. Confirm the product references are accurate and specific. +3. Cut hype, vague value claims, and dramatic language. +4. Rewrite for usefulness first. +5. Add step-by-step structure when the reader needs to do something. + +## Large docs review + +When reviewing a docs PR or doc set, prioritize: + +1. Overview and intro paragraphs. +2. Quickstart steps and prerequisites. +3. Command descriptions and examples. +4. Limitation and troubleshooting sections. +5. Any sentence that implies guarantees, defaults, or unsupported behavior. + +## Docs and support rules + +- Accuracy beats cleverness. +- Clarity beats persuasion. +- State limitations honestly. +- Do not use em dashes. +- If the source material is uncertain or incomplete, say so plainly and recommend verification. diff --git a/.claude/skills/prisma-docs-voice/references/docs-guidance.md b/.claude/skills/prisma-docs-voice/references/docs-guidance.md new file mode 100644 index 0000000000..8842822f0d --- /dev/null +++ b/.claude/skills/prisma-docs-voice/references/docs-guidance.md @@ -0,0 +1,74 @@ +# Docs guidance + +Use this for docs, tutorials, educational content, and support-style replies. + +## Docs voice + +Docs should: + +- Explain what the product or feature is. +- Tell the reader when to use it. +- Show the next action clearly. +- Break workflows into steps when useful. +- Use precise names and precise constraints. + +Docs should not: + +- Sound like launch copy. +- Hide important limitations. +- Replace instructions with slogans. +- Assume the reader knows Prisma product boundaries. + +For overview pages and quickstarts: + +- Put the real setup requirement near the start. +- Put important limitations where readers will actually see them. +- Avoid operational absolutes unless the source docs explicitly support them. + +## Educational content + +Educational content should: + +- Teach through concrete examples. +- Explain why the workflow matters. +- Keep jargon under control. +- Stay grounded in real product behavior. + +Educational content should not: + +- Turn every paragraph into a pitch. +- Inflate routine functionality into a grand narrative. + +## Support-style responses + +Support-style replies should: + +- Start by addressing the question directly. +- Acknowledge limitations or uncertainty clearly. +- Give the next action or decision point. +- Stay calm and specific. + +Support-style replies should not: + +- Sound defensive. +- Borrow website or launch language. +- Promise capabilities that are not confirmed. + +## High-risk docs patterns + +Flag these carefully: + +- Claims that a workflow is automatic without showing the trigger or setup. +- Claims that there are no limits, no timeouts, or no cold starts without explicit documentation. +- Claims that a product works for any workload unless the docs clearly support that scope. +- Claims that remove all configuration steps when the actual workflow still needs setup. + +## Example shift + +Weak: + +Prisma Postgres gives you a powerful database experience for modern apps. + +Better: + +Prisma Postgres is the managed PostgreSQL offering in the Prisma platform. Use the pooled connection string for application traffic and the direct connection string for migrations or Prisma Studio. diff --git a/.claude/skills/prisma-docs-voice/references/prisma-next.md b/.claude/skills/prisma-docs-voice/references/prisma-next.md new file mode 100644 index 0000000000..a203028cac --- /dev/null +++ b/.claude/skills/prisma-docs-voice/references/prisma-next.md @@ -0,0 +1,142 @@ +# Prisma Next docs + +Read this before writing or reviewing any Prisma Next docs. It governs the +source of truth, the information architecture, the fact-check discipline, the +writing voice, and redirect tracking. + +Prisma Next is the next major version of Prisma ORM, available in Early Access. +Docs live in the `prisma/web` repo under `apps/docs/content/docs/`. The Prisma +Next ORM docs are authored at `/docs/orm/next` and become `/docs/orm` when +Prisma Next goes generally available; today's Prisma 7 ORM docs at `/docs/orm` +are then pinned to `/docs/orm/v7`. The Prisma Next getting-started pages live +separately at `/docs/next`. Prisma 7 stays the generally available release. + +## Ground truth: fact-check before you write + +Prisma Next is still shaping up, so its behavior changes faster than memory or +training data can track. Never write a Prisma Next behavioral claim (a command, +flag, API method, config key, default, or output) from memory. Trace every +claim to **ground truth**: the Prisma Next repo. + +Repo: https://github.com/prisma/prisma-next + +Clone or fork it locally when you need to check behavior: + +```bash +git clone https://github.com/prisma/prisma-next +``` + +Check claims against these, in rough order of authority: + +- `packages/` — the actual implementation. The final word on how an API, + runtime, or CLI command behaves. +- `examples/` — runnable example apps (per database and framework: Postgres, + MongoDB, SQLite, Cloudflare Workers, React Router, Supabase, and more). Copy + real, working code shapes from here instead of inventing them. +- `docs/` — the internal reference set: `docs/reference/` (capabilities, + MongoDB idioms, CLI patterns, extension packs), `docs/commands/`, + `docs/glossary.md`, `docs/architecture docs/`, and the topic guides + (Testing, Serverless Deployment, Error Handling). +- `AGENTS.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `ROADMAP.md` — orientation and + the phased plan from Early Access to GA. +- The installed agent skills. `npx prisma-next@latest init` (or + `npm create prisma@next`) in a scratch project writes a `prisma-next.md` + primer and one `SKILL.md` per workflow under `.claude/skills//` and + `.agents/skills//`. These skills are the authoritative agent workflows; + use them to verify the exact commands, flags, and setup flow a page teaches. + +Completion criterion: every behavioral claim on the page is backed by a +specific repo file, example, or generated command output. If you cannot find +it, you have not verified it. + +### Call out deltas from Prisma 7 + +Readers arrive knowing Prisma 7. When Prisma Next changes a workflow (schema +authoring, the generated client, query API, migrations, CLI, project setup), +name the difference explicitly. A silent difference reads as a typo; a named +**delta** teaches. Point migrating readers at the Migration guide, not at a +buried aside. + +### Do not guess + +If Prisma Next behavior is unclear, unverifiable in the repo, or still in flux, +do not write a plausible-sounding guess. Flag it: leave a `TODO` with the +open question and the engineering owner, and say plainly that it needs +verification. An honest gap is fixable; a confident wrong claim ships and +misleads. + +## Information architecture: follow the spec + +The canonical structure for Prisma Next user docs is the user-docs spec: + +https://github.com/prisma/prisma-orm-messaging/blob/main/docs-strategy/prisma-next-user-docs-spec.md + +It is a private repo; fetch it with `gh`: + +```bash +gh api repos/prisma/prisma-orm-messaging/contents/docs-strategy/prisma-next-user-docs-spec.md \ + --jq '.content' | base64 -d +``` + +Before writing a page, read, in order: the section brief for its group, the +page template that brief names, the canonical example schema, and the style +section. The spec's own "Writers' quick start" lists these. + +Load the full spec for detail; the rules that bite most often: + +- **The tree** is canonical. Top-level groups (Introduction, Getting started, + Data modeling, Contract authoring, Fundamentals, Middleware, Extensions, + Migrations, CLI, Reference, Guides) are stable. Anything that does not fit + one of them needs a docs RFC, not a new top-level section. +- **One concept per page. Code first, prose second.** Open every page with one + sentence answering its title, then lead with a working example. +- **Pick one template** and follow it: Tutorial (step-by-step to a working + result), Concept-and-example (what a thing is and how it behaves), or + Reference (a scannable lookup for one symbol, flag, or error). +- **Reuse the canonical `User`/`Post` schema and the `db` import.** Do not + invent a new schema per page unless the topic forces it. +- **Multi-database is one canonical page per symbol**, layered by portability: + the portable core as the body, a `` block near the top, and + per-database differences as `## On ` **delta** sections. Reach for + `` only when the snippets are short, fully parallel, and have no shared + core (schema-shape blocks, the `aggregate` case), always Postgres then + MongoDB. Delta sections beat tabs because they stay crawlable for search and + cleanly chunkable for agents. +- Reuse existing MDX components (``, ``, admonitions). A new MDX + component needs an RFC in `prisma/web`. + +## Writing voice: direct, assertive, useful + +Write for a TypeScript developer, often working alongside a coding agent, who +wants to get something done. The docs read well for both humans and agents: +linear prose, exact product names, one canonical page per concept. + +- **Write assertively.** State what to do and why. Imperative headings ("Filter + results", not "Filtering results"). +- **Guide step by step** where the reader must do something; make the next + action and its reason explicit. +- **Keep explanations succinct.** No filler ("we will explore", "let us dive + in", "it is worth noting"). Respect the length budgets in the spec's briefs. +- **Avoid conceptual complexity the page does not need.** Teach the decision in + front of the reader, and link out for depth. +- **No vague hype**, no empty slogans, no dramatic fragments. No em dashes. +- **Exact product names.** Prisma Next is the next major version of Prisma ORM. + Do not reduce the platform to "just an ORM", and do not blur Prisma ORM (the + toolkit) and Prisma Postgres (the managed database). +- **Be honest about Early Access.** Do not imply GA or production readiness. + MongoDB support is still being validated. Avoid unsupported absolutes (`no`, + `all`, `any`, `automatic`, `instant`) and stacked superlatives (`powerful`, + `seamless`, `effortless`, `fast`) unless the page shows how or why. + +The shift to make, every time: + +- Weak (hype, no task): `Curious now? Go use this.` +- Strong (task, reason): `Use this to see how Prisma Next changes the way you + define models, write queries, and structure your Prisma ORM application.` + +## Redirect tracking + +Prisma Next docs will eventually become the latest ORM docs, so URLs will move. +For every new or moved Prisma Next section, record the migration decision in the +tracking file before the section merges. See `references/redirects-tracking.md` +for the format, the columns, and where the file lives. diff --git a/.claude/skills/prisma-docs-voice/references/redirects-tracking.md b/.claude/skills/prisma-docs-voice/references/redirects-tracking.md new file mode 100644 index 0000000000..9d4d88686f --- /dev/null +++ b/.claude/skills/prisma-docs-voice/references/redirects-tracking.md @@ -0,0 +1,68 @@ +# Redirect and URL migration tracking + +Prisma Next ORM docs are authored at `/docs/orm/next`. Prisma 7 ORM docs are the +generally available docs at `/docs/orm`. When Prisma Next goes generally +available, `/docs/orm/next/*` becomes `/docs/orm/*` (Prisma Next is promoted to +the latest ORM docs) and the current Prisma 7 pages are pinned to a versioned +path, `/docs/orm/v7/*`. (The Prisma Next getting-started pages live separately +under `/docs/next` and are not part of that promotion.) + +So sections move and URLs change. Track every decision before the routing +changes land, so redirects are deliberate rather than reconstructed after the +fact. + +This tracking file **documents decisions only**. It does not implement +redirects. Redirects land later in `apps/docs/next.config.mjs` after the table +is reviewed. + +## Where the file lives + +One tracking file per migration effort, in the `prisma/web` repo: + +``` +apps/docs/prisma-next-redirects.md +``` + +It sits next to `next.config.mjs` (where redirects are implemented) and is a +plain working file, not a docs page (Fumadocs only renders `content/docs/`, so +a file at `apps/docs/` never becomes a route). Update it in the same PR that +adds or moves a Prisma Next section. + +## What to record for each new or moved section + +Maintain a table with one row per page. Columns: + +| Column | Meaning | +| --- | --- | +| Current Prisma 7 URL | The live page today, e.g. `/docs/orm/prisma-schema/overview/generators`. Blank if the page is new to Prisma Next. | +| New Prisma Next URL | Where the page lives (or will live) under Prisma Next. | +| Redirect old → Prisma 7 versioned? | Whether the old URL should redirect to a pinned Prisma 7 page (e.g. `/docs/orm/v7/...`) so Prisma 7 readers keep the old behavior. Yes / No. | +| Redirect old → Prisma Next equivalent? | Whether the old URL should redirect to the Prisma Next page instead. Yes / No. | +| No one-to-one equivalent? | Yes when the page has no direct Prisma Next counterpart (removed, split, or merged concept). | +| Notes | Missing, merged, renamed, or deprecated pages; open questions; owner. | + +Rules: + +- A row's "redirect to Prisma 7 versioned" and "redirect to Prisma Next + equivalent" are usually mutually exclusive. If both look true, the page + probably splits into two, so add a note and a second row. +- When there is no one-to-one equivalent, still record the old URL and say in + Notes where its content went (merged into which page, or dropped and why). +- Do not delete rows as decisions settle. Mark them resolved so the history of + the migration stays legible. + +## Template + +Copy this into `apps/docs/prisma-next-redirects.md` to start (or extend) the +table. + +```markdown +# Prisma Next redirect tracking + +Temporary migration-decision log. Documents redirect intent only; redirects are +implemented later in `next.config.mjs` after review. + +| Current Prisma 7 URL | New Prisma Next URL | Redirect old → Prisma 7 versioned? | Redirect old → Prisma Next equivalent? | No 1:1 equivalent? | Notes | +| --- | --- | --- | --- | --- | --- | +| /docs/orm/prisma-schema/overview/generators | /docs/orm/next/prisma-schema/overview/generators (if it exists) | Yes → /docs/orm/v7/prisma-schema/overview/generators | TBD | TBD | Confirm whether Prisma Next keeps a generators concept. If it does, the Prisma Next page owns /docs/orm/... at GA; if not, mark no 1:1 and note where the concept moved. | +``` diff --git a/.gitignore b/.gitignore index 6cd1410a81..d974a2a963 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,4 @@ next-env.d.ts # opensrc - source code for packages opensrc .env +prisma-next/ 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 2607914e40..d393a20fc4 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 @@ -214,4 +214,4 @@ This command will set up Prisma Next in a new or existing project with a simple Tell us what worked and what didn't on [Discord](https://pris.ly/discord) in the `#prisma-next` channel, and **star and watch [prisma/prisma-next](https://pris.ly/pn-gh) on GitHub** to follow development. We'd love to hear your feedback! -Be aware that Prisma Next is not production-ready yet. Prisma 7 is still the right choice for production today. When Prisma Next is ready for general use, it becomes Prisma 8. +Prisma Next is in Early Access. Prisma 7 is the current generally available release, so if you're using it, keep using it. When Prisma Next is ready for general use, it becomes Prisma 8. diff --git a/apps/blog/content/blog/mongodb-without-compromise/index.mdx b/apps/blog/content/blog/mongodb-without-compromise/index.mdx index 8b5944a6ea..35938f7208 100644 --- a/apps/blog/content/blog/mongodb-without-compromise/index.mdx +++ b/apps/blog/content/blog/mongodb-without-compromise/index.mdx @@ -235,7 +235,7 @@ The ORM ecosystem has plenty of healthy competition, and we wanted to make sure ## Where we are, where we're going -Prisma Next is still in its early stages and isn't ready for production use yet. For production applications, Prisma 7 is still the recommended choice. Once Prisma Next is ready for general use, it will become Prisma 8, and upgrading will be a smooth process. +Prisma Next is in Early Access. Prisma 7 is the current generally available release, so if you're using it, keep using it. Once Prisma Next is ready for general use, it will become Prisma 8, and upgrading will be a smooth process. **What works today**: 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 044f7aab0d..685e6b8ad8 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 @@ -143,6 +143,6 @@ Build it, then tell us about it in [`#prisma-next`](https://pris.ly/discord) on Prisma Next is early, and the SPI is stable enough that the existing extensions are real proof of what's possible, though we expect to iterate as more of you build against it. -Prisma 7 remains the right choice for production today, and Prisma Next will become Prisma 8 once it's ready for general use. +Prisma Next is in Early Access, and Prisma 7 is the current generally available release, so if you're using it, keep using it. Prisma Next will become Prisma 8 once it's ready for general use. The most interesting extensions will be the ones you'll write. 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 32a03e856f..2c3e93151e 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 @@ -439,7 +439,7 @@ If you're shipping today while following this work, start with [Prisma ORM](http ## We’re working in the open -Today we’re publishing the Prisma Next repo so you can follow the work as it happens. Even though it's early and not yet production-ready, we’re sharing it now so the community can see where we’re headed and help shape the design. +Today we’re publishing the Prisma Next repo so you can follow the work as it happens. It’s in Early Access, and we’re sharing it now so the community can see where we’re headed and help shape the design. If you want to stay close to the work, **star + watch** the repo. 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 9cf76d7ade..34efb5e890 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 @@ -284,7 +284,7 @@ Most importantly, `migration.ts` combined with `ops.json` is _really_ easy to re ## Try it yourself -Prisma Next is not production-ready yet. Prisma 7 is still the right choice for production today. When Prisma Next is ready for general use, it becomes Prisma 8. +Prisma Next is in Early Access. Prisma 7 is the current generally available release, so if you're using it, keep using it. When Prisma Next is ready for general use, it becomes Prisma 8. Follow development by starring [`prisma/prisma-next`](https://pris.ly/pn-gh) on GitHub. But you can try it now: diff --git a/apps/docs/content/docs/(index)/index.mdx b/apps/docs/content/docs/(index)/index.mdx index ef519b3400..cb6c9f32c6 100644 --- a/apps/docs/content/docs/(index)/index.mdx +++ b/apps/docs/content/docs/(index)/index.mdx @@ -18,6 +18,12 @@ npx prisma init npx create-db ``` +:::note + +[Prisma Next](/next) is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and share feedback while it’s still actively shaping up. + +::: + diff --git a/apps/docs/content/docs/(index)/meta.json b/apps/docs/content/docs/(index)/meta.json index 878f912fea..607bbfdac8 100644 --- a/apps/docs/content/docs/(index)/meta.json +++ b/apps/docs/content/docs/(index)/meta.json @@ -5,6 +5,12 @@ "---Getting Started---", "index", "getting-started", + "---Get started with Prisma Next---", + "next/index", + "next/getting-started", + "---Prisma Next---", + "next/quickstart", + "next/add-to-existing-project", "---Prisma ORM---", "...prisma-orm", "---Prisma Postgres---", diff --git a/apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json b/apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json new file mode 100644 index 0000000000..84c814653c --- /dev/null +++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Add to Existing Project", + "pages": ["postgresql", "mongodb"] +} diff --git a/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx new file mode 100644 index 0000000000..4f1996e665 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx @@ -0,0 +1,176 @@ +--- +title: MongoDB +description: Add Prisma Next to an existing MongoDB project. +url: /next/add-to-existing-project/mongodb +metaTitle: Add Prisma Next to an existing MongoDB project +metaDescription: Add Prisma Next to an existing MongoDB project. +--- + +This guide shows how to add Prisma Next to a project that already uses MongoDB. You will run `prisma-next 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 Next to create a new app for you, use the [MongoDB quickstart](/next/quickstart/mongodb). + +:::note[Prisma Next is in Early Access] + +Prisma Next is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and [share feedback](https://pris.ly/discord) while it’s still actively shaping up. + +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, `prisma-next init` will also add the Node.js types it needs and make sure the generated Prisma Next files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma Next leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app. + +## 2. Initialize Prisma Next + +From the root of your existing project, run: + +```npm +npx prisma-next init --target mongodb +``` + +This is the existing-project path. It preselects MongoDB, adds Prisma Next 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 Next skills for Cursor, Claude Code, Codex, and Windsurf so your agent can read the Prisma Next usage, upgrade, and extension-author guidance from the project. + +When Prisma Next 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 Next to know about + +This is the key adoption step for MongoDB, because you decide which part of the existing database Prisma Next 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 Next 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 Next 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/next/migration-plan) when you want Prisma Next to own a schema change. diff --git a/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx new file mode 100644 index 0000000000..18ee8e8958 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx @@ -0,0 +1,176 @@ +--- +title: PostgreSQL +description: Add Prisma Next to an existing PostgreSQL project. +url: /next/add-to-existing-project/postgresql +metaTitle: Add Prisma Next to an existing PostgreSQL project +metaDescription: Add Prisma Next to an existing PostgreSQL project. +--- + +This guide shows how to add Prisma Next to a project that already uses PostgreSQL. You will run `prisma-next 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 Next to create a new app for you, use the [PostgreSQL quickstart](/next/quickstart/postgresql). + +:::note[Prisma Next is in Early Access] + +Prisma Next is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and [share feedback](https://pris.ly/discord) while it’s still actively shaping up. + +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, `prisma-next init` will also add the Node.js types it needs and make sure the generated Prisma Next files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma Next leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app. + +## 2. Initialize Prisma Next + +From the root of your existing project, run: + +```npm +npx prisma-next init --target postgres +``` + +This is the existing-project path. It preselects PostgreSQL, adds Prisma Next 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 Next skills for Cursor, Claude Code, Codex, and Windsurf so your agent can read the Prisma Next usage, upgrade, and extension-author guidance from the project. + +When Prisma Next 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 +``` + +This reads the live PostgreSQL schema and 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 Next 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 Next 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 Next 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/next/db-update) for a direct development update, or [migration plan](/cli/next/migration-plan) when you want a checked-in migration. diff --git a/apps/docs/content/docs/(index)/next/getting-started.mdx b/apps/docs/content/docs/(index)/next/getting-started.mdx new file mode 100644 index 0000000000..c4adfa7ac8 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/getting-started.mdx @@ -0,0 +1,62 @@ +--- +title: Choose a setup path +description: Choose the fastest path to try Prisma Next in a new or existing project. +url: /next/getting-started +metaTitle: Prisma Next getting started +metaDescription: Choose a Prisma Next quickstart for a new project or add Prisma Next to an existing app. +badge: early-access +--- + +Start with a quickstart if you want Prisma Next 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@next +``` + + + }> + Create the app, choose PostgreSQL, initialize the database, seed data, and run the first query. + + }> + Create the app, choose MongoDB, start or connect to MongoDB, seed data, and run the first query. + + + +## Use Prisma Postgres + +```npm +npx create-prisma@next +``` + + + }> + Create a Prisma Next app and let setup provision Prisma Postgres for the first run. + + }> + Start from the command line when you want the Prisma Postgres path without browsing Console first. + + + +## Add to an existing project + +```npm +npx prisma-next init +``` + + + }> + Add Prisma Next to an existing PostgreSQL app and infer a starter contract from the live schema. + + }> + Add Prisma Next to an existing MongoDB app and model the collections you want to query first. + + + +## After setup + +- Use the generated app scripts for the first run. +- Open `prisma-next.md` or the installed Prisma Next 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 Next overview](/orm/next) when you want the concepts behind the setup. diff --git a/apps/docs/content/docs/(index)/next/index.mdx b/apps/docs/content/docs/(index)/next/index.mdx new file mode 100644 index 0000000000..95c19b9c63 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/index.mdx @@ -0,0 +1,60 @@ +--- +title: Introduction to Prisma Next +description: Prisma Next is the next major version of Prisma ORM, available in Early Access. +url: /next +metaTitle: Introduction to Prisma Next +metaDescription: Prisma Next is the next major version of Prisma ORM, available in Early Access. +badge: early-access +--- + +Prisma Next is a ground-up rebuild of Prisma ORM, covering the runtime, query APIs, migration flow, and project setup. + +:::note[Prisma Next is in Early Access] + +Prisma Next is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and [share feedback](https://pris.ly/discord) while it’s still actively shaping up. + +If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started). + +::: + +Use Prisma Next when you want to try the new developer experience before it becomes the default Prisma ORM path. + +```npm +npx create-prisma@next +``` + +Start with the setup page when you want a guided first run. + + + }> + Pick a new-project quickstart or add Prisma Next to an existing app. + + + +## What you can try + + + }> + Create a Prisma Next app, initialize the database, seed data, and run the first query. + + }> + Create a Prisma Next app with a local MongoDB replica set or your own MongoDB deployment. + + }> + Add Prisma Next to an existing PostgreSQL app with `prisma-next init`. + + }> + Add Prisma Next to an existing MongoDB app and model the collections you want to query first. + + }> + Create a Prisma Next app backed by Prisma Postgres. + + + +## 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)/next/prisma-postgres/from-the-cli.mdx b/apps/docs/content/docs/(index)/next/prisma-postgres/from-the-cli.mdx new file mode 100644 index 0000000000..3a2239a805 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/prisma-postgres/from-the-cli.mdx @@ -0,0 +1,55 @@ +--- +title: From the CLI +description: Start a Prisma Next app with Prisma Postgres from the command line. +url: /next/prisma-postgres/from-the-cli +metaTitle: Prisma Next with Prisma Postgres from the CLI +metaDescription: Start a Prisma Next app with Prisma Postgres from the command line. +badge: early-access +--- + +Use the CLI when you want Prisma Next and Prisma Postgres set up without leaving the terminal. + +## Start a new app + +```npm +npx create-prisma@next +``` + +Choose PostgreSQL and Prisma Postgres when prompted. + +Setup provisions Prisma Postgres, writes `DATABASE_URL`, adds `prisma-next.md`, installs project-level Prisma Next skills for your coding agent, and writes the generated scripts used below. + +## Initialize the database + +From the generated project directory, run: + +```npm +npm run db:init +``` + +## Seed data + +```npm +npm run db:seed +``` + +## Run the app + +```npm +npm run dev +``` + +## Add Prisma Next to an existing app + +If the app already exists, run Prisma Next from the project root: + +```npm +npx prisma-next init +``` + +Choose PostgreSQL, set `DATABASE_URL` to your Prisma Postgres connection string, and let init add `prisma-next.md`, package scripts, and the Prisma Next skills for your coding agent. Then follow the [PostgreSQL existing-project guide](/next/add-to-existing-project/postgresql). + +## Import an existing database + +- Use [Import from PostgreSQL](/next/prisma-postgres/import-from-existing-database-postgresql) when your source database is PostgreSQL. +- Use [Import from MySQL](/next/prisma-postgres/import-from-existing-database-mysql) when your source database is MySQL. diff --git a/apps/docs/content/docs/(index)/next/prisma-postgres/import-from-existing-database-mysql.mdx b/apps/docs/content/docs/(index)/next/prisma-postgres/import-from-existing-database-mysql.mdx new file mode 100644 index 0000000000..f98417e5c6 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/prisma-postgres/import-from-existing-database-mysql.mdx @@ -0,0 +1,71 @@ +--- +title: Import from MySQL +description: Import an existing MySQL database into Prisma Postgres, then use it with Prisma Next. +url: /next/prisma-postgres/import-from-existing-database-mysql +metaTitle: Import from MySQL into Prisma Postgres for Prisma Next +metaDescription: Import MySQL data into Prisma Postgres, then connect Prisma Next to the imported database. +badge: early-access +--- + +Move an existing MySQL database into Prisma Postgres, then connect Prisma Next 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 Next + +From your app root, initialize Prisma Next: + +```npm +npx prisma-next 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](/next/add-to-existing-project/postgresql) for the first Prisma Next 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)/next/prisma-postgres/import-from-existing-database-postgresql.mdx b/apps/docs/content/docs/(index)/next/prisma-postgres/import-from-existing-database-postgresql.mdx new file mode 100644 index 0000000000..dea8eb60fa --- /dev/null +++ b/apps/docs/content/docs/(index)/next/prisma-postgres/import-from-existing-database-postgresql.mdx @@ -0,0 +1,61 @@ +--- +title: Import from PostgreSQL +description: Import an existing PostgreSQL database into Prisma Postgres, then use it with Prisma Next. +url: /next/prisma-postgres/import-from-existing-database-postgresql +metaTitle: Import from PostgreSQL into Prisma Postgres for Prisma Next +metaDescription: Import PostgreSQL data into Prisma Postgres, then connect Prisma Next to the imported database. +badge: early-access +--- + +Move an existing PostgreSQL database into Prisma Postgres, then connect Prisma Next 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 Next + +From your app root, initialize Prisma Next: + +```npm +npx prisma-next 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](/next/add-to-existing-project/postgresql) for the first Prisma Next 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)/next/prisma-postgres/meta.json b/apps/docs/content/docs/(index)/next/prisma-postgres/meta.json new file mode 100644 index 0000000000..42fcedfea9 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/prisma-postgres/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Prisma Postgres", + "pages": [ + "import-from-existing-database-postgresql", + "import-from-existing-database-mysql", + "from-the-cli" + ] +} diff --git a/apps/docs/content/docs/(index)/next/quickstart/meta.json b/apps/docs/content/docs/(index)/next/quickstart/meta.json new file mode 100644 index 0000000000..3a7edc76ec --- /dev/null +++ b/apps/docs/content/docs/(index)/next/quickstart/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Quickstart", + "pages": ["postgresql", "mongodb"] +} diff --git a/apps/docs/content/docs/(index)/next/quickstart/mongodb.mdx b/apps/docs/content/docs/(index)/next/quickstart/mongodb.mdx new file mode 100644 index 0000000000..b7e1382a7b --- /dev/null +++ b/apps/docs/content/docs/(index)/next/quickstart/mongodb.mdx @@ -0,0 +1,89 @@ +--- +title: MongoDB +description: Create a new Prisma Next project with MongoDB using create-prisma@next. +url: /next/quickstart/mongodb +metaTitle: 'Quickstart: Prisma Next with MongoDB' +metaDescription: Scaffold a Prisma Next project with MongoDB, apply the starter migration, seed data, and run your first query. +--- + +Create a Prisma Next app with MongoDB, seed it, and run your first query. + +:::note[Prisma Next is in Early Access] + +Prisma Next is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and [share feedback](https://pris.ly/discord) while it’s still actively shaping up. + +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@next --provider mongodb +``` + +Run this from a Node.js 24 or newer environment. The command preselects MongoDB. The generated local setup gives you a MongoDB replica set through `db:up`; if you use MongoDB Atlas or another existing deployment, set `DATABASE_URL` and skip `db:up`. + +Setup gives you the app template, a starter contract, `prisma-next.md`, project-level Prisma Next skills for your coding agent, and package scripts for the database steps below. + +For local development, use a replica set. MongoDB Atlas already provides one, and the generated `db:up` script starts one for you. + +## 1. Check the database connection + +Open `.env` and confirm that `DATABASE_URL` points to the MongoDB deployment you want Prisma Next to use. + +```text title=".env" +DATABASE_URL="mongodb://127.0.0.1:27017/app?replicaSet=rs0" +``` + +If you use MongoDB Atlas, replace this with the connection string from your Atlas cluster. + +## 2. Start MongoDB + +From the generated project directory, run `db:up` to start the local replica set. + +```npm +npm run db:up +``` + +Skip this command when you use MongoDB Atlas or another existing deployment. + +## 3. Create the migration plan + +Create the first migration plan from the starter contract. + +```npm +npm run migration:plan -- --name init +``` + +## 4. Apply the migration + +Apply the planned migration to MongoDB. + +```npm +npm run migrate +``` + +## 5. Seed data + +`db:seed` inserts sample users so the first query has data to show. + +```npm +npm run db:seed +``` + +## 6. 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](/next/add-to-existing-project/mongodb) if you already have an app and database. +- Read the [Prisma Next overview](/orm/next) when you want the concepts behind contracts, query APIs, and migrations. diff --git a/apps/docs/content/docs/(index)/next/quickstart/postgresql.mdx b/apps/docs/content/docs/(index)/next/quickstart/postgresql.mdx new file mode 100644 index 0000000000..12156bd803 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/quickstart/postgresql.mdx @@ -0,0 +1,71 @@ +--- +title: PostgreSQL +description: Create a new Prisma Next project with PostgreSQL using create-prisma@next. +url: /next/quickstart/postgresql +metaTitle: 'Quickstart: Prisma Next with PostgreSQL' +metaDescription: Scaffold a Prisma Next project with PostgreSQL, initialize the database, seed data, and run your first query. +--- + +Create a Prisma Next app with PostgreSQL, seed it, and run your first query. + +:::note[Prisma Next is in Early Access] + +Prisma Next is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and [share feedback](https://pris.ly/discord) while it’s still actively shaping up. + +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@next --provider postgres +``` + +Run this from a Node.js 24 or newer environment. The command preselects PostgreSQL, so you can focus on the template and database URL prompts. Pick Prisma Postgres if you want setup to create the database for you, or paste your own `DATABASE_URL`. + +Setup gives you the app template, a starter contract, `prisma-next.md`, project-level Prisma Next skills for your coding agent, and package scripts for the database steps below. + +If you use your own database, keep the connection string ready before you start. + +## 1. Check the database connection + +Open `.env` and confirm that `DATABASE_URL` points to the PostgreSQL database you want Prisma Next to use. + +```text title=".env" +DATABASE_URL="postgresql://username:password@host:5432/database?sslmode=require" +``` + +If you chose Prisma Postgres during setup, this value is already written for you. If you pasted your own connection string, keep it in `.env` and do not hardcode it in application code. + +## 2. Initialize the database + +From the generated project directory, run `db:init` to apply the starter schema to PostgreSQL and sign the database. + +```npm +npm run db:init +``` + +## 3. Seed data + +`db:seed` inserts sample users so the first query has data to show. + +```npm +npm run db:seed +``` + +## 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 PostgreSQL. + +## Next steps + +- Open `src/prisma/contract.prisma` or `src/prisma/contract.ts` and change the starter model. +- Use the [PostgreSQL existing-project guide](/next/add-to-existing-project/postgresql) if you already have an app and database. +- Read the [Prisma Next overview](/orm/next) when you want the concepts behind contracts, query APIs, and migrations. 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 bbfa7c4d52..36716edce9 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,4 @@ { "title": "Quickstart", - "pages": ["prisma-orm", "kysely", "drizzle-orm", "typeorm"] + "pages": ["prisma-next", "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 new file mode 100644 index 0000000000..1bfbeedaaa --- /dev/null +++ b/apps/docs/content/docs/(index)/prisma-postgres/quickstart/prisma-next.mdx @@ -0,0 +1,56 @@ +--- +title: Prisma Next +description: Create a Prisma Next app with Prisma Postgres. +url: /prisma-postgres/quickstart/prisma-next +metaTitle: 'Quickstart: Prisma Next with Prisma Postgres' +metaDescription: Create a Prisma Next app, provision Prisma Postgres, seed data, and run your first query. +badge: early-access +--- + +Create a Prisma Next app backed by Prisma Postgres. + +## Quick start + +```npm +npx create-prisma@next +``` + +Run this from a Node.js 24 or newer environment. When prompted, choose PostgreSQL and Prisma Postgres. + +Setup provisions the database, writes `DATABASE_URL`, adds a starter contract, creates `prisma-next.md`, installs project-level Prisma Next skills for your coding agent, and adds package scripts for the database steps below. + +## 1. Create the app + +Run `create-prisma@next` and choose the minimal template if you want the fastest first run. Choose a framework template when you want the first query wired into an app route or page. + +## 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 +``` + +## 3. Seed data + +`db:seed` inserts sample data so the first query returns something immediately. + +```npm +npm run db:seed +``` + +## 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 to confirm the sample query runs successfully. + +## Next steps + +- Open the generated contract and change the starter model. +- Use [Import from PostgreSQL](/next/prisma-postgres/import-from-existing-database-postgresql) or [Import from MySQL](/next/prisma-postgres/import-from-existing-database-mysql) when you want to move an existing database to Prisma Postgres. +- Use the [PostgreSQL existing-project guide](/next/add-to-existing-project/postgresql) when your app already has a Prisma Postgres database. diff --git a/apps/docs/content/docs/cli/meta.json b/apps/docs/content/docs/cli/meta.json index 648b580a5d..e95c2953ad 100644 --- a/apps/docs/content/docs/cli/meta.json +++ b/apps/docs/content/docs/cli/meta.json @@ -6,6 +6,7 @@ "pages": [ "---Introduction---", "index", + "next", "---Standalone commands---", "init", diff --git a/apps/docs/content/docs/cli/next/configuration.mdx b/apps/docs/content/docs/cli/next/configuration.mdx new file mode 100644 index 0000000000..2559fb493f --- /dev/null +++ b/apps/docs/content/docs/cli/next/configuration.mdx @@ -0,0 +1,91 @@ +--- +title: CLI configuration +description: Configure Prisma Next CLI commands with prisma-next.config.ts and global flags. +url: /cli/next/configuration +metaTitle: Prisma Next CLI configuration +metaDescription: Learn how Prisma Next CLI commands find config, read database URLs, and format output. +--- + +Prisma Next CLI commands use `prisma-next.config.ts` as the project entrypoint for contract emission, database operations, and migrations. + +## Config file + +Commands that need project context read the Prisma Next config from your project. For PostgreSQL projects, use the Postgres config helper: + +```typescript title="prisma-next.config.ts" +import "dotenv/config"; +import { defineConfig } from "@prisma-next/postgres/config"; + +export default defineConfig({ + contract: "./prisma/contract.prisma", + db: { + connection: process.env["DATABASE_URL"]!, + }, +}); +``` + +For MongoDB projects, import `defineConfig` from `@prisma-next/mongo/config` instead. + +Pass `--config` when your config file is not in the default project location: + +```bash +prisma-next contract emit --config ./config/prisma-next.config.ts +``` + +## Emit-only config + +`contract emit` does not connect to a database, so the config can omit `db.connection`: + +```typescript title="prisma-next.config.ts" +import { defineConfig } from "@prisma-next/postgres/config"; + +export default defineConfig({ + contract: "./prisma/contract.prisma", +}); +``` + +Add `db.connection` before running commands such as `db verify`, `db sign`, `db init`, `db update`, `db schema`, `contract infer`, or `migration apply`. + +## Extension packs + +Add extension control descriptors to the config when your contract uses extension-provided types: + +```typescript title="prisma-next.config.ts" +import { defineConfig } from "@prisma-next/postgres/config"; +import pgvector from "@prisma-next/extension-pgvector/control"; + +export default defineConfig({ + contract: "./prisma/contract.prisma", + extensions: [pgvector], + db: { + connection: process.env["DATABASE_URL"]!, + }, +}); +``` + +Re-run `prisma-next contract emit` after changing extension packs, then update the matching runtime client. + +## Database URLs + +Database commands accept `--db `. If you omit it, Prisma Next can use the database connection from `prisma-next.config.ts`. + +```bash +prisma-next db verify --db "$DATABASE_URL" +``` + +## Environment variables + +| Variable | What it does | +| --- | --- | +| `DATABASE_URL` | Common place to store the database connection string used by config files and scripts. | +| `NO_COLOR=1` | Disables colored terminal output. | + +## Output modes + +Use the default text output when running commands locally. Use `--json` in CI or automation: + +```bash +prisma-next db verify --db "$DATABASE_URL" --json +``` + +Use `--no-interactive` for scripts that must never pause for user input. diff --git a/apps/docs/content/docs/cli/next/contract-emit.mdx b/apps/docs/content/docs/cli/next/contract-emit.mdx new file mode 100644 index 0000000000..7991b19c5c --- /dev/null +++ b/apps/docs/content/docs/cli/next/contract-emit.mdx @@ -0,0 +1,52 @@ +--- +title: prisma-next contract emit +description: Emit Prisma Next contract artifacts. +url: /cli/next/contract-emit +metaTitle: prisma-next contract emit +metaDescription: Learn how to emit contract.json and contract.d.ts for Prisma Next. +--- + +`prisma-next contract emit` reads your contract source and writes the generated artifacts used by the runtime, verification, and migration tooling. + +The command is offline. It does not need a database connection. + +## Usage + +```bash +prisma-next contract emit +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--config ` | Reads a specific `prisma-next.config.ts` file. | +| `--json` | Prints a machine-readable result. | +| `-q`, `--quiet` | Suppresses nonessential output. | +| `-v`, `--verbose` | Prints more detail. | + +## What it creates + +The command emits: + +- `contract.json`, the canonical machine-readable contract +- `contract.d.ts`, the generated TypeScript contract declarations + +Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list. + +## Examples + +```bash +prisma-next contract emit +prisma-next contract emit --config ./custom-config.ts +prisma-next contract emit --json +``` + +## Next steps + +After emitting, choose the database workflow: + +- use [`prisma-next db init`](/cli/next/db-init) for first-time bootstrap +- use [`prisma-next db update`](/cli/next/db-update) for direct reconciliation +- use [`prisma-next migration plan`](/cli/next/migration-plan) for checked-in migrations +- use [`prisma-next db verify`](/cli/next/db-verify) to check drift diff --git a/apps/docs/content/docs/cli/next/contract-infer.mdx b/apps/docs/content/docs/cli/next/contract-infer.mdx new file mode 100644 index 0000000000..c4e80b446a --- /dev/null +++ b/apps/docs/content/docs/cli/next/contract-infer.mdx @@ -0,0 +1,54 @@ +--- +title: prisma-next contract infer +description: Infer a starter contract from an existing database. +url: /cli/next/contract-infer +metaTitle: prisma-next contract infer +metaDescription: Learn how to infer a Prisma Next PSL contract from a live database schema. +--- + +`prisma-next contract infer` inspects a live database and writes a starter PSL contract. + +Use it when you are adding Prisma Next to an existing database and want an initial contract to review and edit. + +## Usage + +```bash +prisma-next contract infer --db "$DATABASE_URL" +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--db ` | Connects to the database. | +| `--config ` | Reads a specific `prisma-next.config.ts` file. | +| `--output ` | Writes the inferred PSL contract to a specific path. | +| `--json` | Prints a machine-readable result. | + +## Examples + +```bash +prisma-next contract infer --db "$DATABASE_URL" +prisma-next contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma +prisma-next contract infer --db "$DATABASE_URL" --json +``` + +## What to review + +Inference gives you a starting point, not a finished design. Review: + +- model and field names +- relation names +- mapped database names +- defaults, indexes, and constraints +- extension-backed column types + +Then run: + +```bash +prisma-next contract emit +prisma-next db sign --db "$DATABASE_URL" +prisma-next 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/next/db-init.mdx b/apps/docs/content/docs/cli/next/db-init.mdx new file mode 100644 index 0000000000..0129b726fa --- /dev/null +++ b/apps/docs/content/docs/cli/next/db-init.mdx @@ -0,0 +1,52 @@ +--- +title: prisma-next db init +description: Initialize a database from the current Prisma Next contract. +url: /cli/next/db-init +metaTitle: prisma-next db init +metaDescription: Learn how to create missing database structures from a Prisma Next contract and sign the database. +--- + +`prisma-next db init` creates missing database structures from the current emitted contract and signs the database. + +Use it for first setup of a database that should match your current contract. + +## Usage + +```bash +prisma-next db init --db "$DATABASE_URL" +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--db ` | Connects to the database. | +| `--config ` | Reads a specific `prisma-next.config.ts` file. | +| `--dry-run` | Shows planned operations without applying them. | +| `--json` | Prints a machine-readable result. | + +## Behavior + +`db init` is intended for bootstrap work. It creates missing structures needed by the contract and writes the contract marker after the database matches. + +Run a dry run first when you are not working with a disposable local database: + +```bash +prisma-next db init --db "$DATABASE_URL" --dry-run +``` + +## Examples + +```bash +prisma-next contract emit +prisma-next db init --db "$DATABASE_URL" +prisma-next db verify --db "$DATABASE_URL" +``` + +```bash +prisma-next db init --db "$DATABASE_URL" --dry-run --json +``` + +## When to use db update instead + +Use [`prisma-next db update`](/cli/next/db-update) when the database already exists and you want Prisma Next to reconcile it with a changed contract. Use [`prisma-next migration plan`](/cli/next/migration-plan) when you want a reviewable migration package in version control. diff --git a/apps/docs/content/docs/cli/next/db-schema.mdx b/apps/docs/content/docs/cli/next/db-schema.mdx new file mode 100644 index 0000000000..668f5fc4cd --- /dev/null +++ b/apps/docs/content/docs/cli/next/db-schema.mdx @@ -0,0 +1,36 @@ +--- +title: prisma-next db schema +description: Inspect a live database schema. +url: /cli/next/db-schema +metaTitle: prisma-next db schema +metaDescription: Learn how to inspect a live database schema with Prisma Next. +--- + +`prisma-next db schema` reads the live database schema and prints it. The command is read-only. + +Use it when you need to inspect what Prisma Next sees in the database before inferring, signing, updating, or debugging drift. + +## Usage + +```bash +prisma-next db schema --db "$DATABASE_URL" +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--db ` | Connects to the database. | +| `--config ` | Reads a specific `prisma-next.config.ts` file. | +| `--json` | Prints machine-readable schema output. | + +## Examples + +```bash +prisma-next db schema --db "$DATABASE_URL" +prisma-next db schema --db "$DATABASE_URL" --json > schema.json +``` + +## Related commands + +Use [`prisma-next contract infer`](/cli/next/contract-infer) when you want to turn a live schema into a starter PSL contract. Use [`prisma-next db verify`](/cli/next/db-verify) when you want to compare the live schema with the emitted contract. diff --git a/apps/docs/content/docs/cli/next/db-sign.mdx b/apps/docs/content/docs/cli/next/db-sign.mdx new file mode 100644 index 0000000000..7e265dcdc2 --- /dev/null +++ b/apps/docs/content/docs/cli/next/db-sign.mdx @@ -0,0 +1,43 @@ +--- +title: prisma-next db sign +description: Sign a database with the current Prisma Next contract. +url: /cli/next/db-sign +metaTitle: prisma-next db sign +metaDescription: Learn how to sign a database once it matches the current Prisma Next contract. +--- + +`prisma-next db sign` verifies that the live database satisfies the emitted contract and writes the database signature. + +Use it after importing or inferring an existing schema, or after a deployment flow that already applied the required database changes. + +## Usage + +```bash +prisma-next db sign --db "$DATABASE_URL" +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--db ` | Connects to the database. | +| `--config ` | Reads a specific `prisma-next.config.ts` file. | +| `--json` | Prints a machine-readable result. | + +## Example + +```bash +prisma-next contract emit +prisma-next db sign --db "$DATABASE_URL" +prisma-next db verify --db "$DATABASE_URL" +``` + +## When to use it + +Use `db sign` only after you believe the live database already matches the emitted contract. It is common after: + +- `contract infer` for a brownfield database +- a manually reviewed migration flow +- a database restore that you need to mark as matching the current contract + +Do not use `db sign` to hide drift. If verification fails, fix the contract or database first. diff --git a/apps/docs/content/docs/cli/next/db-update.mdx b/apps/docs/content/docs/cli/next/db-update.mdx new file mode 100644 index 0000000000..68d622f3f6 --- /dev/null +++ b/apps/docs/content/docs/cli/next/db-update.mdx @@ -0,0 +1,44 @@ +--- +title: prisma-next db update +description: Update a database to match the current Prisma Next contract. +url: /cli/next/db-update +metaTitle: prisma-next db update +metaDescription: Learn how to reconcile a database with the current Prisma Next contract. +--- + +`prisma-next db update` compares the live database with the emitted contract and applies the required changes. + +Use it for direct reconciliation when you do not need a checked-in migration package. + +## Usage + +```bash +prisma-next db update --db "$DATABASE_URL" +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--db ` | Connects to the database. | +| `--config ` | Reads a specific `prisma-next.config.ts` file. | +| `--dry-run` | Shows planned operations without applying them. | +| `-y`, `--yes` | Confirms prompts where the command supports confirmation. | +| `--json` | Prints a machine-readable result. | + +## Recommended flow + +```bash +prisma-next contract emit +prisma-next db update --db "$DATABASE_URL" --dry-run +prisma-next db update --db "$DATABASE_URL" +prisma-next 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 [`prisma-next migration plan`](/cli/next/migration-plan) and [`prisma-next migration apply`](/cli/next/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/next/db-verify.mdx b/apps/docs/content/docs/cli/next/db-verify.mdx new file mode 100644 index 0000000000..dca6a1d1ed --- /dev/null +++ b/apps/docs/content/docs/cli/next/db-verify.mdx @@ -0,0 +1,54 @@ +--- +title: prisma-next db verify +description: Verify a database against the current Prisma Next contract. +url: /cli/next/db-verify +metaTitle: prisma-next db verify +metaDescription: Learn how to verify that a database marker and live schema match the Prisma Next contract. +--- + +`prisma-next db verify` checks whether the database marker and live schema match your emitted contract. + +Use it in CI and deployment checks before application code that depends on a contract reaches users. + +## Usage + +```bash +prisma-next db verify --db "$DATABASE_URL" +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--db ` | Connects to the database. | +| `--config ` | Reads a specific `prisma-next.config.ts` file. | +| `--marker-only` | Checks only the database marker. | +| `--schema-only` | Checks only whether the live schema satisfies the contract. | +| `--strict` | Fails if the database includes schema elements not present in the contract. | +| `--json` | Prints machine-readable output. | + +## Examples + +```bash +prisma-next db verify --db "$DATABASE_URL" +prisma-next db verify --db "$DATABASE_URL" --strict +prisma-next db verify --db "$DATABASE_URL" --schema-only +prisma-next db verify --db "$DATABASE_URL" --marker-only +``` + +Use JSON output in automation: + +```bash +prisma-next db verify --db "$DATABASE_URL" --json +``` + +## What failures mean + +| Failure | Meaning | +| --- | --- | +| Marker mismatch | The database was not signed for the emitted contract, or the contract changed after signing. | +| Schema mismatch | The live database does not satisfy the emitted contract. | +| Strict mismatch | The database has extra schema elements not present in the contract. | +| Extension mismatch | The contract requires an extension that is not wired in the config. | + +Fix the database or contract, emit again if needed, then verify again. diff --git a/apps/docs/content/docs/cli/next/index.mdx b/apps/docs/content/docs/cli/next/index.mdx new file mode 100644 index 0000000000..7a7ddeeeb4 --- /dev/null +++ b/apps/docs/content/docs/cli/next/index.mdx @@ -0,0 +1,99 @@ +--- +title: Prisma Next CLI +description: Reference for the Prisma Next command line interface. +url: /cli/next +metaTitle: Prisma Next CLI reference +metaDescription: Learn the Prisma Next CLI commands for contracts, databases, and migrations. +badge: early-access +--- + +The Prisma Next CLI is exposed as `prisma-next`. It reads your `prisma-next.config.ts`, emits contract artifacts, verifies databases, and manages Prisma Next migrations. + +:::note[Prisma Next is in Early Access] + +Prisma Next is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and [share feedback](https://pris.ly/discord) while it’s still actively shaping up. + +If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started). + +::: + +Install the CLI package in a Prisma Next project: + +```bash +npm install -D prisma-next +``` + +Then run commands with your package manager: + +```bash +npx prisma-next help +npx prisma-next contract emit +``` + +For a full app scaffold, use a [Prisma Next quickstart](/next/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. + +## Common workflows + +Start an existing project: + +```bash +prisma-next init --target postgres --authoring psl +prisma-next contract emit +prisma-next db init --db "$DATABASE_URL" +``` + +Adopt an existing database: + +```bash +prisma-next contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma +prisma-next contract emit +prisma-next db sign --db "$DATABASE_URL" +prisma-next db verify --db "$DATABASE_URL" +``` + +Use checked-in migrations: + +```bash +prisma-next contract emit +prisma-next migration plan --name add-users +prisma-next migration status --db "$DATABASE_URL" +prisma-next migration apply --db "$DATABASE_URL" +prisma-next db verify --db "$DATABASE_URL" +``` + +## Command groups + +| Command | Purpose | +| --- | --- | +| [`prisma-next init`](/cli/next/init) | Add Prisma Next files to a project. | +| [`prisma-next contract emit`](/cli/next/contract-emit) | Emit `contract.json` and `contract.d.ts` from your contract source. | +| [`prisma-next contract infer`](/cli/next/contract-infer) | Infer a starter PSL contract from an existing database. | +| [`prisma-next db init`](/cli/next/db-init) | Create missing database structures from the current contract and sign the database. | +| [`prisma-next db update`](/cli/next/db-update) | Reconcile an existing database with the current contract. | +| [`prisma-next db schema`](/cli/next/db-schema) | Inspect the live database schema. | +| [`prisma-next db sign`](/cli/next/db-sign) | Record that a database matches the current contract. | +| [`prisma-next db verify`](/cli/next/db-verify) | Check that a database still matches the current contract. | +| [`prisma-next migration plan`](/cli/next/migration-plan) | Create an on-disk migration package from contract changes. | +| [`prisma-next migration new`](/cli/next/migration-new) | Scaffold a migration package for manual authoring. | +| [`prisma-next migration apply`](/cli/next/migration-apply) | Apply pending on-disk migrations. | +| [`prisma-next migration status`](/cli/next/migration-status) | Show migration history and applied state. | +| [`prisma-next migration show`](/cli/next/migration-show) | Inspect a migration package. | +| [`prisma-next migration ref`](/cli/next/migration-ref) | Manage named migration refs. | + +## Global flags + +Most Prisma Next commands accept these flags. + +| Flag | What it does | +| --- | --- | +| `--json` | Print machine-readable output. Use this in CI and scripts. | +| `-q`, `--quiet` | Suppress nonessential output. | +| `-v`, `--verbose` | Print more detail. | +| `--trace` | Include stack traces for failures. | +| `--color` | Force colored output. | +| `--no-color` | Disable colored output. | +| `--interactive` | Allow prompts. | +| `--no-interactive` | Disable prompts. | +| `-y`, `--yes` | Accept prompts where the command supports confirmation. | + +Use `prisma-next --help` when you need the exact command help from the installed preview version. diff --git a/apps/docs/content/docs/cli/next/init.mdx b/apps/docs/content/docs/cli/next/init.mdx new file mode 100644 index 0000000000..66db8e2de1 --- /dev/null +++ b/apps/docs/content/docs/cli/next/init.mdx @@ -0,0 +1,69 @@ +--- +title: prisma-next init +description: Initialize Prisma Next files in a project. +url: /cli/next/init +metaTitle: prisma-next init +metaDescription: Learn how to initialize Prisma Next files in an existing project. +--- + +`prisma-next init` scaffolds the Prisma Next config, contract source, and runtime files inside an existing project. + +Use a [Prisma Next quickstart](/next/quickstart/postgresql) when you want a complete new application template. Use `prisma-next init` when you already have a project and want to add the lower-level Prisma Next files. + +## Usage + +```bash +prisma-next init +``` + +Run it non-interactively: + +```bash +prisma-next init --yes --target postgres --authoring psl +``` + +## Options + +| Option | What it does | +| --- | --- | +| `--target ` | Sets the database target. Use `postgres` or `mongodb`. | +| `--authoring