# Core concepts (/docs/orm/core-concepts)

> 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.

How Prisma ORM 8 fits together, in the order you meet each piece: the contract, the files contract emit writes, the database signature, queries, and migrations.

Location: ORM > Core concepts

Your application and your database each have an opinion about what the data looks like. In Prisma ORM 7, the generated client trusted that the database matched your schema file, and nothing recorded whether it did.

Your models live in a file called the contract. Prisma ORM 8 stores a record in the database that says which exact contract the database matches. Its CLI checks that record before it changes the database, and you can check it in your deploy pipeline too.

A PostgreSQL project installs two packages: `prisma`, the command-line tool, and `@prisma/orm-postgres`, the library your app imports, which includes the database driver. [`npx prisma@latest orm init`](https://www.prisma.io/docs/cli/orm-init) sets up Prisma ORM in a project, while [`npx prisma@latest init`](https://www.prisma.io/docs/cli/init) installs the agent skills and does not set up the ORM.

This page introduces each piece in the order you meet it, says what it gives you, and ends with a table of the CLI commands and a short glossary.

## The contract and the schema [#the-contract-and-the-schema]

The contract is the file you write: your models, their fields, how they relate, and which tables or collections they map to. It replaces `schema.prisma`. Write it in one of two files: `contract.prisma`, in PSL, the Prisma schema language, or `contract.ts`, in TypeScript. Keep it in your repository:

```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
  published Boolean @default(false)
  userId    Int

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

The first line, `// use prisma-8`, is required: Prisma ORM 8 ignores a `.prisma` file that does not start with it. [`prisma orm init`](https://www.prisma.io/docs/cli/orm-init) writes it for you.

The schema is what the database has right now: its tables or collections, their columns, and their indexes. Prisma ORM 7 called your file the schema, but Prisma ORM 8 keeps that word for the database side, because the whole point is that your file and your database can disagree. So when a command or an error message says "schema", it means the database.

Everything else on this page is a relationship between the two. Queries are typed against the contract, migrations change the schema until it matches the contract, and `db verify` checks that the schema still matches the contract.

Read more in [The data contract](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract), and write your contract [in PSL](https://www.prisma.io/docs/orm/contract-authoring/psl-syntax) or [in TypeScript](https://www.prisma.io/docs/orm/contract-authoring/typescript-schema-builder).

## Emit: build the contract into two files [#emit-build-the-contract-into-two-files]

`prisma contract emit` replaces `prisma generate`, but where Prisma ORM 7 generated a client package from your schema, Prisma ORM 8 reads your contract and writes two plain files next to it:

  

#### bun

```bash
bunx prisma contract emit
```

#### pnpm

```bash
pnpm prisma contract emit
```

#### yarn

```bash
yarn prisma contract emit
```

#### npm

```bash
npx prisma contract emit
```

* `contract.json` describes your models, how they are stored, and which database features they need. Your app reads it when it runs, so it ships with your app, as the [Docker guide](https://www.prisma.io/docs/guides/deployment/docker) shows.
* `contract.d.ts` holds the TypeScript types built from it, which is what makes your queries type-safe.

Every other command reads these two files, never your contract source. The query APIs read `contract.d.ts`, `migration plan` compares your emitted contract with the one your database was last known to match, and `db verify` compares `contract.json` with the database. So after every change to your contract, run `contract emit` before anything else. If you forget, you see it in two places: your editor still shows the types of the old contract, and `migration plan` prints `No changes detected` or writes a migration that is missing your latest change.

The same contract always produces the same two files, byte for byte, so you commit both and they diff cleanly in code review. Think of the pair like `package.json` and `package-lock.json`: the contract source is what you asked for, and the two files are the exact result.

See [contract.json and contract.d.ts](https://www.prisma.io/docs/orm/contract-authoring/the-contract-artifact) for what is inside each file.

## The signature: which contract the database matches [#the-signature-which-contract-the-database-matches]

Because `contract emit` always writes the same bytes for the same contract, a hash of `contract.json` identifies one exact contract, the way a Git commit hash identifies one exact state of your code. You see these contract hashes throughout the CLI output.

The signature is a small record in the database itself that names the contract hash the database currently matches. On PostgreSQL it is a row in the `prisma_contract.marker` table. [Database-specific details](https://www.prisma.io/docs/orm/migrations/the-migration-graph#database-specific-details) says where MongoDB keeps it. Error codes such as `MIGRATION.MARKER_MISMATCH` call it the marker.

You never write the signature by hand, because the commands that change or check the database write it for you:

* [`db init`](https://www.prisma.io/docs/cli/db-init) creates what the contract needs and the database does not have yet, then signs the database. It only adds, so it leaves in place the tables it finds already there. If the contract would need a destructive change to one of them, the run stops.
* [`db sign`](https://www.prisma.io/docs/cli/db-sign) checks that an existing database already matches the emitted contract and, if it does, signs it without changing any table. If the database does not match, it writes nothing and exits with code `4`.
* [`db migrate`](https://www.prisma.io/docs/cli/db-migrate) applies migrations and updates the signature to the contract hash the database now matches.
* [`db update`](https://www.prisma.io/docs/cli/db-update) changes the database to match the contract directly and signs it.

[`db verify`](https://www.prisma.io/docs/cli/db-verify) reads the signature and the database's tables and reports drift, which is any disagreement between the contract and the database. It changes nothing.

The signature stops a migration from running against a database it was not written for. `db migrate` reads the signature first, and when the contract hash it names appears nowhere in your migration history, it stops with `MIGRATION.MARKER_MISMATCH` before it changes anything.

In a deploy pipeline, apply the migrations first and then check the result:

  

#### bun

```bash
bunx prisma db migrate --db "$DATABASE_URL"
bunx prisma db verify --db "$DATABASE_URL"
```

#### pnpm

```bash
pnpm prisma db migrate --db "$DATABASE_URL"
pnpm prisma db verify --db "$DATABASE_URL"
```

#### yarn

```bash
yarn prisma db migrate --db "$DATABASE_URL"
yarn prisma db verify --db "$DATABASE_URL"
```

#### npm

```bash
npx prisma db migrate --db "$DATABASE_URL"
npx prisma db verify --db "$DATABASE_URL"
```

`db verify` fails the step, with exit code `4`, only when the database still does not match the emitted contract after migrating. That catches a contract change nobody planned a migration for, and tables someone changed by hand. Your app checks the signature on its first query too, but it only logs a warning, and it cannot be set to fail.

> [!NOTE]
> Adopting an existing database
> 
> If Prisma ORM 7 still runs migrations on the database, follow [Transfer migration ownership](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) in the upgrade guide, which runs `db sign` at the right point. For any other database you did not create with Prisma ORM 8, emit your contract and run `db sign` before any other `db` or `migration` command, as [Adopting an existing database](#adopting-an-existing-database) explains.

## Queries: every query is built before it runs [#queries-every-query-is-built-before-it-runs]

All the query APIs are typed against `contract.d.ts`. Each query you write is built into a plan, a plain data object that holds the statement, its parameters, and a description of what the query reads or writes. Running the plan is a separate step, and with the SQL query builder you can see both steps in your code:

```typescript
import { db } from "./src/prisma/db";

const plan = db.sql.public.Post
  .select("id", "title", "userId")
  .where((f, fns) => fns.eq(f.published, true))
  .limit(10)
  .build();

const publishedPosts = await db.runtime().query(plan);
```

`db` is the client, which `src/prisma/db.ts` creates from `contract.json`. [`prisma orm init`](https://www.prisma.io/docs/cli/orm-init) writes that file for you.

Every query reaches the database as a plan, however you wrote it. Because a plan is data, you can inspect it before anything touches the database, and a failed query can report exactly what it ran.

On PostgreSQL you write a query in one of the following ways, starting with the one that does the most for you:

1. The ORM client replaces `prisma.user.findMany(...)` and the other model calls. It works with models, `.include()` loads related records, and a call such as `.first()` or `.all()` runs the query: `await db.orm.public.User.where({ email: "alice@prisma.io" }).first()`. Start here, with [Reading data](https://www.prisma.io/docs/orm/fundamentals/reading-data).
2. [The SQL query builder](https://www.prisma.io/docs/orm/fundamentals/advanced-queries), `db.sql.public.Post`, is for the joins, grouping, and projections the ORM client cannot express.
3. [Raw SQL](https://www.prisma.io/docs/orm/reference/raw-queries) replaces `$queryRaw` for a statement the builder cannot express. Write the whole statement with `db.raw.sql`. If it returns rows, end it with `.returnsRow(spec)`, where `spec` gives the columns and their types, and the rows come back converted to JavaScript values. You can also put a `fns.raw` fragment, a piece of raw SQL, inside a builder query, but its values are not converted, so you handle them yourself.

MongoDB has the same levels below the ORM client: a builder and a raw form. [The pipeline builder](https://www.prisma.io/docs/orm/reference/pipeline-builder), `db.query`, builds typed aggregation pipelines. [Raw commands](https://www.prisma.io/docs/orm/reference/raw-queries#mongodb-raw-commands) are sent to the driver as you write them, and the values they return are not converted.

You write `db.orm.public.User` and not `prisma.user` because PostgreSQL groups tables into named schemas, and `public` is the default one. A contract can put models in another one with a `namespace` block:

```prisma
namespace billing {
  model Invoice { id Int @id }
}
```

In queries, that model is `db.orm.billing.Invoice`, and if a long name gets in the way, you can assign it once: `const User = db.orm.public.User`. The name after `db.orm.` follows a different rule on each database. On PostgreSQL it is the PostgreSQL schema, such as `public`, and then the model name. MongoDB has no schemas, so there it is only the collection name: a `User` model stored in a `users` collection is `db.orm.users`.

On PostgreSQL, a `DateTime` field comes back as a `Temporal.Instant`, not a JavaScript `Date`. [Scalar fields](https://www.prisma.io/docs/orm/data-modeling#scalar-fields) explains the type and how to get a `Date` instead.

## Migrations: steps from one contract to another [#migrations-steps-from-one-contract-to-another]

A migration is a recorded change to your database, like a Prisma ORM 7 migration folder, except that it names contracts instead of relying on timestamp order. Each migration records two contract hashes: `from`, the contract it starts at, and `to`, the contract it ends at. A migration that only changes rows, such as a [backfill](https://www.prisma.io/docs/guides/database/data-migration), starts and ends at the same contract. On disk it is a directory in your repository that holds the change as [editable TypeScript](https://www.prisma.io/docs/orm/migrations/editing-a-migration) (`migration.ts`), the compiled operations Prisma ORM runs (`ops.json`), and the `from` and `to` hashes (`migration.json`).

Because every migration names where it starts and ends, your migrations form a graph, not a list. When two branches each add a migration and both merge, `db migrate` still finds its way, and you never renumber or rebase migration files.

Only [`db migrate`](https://www.prisma.io/docs/cli/db-migrate) applies migrations to a database. It starts from the contract hash in the signature and runs the migrations on the path to its target, which is your emitted contract, `contract.json`, unless `--to` names another. The `migration ...` commands create and inspect the migration files in your repository.

On PostgreSQL, a failed `db migrate` is safe to run again once you fix the cause. The whole run is one transaction, so a failure leaves no changes in the database, while migrations applied in earlier runs stay applied. MongoDB has no such transaction, so read [When something goes wrong](https://www.prisma.io/docs/orm/migrations/applying-a-migration#when-something-goes-wrong) before you run it again there.

### The everyday change [#the-everyday-change]

Every project, new or adopted, changes its database the same way. Edit your contract, then emit it, plan the migration, and apply it:

  

#### bun

```bash
bunx prisma contract emit
bunx prisma migration plan --name add_user_phone
bunx prisma db migrate --advance-ref db
```

#### pnpm

```bash
pnpm prisma contract emit
pnpm prisma migration plan --name add_user_phone
pnpm prisma db migrate --advance-ref db
```

#### yarn

```bash
yarn prisma contract emit
yarn prisma migration plan --name add_user_phone
yarn prisma db migrate --advance-ref db
```

#### npm

```bash
npx prisma contract emit
npx prisma migration plan --name add_user_phone
npx prisma db migrate --advance-ref db
```

Review the new directory under `migrations/app/` before you apply it, and commit it with your contract. `--advance-ref db` keeps the `db` ref current, which the next section explains.

In a new project, `db init` creates the first tables and signs the database, but writes no migration file. Your first `migration plan` writes one for those tables, called the baseline, plus one for your change. Your development database already has the baseline tables, so `db migrate` applies only your change there. An empty database, such as one in CI, gets both. [Add Prisma ORM and PostgreSQL to an existing app](https://www.prisma.io/docs/prisma-orm/quickstart/existing-app/postgresql#5-create-the-table) walks through it.

### Planning a migration [#planning-a-migration]

[`migration plan`](https://www.prisma.io/docs/cli/migration-plan) replaces the planning half of `prisma migrate dev`. It writes a new migration by comparing two contracts: your emitted contract, which is where the migration ends, and an origin contract, which is where it starts. The origin is the contract you name with `--from`, or the `db` ref when you pass no `--from`. The command never connects to a database, which is why it needs the `db` ref to know what your database already has.

### The `db` ref [#the-db-ref]

A ref is a named pointer to a contract hash, stored as a file under `migrations/app/refs/` so that it is versioned with your migrations. `app` is your app's own migration history (extension packages can ship their own). The `db` ref has a special meaning: it records the contract hash you expect your development database to match. When you run `migration plan` without `--from`, Prisma ORM assumes you mean from the `db` ref, so as long as the ref is current, each plan contains only your latest change.

Commands that connect to a database take the connection string from `prisma.config.ts`, the config file the CLI reads, unless you pass one on the command line with `--db`. [Configuration](https://www.prisma.io/docs/cli/configuration) describes the file, and `prisma orm init` writes it. The `db` ref describes your development database, and `--db` often points at another one, so whether you pass `--db` decides whether some commands update the ref:

| Command                | When it updates the `db` ref                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| `db init`, `db update` | When the connection comes from `prisma.config.ts`. With `--db`, only if you also pass `--advance-ref db`. |
| `db sign`              | After every successful signature, with or without `--db`. `--no-advance-ref` turns it off.                |
| `db migrate`           | Only with `--advance-ref db`, so a deploy does not change a file in your repository.                      |

`db sign` updates the ref even with `--db`, because it is normally run against the database you are adopting. Pass `--no-advance-ref` to skip it, for example in a deployment pipeline.

Commit `migrations/app/refs/db.json` with your migration files, so that on a fresh clone the ref points at the contract hash the team's development databases are at and the first `migration plan` starts from there. Applying with `db migrate --advance-ref db` in development keeps it current. [The db ref](https://www.prisma.io/docs/orm/migrations/generating-a-migration#the-db-ref-skipping---from) covers merge conflicts on that file.

You can also set the ref by hand with `migration ref set db <contract>`. `<contract>` can be a migration directory name, or a hash, which `migration status` prints for the database's current state.

When there is no `db` ref and you pass no `--from`, what `migration plan` does depends on the migrations already on disk. With none yet, it plans from an empty database, which creates every table, and prints a notice under its summary that it did so. With migrations on disk, it refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN` rather than write a migration that no real database could apply, and the error names the ways out: `migration ref set db <contract>`, `--from <ref>`, or `--from @empty`.

Other refs, such as `production` or `staging`, name the contract hash an environment should match, so a deploy can target it by name with `db migrate --to production`. You manage them with [`migration ref`](https://www.prisma.io/docs/cli/migration-ref).

### Adopting an existing database [#adopting-an-existing-database]

If Prisma ORM 7 still runs migrations on the database, follow [Transfer migration ownership](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership) in the upgrade guide, which runs `db sign` at the right point. For any other database you did not create with Prisma ORM 8, follow the steps below.

What Prisma ORM 7 called baselining, marking an existing database as already migrated, is `db sign` in Prisma ORM 8. The order of commands matters. Write the contract ([`contract infer`](https://www.prisma.io/docs/cli/contract-infer) gives you a draft to review), emit it, and sign the database before you plan anything:

  

#### bun

```bash
bunx prisma contract infer
bunx prisma contract emit
bunx prisma db sign
```

#### pnpm

```bash
pnpm prisma contract infer
pnpm prisma contract emit
pnpm prisma db sign
```

#### yarn

```bash
yarn prisma contract infer
yarn prisma contract emit
yarn prisma db sign
```

#### npm

```bash
npx prisma contract infer
npx prisma contract emit
npx prisma db sign
```

`db sign` signs the database, stores a copy of the signed contract under `migrations/snapshots/`, which you commit with the rest of `migrations/`, and points the `db` ref at it. So when you next edit the contract, emit it, and run `migration plan`, the plan starts from the contract you signed:

  

#### bun

```bash
bunx prisma contract emit
bunx prisma migration plan --name add_user_bio
```

#### pnpm

```bash
pnpm prisma contract emit
pnpm prisma migration plan --name add_user_bio
```

#### yarn

```bash
yarn prisma contract emit
yarn prisma migration plan --name add_user_bio
```

#### npm

```bash
npx prisma contract emit
npx prisma migration plan --name add_user_bio
```

Because there are no migrations on disk yet, that first `migration plan` also writes a baseline for the signed contract. Your own change goes in a second migration. The baseline is expected, and `db migrate` does not apply it to the database you signed. See [the automatic baseline](https://www.prisma.io/docs/cli/migration-plan#the-automatic-baseline) for the full rule.

If you run `migration plan` before `db sign` instead, there is no `db` ref and no migration on disk. So the plan starts from an empty database and proposes creating every table you already have.

### Iterating with db update [#iterating-with-db-update]

[`db update`](https://www.prisma.io/docs/cli/db-update) replaces `prisma db push`, and `prisma migrate dev` is split in two: use `db update` to try changes quickly, and `migration plan` then `db migrate` to write and apply a migration.

`db update` compares the live database with the emitted contract and applies the difference directly, with no migration file. It then signs the database. When the connection comes from `prisma.config.ts`, it also points the `db` ref at the new contract hash. `--dry-run` shows what it would change, and it asks before an operation that would destroy data.

Because no migration ends at the contract `db update` applied, a later `db migrate` on that database stops with `MIGRATION.MARKER_MISMATCH`. Applying a migration from a branch you later abandoned leaves the same problem behind, because the signature then names a contract that no migration on your main branch ends at. After `db update`, a plain `migration plan` also finds no change, because the `db` ref already names the new contract. To turn what `db update` applied into a committed migration, plan from your newest migration instead, as [Drift](https://www.prisma.io/docs/orm/migrations/rollbacks-and-recovery#drift-when-the-database-isnt-where-migrations-left-it) shows:

  

#### bun

```bash
bunx prisma migration plan --from <newest-migration-dir> --name <name>
```

#### pnpm

```bash
pnpm prisma migration plan --from <newest-migration-dir> --name <name>
```

#### yarn

```bash
yarn prisma migration plan --from <newest-migration-dir> --name <name>
```

#### npm

```bash
npx prisma migration plan --from <newest-migration-dir> --name <name>
```

### If you know Git [#if-you-know-git]

The migration vocabulary maps across:

| Git                     | Prisma ORM                         |
| ----------------------- | ---------------------------------- |
| A commit                | A contract, identified by its hash |
| A patch between commits | A migration                        |
| A branch or tag         | A ref                              |
| `HEAD`                  | The database signature             |
| `git checkout <commit>` | `db migrate --to <contract>`       |

Start with [How migrations work](https://www.prisma.io/docs/orm/migrations/how-migrations-work), then [The migration graph](https://www.prisma.io/docs/orm/migrations/the-migration-graph) for branches and merges.

## The command vocabulary [#the-command-vocabulary]

One rule divides the whole [CLI](https://www.prisma.io/docs/cli): only `db ...` commands can change a database. `contract ...` and `migration ...` commands work on the files in your repository. Three of them also connect to a database, but only read it: `contract infer` reads it to write a starter contract, and `migration status` and `migration log` read it to show which migrations are pending and which have run.

| Command                                     | Reads                                                      | Writes                                              | When                                                    |
| ------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
| [`contract emit`](https://www.prisma.io/docs/cli/contract-emit)       | your contract source                                       | `contract.json` and `contract.d.ts`                 | after every contract change, before any other command   |
| [`contract infer`](https://www.prisma.io/docs/cli/contract-infer)     | the live database                                          | a draft `contract.prisma`                           | your first contract for an existing database            |
| [`db init`](https://www.prisma.io/docs/cli/db-init)                   | the emitted contract and the live database                 | the missing tables, the signature, and the `db` ref | a new database, the first time                          |
| [`db sign`](https://www.prisma.io/docs/cli/db-sign)                   | the emitted contract and the live database                 | the signature, a snapshot, and the `db` ref         | adopting a database that already matches                |
| [`db verify`](https://www.prisma.io/docs/cli/db-verify)               | the emitted contract, the signature, and the live database | nothing                                             | checking for drift, in CI or before a deploy            |
| [`db update`](https://www.prisma.io/docs/cli/db-update)               | the emitted contract and the live database                 | table changes, the signature, and the `db` ref      | iterating on a development database                     |
| [`migration plan`](https://www.prisma.io/docs/cli/migration-plan)     | the origin contract and the emitted contract               | a migration directory                               | a change you want reviewed and committed                |
| [`db migrate`](https://www.prisma.io/docs/cli/db-migrate)             | the migration directories and the signature                | table changes and the signature                     | applying committed migrations                           |
| [`migration status`](https://www.prisma.io/docs/cli/migration-status) | the migration directories and the database's signature     | nothing                                             | seeing which migrations are pending                     |
| `migration log`                             | the ledger, the database's list of applied migrations      | nothing                                             | seeing which migrations have run                        |
| [`migration ref set`](https://www.prisma.io/docs/cli/migration-ref)   | a contract hash, ref, or migration name                    | a ref file                                          | naming a contract hash, or pointing `db` at one by hand |

Each command that writes the `db` ref does so only in the situations listed under [The `db` ref](#the-db-ref). `db migrate` writes it only when you pass `--advance-ref db`.

## The pieces underneath [#the-pieces-underneath]

The names in this section come up in error messages and in the pages about extensions and middleware. You do not need them to write queries or migrations.

**The stack behind one package.** One package connects your code to your database. A PostgreSQL project installs `@prisma/orm-postgres`, and its config helper sets up the pieces underneath it: the database family (SQL), the target (PostgreSQL), the adapter that turns a plan into PostgreSQL's dialect of SQL, and the driver that holds the network connection. Error codes such as `CONFIG.DRIVER_REQUIRED` and `CONTRACT.TARGET_MISMATCH` use these names.

**Supported database features.** Your database package and any extension packages list the database features they support, such as `RETURNING` clauses or `DISTINCT ON`, and `contract.json` records that list. If your contract uses a feature your database package does not support, `contract emit` fails. If you call a query method that needs a missing feature, it throws `ORM.CAPABILITY_MISSING` when you build the query, before it runs. See [Supported database features](https://www.prisma.io/docs/orm/contract-authoring/capabilities).

**How values are stored and read.** Each column type in your contract comes with the code that converts its values between JavaScript and the database, in both directions. The `DateTime` to `Temporal.Instant` conversion above is one of these. Extensions bring conversions for the types they add, so a pgvector `Vector(1536)` column comes back as a typed vector, not a string. Error codes such as `RUNTIME.CODEC_DESCRIPTOR_INVALID` refer to this conversion. `fns.raw` fragments and MongoDB raw commands skip the conversion, so you convert those values yourself.

**Extensions.** An extension is a package that adds column types, query operations, index kinds, and database features, and at the widest, support for a whole database. You list it in `prisma.config.ts` and pass it to the client. After that, `pgvector.Vector(1536)` is a column type in your contract, vector operators appear in the query builder, and `migration plan` knows how to create vector indexes. See [Using extensions](https://www.prisma.io/docs/orm/extensions/using-extensions).

**Middleware.** A middleware is an object with a name and one or more hooks that run around every query, like middleware in Express or Koa. The `middleware` option of `postgres(...)` replaces `$use` from Prisma ORM 7, and you register each middleware there once. Because every query is a plan, a hook gets the query as data and can log it, limit it, or reject it by throwing, without changing how your queries are written. Prisma ORM ships three middleware that you can register as they are: [budgets](https://www.prisma.io/docs/orm/middleware/built-in-budgets) limits row counts and query time, [lints](https://www.prisma.io/docs/orm/middleware/built-in-lints) blocks risky queries, and [cache](https://www.prisma.io/docs/orm/middleware/built-in-cache) serves repeated reads from memory. For a policy of your own, [write your own middleware](https://www.prisma.io/docs/orm/middleware/authoring-custom-middleware). [How middleware works](https://www.prisma.io/docs/orm/middleware/how-middleware-works) explains the hooks.

## What moved from Prisma ORM 7 [#what-moved-from-prisma-orm-7]

[Coming from Prisma ORM 7](https://www.prisma.io/docs/orm/coming-from-prisma-orm-7) lists the Prisma ORM 8 name for each Prisma ORM 7 command, API, and schema attribute, and says plainly where there is no equivalent yet.

## The eight words [#the-eight-words]

* **Contract**: what you write, in `contract.prisma` or `contract.ts`.
* **Schema**: what the database has right now.
* **Emit**: build the contract into `contract.json` and `contract.d.ts`.
* **Hash**: the identifier of one exact contract.
* **Signature**: the record in the database of which contract hash it matches, called the marker in error codes.
* **Drift**: the contract and the database disagree.
* **Plan**: a query built as data before it runs. The `migration plan` command is a different use of the word: it writes a migration.
* **Ref**: a named pointer to a contract hash, such as `db` or `production`.

The name `db` has three uses: the client your code imports, the `db ...` group of CLI commands, and the `db` ref.

## Use with your agent [#use-with-your-agent]

Projects set up with `npm create prisma@latest` or `npx prisma@latest init` install the [Prisma ORM skills](https://www.prisma.io/docs/ai/tools/skills#available-skills-for-prisma-8) for your coding agent. Ask your agent to:

* "Using the prisma-8 skill, explain the difference between our contract and the database schema."
* "Show me the plan the SQL query builder produces for this query."
* "Which of our CLI scripts touch the live database, and which are offline?"

## Next steps [#next-steps]

* [The data contract](https://www.prisma.io/docs/orm/contract-authoring/the-data-contract): the concept that this whole page hangs off, in depth.
* [Reading data](https://www.prisma.io/docs/orm/fundamentals/reading-data): put the ORM client to work against your contract.
* [How migrations work](https://www.prisma.io/docs/orm/migrations/how-migrations-work): change your contract, then plan, review, and apply the migration, hands-on.

## Related pages

- [`Coming from Prisma ORM 7`](https://www.prisma.io/docs/orm/coming-from-prisma-orm-7): What each Prisma ORM 7 schema attribute, command, and query is called in Prisma ORM 8, and what is not available.
- [`Extensions`](https://www.prisma.io/docs/orm/extensions): Every package that plugs into Prisma ORM: database packages, column types, indexes, query operations, and middleware, by Prisma and the community.
- [`Overview`](https://www.prisma.io/docs/orm/data-modeling): Describe the data your application needs with models, primary keys, scalar fields, and relations.
- [`Prisma 7`](https://www.prisma.io/docs/orm/v7): Prisma ORM is a next-generation Node.js and TypeScript ORM that provides type-safe database access, migrations, and a visual data editor.
- [`Prisma ORM`](https://www.prisma.io/docs/orm/v6): Learn about Prisma ORM