Get started with Prisma Next

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.

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

pnpm add -D prisma-next
pnpm add @prisma-next/postgres

yarn add -D prisma-next
yarn add @prisma-next/postgres

bun add -D prisma-next
bun add @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.

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

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.

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.

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.

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)

import { db } from './prisma/db'

// Fluent model-level queries
const users = await db.orm.User
  .select('id', 'email')
  .take(10)
  .all()
// users: Array<{ id: string; email: string }>

// Include related models
const posts = await db.orm.Post
  .where((p) => p.userId.eq('some-user-id'))
  .include('user', (u) => u.select('name', 'email'))
  .orderBy((p) => p.createdAt.desc())
  .all()

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.

Get Started

Core Concepts

Guides

Extensions

Get started with Prisma Next

Next steps

ORM client guide

SQL DSL guide

Migrations guide

CLI reference

​Next steps

ORM client guide

SQL DSL guide

Migrations guide

CLI reference

Next steps