feat: add Prisma Next

.gitignore

@@ -40,3 +40,4 @@ next-env.d.ts
 # opensrc - source code for packages
 opensrc
 .env
+prisma-next/

apps/docs/content/docs/(index)/meta.json

@@ -5,6 +5,7 @@
     "---Getting Started---",
     "index",
     "getting-started",
+    "next",
     "---Prisma ORM---",
     "...prisma-orm",
     "---Prisma Postgres---",

apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Add to Existing Project",
+  "pages": ["postgresql", "mongodb"]
+}

apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx

@@ -0,0 +1,186 @@
+---
+title: MongoDB
+description: Add Prisma Next to an existing MongoDB project.
+url: /next/add-to-existing-project/mongodb
+metaTitle: Add Prisma Next to an existing MongoDB project
+metaDescription: Add Prisma Next to an existing MongoDB project.
+---
+
+This guide shows how to add Prisma Next to a project that already uses MongoDB. You will 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]
+
+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
+
+If your project already runs TypeScript scripts, you can skip this step.
+
+Otherwise, install the script tooling:
+
+```npm
+npm install --save-dev tsx typescript
+```
+
+Later, `prisma-next init` will also add the Node.js types it needs and make sure the generated Prisma Next files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma Next leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app.
+
+## 2. Initialize Prisma Next
+
+From the root of your existing project, run:
+
+```npm
+npx prisma-next init --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
+
+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"
+// use prisma-next
+
+model User {
+  id    ObjectId @id @map("_id")
+  email String   @unique
+  name  String?
+  posts Post[]
+  @@map("users")
+}
+
+model Post {
+  id       ObjectId @id @map("_id")
+  title    String
+  content  String?
+  author   User     @relation(fields: [authorId], references: [id])
+  authorId ObjectId
+  @@map("posts")
+}
+```
+
+You do not need to model every collection on day one. Start with the part of the database you want to read and write first.
+
+## 5. Emit the generated artifacts
+
+Once the contract looks right, this step turns it into the generated files the runtime and query APIs use.
+
+Run:
+
+```npm
+npx prisma-next contract emit
+```
+
+This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed.
+
+## 6. Run a simple high-level query
+
+With the emitted artifacts in place, you can test the higher-level API first and confirm Prisma Next can read the existing collections.
+
+Create a `script.ts` file:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const user = await db.orm.users.where({ email: "existing@example.com" }).first();
+  console.log(user);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it:
+
+```npm
+npx tsx script.ts
+```
+
+## 7. Run a simple low-level query
+
+After the ORM example, this step shows the lower-level MongoDB pipeline builder against the same existing collections.
+
+Replace `script.ts` with this version:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const runtime = await db.runtime();
+  const plan = db.query
+    .from("users")
+    .match((fields) => fields.email.eq("existing@example.com"))
+    .project("email", "name")
+    .build();
+
+  const rows = await runtime.execute(plan);
+  console.log(rows);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it again:
+
+```npm
+npx tsx script.ts
+```
+
+## 8. Commands you will use next
+
+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.

apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx

@@ -0,0 +1,190 @@
+---
+title: Postgres
+description: Add Prisma Next to an existing PostgreSQL project.
+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.
+---
+
+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]
+
+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
+
+If your project already runs TypeScript scripts, you can skip this step.
+
+Otherwise, install the script tooling:
+
+```npm
+npm install --save-dev tsx typescript
+```
+
+Later, `prisma-next init` will also add the Node.js types it needs and make sure the generated Prisma Next files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma Next leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app.
+
+## 2. Initialize Prisma Next
+
+From the root of your existing project, run:
+
+```npm
+npx prisma-next init --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
+
+Update `.env` with the connection string for the database your app already uses:
+
+```text title=".env"
+DATABASE_URL="postgres://username:password@host:5432/database?sslmode=require"
+```
+
+## 4. Infer a starter contract from the live database
+
+This step gives you a starting contract by reading the schema that already exists in PostgreSQL.
+
+Run:
+
+```npm
+npx prisma-next contract infer --output ./prisma/contract.prisma
+```
+
+This reads the live PostgreSQL schema and writes a first draft of `prisma/contract.prisma`.
+
+Open that file and review it before you go on. This is the moment to clean up model names, keep only the tables you want Prisma Next to know about first, and make the file easier to read.
+
+## 5. Emit the generated artifacts
+
+Once the contract looks right, this step turns it into the generated files the runtime and CLI use.
+
+After you are happy with the contract, run:
+
+```npm
+npx prisma-next contract emit
+```
+
+This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed.
+
+## 6. Sign the database
+
+Record that the live database matches the emitted contract:
+
+```npm
+npx prisma-next db sign
+```
+
+This step matters in two common cases:
+
+- the database has never been signed by Prisma Next before
+- the database was signed earlier, but under an older contract hash
+
+## 7. Run a simple high-level query
+
+With the database signed, you can test the higher-level API first and confirm Prisma Next is reading the existing schema correctly.
+
+Create a `script.ts` file:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const runtime = await db.connect({ url: process.env.DATABASE_URL! });
+
+  const users = await db.orm.User
+    .select("id", "email", "name")
+    .take(2)
+    .all();
+
+  console.log(users);
+
+  await runtime.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it:
+
+```npm
+npx tsx script.ts
+```
+
+## 8. Run a simple low-level query
+
+After the ORM example, this step shows the lower-level SQL builder against the same existing schema.
+
+Replace `script.ts` with this version:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const runtime = await db.connect({ url: process.env.DATABASE_URL! });
+
+  const plan = db.sql.user
+    .select("id", "email", "name")
+    .limit(2)
+    .build();
+
+  const rows = await db.runtime().execute(plan);
+  console.log(rows);
+
+  await runtime.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it again:
+
+```npm
+npx tsx script.ts
+```
+
+## 9. Commands you will use next
+
+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.