Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prisma/prisma-next/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through the full Prisma Next workflow end to end: installing packages, writing a schema, emitting a contract, initializing the database, and running queries using both the SQL DSL and the ORM client. You need Node.js 24+, pnpm, and a running PostgreSQL database to follow along.
1

Install packages

Install the prisma-next CLI as a dev dependency and the @prisma-next/postgres facade as a runtime dependency.
npm install -D prisma-next
npm install @prisma-next/postgres
Prefer to skip manual setup? Run pnpm dlx prisma-next init instead. The init command prompts for your database target, scaffolds the config, schema, and runtime files, installs packages, and emits your first contract in one step.
2

Create prisma-next.config.ts

Create a prisma-next.config.ts file at the root of your project. This file tells the CLI where your schema lives, how to connect to the database, and which extension packs to load.
prisma-next.config.ts
import { defineConfig } from '@prisma-next/postgres/config'

export default defineConfig({
  contract: './prisma/schema.psl',
  db: { connection: process.env['DATABASE_URL']! },
})
The defineConfig export from @prisma-next/postgres/config pre-wires all Postgres internals (family, target, adapter, driver). You only need to supply your schema path and connection string.Add your database URL to a .env file:
.env
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
3

Define a schema

Create a prisma/ directory and add a schema.psl file. The schema uses PSL (Prisma Schema Language) — the same language as Prisma ORM.
prisma/schema.psl
// use prisma-next

model User {
  id        String   @id @default(uuid())
  email     String   @unique
  name      String
  createdAt DateTime @default(now())
  posts     Post[]

  @@map("user")
}

model Post {
  id        String   @id @default(uuid())
  title     String
  userId    String
  createdAt DateTime @default(now())

  user User @relation(fields: [userId], references: [id])

  @@map("post")
}
The // use prisma-next comment at the top of the file marks it as a Prisma Next schema. It is required.
4

Emit the contract

Run prisma-next contract emit to generate contract.json and contract.d.ts from your schema. These two artifacts — not executable code — are the output of the build step.
pnpm prisma-next contract emit
The output path is configured via config.contract in prisma-next.config.ts. After emission you will find two files:
  • contract.json — the runtime contract, consumed by the Postgres facade
  • contract.d.ts — TypeScript types for full autocompletion and safety
Commit both files to version control. The contractHash inside contract.json is used by the runtime to verify the database is in sync with the schema before any query runs.
5

Initialize the database

Run prisma-next db init to create the tables described by the emitted contract. This command is additive only — it creates what is missing and leaves existing tables untouched.
pnpm prisma-next db init
For subsequent schema changes, use prisma-next db update (which also handles destructive operations) or the full migration workflow with prisma-next migration plan and prisma-next migration apply.
6

Write and run your first query

Create a src/prisma/db.ts file that initializes the Postgres client with your emitted contract:
src/prisma/db.ts
import postgres from '@prisma-next/postgres/runtime'
import type { Contract } from './contract.d'
import contractJson from './contract.json' with { type: 'json' }

export const db = postgres<Contract>({ contractJson })
Now write queries using either the SQL DSL or the ORM client:
import { db } from './prisma/db'

// Build and execute a typed SQL plan
const plan = db.sql.user
  .select('id', 'email', 'name')
  .limit(10)
  .build()

const users = await db.runtime().execute(plan)
// users: Array<{ id: string; email: string; name: string }>

// Insert a row
const insert = db.sql.user
  .insert({ id: crypto.randomUUID(), email: 'alice@example.com', name: 'Alice' })
  .build()

await db.runtime().execute(insert)
Run your script with:
node --env-file=.env src/main.ts
The runtime verifies the contractHash against the database before executing any query. If the database schema has drifted from the emitted contract, you will see a structured error with a stable code and a suggested fix rather than a silent data mismatch.

​
Next steps

ORM client guide

Learn the full ORM client API: filters, includes, pagination, aggregations, and upserts.

SQL DSL guide

Master the SQL plan builder for lower-level query control and advanced use cases.

Migrations guide

Plan, apply, and verify schema migrations across environments.

CLI reference

Full reference for every prisma-next command and configuration option.

Build docs developers (and LLMs) love

Get started for freeTalk to us