CLIIntroduction

Configuration

Configure Prisma ORM CLI commands with prisma.config.ts and global flags.

Prisma ORM CLI commands read prisma.config.ts, starting in the directory you run them from. The file has one section per part of the CLI. The orm section holds your schema, database, and migration settings, which the contract, db, and migration commands read. The skills section holds the settings for the agent skills commands, which copy Prisma's instructions for AI coding agents into your project. The composer section holds Prisma Composer's deploy config, the entry module, the extensions and the deploy-state store that deploy and dev read; Composer getting started shows how to write it.

Config file

The outer definePrismaConfig comes from prisma/config and marks the file as a Prisma ORM 8 CLI config. A Prisma ORM 7 prisma.config.ts without that marker is rejected rather than misread. The import resolves from your project's node_modules, so prisma must be a local dependency. The orm section uses the config helper for your database. For PostgreSQL:

prisma.config.ts
import "dotenv/config";
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  orm: ormConfig({
    contract: "./prisma/contract.prisma",
    db: {
      connection: process.env["DATABASE_URL"]!,
    },
  }),
});

For MongoDB projects, import the section helper from @prisma/orm-mongo/config instead. Both packages export this helper as defineConfig, and the examples on this page rename it to ormConfig when they import it.

This paragraph is only for a config written for a Prisma ORM 8 release candidate before 8.0.0-rc.12. Such a config may import defineConfig from @prisma/cli-engine. That import no longer exists, so the config fails to load. Replace it with definePrismaConfig from prisma/config, and rename the call to match: it is the same function under its new name. Leave the defineConfig import from @prisma/orm-postgres/config or @prisma/orm-mongo/config as it is. That one is the helper for the orm section, and its name has not changed.

orm init writes this file for you. Without --config, the CLI looks for prisma.config.ts in the directory you run the command from and in the directories above it, as How the CLI finds the config explains. Pass --config to use a config file in another place, such as a subdirectory:

npx prisma contract emit --config ./config/prisma.config.ts

How the CLI finds the config

The CLI starts with prisma.config.ts in the current directory, or with the file you pass to --config. It then also reads the prisma.config.ts in each parent directory that has one, up to the root of the repository, which is the first directory that has a .git entry. If neither the starting directory nor any directory above it has a .git entry, the CLI reads only the file it started with.

The CLI combines the files it finds one section at a time. Inside a section such as orm, it takes each top-level key, such as contract, db, or migrations, from the nearest file that sets it, and it takes the whole value of that key from that one file. So if a config higher up sets db.connection and your project's config sets only contract, the CLI uses your contract and the other file's db.

The composer section is not combined this way. The CLI takes it whole from the nearest file that declares a composer section and ignores the composer sections of files higher up.

Extensions are the exception: if your project config has its own orm section, it never inherits extensions from a config higher up, even when it lists none. List the extensions your contract uses, as Extension packs shows, in each project's own config.

More than one project in a repository

If a prisma.config.ts higher up sets db or migrations, a project config that leaves them out uses that file's database and migrations folder. db update, db migrate and db verify then connect to the other project's database, and migration plan writes into the other project's migrations folder, without a warning. Set db and migrations, such as migrations: { dir: "./migrations" }, in every project's own config, or add parent: false to it.

To stop a project's config from inheriting anything, add parent: false to it. The search then ends at that file:

prisma.config.ts
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  parent: false,
  orm: ormConfig({
    contract: "./prisma/contract.prisma",
  }),
});

parent can also be a path to another config file, which the CLI reads next in place of the one in the parent directory. The path is relative to the directory of the config file that sets it, and it may point outside the repository. After reading that file, the CLI goes on to search the directories above that file in the usual way, unless that file sets parent too:

prisma.config.ts
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  parent: "../shared/prisma.config.ts",
  orm: ormConfig({
    contract: "./prisma/contract.prisma",
  }),
});

A relative path in a config file, such as contract, output, or migrations.dir, resolves from the directory of the config file that sets it, not from the directory you run the command in. So --config ./config/prisma.config.ts with contract: "./prisma/contract.prisma" reads ./config/prisma/contract.prisma.

Split the schema across several files

contract accepts a glob, a path pattern where * matches any file name and ** matches any number of folders, so one schema can span several .prisma files:

prisma.config.ts
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  orm: ormConfig({
    contract: "./prisma/**/*.prisma",
  }),
});

contract emit builds one contract from every matched file whose first line is // use prisma-8. The same rule applies when contract names a single file: that file must start with the line too. contract emit skips a matched file without that line and does not warn, so the line is what makes a file part of the schema. The Prisma editor extension uses the same rule, so the editor and contract emit agree on which files make up the schema.

If the glob matches files but none of them starts with the line, contract emit fails with CONTRACT.SOURCE_LOAD_FAILED, and the error's details name the problem PSL_NO_OPTED_IN_SCHEMA_FILES. If the glob matches no file at all, for example because of a typo in the pattern, they name it PSL_NO_SCHEMA_FILES_MATCHED instead. What contract emit creates says where these details appear in the output.

A new file joins the schema the next time you run contract emit, with no change to the config. The emitted files go in the folder before the first wildcard, here ./prisma/contract.json and ./prisma/contract.d.ts.

Use a Prisma ORM 7 schema

On PostgreSQL, Prisma ORM 8 can read a Prisma ORM 7 schema.prisma directly as its contract source, so the two versions can run side by side on the database that Prisma ORM 7 migrates. Wrap the path in prisma7Schema:

prisma.config.ts
import "dotenv/config";
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig, prisma7Schema } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  orm: ormConfig({
    contract: prisma7Schema("prisma/schema.prisma"),
    db: {
      connection: process.env["DATABASE_URL"]!,
    },
  }),
});

prisma7Schema takes one schema file, or a directory of .prisma files as Prisma ORM 7 reads it. prisma7Schema reads every .prisma file it is given, so these files do not need the // use prisma-8 first line. contract emit writes contract.json and contract.d.ts into the directory that holds the schema, here prisma/, unless you set output. Prisma ORM 7 keeps owning the database and its migrations, and you run its commands as prisma7, the Prisma ORM 7 CLI that orm init --from-prisma7-schema installs next to Prisma ORM 8. orm init --from-prisma7-schema also writes this config for you.

With prisma7Schema, each date and time field keeps its column and reads as the type below:

Prisma ORM 7 fieldPrisma ORM 8 typeYour code reads
DateTimeTimestampJsDate(3), printed DateTime(storage: timestamp)a JavaScript Date, the stored value read as UTC, as Prisma ORM 7 did
@db.Timestamptz(p)TimestamptzJsDate(p), printed DateTime(precision: p)a JavaScript Date
@db.Timestamp(p)TimestampJsDate(p)a JavaScript Date, the stored value read as UTC
@db.DateDateStringan ISO 8601 string, such as "2026-09-14"
@db.Time(p)TimeString(p)an ISO 8601 string, such as "10:00:00.5"
@db.Timetz(p)Timetz(p)an ISO 8601 string with a full offset, such as "10:00:00+02:00"

A Date holds milliseconds, so a @db.Timestamptz(6) or @db.Timestamp(6) column with values that use the extra digits reads with them dropped. A Date cannot hold infinity or -infinity either, so a row that stores one fails to read with RUNTIME.DECODE_FAILED.

To read other types, such as strings that keep every digit or Temporal objects, write a Prisma ORM 8 contract with npx prisma contract print --output prisma/contract.prisma. In that file, add as: string or as: temporal to a DateTime(...) field, as in DateTime(as: string, storage: timestamp), and write Date(as: temporal) or Time(as: temporal) for a date or a time. Temporal is the newer JavaScript date and time API. Runtimes without it, such as Node.js 24, need the temporal-polyfill package and import "temporal-polyfill/full/global" at the top of the file that creates your client, before it reads a Temporal field. A column that can hold infinity needs as: string. Then change contract in prisma.config.ts from prisma7Schema("prisma/schema.prisma") to "./prisma/contract.prisma", so that contract emit reads the edited file.

When your code creates or updates a row, Prisma ORM fills each @updatedAt field with the time from your application's clock, as a Date or as text in the form its type reads, rounded down to the column's precision. This also works on a @db.Date, @db.Time, or @db.Timetz field. A field can have both @updatedAt and @default(now()), and @default(now()) stays the column's default in the database. When your code creates a row without a value for a @default(now()) field, Prisma ORM fills it with the current UTC time, as the Prisma ORM 7 client did, so it reads @default(now()) as @default(now()) @onCreate(now()). An INSERT from outside Prisma ORM still gets the column default.

A list such as String[] reads as a list whose elements may be null, because the database that Prisma ORM 7 built does not stop a list from holding null elements.

A @db.Citext field reads as citext.Citext, from the citext pack in @prisma/orm-postgres-contrib. Add the pack to the config with import citext from "@prisma/orm-postgres-contrib/citext/control" and extensions: [citext]; without it, contract emit refuses the field with PSL.PRISMA7_EXTENSION_PACK_MISSING, which names the import to add. The datasource's extensions list, such as extensions = [vector, pg_trgm], is read too: an extension a configured pack provides, such as pgvector's vector, comes from the pack, and any other is declared in the contract, so db sign checks that the database has it.

Once the config is in place, run npx prisma contract emit and then npx prisma db sign. db sign checks that the database matches the contract and then records that in the database, without changing your tables. Run both commands again after each Prisma ORM 7 migration, whether you ran npx prisma7 migrate dev or npx prisma7 migrate deploy, so that the record names the new contract.

An Unsupported("ltree") field becomes a column of that database type with no field on the model, as in the Prisma ORM 7 client: migrations and db verify keep the column, and your code cannot read or write it. contract print cannot write such a column yet, so a schema with Unsupported(...) fields stays your contract source.

contract emit fails on any part of the schema that Prisma ORM 8 cannot represent exactly, such as a view block or relationMode = "prisma". The error names the file and the line and suggests an edit to the Prisma ORM 7 schema. When that edit would also change the database on the next Prisma ORM 7 migration, the error says so.

Prisma ORM 8 has no views, so for a view block the error suggests removing the view or replacing it with a model over the table the view reads.

contract emit also fails when a default function gets an argument it does not take, such as uuid(5) or cuid(1). The error code is PSL.PRISMA7_UNKNOWN_DEFAULT, and the message names the values the function takes, for example uuid: version must be 4 or 7, got 5.

The contract also keeps the columns and tables of @ignore fields and @@ignore models, as storage that no model maps, so adding or removing @ignore plans no migration. The ORM still leaves those fields and models out of its queries, and contract print cannot write them. Because they are in the contract, they have to meet the same rules as the rest of the schema: every @db.* type Prisma ORM 7 accepts on PostgreSQL is read, and @db.Citext needs the citext pack even on an ignored model.

The contract keeps the constraint names Prisma ORM 7 gave the database. Where Prisma ORM 7's name for a primary key or foreign key differs from the name Prisma ORM 8 would derive, the contract states it: a map on @id, @@id, or @relation, the primary key of an implicit many-to-many table such as _PostToTag_AB_pkey, and a name Prisma ORM 7 cut to 63 bytes. A later migration that touches one of these constraints then targets the name the database has. A map longer than PostgreSQL keeps is refused, as Prisma ORM 7 refuses it.

After Prisma ORM 8 takes over the migrations, you can give an existing integer column @default(autoincrement()). migration plan and db update create or reuse a sequence for it and start the sequence past the column's current maximum, so rows already in the table do not collide with new ones.

Use a Prisma ORM 6 MongoDB schema

On MongoDB, Prisma ORM 8 can read a Prisma ORM 6 schema.prisma directly as its contract source. Wrap the path in prisma6Schema:

prisma.config.ts
import "dotenv/config";
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig, prisma6Schema } from "@prisma/orm-mongo/config";

export default definePrismaConfig({
  orm: ormConfig({
    contract: prisma6Schema("prisma/schema.prisma"),
    db: {
      connection: process.env["DATABASE_URL"]!,
    },
  }),
});

The schema file does not need the // use prisma-8 first line. Run npx prisma contract emit and then npx prisma db sign, which checks that the database Prisma ORM 6 built matches the contract.

prisma6Schema reads each field as the BSON type Prisma ORM 6 stores. A plain Int and an Int @db.Long are a number in your code, written as a BSON long, and a stored value with a fraction fails to read with RUNTIME.DECODE_FAILED. A Bytes @db.ObjectId field reads as a 24-digit hex string and takes a hex string or an ObjectId, not a Buffer. Every native type Prisma ORM 6 accepts on MongoDB is read, except DateTime @db.Timestamp.

Each index keeps the name Prisma ORM 6 gave it: the name its map: sets (or name: on @@index), or else the name Prisma ORM 6 derives, such as User_email_key for a unique index on email and User_email_idx for a plain one. db verify checks these names against the database. If it reports an index whose name differs, write the name the database holds with map:.

The indexes are kept as Prisma ORM 6 wrote them, and none are merged. Two indexes of one model with the same fields and the same sort, such as @unique and @@unique on one field, are refused with PSL.PRISMA6_MONGO_INDEX_ALREADY_EXISTS, as Prisma ORM 6 refuses them. Remove one of them, and when only one is unique, keep that one. A unique and a plain index on the same field that Prisma ORM 6 accepts, such as @unique beside @@index([email(sort: Asc)]), are both kept. Two indexes of one model with one name are refused with PSL.PRISMA6_MONGO_INDEX_NAME_DUPLICATE, and an empty map: or one longer than 127 bytes with PSL.PRISMA6_MONGO_INDEX_NAME_INVALID.

After you upgrade from a release before 8.0.0-rc.23, a contract emitted from a schema with indexes gets a new storage hash. Run npx prisma contract emit, then npx prisma db verify and npx prisma db sign against each database. The database does not change; db sign only updates the storage hash it records.

contract emit fails on any part of the schema that Prisma ORM 8 cannot represent exactly, with an error code that starts with PSL.PRISMA6_MONGO_. The error reference lists each code and what to change.

Write your own contract source

A config that builds contract.source itself, as an object with a load function, must give the object a format: "psl" when its inputs are PSL text, and "typescript" when it builds the contract in TypeScript. Without it, every command that reads the config fails with CONFIG.VALIDATION_FAILED. A path, a glob, prisma7Schema and prisma6Schema set the format for you.

Emit-only config

contract emit does not connect to a database, so the orm section can omit db.connection:

prisma.config.ts
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  orm: ormConfig({
    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 db migrate.

Extension packs

Add extension control descriptors to the orm section when your contract uses extension-provided types:

prisma.config.ts
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";
import pgvector from "@prisma/orm-extension-pgvector/control";

export default definePrismaConfig({
  orm: ormConfig({
    contract: "./prisma/contract.prisma",
    extensions: [pgvector],
    db: {
      connection: process.env["DATABASE_URL"]!,
    },
  }),
});

Re-run contract emit after changing extension packs, then update the matching runtime client.

Schema formatting

contract format rewrites your .prisma files so that every file has the same indentation and line endings. It replaces prisma format from Prisma ORM 7:

npx prisma contract format

It formats every .prisma file that the contract setting matches, including a file that contract emit skips because it lacks the // use prisma-8 first line. It always writes the files, because it has no mode that only checks them. If your contract is built in TypeScript and not in .prisma files, the command does nothing.

To make CI fail on an unformatted file, format there and let Git report any change:

npx prisma contract format && git diff --exit-code

When that check fails, run npx prisma contract format on your machine and commit the result.

By default the command indents with two spaces. To change the indentation or the line endings, add formatter to the orm section. Both fields are optional:

prisma.config.ts
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  orm: ormConfig({
    contract: "./prisma/contract.prisma",
    formatter: {
      indent: 4,
      newline: "LF",
    },
  }),
});
FieldWhat it does
indentThe number of spaces for each level of indentation, as a whole number of 1 or more, or "tab" for one tab for each level. Default: 2.
newlineThe line ending to write: "LF", which macOS and Linux use, or "CRLF", which Windows uses. Without it, the command writes the line ending of the operating system it runs on.

Set newline when anyone works on the project from Windows; "LF" is the usual choice. Without it, on Windows contract format writes CRLF but the Prisma editor extension writes LF. Each one rewrites every line the other wrote, so Git shows the whole file as changed. The editor extension reads formatter from prisma.config.ts too, so once newline is set, the command and the editor write the same line endings on every machine.

formatter needs @prisma/orm-postgres or @prisma/orm-mongo at 8.0.0-rc.24 or later. An earlier release ignores the setting without an error, and contract format still indents with two spaces. npm ls @prisma/orm-postgres, or the same command with @prisma/orm-mongo, prints the release you have.

If indent or newline has a value the table does not allow, every command that reads the config fails with CLI.CONFIG_FIELD_INVALID. The message names the field, as in formatter.indent must be at least 1 (was 0).

Agent skills

The skills section controls the agent skills commands and the staleness check:

prisma.config.ts
import { definePrismaConfig } from "prisma/config";

export default definePrismaConfig({
  skills: {
    agents: ["claude", "cursor"],
    check: true,
  },
});
FieldWhat it does
agentsThe agent harnesses skills sync writes and skills list reports: claude, cursor, agents, devin. An empty array records that no agent skills are wanted, and the next skills sync removes the copies already on disk. Default: all of them.
checkSet false to stop commands reporting out-of-date skills, for everyone working in the project. Default: true.

init scaffolds this section for you.

Database URLs

Database commands accept --db <url>, and without it they use the database connection from prisma.config.ts.

npx prisma db verify --db "$DATABASE_URL"

Environment variables

The variables the CLI reads, such as PRISMA_DISABLE_TELEMETRY, PRISMA_SKILLS_CHECK, and the PRISMA_SERVICE_TOKEN pair for CI, are listed on Environment variables. DATABASE_URL is not one of them: your config file reads it, as in the example above.

Output modes

Use the default text output when running commands locally. Use --json in CI or automation:

npx prisma db verify --db "$DATABASE_URL" --json

Piping a command does not switch it to JSON: without --json, standard output gets the command's plain data, such as one line per item of a list. See Global flags.

For an AI agent that reads the output as text rather than parsing JSON, use --format markdown; see Global flags.

Use --no-interactive for scripts that must never pause for user input. Use --confirm <token> to grant a consent prompt non-interactively. Commands that ask about data loss, such as db update, take their answers as flags instead: --delete, --rename, and --allow.

JSON output

In --json mode, commands emit newline-delimited JSON events. Progress events have kind: "step-finished". The final event has kind: "result" and carries the envelope object your script branches on:

  • envelope.ok: true or false.
  • envelope.result: the command's data, when ok is true.
  • envelope.error.code: a dotted NAMESPACE.SUBCODE, for example PROJECT.NOT_FOUND or SERVICE.PROJECT_SETUP_REQUIRED.
  • envelope.error.summary and envelope.error.why: what failed and why it was rejected.
  • envelope.nextActions: machine-readable follow-up commands, so agents can drive the CLI.

Branch on envelope.error.code, not the message text: codes are a stable contract, while message wording can change between releases.