# db migrate (/docs/cli/db-migrate)

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

Apply pending Prisma ORM migrations.

Location: CLI > db migrate

`db migrate` applies pending on-disk migrations to advance the database. It walks every contract space and applies migrations in canonical order: extensions alphabetically, then the app. It applies only the migrations that exist on disk and never generates new operations.

Prisma ORM keeps one migration history for your own models, called the `app` space, in `migrations/app/`, and one for each [extension package](https://www.prisma.io/docs/orm/extensions/using-extensions) that ships its own migrations, such as pgvector. Each of these histories is a [contract space](https://www.prisma.io/docs/orm/migrations/the-migration-graph#terms-used-on-this-page).

Use it from a controlled deployment step after reviewing migration packages.

## Usage [#usage]

  

#### bun

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

#### pnpm

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

#### yarn

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

#### npm

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

## Options [#options]

| Option                 | What it does                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--db <url>`           | Connects to the database.                                                                                                                                                                                                                                                                                                                                                                               |
| `--to <contract>`      | Applies migrations up to a target contract state. Accepts a [contract reference](https://www.prisma.io/docs/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`<dir>^`](#contract-references), [`@contract`](#contract-references), [`@db`](#contract-references), or [`@empty`](#contract-references).                       |
| `--advance-ref <name>` | Advances the named [ref](https://www.prisma.io/docs/cli/migration-ref) to the post-apply marker after success.                                                                                                                                                                                                                                                                                                                    |
| `--show`               | Previews the migration route without applying (read-only).                                                                                                                                                                                                                                                                                                                                              |
| `--from <contract>`    | Use it with `--show`, where it sets the starting state for the preview. Accepts a [contract reference](https://www.prisma.io/docs/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`<dir>^`](#contract-references), [`@contract`](#contract-references), [`@db`](#contract-references), or [`@empty`](#contract-references). |
| `--config <path>`      | Read this config file instead of `./prisma.config.ts`.                                                                                                                                                                                                                                                                                                                                                  |
| `--json`               | Prints a machine-readable result.                                                                                                                                                                                                                                                                                                                                                                       |

### Contract references [#contract-references]

A ref name is a name you gave a contract state with [`migration ref set`](https://www.prisma.io/docs/cli/migration-ref), such as `prod`. `<dir>^` is a migration directory name followed by `^`, and it names the contract state before that migration, while the directory name alone names the state after it. [Contract references each command accepts](https://www.prisma.io/docs/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command.

`@contract` names the contract in `contract.json`, which `contract emit` writes. The database stores a marker, a row that says which contract state it matches. `@db` names that state, or the empty database when the database has no marker. `@empty` names the empty database, before any migration.

## Recommended flow [#recommended-flow]

  

#### bun

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

#### pnpm

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

#### yarn

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

#### npm

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

Run `migration status` before and after applying migrations to see what changed.

## Previewing the route [#previewing-the-route]

`--show` prints the route `db migrate` would take without touching the database:

  

#### bun

```bash
bunx prisma db migrate --show
bunx prisma db migrate --show --from @contract --to production
```

#### pnpm

```bash
pnpm prisma db migrate --show
pnpm prisma db migrate --show --from @contract --to production
```

#### yarn

```bash
yarn prisma db migrate --show
yarn prisma db migrate --show --from @contract --to production
```

#### npm

```bash
npx prisma db migrate --show
npx prisma db migrate --show --from @contract --to production
```

## Applying to a target [#applying-to-a-target]

If your project uses named [refs](https://www.prisma.io/docs/cli/migration-ref), apply up to a target ref:

  

#### bun

```bash
bunx prisma db migrate --db "$DATABASE_URL" --to production
```

#### pnpm

```bash
pnpm prisma db migrate --db "$DATABASE_URL" --to production
```

#### yarn

```bash
yarn prisma db migrate --db "$DATABASE_URL" --to production
```

#### npm

```bash
npx prisma db migrate --db "$DATABASE_URL" --to production
```

Manage refs with [`migration ref`](https://www.prisma.io/docs/cli/migration-ref).

## When an apply fails [#when-an-apply-fails]

Each operation checks the database before and after it runs, as [How migrations work](https://www.prisma.io/docs/orm/migrations/how-migrations-work#every-operation-checks-itself) explains. When a check fails, `db migrate` stops and its `why` says which check failed and, when the check names one object, what the database already has or lacks:

```text
✘ [MIGRATION.PRECHECK_FAILED] Operation table.user failed during precheck: ensure table "user" does not exist
  why: Before operation table.user runs, it checks: ensure table "user" does not exist. That check failed: the database already has table "user". The failed apply changed nothing.
```

Some checks name no object, such as a check about data or a check in a migration planned before `8.0.0-rc.20`. For those, `why` says only "That check failed on this database."

The `why` ends by saying whether the database changed. On PostgreSQL and SQLite a failed apply is rolled back, so it says "The failed apply changed nothing." MongoDB has no transaction around a migration, so once an operation has written anything it says "The operations that ran before the failure stay applied." Before `8.0.0-rc.20`, `db migrate` said a failed apply on MongoDB changed nothing even when earlier operations stayed applied.

With `--json`, the error's `meta` holds the same facts:

```json
{
  "failedCheck": {
    "operationId": "table.user",
    "phase": "precheck",
    "description": "ensure table \"user\" does not exist",
    "expectation": { "expects": "absent", "object": "table \"user\"" }
  },
  "failingSpace": "app",
  "databaseUnchanged": true
}
```

`databaseUnchanged` is `true` when the database is exactly as it was before the apply, and `false` when changes stay. When the schema check after the last operation fails, `meta.schemaIssues` lists the differences, in the shape [`db verify`](https://www.prisma.io/docs/cli/db-verify#schema-differences-in-json-output) describes.

`nextActions` lists each way to fix the failure as its own entry. A script reads its `kind`:

* `run-command`: running this command alone fixes the failure, such as `prisma db sign` for a database that already matches the contract.
* `edit-file`: a person edits a file first, such as the contract source or a migration's `migration.ts`.
* `user-choice`: a person decides, because the step changes data or chooses between plans.

## Data lines [#data-lines]

Without `--json`, standard output gets one line per applied migration, with these fields separated by tabs: `space`, `name`, `from`, `to`, and the number of operations run. With `--show`, it gets one line per migration that will run, with `space`, `name`, `from`, and `to`; there is no operation count before the run. `from` is empty for a migration that starts from the empty database. [Global flags](https://www.prisma.io/docs/cli/global-flags#data-lines-of-prisma-orm-commands) lists the rules data lines follow.

```bash
npx prisma db migrate --show | cut -f2
```

## Related pages

- [`auth`](https://www.prisma.io/docs/cli/auth): Sign in to your Prisma account from the CLI, sign out, and manage workspace sessions.
- [`branch`](https://www.prisma.io/docs/cli/branch): List platform branches for a project.
- [`bucket`](https://www.prisma.io/docs/cli/bucket): Create and manage object-store buckets.
- [`Configuration`](https://www.prisma.io/docs/cli/configuration): Configure Prisma ORM CLI commands with prisma.config.ts and global flags.
- [`contract emit`](https://www.prisma.io/docs/cli/contract-emit): Emit Prisma ORM contract artifacts.