# migration ref (/docs/cli/migration-ref)

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

Manage named Prisma ORM refs that point at contracts.

Location: CLI > migration ref

Use `migration ref` commands to manage named refs stored with your migration history. A ref maps a logical environment name, such as `staging` or `production`, to a contract hash. Other commands can then target that environment by name: [`db migrate --to production`](https://www.prisma.io/docs/cli/db-migrate), [`db update --to production`](https://www.prisma.io/docs/cli/db-update), or [`db sign production`](https://www.prisma.io/docs/cli/db-sign).

Refs live on disk as `migrations/app/refs/<name>.json`, so they are versioned with your migrations. The commands are offline. The contract a ref points at must already be part of the on-disk migration graph, which is why `migration ref set` does not accept `@db`: that token stands for the live database's marker, and the offline commands never read one.

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

The `db` ref has a special meaning: it records the contract state you expect your local database to match. When you run [`migration plan`](https://www.prisma.io/docs/cli/migration-plan) without `--from`, Prisma ORM assumes you mean from the `db` ref, so as long as the ref is kept up to date, each plan contains only your latest change.

The `db` ref is updated automatically in the following situations:

* [`db init`](https://www.prisma.io/docs/cli/db-init) and [`db update`](https://www.prisma.io/docs/cli/db-update) update it when you run them without `--db`, so that the connection comes from `prisma.config.ts`. With `--db`, they leave it alone unless you also pass `--advance-ref db`.
* [`db sign`](https://www.prisma.io/docs/cli/db-sign) updates it after a successful signature, with or without `--db`. `--no-advance-ref` turns that off.
* [`db migrate --advance-ref db`](https://www.prisma.io/docs/cli/db-migrate) updates it after an apply. Plain `db migrate` never touches it, on purpose: a deploy or CI run should not change a file in your repository.

You can also set it by hand with `migration ref set db <contract>`.

## Usage [#usage]

  

#### bun

```bash
bunx prisma@latest migration ref set production 4cb4256
bunx prisma@latest migration ref list
bunx prisma@latest migration ref delete production
```

#### pnpm

```bash
pnpm dlx prisma@latest migration ref set production 4cb4256
pnpm dlx prisma@latest migration ref list
pnpm dlx prisma@latest migration ref delete production
```

#### yarn

```bash
yarn dlx prisma@latest migration ref set production 4cb4256
yarn dlx prisma@latest migration ref list
yarn dlx prisma@latest migration ref delete production
```

#### npm

```bash
npx prisma@latest migration ref set production 4cb4256
npx prisma@latest migration ref list
npx prisma@latest migration ref delete production
```

## Subcommands [#subcommands]

| Subcommand              | What it does                                                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `set <name> <contract>` | Points a ref at a contract. The contract is a hash or prefix, another ref name, a migration directory name, or `<dir>^` for that migration's source contract. |
| `list`                  | Lists every ref with the contract hash it points at and the invariants recorded against it.                                                                   |
| `delete <name>`         | Deletes a ref. The contract it pointed at is untouched.                                                                                                       |

## Example workflow [#example-workflow]

  

#### bun

```bash
bunx prisma@latest migration ref set production 20260101T1000_add_user
bunx prisma@latest migration status --db "$DATABASE_URL" --to production
bunx prisma@latest db migrate --db "$DATABASE_URL" --to production
```

#### pnpm

```bash
pnpm dlx prisma@latest migration ref set production 20260101T1000_add_user
pnpm dlx prisma@latest migration status --db "$DATABASE_URL" --to production
pnpm dlx prisma@latest db migrate --db "$DATABASE_URL" --to production
```

#### yarn

```bash
yarn dlx prisma@latest migration ref set production 20260101T1000_add_user
yarn dlx prisma@latest migration status --db "$DATABASE_URL" --to production
yarn dlx prisma@latest db migrate --db "$DATABASE_URL" --to production
```

#### npm

```bash
npx prisma@latest migration ref set production 20260101T1000_add_user
npx prisma@latest migration status --db "$DATABASE_URL" --to production
npx prisma@latest db migrate --db "$DATABASE_URL" --to production
```

Use refs when you want to name the contract state an environment should match, instead of always applying up to the latest migration on disk. If you pass `--advance-ref <name>` to a command that changes the database, that command also points the ref at the state it applied, once it succeeds.

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