# 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/.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 `. ## Usage [#usage] #### bun ```bash bunx prisma migration ref set production 4cb4256 bunx prisma migration ref list bunx prisma migration ref delete production ``` #### pnpm ```bash pnpm prisma migration ref set production 4cb4256 pnpm prisma migration ref list pnpm prisma migration ref delete production ``` #### yarn ```bash yarn prisma migration ref set production 4cb4256 yarn prisma migration ref list yarn prisma migration ref delete production ``` #### npm ```bash npx prisma migration ref set production 4cb4256 npx prisma migration ref list npx prisma migration ref delete production ``` ## Subcommands [#subcommands] | Subcommand | What it does | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `set ` | Points a ref at a contract. The contract is a [contract reference](https://www.prisma.io/docs/orm/migrations/the-migration-graph#contract-reference-forms): a hash or prefix, another ref name, a migration directory name, or `^` for that migration's source contract. | | `list` | Lists every ref with the contract hash it points at and the invariants recorded against it. | | `delete ` | Deletes a ref. The contract it pointed at is untouched. | ## Data lines [#data-lines] Without `--json`, the subcommands print these data lines on standard output: * `list`: one line per ref, with three fields separated by tabs: `name`, `hash`, and `invariants`. `invariants` lists, separated by commas, the ids of the data operations (their `invariantId`) that a migration to the ref must run. * `set`: one line, the contract hash the ref now points at. * `delete`: nothing. Its exit code says whether the ref was deleted, and `--json` carries the result. ```bash npx prisma migration ref list | cut -f1 ``` [Global flags](https://www.prisma.io/docs/cli/global-flags#data-lines-of-prisma-orm-commands) lists the rules data lines follow. ## Example workflow [#example-workflow] #### bun ```bash bunx prisma migration ref set production 20260101T1000_add_user bunx prisma migration status --db "$DATABASE_URL" --to production bunx prisma db migrate --db "$DATABASE_URL" --to production ``` #### pnpm ```bash pnpm prisma migration ref set production 20260101T1000_add_user pnpm prisma migration status --db "$DATABASE_URL" --to production pnpm prisma db migrate --db "$DATABASE_URL" --to production ``` #### yarn ```bash yarn prisma migration ref set production 20260101T1000_add_user yarn prisma migration status --db "$DATABASE_URL" --to production yarn prisma db migrate --db "$DATABASE_URL" --to production ``` #### npm ```bash npx prisma migration ref set production 20260101T1000_add_user npx prisma migration status --db "$DATABASE_URL" --to production npx prisma 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 ` 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.