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, db update --to production, or db sign production.

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 has a special meaning: it records the contract state you expect your local 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 kept up to date, each plan contains only your latest change.

The db ref is updated automatically in the following situations:

• db init and 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 updates it after a successful signature, with or without --db. --no-advance-ref turns that off.
• db migrate --advance-ref db 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>.

bunx prisma migration ref set production 4cb4256

bunx prisma migration ref list

bunx prisma migration ref delete production

pnpm prisma migration ref set production 4cb4256
pnpm prisma migration ref list
pnpm prisma migration ref delete production

yarn prisma migration ref set production 4cb4256
yarn prisma migration ref list
yarn prisma migration ref delete production

npx prisma migration ref set production 4cb4256
npx prisma migration ref list
npx prisma migration ref delete production

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

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 <name> to a command that changes the database, that command also points the ref at the state it applied, once it succeeds.