# The data contract (/docs/orm/contract-authoring/the-data-contract)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

The data contract is the one description of your data model and how it is stored. Prisma ORM types your queries, plans your migrations, and checks your database against it.

Location: ORM > Contract authoring > The data contract

Every Prisma ORM project has one description of its data: the models, their fields, and how they map to database tables. That description is the data contract, the `contract.prisma` file that replaced `schema.prisma`. For example, a blog's contract declares a `User` and a `Post`, the fields each one has, and how they relate. You author it in PSL, the Prisma Schema Language, the same language as `schema.prisma`:

```prisma title="src/prisma/contract.prisma"
// use prisma-8

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  posts Post[]
}

model Post {
  id     Int    @id @default(autoincrement())
  title  String
  userId Int
  user   User   @relation(fields: [userId], references: [id])
}
```

`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. The CLI does not need this line, but the editor extension looks for it before it checks, completes, or formats the file, so keep it. A `contract.ts` file needs no header line. See [Editor support](https://www.prisma.io/docs/orm/contract-authoring/editor-support).

`npx prisma contract emit` turns this file into two files that the CLI and your application read: `contract.json` and `contract.d.ts`. Your queries are type-checked against the contract, migrations are planned as changes to it, and `npx prisma db verify` checks a live database against it.

> [!NOTE]
> Contract vs. schema
> 
> In Prisma ORM, the **contract** is what you write in your code. The **schema** is your database's actual structure.

## Why a contract [#why-a-contract]

Your contract compiles to two plain files you can open and read: `contract.json` describes your models, how they are stored, and the [database features they need](https://www.prisma.io/docs/orm/contract-authoring/capabilities), and `contract.d.ts` holds the TypeScript types derived from it. You can read both files in a code review and hand them to tools and coding agents.

`npx prisma db migrate` records in your database which contract it applied, and the first time `db` runs a query it checks that record and logs a warning on a mismatch. To fail instead, run [`npx prisma db verify`](https://www.prisma.io/docs/cli/db-verify) in a deploy check.

## How it works [#how-it-works]

A Prisma ORM project declares one contract file in `prisma.config.ts`:

```typescript title="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: "./src/prisma/contract.prisma",
    db: {
      connection: process.env["DATABASE_URL"]!,
    },
  }),
});
```

`definePrismaConfig` holds the whole config: which contract file to use and how to reach your database. Your connection string is in `prisma.config.ts` now, and the contract has no `datasource` block. `npx prisma orm init` writes `.env.example`, and your `DATABASE_URL` goes in `.env`. `@prisma/orm-postgres/config` exports `defineConfig`, which the example renames to `ormConfig` on import. The packages are `@prisma/orm-postgres` for PostgreSQL, `@prisma/orm-sqlite` for SQLite, and `@prisma/orm-mongo` for MongoDB. The examples here use PostgreSQL.

To start a new project, run `npm create prisma@latest -- my-app`. To add Prisma ORM 8 to a project that has no Prisma ORM at all, run `npx prisma orm init`. If you already have a Prisma ORM 7 `schema.prisma`, follow the [PostgreSQL upgrade guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql) instead, and [Coming from Prisma ORM 7](https://www.prisma.io/docs/orm/coming-from-prisma-orm-7) lists what changed. Both `npm create prisma@latest` and `npx prisma orm init` write `prisma.config.ts`, the contract file, and `src/prisma/db.ts`, and install the database package.

The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](https://www.prisma.io/docs/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features, such as pgvector, a PostgreSQL extension for vector columns.

After every change to the contract, run these three commands:

  

#### bun

```bash
bunx prisma contract emit
bunx prisma migration plan
bunx prisma db migrate
```

#### pnpm

```bash
pnpm dlx prisma contract emit
pnpm dlx prisma migration plan
pnpm dlx prisma db migrate
```

#### yarn

```bash
yarn dlx prisma contract emit
yarn dlx prisma migration plan
yarn dlx prisma db migrate
```

#### npm

```bash
npx prisma contract emit
npx prisma migration plan
npx prisma db migrate
```

`npx prisma contract emit` writes `contract.json` and `contract.d.ts` beside the contract file, so `src/prisma/`. [`npx prisma migration plan`](https://www.prisma.io/docs/orm/migrations/generating-a-migration) compares your contract against the last one and writes a migration. [`npx prisma db migrate`](https://www.prisma.io/docs/orm/migrations/applying-a-migration) applies it and records the match for you. When the database already matches the contract, run [`npx prisma db sign`](https://www.prisma.io/docs/cli/db-sign), which records the match without applying anything, for example after [`npx prisma contract infer`](https://www.prisma.io/docs/cli/contract-infer), which writes a contract from an existing database.

`db` is the client you create once in `src/prisma/db.ts`, and `npx prisma orm init` writes that file for you. From a file directly inside `src/`, import it with `import { db } from "./prisma/db"` and query a model: `await db.orm.public.User.all()` returns every user row. From a deeper file, adjust the relative path. `db.orm` is the ORM client, one of the [three query APIs](https://www.prisma.io/docs/orm/reference), and `public` is the PostgreSQL schema, the namespace your tables are in, unless you configured a different one. [Reading data](https://www.prisma.io/docs/orm/fundamentals/reading-data) covers queries.

## Two authoring modes, one `contract.json` [#two-authoring-modes-one-artifact]

**[PSL](https://www.prisma.io/docs/orm/contract-authoring/psl-syntax)**, a compact language for describing data, is the usual way to write the contract: it is what `npm create prisma@latest` scaffolds, and what [`npx prisma contract infer`](https://www.prisma.io/docs/cli/contract-infer) writes when you start from an existing database.

Define models with the **[TypeScript builder](https://www.prisma.io/docs/orm/contract-authoring/typescript-schema-builder)** instead when you want to build them with code: reach for it when model definitions must be composed, generated, or shared as ordinary TypeScript modules. That page shows what a `contract.ts` file looks like.

Both modes produce the same contract, so migrations, database checks, and `db` behave the same no matter which mode you write. A project has exactly one contract file, so do not keep both a `contract.prisma` and a `contract.ts`: the config names one file and Prisma ORM reads only that one, so edits to the other file do nothing. To switch modes, change the path in `contract` and delete the old file.

## What the contract contains [#what-the-contract-contains]

The contract describes structure, not data:

* models, fields, and relations, plus how they map to tables and columns
* how the data is stored: primary keys, unique constraints, indexes, and foreign keys
* [named types](https://www.prisma.io/docs/orm/contract-authoring/psl-syntax#named-types), which are reusable aliases for a database column type, and enums
* [`type` blocks](https://www.prisma.io/docs/orm/contract-authoring/psl-syntax#value-objects), also called value objects, each a reusable group of fields such as an address, stored inside its parent row with no table of its own
* the types and database features that extension packages add, such as pgvector's `Vector` type

It contains no rows, no credentials, and no connection details, so committing the source, `contract.json`, and `contract.d.ts` to version control is safe and expected.

## Prompt your coding agent [#prompt-your-coding-agent]

Projects created with `npm create prisma@latest` include the [Prisma ORM skills](https://www.prisma.io/docs/ai/tools/skills#available-skills-for-prisma-8) for your coding agent. In an existing project, run `npx prisma skills sync` to add them. The `prisma-8` skill covers the contract, so ask your agent to:

* "Using the prisma-8 skill, explain what our contract.json currently declares."
* "Add an Invoice model to the contract and run prisma contract emit."
* "Check whether our database still satisfies the contract."

## Next steps [#next-steps]

* [Model your data](https://www.prisma.io/docs/orm/data-modeling) before writing the contract: models, keys, and relations.

- [Author in PSL](https://www.prisma.io/docs/orm/contract-authoring/psl-syntax): Write the contract as a PSL file.

- [Author in TypeScript](https://www.prisma.io/docs/orm/contract-authoring/typescript-schema-builder): Define the same models with the TypeScript builder.

- [contract.json and contract.d.ts](https://www.prisma.io/docs/orm/contract-authoring/the-contract-artifact): What is inside contract.json and contract.d.ts, and how the hashes work.

- [Supported database features](https://www.prisma.io/docs/orm/contract-authoring/capabilities): How Prisma ORM checks that your database supports what the contract needs.

## Related pages

- [`Author in PSL`](https://www.prisma.io/docs/orm/contract-authoring/psl-syntax): Write the Prisma ORM contract in the Prisma schema language you already know, plus the Prisma ORM 8 additions.
- [`Author in TypeScript`](https://www.prisma.io/docs/orm/contract-authoring/typescript-schema-builder): Define the Prisma ORM contract with a typed builder in TypeScript instead of a schema file. Same models, same `contract.json` and `contract.d.ts`, no separate language.
- [`contract.json and contract.d.ts`](https://www.prisma.io/docs/orm/contract-authoring/the-contract-artifact): contract.json and contract.d.ts are the two files every other part of Prisma ORM reads. Here is what is inside them.
- [`Editor support`](https://www.prisma.io/docs/orm/contract-authoring/editor-support): What the Prisma VS Code extension does for a Prisma ORM contract, and what to do when it stops accepting the file.
- [`Supported database features`](https://www.prisma.io/docs/orm/contract-authoring/capabilities): The contract records which database features your packages support, so Prisma ORM can reject an unsupported one early with a clear error.