diff --git a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx index f3dfa4c195..80575bbc36 100644 --- a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx @@ -79,7 +79,7 @@ In a long-running server, don't call `db.close()` in route handlers; the client' ## Prompt your coding agent -The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: +The scaffold installs [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Prompts that map to this guide: - "Using the prisma-next-queries skill, add GET /users/:id that returns one user or a 404." - "Add a POST /users route that creates a user from the request body." diff --git a/apps/docs/content/docs/guides/next/frameworks/hono.mdx b/apps/docs/content/docs/guides/next/frameworks/hono.mdx index e7623d4268..b0bd21d446 100644 --- a/apps/docs/content/docs/guides/next/frameworks/hono.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/hono.mdx @@ -109,7 +109,7 @@ In a long-running server, don't call `db.close()` in route handlers; the client' ## Prompt your coding agent -The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: +The scaffold installs [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Prompts that map to this guide: - "Using the prisma-next-queries skill, add GET /users/:id that returns one user or a 404." - "Add a Post model related to User, update the database, and expose GET /users/:id/posts." diff --git a/apps/docs/content/docs/guides/next/runtimes/bun.mdx b/apps/docs/content/docs/guides/next/runtimes/bun.mdx index a5a7fe90e2..630ead7a80 100644 --- a/apps/docs/content/docs/guides/next/runtimes/bun.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/bun.mdx @@ -85,7 +85,7 @@ That is the whole loop: schema to contract, contract to database, typed queries ## Prompt your coding agent -The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: +The scaffold installs [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Prompts that map to this guide: - "Using the prisma-next-queries skill, add a script that lists the 10 newest users." - "Add a Post model related to User, emit the contract, and update the database." diff --git a/apps/docs/content/docs/guides/next/runtimes/deno.mdx b/apps/docs/content/docs/guides/next/runtimes/deno.mdx index be0aa9e9c2..5d9f8287fe 100644 --- a/apps/docs/content/docs/guides/next/runtimes/deno.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/deno.mdx @@ -86,7 +86,7 @@ Deno reports `Unsupported compiler options in tsconfig.json` for a few options t ## Prompt your coding agent -The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: +The scaffold installs [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Prompts that map to this guide: - "Using the prisma-next-queries skill, add a Deno task that prints every user created in the last day." - "Tighten the Deno permissions for this project from -A to an explicit allow list." diff --git a/apps/docs/content/docs/orm/next/contract-authoring/capabilities.mdx b/apps/docs/content/docs/orm/next/contract-authoring/capabilities.mdx index 9c249b4b24..b61593e32c 100644 --- a/apps/docs/content/docs/orm/next/contract-authoring/capabilities.mdx +++ b/apps/docs/content/docs/orm/next/contract-authoring/capabilities.mdx @@ -4,6 +4,7 @@ description: Capabilities record what your database stack supports, so Prisma Ne url: /orm/next/contract-authoring/capabilities metaTitle: Capabilities in Prisma Next metaDescription: How Prisma Next capabilities are derived from the target, adapter, and extension packs, what they gate, and what happens when a required capability is missing. +badge: early-access --- Not every database stack supports every feature. One setup can run lateral joins, `RETURNING` clauses, and vector distance operations; another cannot. @@ -86,7 +87,7 @@ Extensions are the main source of capabilities beyond the core; [Using extension ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: - "Which capabilities does our contract currently require, and which package provides each?" - "Add pgvector to the project and confirm the capability shows up in the emitted contract." diff --git a/apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx b/apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx index 97649f504a..c39ee88ab2 100644 --- a/apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx +++ b/apps/docs/content/docs/orm/next/contract-authoring/psl-syntax.mdx @@ -4,6 +4,7 @@ description: Write the Prisma Next contract as a Prisma schema file, using the s url: /orm/next/contract-authoring/psl-syntax metaTitle: Author the Prisma Next contract in PSL metaDescription: Learn how to write a Prisma Next contract in the Prisma schema language, including named types, enums, value objects, relations, and extension types. +badge: early-access --- PSL is the preferred way to author the Prisma Next [data contract](/orm/next/contract-authoring/the-data-contract). You write a Prisma schema file, usually `prisma/contract.prisma`, and [`prisma-next contract emit`](/cli/next/contract-emit) turns it into `contract.json` and `contract.d.ts`. @@ -309,7 +310,7 @@ The syntax above declares relations; for which shape to choose and which side ow ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: - "Using the prisma-next-contract skill, add a Status enum stored as text and use it on the Order model." - "Add a one-to-many between User and Post with the foreign key on Post." @@ -318,5 +319,5 @@ Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/ ## Next steps - Emit and inspect [the artifacts](/orm/next/contract-authoring/the-contract-artifact) the schema produces. -- Prefer defining models in code? See [authoring in TypeScript](/orm/next/contract-authoring/typescript-schema-builder). +- If you prefer defining models in code, see [authoring in TypeScript](/orm/next/contract-authoring/typescript-schema-builder). - Apply the contract to a database with [`prisma-next db init`](/cli/next/db-init) or plan changes with [`prisma-next migration plan`](/cli/next/migration-plan). diff --git a/apps/docs/content/docs/orm/next/contract-authoring/the-contract-artifact.mdx b/apps/docs/content/docs/orm/next/contract-authoring/the-contract-artifact.mdx index e5ff97ee21..c279907f9d 100644 --- a/apps/docs/content/docs/orm/next/contract-authoring/the-contract-artifact.mdx +++ b/apps/docs/content/docs/orm/next/contract-authoring/the-contract-artifact.mdx @@ -4,6 +4,7 @@ description: contract.json and contract.d.ts are the deterministic artifacts eve url: /orm/next/contract-authoring/the-contract-artifact metaTitle: The Prisma Next contract artifacts metaDescription: What contract.json and contract.d.ts contain, how deterministic emission and content hashes work, and how the runtime and tooling consume the artifacts. +badge: early-access --- Emitting your contract produces two generated files. This page explains what is in each, why they are deterministic, and how their hashes keep your code and your database in agreement. @@ -104,7 +105,7 @@ An abridged emit of a `User`/`Post` schema: The sections, top to bottom: - **`schemaVersion`, `targetFamily`, `target`**: the contract format version and the database this contract targets. -- **`roots`**: the accessor names your queries start from, each mapping to a model. `db.user` exists because `roots.user` points at `User`. +- **`roots`**: the accessor names your queries start from, each mapping to a model. The SQL builder's `db.sql.public.user` exists because `roots.user` points at `User`, and the model it names is what the ORM accessor `db.orm.public.User` hangs off. - **`domain`**: the application's view. Each field carries `nullable` and a `codecId` such as `pg/text@1`, which names the codec that encodes and decodes values of that type. Relations record cardinality and the fields they join on. The model's `storage` block maps fields to columns. - **`storage`**: the database's view: tables with columns (native type plus codec), primary keys, uniques, indexes, foreign keys, and value sets backing enums. This is the section migration tooling diffs and `db verify` checks the live schema against. - **`execution`**: defaults Prisma Next applies before writes, such as UUID generation, kept out of the database's DDL. @@ -152,7 +153,7 @@ Commit the artifacts alongside the source. They contain structure only, no data ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: - "Explain the difference between contract.json and contract.d.ts in this project." - "Re-emit the contract and show me what changed in the artifact." diff --git a/apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx index 289c914fa7..0954edc34c 100644 --- a/apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx +++ b/apps/docs/content/docs/orm/next/contract-authoring/the-data-contract.mdx @@ -4,6 +4,7 @@ description: The data contract is the single description of your data model and url: /orm/next/contract-authoring/the-data-contract metaTitle: The Prisma Next data contract metaDescription: What the Prisma Next data contract is, how PSL and TypeScript authoring produce the same artifacts, and how the contract drives typing, migrations, and verification. +badge: early-access --- Every Prisma Next project has one description of its data: the models, their fields, and how they map to database tables. That description is the data contract. @@ -92,7 +93,7 @@ It contains no rows, no credentials, and no connection details, so committing th ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: - "Using the prisma-next-contract skill, explain what our contract.json currently declares." - "Add an Invoice model to the contract and emit it." diff --git a/apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx b/apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx index 12d0d89e1d..9ee6921e9b 100644 --- a/apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx +++ b/apps/docs/content/docs/orm/next/contract-authoring/typescript-schema-builder.mdx @@ -4,6 +4,7 @@ description: Define the Prisma Next contract with a typed builder API instead of url: /orm/next/contract-authoring/typescript-schema-builder metaTitle: Author the Prisma Next contract in TypeScript metaDescription: Learn how to define a Prisma Next contract in TypeScript with defineContract, including fields, relations, enums, storage mapping, and extension types. +badge: early-access --- TypeScript authoring defines the Prisma Next [data contract](/orm/next/contract-authoring/the-data-contract) in code. Instead of a `.prisma` file, you write `prisma/contract.ts` with the `defineContract` builder, and [`prisma-next contract emit`](/cli/next/contract-emit) produces exactly the same `contract.json` and `contract.d.ts` a PSL schema would. @@ -207,7 +208,7 @@ Post.relations({ }); ``` -`rel.hasMany(Model, { by })` names the foreign key field on the other model; `rel.belongsTo(Model, { from, to })` maps the local foreign key field to the referenced field. `rel.hasOne` and `rel.manyToMany` cover the remaining shapes. Because the arguments are model objects, not strings, a typo in a relation target is a compile error. +`rel.hasMany(Model, { by })` names the foreign key field on the other model; `rel.belongsTo(Model, { from, to })` maps the local foreign key field to the referenced field. `rel.hasOne` and `rel.manyToMany` cover the remaining shapes. A typo in a relation target is a compile error either way: the PostgreSQL builder takes model objects, and the MongoDB builder takes model names that are type-checked against the declared models. ## Storage mapping @@ -265,7 +266,7 @@ TypeScript and [PSL](/orm/next/contract-authoring/psl-syntax) authoring emit the ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to: - "Convert this contract.prisma to the TypeScript schema builder." - "Using the prisma-next-contract skill, add a unique index to the email field in our TypeScript schema." diff --git a/apps/docs/content/docs/orm/next/data-modeling/index.mdx b/apps/docs/content/docs/orm/next/data-modeling/index.mdx index a22b229bb1..ca24a9f5d6 100644 --- a/apps/docs/content/docs/orm/next/data-modeling/index.mdx +++ b/apps/docs/content/docs/orm/next/data-modeling/index.mdx @@ -15,7 +15,7 @@ In Prisma Next, you define this structure in a `contract.prisma` file. This file If you are coming from Prisma 7, `contract.prisma` plays a similar role to the `schema.prisma` file you used before. -This page introduces the four building blocks of every Prisma Next schema: +This page introduces the four building blocks of every Prisma Next contract: - [Models](#models): the things your application works with - [Primary keys](#primary-keys): how each record is identified @@ -234,11 +234,11 @@ How each shape is stored, and which model should hold the connecting field, is w ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-contract` skill covers schema authoring. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers contract authoring. Prompts that map to each section: - "Using the prisma-next-contract skill, add a Product model with a surrogate id and a unique sku field." - "Add a Country reference table keyed by its ISO code." -- "Review my schema for fields that should be an enum or a DateTime instead of a String." +- "Review my contract for fields that should be an enum or a DateTime instead of a String." - "Connect Post to User with a foreign key and a relation field." ## Next steps diff --git a/apps/docs/content/docs/orm/next/data-modeling/mongodb.mdx b/apps/docs/content/docs/orm/next/data-modeling/mongodb.mdx index 4217dce559..a01a2031cf 100644 --- a/apps/docs/content/docs/orm/next/data-modeling/mongodb.mdx +++ b/apps/docs/content/docs/orm/next/data-modeling/mongodb.mdx @@ -9,7 +9,7 @@ badge: early-access MongoDB stores data as documents grouped into collections. A document can nest objects and arrays directly, which gives you a real choice for related data: keep it inside the document (embed it) or store it in its own collection and link to it (reference it). -Making that choice well is the core of MongoDB data modeling, and it is what this page focuses on. New to models and keys? Start with the [data modeling overview](/orm/next/data-modeling). +Making that choice well is the core of MongoDB data modeling, and it is what this page focuses on. If you are new to models and keys, start with the [data modeling overview](/orm/next/data-modeling). ## Documents, collections, and the _id key @@ -154,7 +154,7 @@ Use one polymorphic collection when the variants are handled together far more t ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-contract` skill covers document modeling. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers document modeling. Prompts that map to each section: - "Using the prisma-next-contract skill, add an embedded Address type to the User model." - "Cart items are always read with the cart. Model them as an embedded list." diff --git a/apps/docs/content/docs/orm/next/data-modeling/relational-databases.mdx b/apps/docs/content/docs/orm/next/data-modeling/relational-databases.mdx index 850deb9945..c126ad29cd 100644 --- a/apps/docs/content/docs/orm/next/data-modeling/relational-databases.mdx +++ b/apps/docs/content/docs/orm/next/data-modeling/relational-databases.mdx @@ -9,7 +9,7 @@ badge: early-access In a relational database, each model becomes a table and each scalar field becomes a column. Models connect through foreign keys: a column in one table that holds the primary key of a row in another table. -This page shows how to model each relation shape and, for each one, where the foreign key belongs. New to models and keys? Start with the [data modeling overview](/orm/next/data-modeling). +This page shows how to model each relation shape and, for each one, where the foreign key belongs. If you are new to models and keys, start with the [data modeling overview](/orm/next/data-modeling). ## How relations are declared @@ -201,7 +201,7 @@ Use polymorphism when you query the variants together (one feed of tasks, one st ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-contract` skill covers relation modeling. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers relation modeling. Prompts that map to each section: - "Using the prisma-next-contract skill, add a one-to-many between User and Post with the foreign key on Post." - "Make the Profile relation one-to-one by adding a unique constraint to its foreign key." diff --git a/apps/docs/content/docs/orm/next/extensions/using-extensions.mdx b/apps/docs/content/docs/orm/next/extensions/using-extensions.mdx index d52b2043e8..b408ae8734 100644 --- a/apps/docs/content/docs/orm/next/extensions/using-extensions.mdx +++ b/apps/docs/content/docs/orm/next/extensions/using-extensions.mdx @@ -101,7 +101,7 @@ The point of this bookkeeping is failing early: ## Available extensions -Want an extension that does not exist yet? Build it: the catalog is first-party today and built for community authors, extension packs are versioned npm packages with a documented layout, and the [call for extension authors](https://www.prisma.io/blog/prisma-next-call-for-extension-authors) explains how to write and publish one. +You can build an extension that does not exist yet. The catalog is first-party today and built for community authors, extension packs are versioned npm packages with a documented layout, and the [call for extension authors](https://www.prisma.io/blog/prisma-next-call-for-extension-authors) explains how to write and publish one. | Extension | Adds | Package | | --- | --- | --- | diff --git a/apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx b/apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx index 7cf93f6323..e3fead9eef 100644 --- a/apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx +++ b/apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx @@ -4,6 +4,7 @@ description: Use the SQL query builder on PostgreSQL and the pipeline builder on url: /orm/next/fundamentals/advanced-queries metaTitle: Advanced queries in Prisma Next metaDescription: Use the Prisma Next SQL query builder for explicit joins, grouped aggregates, and RETURNING, and the typed aggregation pipeline builder on MongoDB. +badge: early-access --- When the ORM API can't express a query, drop one level: the SQL query builder on PostgreSQL, or the pipeline builder on MongoDB. Both stay typed against your contract; neither means writing raw strings. @@ -25,7 +26,7 @@ The SQL query builder composes a single SQL statement as a typed *plan*: a descr ### Build and run a plan -Start from a table with `db.sql.public.` (tables use lowercase storage names), chain clauses, and call `.build()`. Execute the plan with the runtime: +Start from a table with `db.sql.public.
` (tables use the contract's mapped table names (snake_case storage names)), chain clauses, and call `.build()`. Execute the plan with the runtime: ```typescript import { db } from "./prisma/db"; @@ -65,7 +66,7 @@ const postsWithAuthors = await db.runtime().execute(plan); Chain more joins for multi-hop traversals. This is how you get a flat post-tag list through a [many-to-many junction table](/orm/next/fundamentals/relations-and-joins#many-to-many), one row per pair: ```typescript -const plan = db.sql.public.postTag +const plan = db.sql.public.post_tag .as("pt") .innerJoin(db.sql.public.tag.as("t"), (f, fns) => fns.eq(f.pt.tagId, f.t.id)) .innerJoin(db.sql.public.post.as("p"), (f, fns) => fns.eq(f.pt.postId, f.p.id)) @@ -231,7 +232,7 @@ Plans execute through `db.runtime().execute(plan)` on PostgreSQL and `(await db. ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-queries` skill covers both builders and the choice between them and the ORM API. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-queries` skill covers both builders and the choice between them and the ORM API. Prompts that map to each section: - "Using the prisma-next-queries skill, write a SQL builder plan for the top 10 authors by post count." - "This report needs post and author columns in one flat result. Build the join with the SQL query builder." diff --git a/apps/docs/content/docs/orm/next/fundamentals/reading-data.mdx b/apps/docs/content/docs/orm/next/fundamentals/reading-data.mdx index 03acab6a99..f967de3fb6 100644 --- a/apps/docs/content/docs/orm/next/fundamentals/reading-data.mdx +++ b/apps/docs/content/docs/orm/next/fundamentals/reading-data.mdx @@ -4,6 +4,7 @@ description: Fetch one record or many with Prisma Next, then filter, select, sor url: /orm/next/fundamentals/reading-data metaTitle: Reading data with Prisma Next metaDescription: Query PostgreSQL and MongoDB with Prisma Next. Filter with where, project with select, sort with orderBy, paginate with take and skip, and stream large results. +badge: early-access --- This page shows how to read data with Prisma Next: fetching [many records or one](#fetch-many-records-or-one), [filtering](#filter-records), [selecting fields](#select-fields), [sorting and paginating](#sort-and-paginate), [counting](#count-records), and [streaming large results](#stream-large-results). @@ -176,7 +177,7 @@ const highlighted = await db.orm.public.Post ### Filter operators on MongoDB -On MongoDB, `.where(...)` accepts the object form only. Comparison operators and boolean logic are not available on it yet. The same filters are available one level down, in the [pipeline builder](/orm/next/fundamentals/advanced-queries#mongodb-pipeline-builder), where `.match(...)` gives you the full operator set: +On MongoDB, `.where(...)` does not take a lambda. It accepts the object form, plus lower-level `MongoFieldFilter` expressions from `@prisma-next/mongo-query-ast/execution` that cover comparisons and boolean logic; see [Filter conditions and operators](/orm/next/reference/orm-client#filter-conditions-and-operators) in the reference. For a lambda-style operator set, go one level down to the [pipeline builder](/orm/next/fundamentals/advanced-queries#mongodb-pipeline-builder), where `.match(...)` covers the same filters: ```typescript // Object form: equality filters @@ -327,6 +328,8 @@ Error: AsyncIterableResult iterator has already been consumed via for-await loop Each AsyncIterableResult can only be iterated once. ``` +The error carries the code `RUNTIME.ITERATOR_CONSUMED`. + If you need the data more than once, `await` the query into an array and reuse the array: ```typescript @@ -370,7 +373,7 @@ const posts = await db.orm.public.Post.all(); ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-queries` skill covers everything on this page. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-queries` skill covers everything on this page. Prompts that map to each section: - "Using the prisma-next-queries skill, write a query that returns the 20 newest published posts." - "Add a case-insensitive title search to the posts query, using the field-proxy operators." diff --git a/apps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdx b/apps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdx index 7bda40b5f8..f63aae2d2b 100644 --- a/apps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdx +++ b/apps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdx @@ -4,6 +4,7 @@ description: Read related records in one query with .include(), and understand h url: /orm/next/fundamentals/relations-and-joins metaTitle: Relations and joins in Prisma Next metaDescription: Query one-to-one, one-to-many, and many-to-many relationships with Prisma Next on PostgreSQL and MongoDB, with diagrams and tested examples. +badge: early-access --- Read related records in the same query by adding `.include(...)`. The related records come back nested on the parent, typed to match. @@ -219,7 +220,7 @@ The relationship shapes above apply to reference-style relations on both databas ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-queries` skill covers relation queries, and `prisma-next-contract` covers the relation fields in your schema. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-queries` skill covers relation queries, and `prisma-next-contract` covers the relation fields in your schema. Prompts that map to each section: - "Using the prisma-next-contract skill, add a one-to-one Profile model with a unique foreign key to User." - "Using the prisma-next-queries skill, fetch each user with their five newest posts in one query." diff --git a/apps/docs/content/docs/orm/next/fundamentals/transactions.mdx b/apps/docs/content/docs/orm/next/fundamentals/transactions.mdx index d288cc01f4..58d21035f1 100644 --- a/apps/docs/content/docs/orm/next/fundamentals/transactions.mdx +++ b/apps/docs/content/docs/orm/next/fundamentals/transactions.mdx @@ -4,6 +4,7 @@ description: Run several writes so they all succeed or all fail together with db url: /orm/next/fundamentals/transactions metaTitle: Transactions in Prisma Next metaDescription: Group writes atomically with db.transaction() on PostgreSQL, and run multi-document MongoDB transactions with the MongoDB driver. +badge: early-access --- Run several writes as one unit with `db.transaction(...)`: they all commit together, or they all roll back. @@ -171,7 +172,7 @@ You get the same atomicity, plus something the array form never had: one query's ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-queries` skill covers transactions. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-queries` skill covers transactions. Prompts that map to each section: - "Using the prisma-next-queries skill, wrap this signup flow (create user, create welcome post) in a db.transaction so both writes commit together." - "Check this transaction callback for queries that use db instead of tx." diff --git a/apps/docs/content/docs/orm/next/fundamentals/writing-data.mdx b/apps/docs/content/docs/orm/next/fundamentals/writing-data.mdx index 09081d9acf..4ea744bb64 100644 --- a/apps/docs/content/docs/orm/next/fundamentals/writing-data.mdx +++ b/apps/docs/content/docs/orm/next/fundamentals/writing-data.mdx @@ -4,6 +4,7 @@ description: Create, update, delete, and upsert records with Prisma Next, one at url: /orm/next/fundamentals/writing-data metaTitle: Writing data with Prisma Next metaDescription: Create, update, delete, and upsert records in PostgreSQL and MongoDB with Prisma Next, and use createAll, updateAll, and deleteAll for bulk writes. +badge: early-access --- This page shows how to write data with Prisma Next: [creating](#create-one-record), [updating](#update-one-record), [deleting](#delete-one-record), and [upserting](#upsert-a-record) single records, and [writing many records at once](#write-many-records) with the `All` and `Count` variants. @@ -148,14 +149,14 @@ const updatedUser = await db.orm.users If the filter can match more than one record, `.update(...)` still changes only one. To change every match, use [`updateAll` or `updateCount`](#write-many-records). -On MongoDB, you can also update with field operations such as `.set(...)`, `.inc(...)`, and `.push(...)` by passing a callback: - ```typescript await db.orm.posts .where({ title: "Draft thoughts" }) .update((p) => [p.content.set("Now filled in")]); ``` +Array operations such as `.push(...)` and `.pull(...)` are not verified yet; test them against your own schema before relying on them. See [Field update operations](/orm/next/reference/orm-client#field-update-operations) in the reference. + ## Delete one record Use `.where(...)` then `.delete()`. It deletes **one** matching record and returns it: @@ -310,7 +311,7 @@ Prisma 7 supported `$transaction([query1, query2])`. Prisma Next does not: there ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent; the `prisma-next-queries` skill covers everything on this page. Prompts that map to each section: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-queries` skill covers everything on this page. Prompts that map to each section: - "Using the prisma-next-queries skill, add a signup function that creates a User and returns only its id and email." - "Write an upsert that creates a user by email or updates their name if they exist." diff --git a/apps/docs/content/docs/orm/next/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/next/middleware/authoring-custom-middleware.mdx index 1242da2c0b..9f749c594d 100644 --- a/apps/docs/content/docs/orm/next/middleware/authoring-custom-middleware.mdx +++ b/apps/docs/content/docs/orm/next/middleware/authoring-custom-middleware.mdx @@ -219,7 +219,7 @@ One honest note on `ctx.log`: the `postgres(...)` client does not expose a way t ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent. Prompts that map to this guide: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Prompts that map to this guide: - "Write a Prisma Next middleware that logs every query slower than 250ms, and register it before budgets." - "Add a beforeCompile middleware that scopes every SELECT on the user table to the current tenant." diff --git a/apps/docs/content/docs/orm/next/middleware/how-middleware-works.mdx b/apps/docs/content/docs/orm/next/middleware/how-middleware-works.mdx index 6f1e5e9831..52a3d4decf 100644 --- a/apps/docs/content/docs/orm/next/middleware/how-middleware-works.mdx +++ b/apps/docs/content/docs/orm/next/middleware/how-middleware-works.mdx @@ -107,7 +107,7 @@ When the driver itself fails, `afterExecute` still runs on every middleware with ## Prompt your coding agent -Projects scaffolded with `create-prisma` install Prisma Next skills for your coding agent. Prompts that map to this page: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Prompts that map to this page: - "Register the lints and budgets middleware on our Prisma Next client with a 10k row budget." - "Add the cache middleware and opt the dashboard queries in with a 60 second TTL." diff --git a/apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx index f3ebb37e22..283287afa5 100644 --- a/apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx +++ b/apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx @@ -64,7 +64,7 @@ npx prisma-next migrate --db $DATABASE_URL 1 pending — run `prisma-next migrate --to 925198f3cc27` ``` -Read the markers on the right: `@db` is where the database is, `@contract` is where your emitted contract is, and `(db)` is the [ref](/orm/next/migrations/the-migration-graph#refs-naming-places-in-the-graph) of that name pointing at the same node. +Read the markers on the right: `@db` is where the database is, `@contract` is where your emitted contract is, and `(db)` is the [ref](/orm/next/migrations/the-migration-graph#name-important-states-with-refs) of that name pointing at the same node. `migrate --show` is the read-only dry run: it draws the path from the database's position to the target and stops. Nothing touches the database: @@ -169,7 +169,7 @@ Apply, targeting, preview, refs, the ledger, and multi-space runs all work today ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: - "Check migration status against staging and apply whatever is pending." - "Preview what `migrate --to prod` would run and summarize the destructive operations." diff --git a/apps/docs/content/docs/orm/next/migrations/editing-a-migration.mdx b/apps/docs/content/docs/orm/next/migrations/editing-a-migration.mdx index 45475fbcce..0cff138fc1 100644 --- a/apps/docs/content/docs/orm/next/migrations/editing-a-migration.mdx +++ b/apps/docs/content/docs/orm/next/migrations/editing-a-migration.mdx @@ -223,7 +223,7 @@ The typed-builder wiring and the raw Mongo command shapes above are the current ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: - "Fill in the placeholder in the latest migration: backfill `displayName` with the user's email prefix." - "Add a data transform to this migration that normalizes existing `phone` values before the unique constraint." diff --git a/apps/docs/content/docs/orm/next/migrations/generating-a-migration.mdx b/apps/docs/content/docs/orm/next/migrations/generating-a-migration.mdx index 4bc0bd51cc..9eab66506b 100644 --- a/apps/docs/content/docs/orm/next/migrations/generating-a-migration.mdx +++ b/apps/docs/content/docs/orm/next/migrations/generating-a-migration.mdx @@ -153,7 +153,7 @@ ALTER TABLE "public"."user" ADD COLUMN "phone" text; ### The db ref: skipping --from -Passing `--from` every time gets old. The planner's default is smarter: if a [ref](/orm/next/migrations/the-migration-graph#refs-naming-places-in-the-graph) named **`db`** exists, planning starts from whatever it points at. Keep it advanced as part of applying: +Passing `--from` every time gets old. The planner's default is smarter: if a [ref](/orm/next/migrations/the-migration-graph#name-important-states-with-refs) named **`db`** exists, planning starts from whatever it points at. Keep it advanced as part of applying: ```bash npx prisma-next migrate --advance-ref db @@ -190,7 +190,7 @@ npx prisma-next migration show 20260707T1006_add_user_phone # The whole graph, with your new edge in place npx prisma-next migration graph -# Integrity check: hashes match, files complete, graph well-formed — exits non-zero on failure +# Integrity check: hashes match, files complete, graph well-formed; exits non-zero on failure npx prisma-next migration check ``` @@ -204,7 +204,7 @@ Planning covers tables, columns, indexes, constraints, and the backfill scaffold ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: - "Add a required `displayName` field to User, emit the contract, and plan the migration." - "Plan a migration named `add-orders-table` and show me its DDL preview before I commit it." diff --git a/apps/docs/content/docs/orm/next/migrations/how-migrations-work.mdx b/apps/docs/content/docs/orm/next/migrations/how-migrations-work.mdx index f831f7390f..92b5d77eed 100644 --- a/apps/docs/content/docs/orm/next/migrations/how-migrations-work.mdx +++ b/apps/docs/content/docs/orm/next/migrations/how-migrations-work.mdx @@ -13,7 +13,7 @@ The workflow is a loop you will run many times a day in development: -1. **Change your contract**: edit your `.prisma` file, then run `prisma-next contract emit`, which compiles the schema into the `contract.json` that every other command reads. +1. **Change your contract**: edit your `.prisma` file, then run `prisma-next contract emit`, which compiles the contract into the `contract.json` artifact that every other command reads. 2. **Plan a migration**: `prisma-next migration plan` compares the new contract against your migration history and writes a migration directory under `migrations/`. 3. **Review it**: read the generated TypeScript and the DDL preview. Edit the migration if the change needs a data step, then re-run the file to recompile it. 4. **Apply it**: `prisma-next migrate` runs the pending migrations against your database. @@ -139,7 +139,17 @@ migration.json Prisma tracks the migration in history ## Every operation checks itself -Inside `ops.json`, each operation has three parts: a **precheck** that confirms the database is in the expected state, the **execute** statements that make the change, and a **postcheck** that confirms the change worked. Each operation also carries a class: **additive** (safe, like adding a column), **destructive** (can lose data, like dropping one), or **data** (changes rows, not structure). The class is what drives the `(destructive)` flags and data-loss warnings you'll see in CLI output. +Inside `ops.json`, each operation runs in three parts, in order: + +1. **Precheck**: confirms the database is in the expected state before the change runs. +2. **Execute**: the statements that make the change. +3. **Postcheck**: confirms the change worked after it runs. + +Each operation also carries a class, which drives the `(destructive)` flags and data-loss warnings you see in CLI output: + +- **Additive**: safe to apply, like adding a column. +- **Destructive**: can lose data, like dropping a column. +- **Data**: changes rows, not structure. ```json title="One operation from ops.json" { @@ -222,7 +232,7 @@ Prisma Next is in Early Access and migrations are one of its newest parts. The c ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: - "Add a `phone` field to the User model and plan a migration for it." - "Show me the pending migrations and what SQL they will run." diff --git a/apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx b/apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx index 43d016f72f..faebfa2432 100644 --- a/apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx +++ b/apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx @@ -110,7 +110,7 @@ Reverse planning (`--to ^`), destructive-operation warnings, resumable re-r ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: - "Plan a rollback for the last migration and show me its destructive operations before I decide." - "This migrate run failed. Read the error, fix the migration, and re-run it." diff --git a/apps/docs/content/docs/orm/next/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/next/migrations/the-migration-graph.mdx index bbce8154b8..859a1822c8 100644 --- a/apps/docs/content/docs/orm/next/migrations/the-migration-graph.mdx +++ b/apps/docs/content/docs/orm/next/migrations/the-migration-graph.mdx @@ -1,27 +1,62 @@ --- title: The migration graph -description: Migrations form a graph of contract states, not a numbered list. That's what makes history, branching, and parallel work safe. +description: You changed your schema, a teammate changed theirs, both merged. The migration graph is what lets every database catch up without renaming files or rebuilding history. url: /orm/next/migrations/the-migration-graph metaTitle: The migration graph in Prisma Next -metaDescription: How Prisma Next models migrations as a graph, with contract states as nodes and migrations as edges, and how that enables branching, merging, rollback, and parallel work. +metaDescription: How Prisma Next models migrations as a graph of contract states, why that makes branching and parallel work safe, and the commands to inspect it. badge: early-access --- -Classic migration tools keep migrations in a straight line: a folder of files executed in timestamp order, exactly once. That model breaks in the situations modern teams hit constantly: two branches each add a migration, timestamps interleave, CI fails, and someone spends an afternoon renaming files. +You add a `phone` column on your branch. A teammate adds an `avatarUrl` column on theirs. Both branches merge the same afternoon. Now your laptop, your teammate's laptop, staging, and production are each sitting on a slightly different version of the schema, and something has to bring every one of them up to the merged state without losing work or running the same change twice. -Prisma Next drops the line. Migrations form a **graph**, and the graph is the one idea that everything else in this section builds on. +Classic migration tools make this hard. They keep migrations in a single folder, run in timestamp order, exactly once. When two branches each add a migration, the timestamps interleave, the "run once in order" assumption breaks, and someone spends an afternoon renaming files to force a clean line. The migration graph is how Prisma Next avoids that. -## Nodes are contract states, edges are migrations +## When this matters -Every time you emit your contract, the result is a deterministic JSON artifact. Hashing it produces an identifier for that exact schema shape, `sha256:705b1a6...`, the way a git commit hash identifies an exact state of your files. +You can build a whole app without thinking about the graph. It earns its place the moment more than one line of history exists: -Those hashes are the **nodes** of the graph. A migration is an **edge**: it records the contract hash it starts `from` and the hash it moves the database `to`. Nothing about a migration's position in history comes from its file name: the timestamps in directory names are for humans, and the linkage lives entirely in the `from`/`to` hashes inside each `migration.json`. +- Two people (or two AI agents) change the schema on separate branches and merge. +- You need to roll a database back to an earlier schema and then forward again. +- A database is behind (a fresh clone, a long-lived staging box) and has to catch up through several changes. +- You want to point an environment at an exact schema state and prove in review that it is there. + +If none of these apply yet, read [How migrations work](/orm/next/migrations/how-migrations-work) instead and come back when they do. + +## The short version + +Prisma Next does not treat migrations as one timestamp-ordered list. Each migration records the schema state it starts from and the schema state it produces, and those links form a graph. A database moves through the graph by following migrations from wherever it currently sits to wherever you tell it to go. Because every migration is anchored to real schema states rather than to its position in a folder, branches, merges, and rollbacks are all just paths through the same graph. + +:::tip[You probably just want three commands] + +Most days you never touch the graph directly. To see it, run `prisma-next migration graph`. To check where a database is and what is pending, run `prisma-next migration status`. To move a database to a specific state, run `prisma-next migrate --to `. The rest of this page explains what those commands are showing you. + +::: + +## Terms used on this page + +| Term | Meaning | +| --- | --- | +| **Contract** | The schema you author, and the `contract.json` artifact it compiles to. | +| **Contract state** | One exact shape of the schema at a point in history. | +| **Hash** | A short fingerprint of a contract state, like `sha256:705b1a6…`, the way a Git commit hash names an exact state of your files. | +| **Node** | A contract state in the graph, identified by its hash. | +| **Edge** | A migration. It moves the database from one node (`from`) to another (`to`). | +| **Marker** | A record Prisma Next keeps inside the database naming the one node it currently matches. | +| **Ref** | A human-readable name for a node, like `prod`, stored as a file in your repo. | + +## How it works + +Every time you emit your contract, you get a deterministic JSON artifact. Hashing it produces an identifier for that exact schema shape. Those hashes are the **nodes** of the graph. + +A migration is an **edge**. It records the contract hash it starts `from` and the hash it moves the database `to`. Nothing about a migration's place in history comes from its file name: the timestamps in directory names are for humans, and the real linkage lives in the `from`/`to` hashes inside each `migration.json`. -A database always sits at exactly one node: its **marker**, a record Prisma Next keeps in the database itself, holds the hash of the contract it currently matches. Applying a migration means walking one edge and moving the marker. When you run `prisma-next migrate`, the runner finds a path through the graph from the marker to your target and applies each edge along the way. +A database always sits at exactly one node. Its **marker**, a record Prisma Next keeps in the database itself, holds the hash of the contract it currently matches. Applying a migration means walking one edge and moving the marker. + +## A worked example -You can see the graph of any project without touching a database: +Here is the Alice-and-Bob situation as an actual graph. Alice adds `phone`, Bob adds `avatarUrl`, and both branches merge: ```bash npx prisma-next migration graph @@ -30,62 +65,54 @@ npx prisma-next migration graph ```text * f9a41d7 (prod) |-\ -|^| 20260303T1000_merge_alice 93be6c2 -> f9a41d7 1 ops -| |^ 20260303T1100_merge_bob 7e3fa7f -> f9a41d7 1 ops +|^| 20260303T1000_merge_alice 93be6c2 -> f9a41d7 1 ops +| |^ 20260303T1100_merge_bob 7e3fa7f -> f9a41d7 1 ops * | 93be6c2 -|^| 20260302T1000_alice_add_phone 789dd79 -> 93be6c2 1 ops +|^| 20260302T1000_alice_add_phone 705b1a6 -> 93be6c2 1 ops | * 7e3fa7f -| |^ 20260302T1100_bob_add_avatar 789dd79 -> 7e3fa7f 1 ops +| |^ 20260302T1100_bob_add_avatar_url 705b1a6 -> 7e3fa7f 1 ops |-/ -* 789dd79 -|^ 20260301T1000_init - -> 789dd79 1 ops +* 705b1a6 +|^ 20260301T1000_init - -> 705b1a6 1 ops * - 1 space(s), 5 contract(s), 5 migration(s) ``` -This project's history is a diamond. Read it bottom-up: from an empty database (`-`), `init` establishes state `789dd79`. Alice and Bob branch from it in parallel: she adds a phone column, he adds an avatar. Then each branch gets a merge migration into the combined state `f9a41d7`, which the `prod` ref points at. (The summary line counts contract *spaces*: independent migration lanes, one for your app plus one per [database extension](/orm/next/migrations/applying-a-migration#extension-spaces).) +Read it bottom-up. From an empty database (`-`), `init` establishes state `705b1a6`. Alice and Bob both branch from `705b1a6`: her migration produces `93be6c2`, his produces `7e3fa7f`. Each branch then has a merge migration into the combined state `f9a41d7`, which the `prod` ref points at. This shape is a diamond: one start, two parallel branches, one shared end. -## What the graph gives you - -**Parallel work without ordering conflicts.** Alice and Bob each planned a migration from `789dd79` on their own branches. In a timestamp-ordered system, whoever merges second gets a broken history. Here, both edges are in the graph. A database that followed Alice's branch sits at `93be6c2` and reaches the merged state through `merge_alice`; a database that followed Bob's sits at `7e3fa7f` and takes `merge_bob`. Every environment finds its own path. This matters double when the "two developers" are two AI agents planning migrations concurrently; neither has to know about the other. - -**History you can trust.** Because each edge declares its `from` state, a migration can never silently run against a database in the wrong shape. If the marker doesn't match, the run stops before any SQL executes, with an error naming the mismatch. +The payoff is in the last column and the two merge edges. A database that followed Alice's branch is sitting at `93be6c2` and reaches `f9a41d7` through `merge_alice`. A database that followed Bob's is at `7e3fa7f` and takes `merge_bob`. Neither developer had to know about the other's migration, and no files were renamed to make the timestamps line up. -**Rollback as a first-class move.** An edge can point "backwards", from a later contract state to an earlier one. Rolling back isn't a special mode; it's planning one more migration whose destination is a state you've already been in. See [Rollbacks and recovery](/orm/next/migrations/rollbacks-and-recovery). +(The summary line counts contract *spaces*: independent migration lanes, one for your app plus one per [database extension](/orm/next/migrations/applying-a-migration#extension-spaces).) -**More than one shape of history.** The graph accommodates whatever your team's workflow produces: long linear spines, wide fan-outs where many branches leave one node, diamonds that converge again, and even a fast-forward edge that jumps several states in one hop. +## What happens when you run migrate -## Refs: naming places in the graph - -Raw hashes are awkward to type, so the graph supports **refs**: named pointers to a node, stored as small files in `migrations/app/refs/`: - -```bash -npx prisma-next ref set prod sha256:f9a41d7... -npx prisma-next ref list -npx prisma-next migrate --to prod -``` +When you run `prisma-next migrate`, the runner walks the graph for you: -Refs are committed to your repo, so "where production should be" is a reviewable fact, not tribal knowledge. A ref named `db` has one extra job: `migration plan` uses it as the default starting point when you don't pass `--from`. Keep it advanced with `prisma-next migrate --advance-ref db` and planning stays incremental automatically. +1. It reads the database's **marker** to find which node the database is on now. +2. It resolves your target: the merged state, a ref like `prod`, or the latest state if you did not pass `--to`. +3. It finds a path of edges from the marker to the target. +4. It applies each edge in order, moving the marker after each one. +5. If any migration's precheck fails, it stops before running SQL and names the mismatch. -Alongside refs, two reserved tokens work anywhere a command accepts a contract reference: `@contract` (the contract you most recently emitted) and `@db` (whatever state the connected database's marker holds). +If two branch tips are both reachable and neither is clearly the target, the runner does not guess. It stops and asks you to pick one with `--to`. ## Inspecting the graph Four read-only commands, each answering a different question: -| Command | Question it answers | Needs a database? | -| ------------------ | ------------------------------------------------ | ----------------- | -| `migration graph` | What does the whole topology look like? | No | -| `migration list` | Which migration directories exist on disk? | No | -| `migration status` | Where is my database, and what's pending? | Yes | -| `migration log` | What has actually been applied, and when? | Yes | +| Question you have | Command | Needs a database? | +| --- | --- | --- | +| What does the whole topology look like? | `migration graph` | No | +| Which migration directories exist on disk? | `migration list` | No | +| Where is my database, and what is pending? | `migration status` | Yes | +| What has actually been applied, and when? | `migration log` | Yes | -`migration graph` also takes `--json` for machine-readable output and `--dot` to render with Graphviz. `migration log` reads a **ledger** the runner appends to on every apply, so even a rollback shows up as history, never as deleted history. +`migration graph` also takes `--json` for machine-readable output, `--dot` to render with Graphviz, and `--legend` to print a key for the glyphs. `migration log` reads a **ledger** the runner appends to on every apply, so even a rollback shows up as history rather than as deleted history. ### Try it on real fixtures -The Prisma Next repo ships a set of example graphs (a diamond, a wide fan-out, converging branches, rollback chains) as ready-to-render fixtures: +The Prisma Next repo ships example graphs (a diamond, a wide fan-out, converging branches, rollback chains) as ready-to-render fixtures: ```bash git clone https://github.com/prisma/prisma-next @@ -96,19 +123,76 @@ npx prisma-next migration graph --config fixtures/showcase/prisma-next.config.ts Swap `showcase` for `diamond`, `wide-fan`, `converging-branches`, `multi-branch`, `long-spine`, or `skip-rollback` to explore each shape. -## SQL and MongoDB share the graph +## Name important states with refs + +Raw hashes are awkward to type and impossible to remember, so name the states that matter. A **ref** is a human-readable pointer to a node, stored as a small file in `migrations/app/refs/` and committed to your repo: + +```bash +npx prisma-next ref set prod sha256:f9a41d7... +npx prisma-next ref list +npx prisma-next migrate --to prod +``` -The graph model is family-neutral. On PostgreSQL, the marker lives in a `prisma_contract.marker` table and applies are wrapped in a transaction guarded by an advisory lock. On MongoDB, the marker and ledger live in a `_prisma_migrations` collection updated with compare-and-swap. Same nodes, same edges, same commands. +Because refs are committed, "where production should be" is a reviewable fact in a pull request, not tribal knowledge in someone's terminal history. -:::note[What's early] +One ref name is special. A ref called `db` is the default starting point `migration plan` uses when you do not pass `--from`. Keep it current with `prisma-next migrate --advance-ref db` and planning stays incremental on its own. -The graph, pathfinding, refs, and the marker/ledger model all work today. What doesn't exist yet: commands to squash a chain of migrations into one, baseline an existing history, or split a large migration; the graph was designed for them, but the commands haven't shipped. If two branch tips are both reachable, `migrate` asks you to pick a target with `--to` rather than guessing. +Two reserved tokens also work anywhere a command accepts a contract reference, without setting up a ref: -::: +- `@contract`: the contract you most recently emitted. +- `@db`: whatever state the connected database's marker holds. + +## What the graph gives you + +### Parallel work without ordering conflicts + +Alice and Bob each planned a migration from `705b1a6` on their own branches. In a timestamp-ordered system, whoever merges second inherits a broken history. Here, both edges are in the graph and every environment finds its own path to the merged state. This matters twice over when the "two developers" are two AI agents planning migrations concurrently, since neither has to know about the other. + +### History you can trust + +Because each edge declares its `from` state, a migration can never silently run against a database in the wrong shape. If the marker does not match, the run stops before any SQL executes, with an error naming the mismatch. + +### Rollback as a normal move + +An edge can point backwards, from a later contract state to an earlier one. Rolling back is not a special mode: it is planning one more migration whose destination is a state you have already been in. See [Rollbacks and recovery](/orm/next/migrations/rollbacks-and-recovery). + +### More than one shape of history + +The graph accommodates whatever your workflow produces: long linear spines, wide fan-outs where many branches leave one node, diamonds that converge again, and fast-forward edges that jump several states in one hop. + +## Database-specific details + +The graph model is family-neutral: same nodes, same edges, same commands on every database. The parts that differ are in how the marker and ledger are stored. + +- **PostgreSQL**: the marker lives in a `prisma_contract.marker` table, and each apply runs inside a transaction guarded by an advisory lock so two runners cannot move the same database at once. +- **MongoDB**: the marker and ledger live in a `_prisma_migrations` collection, updated with a compare-and-swap so a concurrent apply is rejected rather than interleaved. + +## Early-access limitations + +The graph, pathfinding, refs, and the marker/ledger model all work today. A few things you might reach for do not exist yet: + +- **No squash.** You cannot yet collapse a long chain of migrations into one. The chain stays as-is. +- **No baseline.** You cannot yet adopt an existing database's history as a starting node without replaying it. +- **No split.** You cannot yet break one large migration into smaller ones after the fact. +- **Ambiguous targets need a choice.** When two branch tips are both reachable, `migrate` asks you to pick one with `--to` rather than guessing. + +The graph was designed with these in mind; the commands simply have not shipped. Each migrations page calls out what is missing rather than papering over it. + +## Common tasks + +| Task | Command | +| --- | --- | +| See the whole graph | `prisma-next migration graph` | +| Check where a database is | `prisma-next migration status` | +| Move a database to a named state | `prisma-next migrate --to prod` | +| Name the current state `prod` | `prisma-next ref set prod @db` | +| List the refs you have named | `prisma-next ref list` | +| Roll a database back one state | `prisma-next migrate --to ` | +| Verify migration files and graph integrity | `prisma-next migration check` | ## Prompt your coding agent -Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: +Projects scaffolded with `create-prisma@next` install [Prisma Next skills](/ai/tools/skills#available-skills-for-prisma-next) for your coding agent. Ask your agent to: - "Draw the migration graph for this project and explain the branches." - "Which contract state is the `prod` ref pointing at, and is the database there yet?" @@ -116,6 +200,6 @@ Projects scaffolded with `create-prisma` install [Prisma Next skills](/ai/tools/ ## See also -- [How migrations work](/orm/next/migrations/how-migrations-work): the plan–review–apply loop +- [How migrations work](/orm/next/migrations/how-migrations-work): the plan-review-apply loop - [Applying a migration](/orm/next/migrations/applying-a-migration): how the runner walks the graph - [Rollbacks and recovery](/orm/next/migrations/rollbacks-and-recovery): backwards edges in practice diff --git a/apps/docs/content/docs/orm/next/reference/orm-client.mdx b/apps/docs/content/docs/orm/next/reference/orm-client.mdx index 50ce6c46e8..5b192c239b 100644 --- a/apps/docs/content/docs/orm/next/reference/orm-client.mdx +++ b/apps/docs/content/docs/orm/next/reference/orm-client.mdx @@ -197,7 +197,7 @@ const db = postgres({ contractJson, url: process.env.DATABASE_URL }); const users = await db.orm.public.User.all(); ``` -If your contract uses types from an extension pack, pass the pack when you create the client — the example schema's `Embedding1536` (pgvector) type needs `extensions: [pgvector]`, with `pgvector` imported from `@prisma-next/extension-pgvector/runtime`. +If your contract uses types from an extension pack, pass the pack when you create the client. The example schema's `Embedding1536` (pgvector) type needs `extensions: [pgvector]`, with `pgvector` imported from `@prisma-next/extension-pgvector/runtime`. To attach domain methods to a model, register a custom `Collection` subclass when you build the client. That path uses the `orm(...)` factory instead of the client's built-in facet; see [Custom `Collection` subclass](#custom-collection-subclass). @@ -1111,7 +1111,7 @@ Update every matching row and collect the results. #### Remarks -- Available for PostgreSQL and MongoDB. Call `where()` first — MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). +- Available for PostgreSQL and MongoDB. Call `where()` first: MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). - On PostgreSQL, `updateAll()` is a single `UPDATE ... RETURNING` statement, and is atomic. - On MongoDB, `updateAll()` is **not atomic**. It (1) reads the matching `_id`s, (2) runs an update against the original filter, then (3) re-reads by those captured `_id`s. A concurrent write between these steps could change which documents match or their values; the result reflects the `_id` set from step 1, not one atomic snapshot. @@ -1146,7 +1146,7 @@ Update every matching row and return the count. #### Remarks -- Available for PostgreSQL and MongoDB. Call `where()` first — MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). +- Available for PostgreSQL and MongoDB. Call `where()` first: MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). - On MongoDB, `updateCount()` accepts a data object or a field-operations callback. #### Options @@ -1228,7 +1228,7 @@ Remove every matching row and collect the results. #### Remarks -- Available for PostgreSQL and MongoDB. Call `where()` first — MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). +- Available for PostgreSQL and MongoDB. Call `where()` first: MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). #### Options @@ -1258,7 +1258,7 @@ Remove every matching row and return the count. #### Remarks -- Available for PostgreSQL and MongoDB. Call `where()` first — MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). +- Available for PostgreSQL and MongoDB. Call `where()` first: MongoDB enforces this at runtime; PostgreSQL does not (see the section warning above: without a filter these affect every row). - Returns `0` when no row matches. #### Options diff --git a/apps/docs/content/docs/orm/next/reference/raw-queries.mdx b/apps/docs/content/docs/orm/next/reference/raw-queries.mdx index e93f5f73f7..3662d160b0 100644 --- a/apps/docs/content/docs/orm/next/reference/raw-queries.mdx +++ b/apps/docs/content/docs/orm/next/reference/raw-queries.mdx @@ -132,7 +132,7 @@ const rows = await runtime.execute(plan); ### Unsupported interpolation -Interpolation accepts columns, typed expressions, `param(...)` values, and the bare scalar types (`number`, `bigint`, `string`, `boolean`, `Uint8Array`) — though bare scalars then fail at render time on PostgreSQL (see [the warning above](#binding-a-bare-value-with-param)). Interpolating anything else, such as a `Date`, throws synchronously with code `RUNTIME.RAW_SQL_UNSUPPORTED_INTERPOLATION`: +Interpolation accepts columns, typed expressions, `param(...)` values, and the bare scalar types (`number`, `bigint`, `string`, `boolean`, `Uint8Array`), though bare scalars then fail at render time on PostgreSQL (see [the warning above](#binding-a-bare-value-with-param)). Interpolating anything else, such as a `Date`, throws synchronously with code `RUNTIME.RAW_SQL_UNSUPPORTED_INTERPOLATION`: ``` ... wrap this value in `param(...)` with an explicit codec ... diff --git a/apps/docs/content/docs/orm/next/reference/sql-query-builder.mdx b/apps/docs/content/docs/orm/next/reference/sql-query-builder.mdx index d8de1ab4d3..62ff6ae44d 100644 --- a/apps/docs/content/docs/orm/next/reference/sql-query-builder.mdx +++ b/apps/docs/content/docs/orm/next/reference/sql-query-builder.mdx @@ -923,7 +923,7 @@ There is no `fns.coalesce` or `fns.cast`. Express `COALESCE`, `CAST`, and any ot ### `fns.raw` and `.returns()` -Write a raw SQL fragment as a tagged template. Interpolate columns and typed expressions with `${...}`; each interpolation is parameterized. For bare JavaScript values, always wrap them in `param(...)` with an explicit codec id — bare-scalar interpolation is currently broken on PostgreSQL (see the [raw queries reference](/orm/next/reference/raw-queries#binding-a-bare-value-with-param) for the verified details). Call `.returns(codecId)` to declare the fragment's result type. +Write a raw SQL fragment as a tagged template. Interpolate columns and typed expressions with `${...}`; each interpolation is parameterized. For bare JavaScript values, always wrap them in `param(...)` with an explicit codec id: bare-scalar interpolation is currently broken on PostgreSQL (see the [raw queries reference](/orm/next/reference/raw-queries#binding-a-bare-value-with-param) for the verified details). Call `.returns(codecId)` to declare the fragment's result type. #### Options diff --git a/apps/docs/content/docs/orm/next/reference/transactions-and-runtime.mdx b/apps/docs/content/docs/orm/next/reference/transactions-and-runtime.mdx index baa1361204..ed5d409b0c 100644 --- a/apps/docs/content/docs/orm/next/reference/transactions-and-runtime.mdx +++ b/apps/docs/content/docs/orm/next/reference/transactions-and-runtime.mdx @@ -15,7 +15,7 @@ Every PostgreSQL example is transcribed from an executable test suite that runs For a task-oriented walkthrough, see the Fundamentals guide to [Transactions](/orm/next/fundamentals/transactions). For the query surfaces you run inside a transaction, see the [ORM client reference](/orm/next/reference/orm-client), the [SQL query builder reference](/orm/next/reference/sql-query-builder), and the [raw queries reference](/orm/next/reference/raw-queries). -## Client lifecycle — PostgreSQL +## Client lifecycle on PostgreSQL Create a PostgreSQL client with `postgres(...)`, connect it to get a runtime, run queries, and close it when you are done. @@ -168,7 +168,7 @@ The client implements `Symbol.asyncDispose`, so `await using` closes it automati } // db is closed here ``` -## Client lifecycle — MongoDB +## Client lifecycle on MongoDB Create a MongoDB client with `mongo(...)`. The entry point and several lifecycle details differ from PostgreSQL, most notably that `runtime()` is asynchronous. @@ -179,7 +179,7 @@ Create a MongoDB client. #### Remarks - Pass the contract with `contractJson` or `contract` (supply exactly one). -- Bind to a database in one of three ways: `url` (a `mongodb://` connection string, with an optional `dbName` to select or override the database — the form the examples on this page use), `uri` plus an explicit `dbName`, or `mongoClient` (an existing `MongoClient` from the `mongodb` package) plus an explicit `dbName`. +- Bind to a database in one of three ways: `url` (a `mongodb://` connection string, with an optional `dbName` to select or override the database, the form the examples on this page use), `uri` plus an explicit `dbName`, or `mongoClient` (an existing `MongoClient` from the `mongodb` package) plus an explicit `dbName`. - **Client ownership** (source-read from `binding.ts` / `mongo-driver.ts`): with `url` or `uri`, Prisma Next creates the underlying `MongoClient` and closes it on `close()`. With `mongoClient`, you supplied the client, so Prisma Next does **not** close it: `close()` is a no-op on your client, and you close it yourself. This is what lets you share one `MongoClient` between Prisma Next and driver-level code. - `mongo(options)` does not open a connection. The runtime is built lazily on first use, or explicitly via [`connect()`](#connect-1). diff --git a/packages/eclipse/src/components/codeblock.tsx b/packages/eclipse/src/components/codeblock.tsx index 86ad36140e..a611b41788 100644 --- a/packages/eclipse/src/components/codeblock.tsx +++ b/packages/eclipse/src/components/codeblock.tsx @@ -261,7 +261,6 @@ export function CodeBlockTabs({ // When the primary tab changes, update the state function handleTabChange(tab: string) { - console.log("handleTabChange called:", { tab, activeTab, activeVariant }); setInternalActiveTab(tab); onValueChange?.(tab); } @@ -270,12 +269,6 @@ export function CodeBlockTabs({ const availableVariants = useMemo>(() => { if (!hasVariants) return new Set(); const available = new Set(variants!.filter((v) => existingCombos.has(`${activeTab}__${v}`))); - console.log("availableVariants calculation:", { - activeTab, - variants, - existingCombos: Array.from(existingCombos), - available: Array.from(available), - }); return available; }, [variants, activeTab, existingCombos]); diff --git a/packages/eclipse/src/components/tabs.tsx b/packages/eclipse/src/components/tabs.tsx index 3d2c625050..9417ea9646 100644 --- a/packages/eclipse/src/components/tabs.tsx +++ b/packages/eclipse/src/components/tabs.tsx @@ -187,7 +187,7 @@ export function TabsContent({ value={value} forceMount className={cn( - "text-[0.9375rem] outline-none prose-no-margin data-[state=inactive]:hidden [&>figure:only-child]:-m-4 [&>figure:only-child]:border-none", + "text-[0.9375rem] outline-none prose-no-margin data-[state=inactive]:hidden [&>figure:only-child]:mt-2 [&>figure:only-child]:mb-0", className, )} {...props}