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

## 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 environments need named targets instead of always applying to the latest migration on disk. Several commands can also move a ref forward for you after they succeed when you pass `--advance-ref <name>`.

## 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 8 CLI commands with prisma.config.ts and global flags.
- [`contract emit`](https://www.prisma.io/docs/cli/contract-emit): Emit Prisma 8 contract artifacts.