From 7149a46547195726eaee26a94cce914fe3388486 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Mon, 11 May 2026 16:41:09 +0200 Subject: [PATCH 1/2] feat: add versioning --- .gitignore | 1 + .../next/add-to-existing-project/meta.json | 4 + .../next/add-to-existing-project/mongodb.mdx | 199 +++++++++++++ .../add-to-existing-project/postgresql.mdx | 207 +++++++++++++ apps/docs/content/docs/orm/next/index.mdx | 172 +++++++++++ apps/docs/content/docs/orm/next/meta.json | 12 + .../docs/orm/next/quickstart/meta.json | 4 + .../docs/orm/next/quickstart/mongodb.mdx | 273 +++++++++++++++++ .../docs/orm/next/quickstart/postgresql.mdx | 281 ++++++++++++++++++ apps/docs/src/lib/version.ts | 4 +- 10 files changed, 1155 insertions(+), 2 deletions(-) create mode 100644 apps/docs/content/docs/orm/next/add-to-existing-project/meta.json create mode 100644 apps/docs/content/docs/orm/next/add-to-existing-project/mongodb.mdx create mode 100644 apps/docs/content/docs/orm/next/add-to-existing-project/postgresql.mdx create mode 100644 apps/docs/content/docs/orm/next/index.mdx create mode 100644 apps/docs/content/docs/orm/next/meta.json create mode 100644 apps/docs/content/docs/orm/next/quickstart/meta.json create mode 100644 apps/docs/content/docs/orm/next/quickstart/mongodb.mdx create mode 100644 apps/docs/content/docs/orm/next/quickstart/postgresql.mdx 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/docs/content/docs/orm/next/add-to-existing-project/meta.json b/apps/docs/content/docs/orm/next/add-to-existing-project/meta.json new file mode 100644 index 0000000000..84c814653c --- /dev/null +++ b/apps/docs/content/docs/orm/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/orm/next/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/orm/next/add-to-existing-project/mongodb.mdx new file mode 100644 index 0000000000..82b6ec84f3 --- /dev/null +++ b/apps/docs/content/docs/orm/next/add-to-existing-project/mongodb.mdx @@ -0,0 +1,199 @@ +--- +title: MongoDB +description: Add Prisma Next to an existing MongoDB project. +url: /orm/next/add-to-existing-project/mongodb +metaTitle: Add Prisma Next to an existing MongoDB project +metaDescription: Add Prisma Next to an existing MongoDB project. +badge: early-access +--- + +This guide shows how to add Prisma Next to a project that already exists and already talks to MongoDB. The first goal is simple: initialize Prisma Next, describe the collections you want to work with, emit the generated artifacts, and then run a couple of queries. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +## Prerequisites + +Before you start, make sure you can already reach the MongoDB deployment this project uses today. + +- Node.js 24 or newer +- npm +- An existing MongoDB 6.0 or newer deployment + +For local development, use a replica set. MongoDB Atlas already gives you that. + +## 1. Make sure you can run the example script + +This first step keeps the rest of the guide smooth by making sure the small TypeScript examples can run locally. + +If your project already runs TypeScript scripts, you can skip this step. + +Otherwise, install the script tooling: + +```npm +npm install --save-dev typescript tsx @types/node +``` + +Then make sure `package.json` contains `"type": "module"`: + +```json title="package.json" +{ + "type": "module" +} +``` + +## 2. Initialize Prisma Next + +Now that the project can run the examples, this step adds the Prisma Next files without changing your existing application code yet. + +From the root of your existing project, run: + +```npm +npx prisma-next init --write-env +``` + +When Prisma Next asks a few setup questions: + +- choose `MongoDB` +- choose `PSL` +- keep the default schema path, `prisma/contract.prisma` + +## 3. Set your database connection string + +With the Prisma Next files in place, the next step is to point them at the same MongoDB deployment your app already uses. + +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/my-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" +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. Commands you will use next + +Once Prisma Next is connected to the existing collections, these are the MongoDB commands you will keep using as the project evolves. + +Once Prisma Next is in the project, these are the MongoDB commands to remember: + +```npm +npx prisma-next contract emit +``` + +Run this after you change `prisma/contract.prisma`. + +```npm +npx prisma-next migration plan --name add-user-bio +npx prisma-next migration apply +``` + +Use these when you want Prisma Next to manage a schema change for the collections in your contract. + +You do not need to create a migration just to start reading collections that already exist. Create a migration when you are ready for Prisma Next to own a change. diff --git a/apps/docs/content/docs/orm/next/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/orm/next/add-to-existing-project/postgresql.mdx new file mode 100644 index 0000000000..1b9dc70291 --- /dev/null +++ b/apps/docs/content/docs/orm/next/add-to-existing-project/postgresql.mdx @@ -0,0 +1,207 @@ +--- +title: Postgres +description: Add Prisma Next to an existing PostgreSQL project. +url: /orm/next/add-to-existing-project/postgresql +metaTitle: Add Prisma Next to an existing Postgres project +metaDescription: Add Prisma Next to an existing PostgreSQL project. +badge: early-access +--- + +This guide shows how to add Prisma Next to a project that already exists and already talks to PostgreSQL. The idea is to keep the first pass small: initialize Prisma Next, infer a contract from the live schema, sign the database, and then run a couple of queries. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +## Prerequisites + +Before you start, make sure you can already reach the PostgreSQL database this project uses today. + +- Node.js 24 or newer +- npm +- An existing PostgreSQL database + +## 1. Make sure you can run the example script + +This first step keeps the rest of the guide smooth by making sure the small TypeScript examples can run locally. + +If your project already runs TypeScript scripts, you can skip this step. + +Otherwise, install the script tooling: + +```npm +npm install --save-dev typescript tsx @types/node +``` + +Then make sure `package.json` contains `"type": "module"`: + +```json title="package.json" +{ + "type": "module" +} +``` + +## 2. Initialize Prisma Next + +Now that the project can run the examples, this step adds the Prisma Next files without changing your existing application code yet. + +From the root of your existing project, run: + +```npm +npx prisma-next init --write-env +``` + +When Prisma Next asks a few setup questions: + +- choose `PostgreSQL` +- choose `PSL` +- keep the default schema path, `prisma/contract.prisma` + +## 3. Set your database connection string + +With the Prisma Next files in place, the next step is to point them at the same database your app already uses. + +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 + +After the artifacts are emitted, this step records that the current database matches that contract. + +Now 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. Commands you will use next + +Once Prisma Next is connected to the existing database, these are the PostgreSQL commands you will keep using as the project evolves. + +Once Prisma Next is in the project, these are the PostgreSQL commands to remember: + +```npm +npx prisma-next contract emit +``` + +Run this after you change `prisma/contract.prisma`. + +```npm +npx prisma-next db update +``` + +Use this when you want Prisma Next to update the live database directly so it matches the latest contract. + +```npm +npx prisma-next migration plan --name add-user-bio +npx prisma-next migration apply +``` + +Use these when you want checked-in migration packages instead of a direct database update. diff --git a/apps/docs/content/docs/orm/next/index.mdx b/apps/docs/content/docs/orm/next/index.mdx new file mode 100644 index 0000000000..eace8b9fbd --- /dev/null +++ b/apps/docs/content/docs/orm/next/index.mdx @@ -0,0 +1,172 @@ +--- +title: Prisma Next +description: 'Learn what Prisma Next is, why it exists, and how its main pieces fit together.' +url: /orm/next +metaTitle: What is Prisma Next? +metaDescription: Learn what Prisma Next is, why it exists, and how its main pieces fit together. +badge: early-access +--- + +Prisma Next is the next foundation for Prisma ORM. The goal is simple: describe your data once, keep that description in version control, and use it to drive both your queries and your database changes. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +If you want the broader story first, read [The Next Evolution of Prisma ORM](https://www.prisma.io/blog/the-next-evolution-of-prisma-orm). + +## Why Prisma Next exists + +Prisma Next keeps the part of Prisma that feels approachable. You still describe your data in one place, and you still get a typed way to query it from TypeScript. + +The main change is how much of that workflow becomes explicit. Prisma Next treats your schema as a contract that can be emitted, inspected, compared, and verified. That helps with a few practical problems: + +- it is easier to see what your app expects from the database +- it is easier to choose how database changes should be applied +- it is easier for tools, CI, and AI assistants to work from the same source of truth + +So the big idea is not "more features first." The big idea is a clearer foundation that makes the rest of the workflow easier to reason about. + +## The main pieces to know + +The easiest way to understand Prisma Next is to follow the workflow from setup, to contract, to runtime, and then to database changes. + +### `prisma-next init` + +`prisma-next init` is the starting point. It scaffolds the files Prisma Next needs so you do not have to guess the shape of the project or wire the basics by hand. + +In the guides below, `init` creates a contract file, generated artifacts, a small runtime entrypoint, and a config file for the CLI. That means you can move from "empty folder" to "working project structure" in one step, then spend your time editing the contract instead of setting up plumbing. + +In practice, the generated pieces are: + +- `prisma/contract.prisma` for the contract you edit +- `prisma/contract.json` and `prisma/contract.d.ts` for emitted artifacts +- `prisma/db.ts` for the runtime client +- `prisma-next.config.ts` for CLI configuration + +### Your contract and emitted artifacts + +The contract is the center of the workflow. It describes the models, fields, and relations your application expects. That part is close to what many Prisma users already know. + +What is new is that Prisma Next treats the emitted output as a first-class artifact. When you run `prisma-next contract emit`, Prisma Next turns the contract into machine-readable JSON and matching TypeScript types. The JSON is useful for tooling and verification. The TypeScript types are useful for the runtime and query surfaces. + +That split matters because it gives different parts of the system a dependable artifact to work from. Humans edit the contract. Tooling and runtimes consume the emitted output. + +### The runtime client + +Once the contract is emitted, you create a runtime client from it. This is where Prisma Next starts to feel concrete. + +In the PostgreSQL demo app inside the Prisma Next repo, the runtime is created in `examples/prisma-next-demo/src/prisma/db.ts` like this: + +```typescript title="prisma-next/examples/prisma-next-demo/src/prisma/db.ts" +import pgvector from '@prisma-next/extension-pgvector/runtime'; +import { createTelemetryMiddleware } from '@prisma-next/middleware-telemetry'; +import postgres from '@prisma-next/postgres/runtime'; +import { budgets, lints } from '@prisma-next/sql-runtime'; +import type { Contract } from './contract.d'; +import contractJson from './contract.json' with { type: 'json' }; + +export const db = postgres({ + contractJson, + extensions: [pgvector], + middleware: [ + createTelemetryMiddleware(), + lints(), + budgets({ + maxRows: 10_000, + defaultTableRows: 10_000, + tableRows: { user: 10_000, post: 10_000 }, + maxLatencyMs: 1_000, + }), + ], +}); +``` + +This is a good example of what Prisma Next is aiming for. The contract is the core input, then you compose in extras like middleware, budgets, or extension packs around it. + +The MongoDB examples follow the same idea. In `examples/mongo-blog-leaderboard/src/db.ts`, the runtime is created from the emitted contract with a Mongo-specific runtime entrypoint: + +```typescript title="prisma-next/examples/mongo-blog-leaderboard/src/db.ts" +import mongo from '@prisma-next/mongo/runtime'; +import { ifDefined } from '@prisma-next/utils/defined'; +import type { Contract } from './contract'; +import contractJson from './contract.json' with { type: 'json' }; + +export function createClient(options: { url: string; dbName?: string }) { + return mongo({ + contractJson, + url: options.url, + ...ifDefined('dbName', options.dbName), + }); +} +``` + +So even though the databases are different, the shape is familiar: emit a contract, load it, then create a runtime client for that database family. + +### Two query styles + +Prisma Next gives you two ways to work because not every query wants the same level of abstraction. + +For day-to-day work, the high-level ORM API is usually the easiest path. In the retail store example in the Prisma Next repo, a Mongo helper that reads one user can stay very small: + +```typescript title="prisma-next/examples/retail-store/src/data/users.ts" +export function findUserById(db: Db, id: string) { + return db.orm.users.where({ _id: id }).first(); +} +``` + +This is the "just let me work with models" side of Prisma Next. + +When you want a more explicit query plan, Prisma Next also gives you a lower-level builder. In the PostgreSQL demo, `examples/prisma-next-demo/src/queries/get-users.ts` builds a SQL plan and then executes it: + +```typescript title="prisma-next/examples/prisma-next-demo/src/queries/get-users.ts" +import { db } from '../prisma/db'; + +export async function getUsers(limit = 10) { + const plan = db.sql.user.select('id', 'email', 'createdAt', 'kind').limit(limit).build(); + return db.runtime().execute(plan); +} +``` + +MongoDB has an equivalent lower-level surface, but it uses `db.query` instead of `db.sql`. In the retail store example, pagination is written like this: + +```typescript title="prisma-next/examples/retail-store/src/data/products.ts" +export async function findProductsPaginated(db: Db, skip: number, take: number): Promise { + const plan = db.query.from('products').sort({ _id: 1 }).skip(skip).limit(take).build(); + return collectResults(db, plan); +} +``` + +That is the basic mental model: + +- use `db.orm` when you want the higher-level model API +- use `db.sql` for PostgreSQL when you want an explicit SQL plan +- use `db.query` for MongoDB when you want an explicit pipeline + +### Database change commands + +Prisma Next can apply contract changes in more than one way, and this is one of the most important parts to understand. + +For PostgreSQL, you can use direct database reconciliation commands like `db init` and `db update`. That path is helpful when you want Prisma Next to bring a database in line with the contract directly. PostgreSQL can also use checked-in migration packages with `migration plan` and `migration apply`, which is useful when you want a reviewable change record in version control. + +For MongoDB, the guides below focus on the checked-in migration flow. That means you plan a migration package, review it, and then apply it. + +For existing projects, there is one more piece to know on the PostgreSQL side: `contract infer` and `db sign`. `contract infer` gives you a starter contract from a live schema. `db sign` records that the live database matches the emitted contract so Prisma Next can verify future work against it. + +If you want the background on why Prisma Next is approaching changes this way, start with [Rethinking Database Migrations](https://www.prisma.io/blog/rethinking-database-migrations). For more detail on the Prisma Next workflow itself, see [TypeScript Migrations in Prisma Next](https://www.prisma.io/blog/typescript-migrations-in-prisma-next) and [Data Migrations in Prisma Next](https://www.prisma.io/blog/data-migrations-in-prisma-next). + +## Choose your path + +The guides below are split by both starting point and database so each path can stay specific and easy to follow. + +If you are starting fresh, use one of these quickstarts: + +- [Quickstart for PostgreSQL](/orm/next/quickstart/postgresql) +- [Quickstart for MongoDB](/orm/next/quickstart/mongodb) + +If you want to add Prisma Next to an app that already exists, use one of these: + +- [Add Prisma Next to an existing PostgreSQL project](/orm/next/add-to-existing-project/postgresql) +- [Add Prisma Next to an existing MongoDB project](/orm/next/add-to-existing-project/mongodb) diff --git a/apps/docs/content/docs/orm/next/meta.json b/apps/docs/content/docs/orm/next/meta.json new file mode 100644 index 0000000000..38106636ee --- /dev/null +++ b/apps/docs/content/docs/orm/next/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Next", + "defaultOpen": true, + "root": true, + "pages": [ + "---Introduction---", + "index", + "---Getting started---", + "quickstart", + "add-to-existing-project" + ] +} diff --git a/apps/docs/content/docs/orm/next/quickstart/meta.json b/apps/docs/content/docs/orm/next/quickstart/meta.json new file mode 100644 index 0000000000..3a7edc76ec --- /dev/null +++ b/apps/docs/content/docs/orm/next/quickstart/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Quickstart", + "pages": ["postgresql", "mongodb"] +} diff --git a/apps/docs/content/docs/orm/next/quickstart/mongodb.mdx b/apps/docs/content/docs/orm/next/quickstart/mongodb.mdx new file mode 100644 index 0000000000..d0ca9c4a03 --- /dev/null +++ b/apps/docs/content/docs/orm/next/quickstart/mongodb.mdx @@ -0,0 +1,273 @@ +--- +title: MongoDB +description: Set up Prisma Next from scratch with MongoDB. +url: /orm/next/quickstart/mongodb +metaTitle: 'Quickstart: Prisma Next with MongoDB' +metaDescription: Set up Prisma Next from scratch with MongoDB. +badge: early-access +--- + +[MongoDB](https://www.mongodb.com/) is a document database. In this guide, you will create a small Prisma Next project from scratch, connect it to MongoDB, create the first migration package, apply it, and run both a high-level and a low-level query. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +## Prerequisites + +Before you start, make sure your machine can run the Prisma Next CLI and can connect to a MongoDB deployment that matches the assumptions in this guide. + +- Node.js 24 or newer +- npm +- A MongoDB 6.0 or newer deployment + +For local development, use a replica set. MongoDB Atlas already gives you that. A single standalone `mongod` is not the setup this guide assumes. + +## 1. Create a new project + +This gives you a clean folder so it is easy to see which files Prisma Next creates for you. + +Start with an empty folder: + +```shell +mkdir hello-prisma-next-mongo +cd hello-prisma-next-mongo +``` + +Create a `package.json`: + +```npm +npm init -y +``` + +## 2. Initialize Prisma Next + +This is the setup step where Prisma Next writes the starting files we will use for the rest of the guide. + +Run: + +```npm +npx prisma-next init --write-env +``` + +When Prisma Next asks a few setup questions: + +- choose `MongoDB` +- choose `PSL` +- keep the default schema path, `prisma/contract.prisma` + +This creates the Prisma Next files for you, including `prisma/contract.prisma`, `prisma/db.ts`, `prisma-next.config.ts`, and a starter `.env` file. + +## 3. Add script tooling for the examples + +We add this now so the query examples later run without any extra setup in the middle of the guide. + +The query examples in this guide use a small TypeScript script. Install the tools for that now: + +```npm +npm install --save-dev typescript tsx @types/node +``` + +Then open `package.json` and add `"type": "module"`: + +```json title="package.json" +{ + "type": "module" +} +``` + +`prisma-next init` already created a `tsconfig.json`, so you do not need to create one by hand. + +## 4. Add your MongoDB connection string + +Now that the project files exist, the next step is to point them at the MongoDB deployment you want to use. + +Update `.env` with your MongoDB connection string: + +```text title=".env" +DATABASE_URL="mongodb://127.0.0.1:27017/prisma_next?replicaSet=rs0" +``` + +If you are using MongoDB Atlas, your value will usually start with `mongodb+srv://...`. + +## 5. Review the starter contract + +Before Prisma Next plans any changes, it helps to look at the contract it is about to use. + +Open `prisma/contract.prisma`. After `init`, the starter contract looks like this: + +```prisma title="prisma/contract.prisma" +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") +} +``` + +That is enough for the first run, so you can keep it as-is. + +## 6. Create and apply the first migration package + +This is the first database-facing step, so it is where the contract turns into MongoDB collections and indexes. + +For MongoDB, this guide uses the checked-in migration flow from the start: + +```npm +npx prisma-next migration plan --name init +npx prisma-next migration apply +``` + +That creates the `users` and `posts` collections, adds the `users.email` unique index, and records the migration history for later changes. + +## 7. Run a simple high-level query + +With the collections in place, you can test the higher-level API first and confirm the setup is working end to end. + +Create a `script.ts` file: + +```typescript title="script.ts" +import "dotenv/config"; +import { db } from "./prisma/db"; + +async function main() { + const createdUser = await db.orm.users.create({ + email: `alice+${Date.now()}@example.com`, + name: "Alice", + }); + + console.log(createdUser); + + await db.close(); +} + +main().catch((error) => { + console.error(error); + process.exit(1); +}); +``` + +Run it: + +```npm +npx tsx script.ts +``` + +This is the high-level path. You work with the `users` collection through the ORM surface. + +## 8. Run a simple low-level query + +After the ORM example, this step shows the lower-level MongoDB pipeline builder against the same contract and database. + +Replace `script.ts` with this version: + +```typescript title="script.ts" +import "dotenv/config"; +import { db } from "./prisma/db"; + +async function main() { + const email = `alice+${Date.now()}@example.com`; + + await db.orm.users.create({ + email, + name: "Alice", + }); + + const runtime = await db.runtime(); + const plan = db.query + .from("users") + .match((fields) => fields.email.eq(email)) + .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 +``` + +This is the lower-level path. You build a typed MongoDB pipeline yourself and then execute it. + +## 9. Commands you will use next + +Once the first query works, these are the MongoDB commands you will keep reaching for as the project grows. + +After the first setup, these are the MongoDB commands to remember: + +```npm +npx prisma-next contract emit +``` + +Run this after you change `prisma/contract.prisma`. + +```npm +npx prisma-next migration plan --name add-user-bio +npx prisma-next migration apply +``` + +Use these to create and apply the next contract-driven change. + +This guide uses the migration package workflow on purpose. It gives you a clear, reviewable record of what changed. + +## Want the full Prisma Next docs right now? + +If you want to keep going after this quickstart, the Prisma Next repo already has more examples, demos, and internal docs than we have brought over here so far. Those materials will be cleaned up and moved into the main docs closer to GA. + +Until then, clone the repo and use it as the source of truth for deeper MongoDB examples: + +```shell +git clone https://github.com/prisma/prisma-next.git +cd prisma-next +``` + +For MongoDB, the most useful places to start are: + +- [`README.md`](https://github.com/prisma/prisma-next/blob/main/README.md) +- [`examples/mongo-demo`](https://github.com/prisma/prisma-next/tree/main/examples/mongo-demo) +- [`examples/mongo-blog-leaderboard`](https://github.com/prisma/prisma-next/tree/main/examples/mongo-blog-leaderboard) +- [`docs`](https://github.com/prisma/prisma-next/tree/main/docs) + +If you want help from an assistant after cloning the repo, paste this prompt: + +```text +I cloned the Prisma Next repo locally at ./prisma-next. + +Database: MongoDB +My exact question: +Examples: +- How do I add a new field and ship it with migration plan and migration apply? +- How do I write this read with db.query instead of db.orm? +- How do I model my existing users and posts collections in contract.prisma? + +Please use README.md, docs/, examples/mongo-demo/, and examples/mongo-blog-leaderboard/ as the source of truth. +Please answer with: +1. The exact commands I should run +2. The exact files I should open or edit +3. A minimal code example that matches the repo style +4. Any caveats if the repo and public docs differ +5. The specific repo files you used +``` diff --git a/apps/docs/content/docs/orm/next/quickstart/postgresql.mdx b/apps/docs/content/docs/orm/next/quickstart/postgresql.mdx new file mode 100644 index 0000000000..d589e3175e --- /dev/null +++ b/apps/docs/content/docs/orm/next/quickstart/postgresql.mdx @@ -0,0 +1,281 @@ +--- +title: Postgres +description: Set up Prisma Next from scratch with PostgreSQL. +url: /orm/next/quickstart/postgresql +metaTitle: 'Quickstart: Prisma Next with Postgres' +metaDescription: Set up Prisma Next from scratch with PostgreSQL. +badge: early-access +--- + +[PostgreSQL](https://www.postgresql.org/) is a relational database. In this guide, you will create a small Prisma Next project from scratch, create a PostgreSQL database with `create-db`, create the first tables, and run both a high-level and a low-level query. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +## Prerequisites + +Before you start, make sure your machine can run the Prisma Next CLI and the small TypeScript scripts used later in the guide. + +- Node.js 24 or newer +- npm + +## 1. Create a new project + +This gives you a clean folder so it is easy to see which files Prisma Next creates for you. + +Start with an empty folder: + +```shell +mkdir hello-prisma-next +cd hello-prisma-next +``` + +Create a `package.json`: + +```npm +npm init -y +``` + +## 2. Initialize Prisma Next + +This is the setup step where Prisma Next writes the starting files we will use for the rest of the guide. + +Run: + +```npm +npx prisma-next init --write-env +``` + +When Prisma Next asks a few setup questions: + +- choose `PostgreSQL` +- choose `PSL` +- keep the default schema path, `prisma/contract.prisma` + +This creates the Prisma Next files for you, including `prisma/contract.prisma`, `prisma/db.ts`, `prisma-next.config.ts`, and a starter `.env` file. + +## 3. Add script tooling for the examples + +We add this now so the query examples later run without any extra setup in the middle of the guide. + +The query examples in this guide use a small TypeScript script. Install the tools for that now: + +```npm +npm install --save-dev typescript tsx @types/node +``` + +Then open `package.json` and add `"type": "module"`: + +```json title="package.json" +{ + "type": "module" +} +``` + +`prisma-next init` already created a `tsconfig.json`, so you do not need to create one by hand. + +## 4. Create a PostgreSQL database + +Now that the project files exist, the next step is to create a real database for Prisma Next to connect to. + +Now create a temporary PostgreSQL database: + +```npm +npx create-db@latest +``` + +The command prints a `postgres://...` connection string. Copy that value into `.env`: + +```text title=".env" +DATABASE_URL="postgres://username:password@db.prisma.io:5432/postgres?sslmode=require" +``` + +## 5. Review the starter contract + +Before Prisma Next changes the database, it helps to look at the contract it is about to apply. + +Open `prisma/contract.prisma`. After `init`, the starter contract looks like this: + +```prisma title="prisma/contract.prisma" +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? + posts Post[] + createdAt DateTime @default(now()) +} + +model Post { + id Int @id @default(autoincrement()) + title String + content String? + author User @relation(fields: [authorId], references: [id]) + authorId Int + createdAt DateTime @default(now()) +} +``` + +That is enough for the first run, so you can keep it as-is. + +## 6. Create the first tables + +This is the first database-facing step, so it is where the contract turns into real PostgreSQL tables. + +Run: + +```npm +npx prisma-next db init +``` + +This bootstraps the database to match the current contract and signs the database so Prisma Next knows which contract it matches. + +## 7. Run a simple high-level query + +With the tables in place, you can test the higher-level API first and confirm the setup is working end to end. + +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 createdUser = await db.orm.User + .select("id", "email", "name", "createdAt") + .create({ + email: `alice+${Date.now()}@example.com`, + name: "Alice", + }); + + console.log(createdUser); + + await runtime.close(); +} + +main().catch((error) => { + console.error(error); + process.exit(1); +}); +``` + +Run it: + +```npm +npx tsx script.ts +``` + +This is the high-level path. You work with the `User` model and let Prisma Next handle the SQL planning for you. + +## 8. Run a simple low-level query + +After the ORM example, this step shows the lower-level SQL builder against the same contract and database. + +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 email = `alice+${Date.now()}@example.com`; + + await db.orm.User.create({ + email, + name: "Alice", + }); + + const plan = db.sql.user + .select("id", "email", "name", "createdAt") + .where((fields, fns) => fns.eq(fields.email, email)) + .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 +``` + +This is the lower-level path. You build a typed SQL plan yourself and then execute it. + +## 9. Commands you will use next + +Once the first query works, these are the PostgreSQL commands you will keep reaching for as the project grows. + +After the first setup, these are the PostgreSQL commands to remember: + +```npm +npx prisma-next contract emit +``` + +Run this after you change `prisma/contract.prisma`. + +```npm +npx prisma-next db update +``` + +Use this when you want Prisma Next to update the live database directly so it matches the latest contract. + +```npm +npx prisma-next migration plan --name add-user-bio +npx prisma-next migration apply +``` + +Use these when you want checked-in migration packages instead of a direct database update. + +PostgreSQL supports both workflows. Many teams pick one and stay consistent: either direct reconciliation with `db init` and `db update`, or checked-in migration packages with `migration plan` and `migration apply`. + +## Want the full Prisma Next docs right now? + +If you want to keep going after this quickstart, the Prisma Next repo already has more examples, demos, and internal docs than we have brought over here so far. Those materials will be cleaned up and moved into the main docs closer to GA. + +Until then, clone the repo and use it as the source of truth for deeper examples: + +```shell +git clone https://github.com/prisma/prisma-next.git +cd prisma-next +``` + +For PostgreSQL, the most useful places to start are: + +- [`README.md`](https://github.com/prisma/prisma-next/blob/main/README.md) +- [`examples/prisma-next-demo`](https://github.com/prisma/prisma-next/tree/main/examples/prisma-next-demo) +- [`docs`](https://github.com/prisma/prisma-next/tree/main/docs) + +If you want help from an assistant after cloning the repo, paste this prompt: + +```text +I cloned the Prisma Next repo locally at ./prisma-next. + +Database: PostgreSQL +My exact question: +Examples: +- How do I add a Profile table and query it with db.orm? +- How do I choose between db update and migration plan for this change? +- How do I write the same read using db.sql instead of db.orm? + +Please use README.md, docs/, and examples/prisma-next-demo/ as the source of truth. +Please answer with: +1. The exact commands I should run +2. The exact files I should open or edit +3. A minimal code example that matches the repo style +4. Any caveats if the repo and public docs differ +5. The specific repo files you used +``` diff --git a/apps/docs/src/lib/version.ts b/apps/docs/src/lib/version.ts index a868ef86ca..2db70c3829 100644 --- a/apps/docs/src/lib/version.ts +++ b/apps/docs/src/lib/version.ts @@ -152,7 +152,7 @@ export function getOrmVersionFromRoute(route?: string | string[]): Version | nul export function getOrmVersions(tree: PageTree.Root): Version[] { const ormNode = findOrmNode(tree as TreeNode); - const versions = new Set(); + const versions = new Set(["next", "v6"]); for (const child of ormNode?.children ?? []) { const version = getVersionFromNode(child); @@ -161,5 +161,5 @@ export function getOrmVersions(tree: PageTree.Root): Version[] { } } - return [LATEST_VERSION, "v6", ...Array.from(versions).sort(compareVersionsDescending)]; + return [LATEST_VERSION, ...Array.from(versions).sort(compareVersionsDescending)]; } From c785d9648310f33ba0c24c678c6b05c5d17d2d1f Mon Sep 17 00:00:00 2001 From: Aman Varshney Date: Fri, 15 May 2026 18:46:10 +0530 Subject: [PATCH 2/2] docs: flesh out Prisma Next docs --- apps/docs/content/docs/(index)/meta.json | 1 + .../next/add-to-existing-project/meta.json | 0 .../next/add-to-existing-project/mongodb.mdx | 25 +- .../add-to-existing-project/postgresql.mdx | 27 +- .../docs/(index)/next/create-prisma.mdx | 80 +++++ apps/docs/content/docs/(index)/next/index.mdx | 29 ++ apps/docs/content/docs/(index)/next/meta.json | 11 + apps/docs/content/docs/cli/meta.json | 1 + .../content/docs/cli/next/configuration.mdx | 91 ++++++ .../content/docs/cli/next/contract-emit.mdx | 52 ++++ .../content/docs/cli/next/contract-infer.mdx | 54 ++++ apps/docs/content/docs/cli/next/db-init.mdx | 52 ++++ apps/docs/content/docs/cli/next/db-schema.mdx | 36 +++ apps/docs/content/docs/cli/next/db-sign.mdx | 43 +++ apps/docs/content/docs/cli/next/db-update.mdx | 44 +++ apps/docs/content/docs/cli/next/db-verify.mdx | 54 ++++ apps/docs/content/docs/cli/next/index.mdx | 97 ++++++ apps/docs/content/docs/cli/next/init.mdx | 69 +++++ apps/docs/content/docs/cli/next/meta.json | 32 ++ .../content/docs/cli/next/migration-apply.mdx | 47 +++ .../content/docs/cli/next/migration-new.mdx | 49 +++ .../content/docs/cli/next/migration-plan.mdx | 42 +++ .../content/docs/cli/next/migration-ref.mdx | 46 +++ .../content/docs/cli/next/migration-show.mdx | 48 +++ .../docs/cli/next/migration-status.mdx | 44 +++ .../next/concepts/contract-first-design.mdx | 78 +++++ .../orm/next/concepts/extension-packs.mdx | 81 +++++ .../content/docs/orm/next/concepts/meta.json | 9 + .../docs/orm/next/concepts/query-apis.mdx | 118 ++++++++ ...chema-definition-and-contract-emission.mdx | 105 +++++++ .../docs/orm/next/extensions/cipherstash.mdx | 172 +++++++++++ .../docs/orm/next/extensions/meta.json | 8 + .../docs/orm/next/extensions/pgvector.mdx | 141 +++++++++ .../docs/orm/next/extensions/postgis.mdx | 180 +++++++++++ .../guides/building-queries-with-sql-dsl.mdx | 136 +++++++++ .../deploying-to-serverless-runtimes.mdx | 91 ++++++ .../next/guides/error-handling-patterns.mdx | 93 ++++++ .../guides/managing-database-migrations.mdx | 85 ++++++ .../content/docs/orm/next/guides/meta.json | 10 + .../orm/next/guides/using-the-orm-client.mdx | 147 +++++++++ apps/docs/content/docs/orm/next/index.mdx | 182 +++--------- apps/docs/content/docs/orm/next/meta.json | 12 +- .../docs/orm/next/quickstart/meta.json | 4 - .../docs/orm/next/quickstart/mongodb.mdx | 273 ----------------- .../docs/orm/next/quickstart/postgresql.mdx | 281 ------------------ apps/docs/cspell.json | 6 + apps/docs/next.config.mjs | 26 +- apps/docs/src/app/(docs)/(default)/layout.tsx | 9 +- apps/docs/src/app/layout.tsx | 25 ++ apps/docs/src/components/layout/link-item.tsx | 9 +- .../layout/notebook/page/client.tsx | 9 +- apps/docs/src/components/version-switcher.tsx | 83 ++++-- apps/docs/src/lib/layout.shared.tsx | 7 +- apps/docs/src/lib/version.ts | 228 +++++++++++++- apps/docs/src/lib/versioned-sidebar-tree.ts | 194 +++++++++++- 55 files changed, 3085 insertions(+), 791 deletions(-) rename apps/docs/content/docs/{orm => (index)}/next/add-to-existing-project/meta.json (100%) rename apps/docs/content/docs/{orm => (index)}/next/add-to-existing-project/mongodb.mdx (83%) rename apps/docs/content/docs/{orm => (index)}/next/add-to-existing-project/postgresql.mdx (79%) create mode 100644 apps/docs/content/docs/(index)/next/create-prisma.mdx create mode 100644 apps/docs/content/docs/(index)/next/index.mdx create mode 100644 apps/docs/content/docs/(index)/next/meta.json create mode 100644 apps/docs/content/docs/cli/next/configuration.mdx create mode 100644 apps/docs/content/docs/cli/next/contract-emit.mdx create mode 100644 apps/docs/content/docs/cli/next/contract-infer.mdx create mode 100644 apps/docs/content/docs/cli/next/db-init.mdx create mode 100644 apps/docs/content/docs/cli/next/db-schema.mdx create mode 100644 apps/docs/content/docs/cli/next/db-sign.mdx create mode 100644 apps/docs/content/docs/cli/next/db-update.mdx create mode 100644 apps/docs/content/docs/cli/next/db-verify.mdx create mode 100644 apps/docs/content/docs/cli/next/index.mdx create mode 100644 apps/docs/content/docs/cli/next/init.mdx create mode 100644 apps/docs/content/docs/cli/next/meta.json create mode 100644 apps/docs/content/docs/cli/next/migration-apply.mdx create mode 100644 apps/docs/content/docs/cli/next/migration-new.mdx create mode 100644 apps/docs/content/docs/cli/next/migration-plan.mdx create mode 100644 apps/docs/content/docs/cli/next/migration-ref.mdx create mode 100644 apps/docs/content/docs/cli/next/migration-show.mdx create mode 100644 apps/docs/content/docs/cli/next/migration-status.mdx create mode 100644 apps/docs/content/docs/orm/next/concepts/contract-first-design.mdx create mode 100644 apps/docs/content/docs/orm/next/concepts/extension-packs.mdx create mode 100644 apps/docs/content/docs/orm/next/concepts/meta.json create mode 100644 apps/docs/content/docs/orm/next/concepts/query-apis.mdx create mode 100644 apps/docs/content/docs/orm/next/concepts/schema-definition-and-contract-emission.mdx create mode 100644 apps/docs/content/docs/orm/next/extensions/cipherstash.mdx create mode 100644 apps/docs/content/docs/orm/next/extensions/meta.json create mode 100644 apps/docs/content/docs/orm/next/extensions/pgvector.mdx create mode 100644 apps/docs/content/docs/orm/next/extensions/postgis.mdx create mode 100644 apps/docs/content/docs/orm/next/guides/building-queries-with-sql-dsl.mdx create mode 100644 apps/docs/content/docs/orm/next/guides/deploying-to-serverless-runtimes.mdx create mode 100644 apps/docs/content/docs/orm/next/guides/error-handling-patterns.mdx create mode 100644 apps/docs/content/docs/orm/next/guides/managing-database-migrations.mdx create mode 100644 apps/docs/content/docs/orm/next/guides/meta.json create mode 100644 apps/docs/content/docs/orm/next/guides/using-the-orm-client.mdx delete mode 100644 apps/docs/content/docs/orm/next/quickstart/meta.json delete mode 100644 apps/docs/content/docs/orm/next/quickstart/mongodb.mdx delete mode 100644 apps/docs/content/docs/orm/next/quickstart/postgresql.mdx diff --git a/apps/docs/content/docs/(index)/meta.json b/apps/docs/content/docs/(index)/meta.json index 878f912fea..1737611716 100644 --- a/apps/docs/content/docs/(index)/meta.json +++ b/apps/docs/content/docs/(index)/meta.json @@ -5,6 +5,7 @@ "---Getting Started---", "index", "getting-started", + "next", "---Prisma ORM---", "...prisma-orm", "---Prisma Postgres---", diff --git a/apps/docs/content/docs/orm/next/add-to-existing-project/meta.json b/apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json similarity index 100% rename from apps/docs/content/docs/orm/next/add-to-existing-project/meta.json rename to apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json diff --git a/apps/docs/content/docs/orm/next/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx similarity index 83% rename from apps/docs/content/docs/orm/next/add-to-existing-project/mongodb.mdx rename to apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx index 82b6ec84f3..15dd0684c0 100644 --- a/apps/docs/content/docs/orm/next/add-to-existing-project/mongodb.mdx +++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx @@ -1,13 +1,12 @@ --- title: MongoDB description: Add Prisma Next to an existing MongoDB project. -url: /orm/next/add-to-existing-project/mongodb +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. -badge: early-access --- -This guide shows how to add Prisma Next to a project that already exists and already talks to MongoDB. The first goal is simple: initialize Prisma Next, describe the collections you want to work with, emit the generated artifacts, and then run a couple of queries. +This guide shows how to add Prisma Next to a project that already uses MongoDB. You will initialize Prisma Next, describe the collections you want to work with, emit the generated artifacts, and run a couple of queries. :::warning[Prisma Next is still in development] @@ -27,28 +26,18 @@ For local development, use a replica set. MongoDB Atlas already gives you that. ## 1. Make sure you can run the example script -This first step keeps the rest of the guide smooth by making sure the small TypeScript examples can run locally. - If your project already runs TypeScript scripts, you can skip this step. Otherwise, install the script tooling: ```npm -npm install --save-dev typescript tsx @types/node +npm install --save-dev tsx typescript ``` -Then make sure `package.json` contains `"type": "module"`: - -```json title="package.json" -{ - "type": "module" -} -``` +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 -Now that the project can run the examples, this step adds the Prisma Next files without changing your existing application code yet. - From the root of your existing project, run: ```npm @@ -63,8 +52,6 @@ When Prisma Next asks a few setup questions: ## 3. Set your database connection string -With the Prisma Next files in place, the next step is to point them at the same MongoDB deployment your app already uses. - Update `.env` with the connection string for the MongoDB deployment your app already uses: ```text title=".env" @@ -80,6 +67,8 @@ 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 @@ -179,8 +168,6 @@ npx tsx script.ts ## 8. Commands you will use next -Once Prisma Next is connected to the existing collections, these are the MongoDB commands you will keep using as the project evolves. - Once Prisma Next is in the project, these are the MongoDB commands to remember: ```npm diff --git a/apps/docs/content/docs/orm/next/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx similarity index 79% rename from apps/docs/content/docs/orm/next/add-to-existing-project/postgresql.mdx rename to apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx index 1b9dc70291..6db183be5e 100644 --- a/apps/docs/content/docs/orm/next/add-to-existing-project/postgresql.mdx +++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx @@ -1,13 +1,12 @@ --- title: Postgres description: Add Prisma Next to an existing PostgreSQL project. -url: /orm/next/add-to-existing-project/postgresql +url: /next/add-to-existing-project/postgresql metaTitle: Add Prisma Next to an existing Postgres project metaDescription: Add Prisma Next to an existing PostgreSQL project. -badge: early-access --- -This guide shows how to add Prisma Next to a project that already exists and already talks to PostgreSQL. The idea is to keep the first pass small: initialize Prisma Next, infer a contract from the live schema, sign the database, and then run a couple of queries. +This guide shows how to add Prisma Next to a project that already uses PostgreSQL. You will initialize Prisma Next, infer a contract from the live schema, sign the database, and run a couple of queries. :::warning[Prisma Next is still in development] @@ -25,28 +24,18 @@ Before you start, make sure you can already reach the PostgreSQL database this p ## 1. Make sure you can run the example script -This first step keeps the rest of the guide smooth by making sure the small TypeScript examples can run locally. - If your project already runs TypeScript scripts, you can skip this step. Otherwise, install the script tooling: ```npm -npm install --save-dev typescript tsx @types/node +npm install --save-dev tsx typescript ``` -Then make sure `package.json` contains `"type": "module"`: - -```json title="package.json" -{ - "type": "module" -} -``` +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 -Now that the project can run the examples, this step adds the Prisma Next files without changing your existing application code yet. - From the root of your existing project, run: ```npm @@ -61,8 +50,6 @@ When Prisma Next asks a few setup questions: ## 3. Set your database connection string -With the Prisma Next files in place, the next step is to point them at the same database your app already uses. - Update `.env` with the connection string for the database your app already uses: ```text title=".env" @@ -97,9 +84,7 @@ This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime ## 6. Sign the database -After the artifacts are emitted, this step records that the current database matches that contract. - -Now record that the live database matches the emitted contract: +Record that the live database matches the emitted contract: ```npm npx prisma-next db sign @@ -183,8 +168,6 @@ npx tsx script.ts ## 9. Commands you will use next -Once Prisma Next is connected to the existing database, these are the PostgreSQL commands you will keep using as the project evolves. - Once Prisma Next is in the project, these are the PostgreSQL commands to remember: ```npm diff --git a/apps/docs/content/docs/(index)/next/create-prisma.mdx b/apps/docs/content/docs/(index)/next/create-prisma.mdx new file mode 100644 index 0000000000..903e92d836 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/create-prisma.mdx @@ -0,0 +1,80 @@ +--- +title: create-prisma@next +description: Scaffold a new Prisma Next app with create-prisma@next. +url: /next/create-prisma +metaTitle: Scaffold a Prisma Next app with create-prisma@next +metaDescription: Use create-prisma@next to create a new Prisma Next app with templates, database scripts, and runtime helpers. +--- + +`create-prisma@next` creates a new Prisma Next project from an app template. It installs the Prisma Next packages and adds the files and scripts needed to start developing. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +Use this when you want to start from a working app template. If you already have an app, use [Add Prisma Next to an existing PostgreSQL project](/next/add-to-existing-project/postgresql) or [Add Prisma Next to an existing MongoDB project](/next/add-to-existing-project/mongodb). + +## Create a project + +Run: + +```npm +npx create-prisma@next +``` + +Then choose a project name, app template, database provider, contract authoring style, and package manager. + +Generated Node.js projects expect Node.js 24 LTS or newer. + +## Skip the prompts + +Pass flags when you already know the project shape: + +```npm +npx create-prisma@next --name my-app --template next --provider postgres +``` + +Use `--name .` to create the project in the current directory. + +Useful flags: + +| Flag | What it does | +| --- | --- | +| `--template ` | Chooses the app template. | +| `--provider postgres\|mongodb` | Chooses the database provider. | +| `--authoring psl\|typescript` | Chooses the contract authoring style. | +| `--package-manager ` | Chooses `npm`, `pnpm`, `yarn`, `bun`, or `deno`. | +| `--database-url ` | Writes `DATABASE_URL` during setup. | +| `--no-install` | Scaffolds files without installing dependencies. | +| `--no-emit` | Skips `prisma-next contract emit`. | +| `--force` | Allows scaffolding into a non-empty directory. | + +## What gets created + +The generated project includes Prisma Next dependencies, a contract file, Prisma Next configuration, environment files, and package scripts for local development. + +Supported templates include Hono, Elysia, NestJS, Next.js, SvelteKit, Astro, Nuxt, TanStack Start, and Turborepo. + +## Start the app + +Review `DATABASE_URL` in `.env`, then initialize the database. + +For PostgreSQL: + +```npm +npm run db:init +npm run dev +``` + +For MongoDB: + +```npm +npm run db:up +npm run migration:plan -- --name init +npm run migration:apply +npm run dev +``` + +To add Prisma Next to an app you already have, use the [PostgreSQL existing-project guide](/next/add-to-existing-project/postgresql) or [MongoDB existing-project guide](/next/add-to-existing-project/mongodb). 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..54e4e477d5 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/index.mdx @@ -0,0 +1,29 @@ +--- +title: Get started with Prisma Next +description: Start a new Prisma Next app or add Prisma Next to an existing project. +url: /next +metaTitle: Get started with Prisma Next +metaDescription: Start a Prisma Next project with create-prisma@next or add Prisma Next to an existing project. +badge: early-access +--- + +Prisma Next is the next foundation for Prisma ORM. Start here if you want to try the Prisma Next workflow. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +## Start a new project + +- [Scaffold a Prisma Next app with create-prisma@next](/next/create-prisma) + +## Add Prisma Next to an existing project + +- [Add Prisma Next to an existing PostgreSQL project](/next/add-to-existing-project/postgresql) +- [Add Prisma Next to an existing MongoDB project](/next/add-to-existing-project/mongodb) + +## Learn the ORM workflow + +Read the [Prisma Next overview](/orm/next) to learn about contracts, emitted artifacts, runtime clients, query styles, and database change commands. diff --git a/apps/docs/content/docs/(index)/next/meta.json b/apps/docs/content/docs/(index)/next/meta.json new file mode 100644 index 0000000000..022d2ebb44 --- /dev/null +++ b/apps/docs/content/docs/(index)/next/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Next", + "defaultOpen": true, + "root": true, + "pages": [ + "---Getting Started---", + "index", + "create-prisma", + "add-to-existing-project" + ] +} 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..bcd24d33db --- /dev/null +++ b/apps/docs/content/docs/cli/next/index.mdx @@ -0,0 +1,97 @@ +--- +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. + +:::warning[Prisma Next is still in development] + +Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today. + +::: + +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 [`create-prisma@next`](/next/create-prisma). 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..07f76eb742 --- /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 [`create-prisma@next`](/next/create-prisma) 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