Configuring Prisma Next with prisma-next.config.ts

Every prisma-next CLI command reads a prisma-next.config.ts file to understand your database family, target, adapter, contract location, and optional connection details. The config is a TypeScript module that exports a default value produced by defineConfig. There are two ways to write it: the simplified facade approach (recommended for most projects) and the full explicit approach for advanced wiring.

Approaches

Simplified (recommended)
Full explicit

The @prisma-next/postgres/config package exposes a defineConfig helper that pre-wires the SQL family, Postgres target, adapter, and driver. You only need to provide a contract path and, optionally, a database connection:

// prisma-next.config.ts
import { defineConfig } from '@prisma-next/postgres/config';

export default defineConfig({
  contract: './prisma/contract.prisma',
  db: { connection: process.env['DATABASE_URL']! },
});

This is the shortest path to a working config and is what prisma-next init scaffolds for Postgres projects.

The simplified helper is provided by @prisma-next/postgres. A MongoDB equivalent is available via @prisma-next/mongo/config. Use the facade that matches your target database.

When you need fine-grained control — for example, to wire an extension pack, use a PSL contract provider, or build a custom integration — import defineConfig from @prisma-next/cli/config-types and supply each descriptor explicitly:

// prisma-next.config.ts
import { defineConfig } from '@prisma-next/cli/config-types';
import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
import postgresAdapter from '@prisma-next/adapter-postgres/control';
import postgresDriver from '@prisma-next/driver-postgres/control';
import postgres from '@prisma-next/target-postgres/control';
import sql from '@prisma-next/family-sql/control';
import { contract } from './prisma/contract';

export default defineConfig({
  family: sql,
  target: postgres,
  adapter: postgresAdapter,
  driver: postgresDriver,
  extensionPacks: [],
  contract: typescriptContract(contract, 'src/prisma/contract.json'),
  db: {
    connection: process.env.DATABASE_URL,
  },
  migrations: {
    dir: 'migrations/',
  },
});

Required fields

The following fields must be present in any valid config (the simplified facade sets them for you):

Field	Type	Description
`family`	descriptor	The database family (for example `sql` from `@prisma-next/family-sql/control`).
`target`	descriptor	The specific database target (for example `postgres` from `@prisma-next/target-postgres/control`).
`adapter`	descriptor	The query adapter for the target (for example `postgresAdapter` from `@prisma-next/adapter-postgres/control`).
`contract`	provider	A contract provider created by `typescriptContract()` or `prismaContract()`.

Optional fields

Field	Type	Description
`driver`	descriptor	Required for any command that connects to the database (`db verify`, `db sign`, `db init`, `db update`, `db schema`, `contract infer`, `migration apply`). Not needed for `contract emit`.
`extensionPacks`	descriptor[]	Extension pack descriptors. Must include a descriptor for every extension pack referenced in the contract.
`db.connection`	string	Default database URL. Can be overridden with `--db <url>` on any command.
`migrations.dir`	string	Directory for migration packages. Defaults to `migrations/`.

Commands that require a database connection will exit with error code PN-CLI-4010 if driver is missing from the config, and PN-CLI-4005 if no connection URL is available from either db.connection or --db.

Contract providers

The contract field takes a provider value rather than a plain path. Two providers ship out of the box:

`typescriptContract` — TypeScript-authored contracts

Use when your contract is authored in TypeScript and imported as a module:

import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
import { contract } from './prisma/contract';

// Second argument is the output path for contract.json (defaults to 'src/prisma/contract.json')
contract: typescriptContract(contract, 'src/prisma/contract.json'),

`prismaContract` — PSL-authored contracts

Use when your contract is authored in Prisma Schema Language (.prisma files):

import { prismaContract } from '@prisma-next/sql-contract-psl/provider';

contract: prismaContract('./prisma/schema.prisma', {
  output: 'src/prisma/contract.json',
}),

contract.d.ts is always co-located with contract.json and derived automatically from contract.output — you do not configure it separately.

Extension packs and wiring validation

When your contract declares extension packs, the CLI performs wiring validation before running any db command that touches the database. It checks that:

contract.targetFamily matches config.family.familyId
contract.target matches config.target.targetId
Every extension pack listed in the contract is present in config.extensionPacks (matched by descriptor id)

If validation fails, the command exits with a structured error describing the mismatch. To fix it, add the required extension pack descriptor to config.extensionPacks and re-run. Commands that enforce wiring validation: db verify, db sign, db init, db update.

A mismatch between your emitted contract and the descriptors in your config will prevent database commands from running. Always re-emit (prisma-next contract emit) after changing extension packs, then update the extensionPacks array in your config to match.

Commands that do not need a driver

prisma-next contract emit does not connect to the database, so driver and db.connection are not required:

import { defineConfig } from '@prisma-next/cli/config-types';
import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
import postgresAdapter from '@prisma-next/adapter-postgres/control';
import postgres from '@prisma-next/target-postgres/control';
import sql from '@prisma-next/family-sql/control';
import { contract } from './prisma/contract';

export default defineConfig({
  family: sql,
  target: postgres,
  adapter: postgresAdapter,
  extensionPacks: [],
  contract: typescriptContract(contract, 'src/prisma/contract.json'),
});

This is useful in CI jobs that only emit the contract artifact without connecting to a live database.

Config validation

defineConfig validates and normalizes the config at load time using Arktype schemas. Validation failures produce actionable error messages. Normalization applies default values — for example, contract.output defaults to 'src/prisma/contract.json' when not specified.

Full example: emit-only config

Install the CLI and facade

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

Write prisma-next.config.ts

import { defineConfig } from '@prisma-next/postgres/config';

export default defineConfig({
  contract: './prisma/contract.prisma',
});

Emit your contract

prisma-next contract emit

This writes src/prisma/contract.json and src/prisma/contract.d.ts.

Add a driver for database commands

Update your config to include a connection URL. The simplified facade picks up the driver automatically when db.connection is set:

import { defineConfig } from '@prisma-next/postgres/config';

export default defineConfig({
  contract: './prisma/contract.prisma',
  db: { connection: process.env['DATABASE_URL']! },
});

Now commands like prisma-next db verify and prisma-next db sign will work.

Overview

Contract Commands

Database Commands

Migration Commands

Configuring Prisma Next with prisma-next.config.ts

Approaches

Required fields

Optional fields

Contract providers

`typescriptContract` — TypeScript-authored contracts

`prismaContract` — PSL-authored contracts

Extension packs and wiring validation

Commands that do not need a driver

Config validation

Full example: emit-only config

​Approaches

​Required fields

​Optional fields

​Contract providers

​typescriptContract — TypeScript-authored contracts

​prismaContract — PSL-authored contracts

​Extension packs and wiring validation

​Commands that do not need a driver

​Config validation

​Full example: emit-only config

Approaches

Required fields

Optional fields

Contract providers

`typescriptContract` — TypeScript-authored contracts

`prismaContract` — PSL-authored contracts

Extension packs and wiring validation

Commands that do not need a driver

Config validation

Full example: emit-only config