migration ref
Manage named Prisma ORM refs that point at contracts.
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
One name is special. A ref called db is what migration plan starts from when you do not pass --from, so keeping it current is what keeps plans incremental.
Four things move it:
db initanddb updateadvance it automatically when you run them without--dband let the connection come fromprisma.config.ts. Passing--dbsuppresses that unless you also pass--advance-ref db.db signadvances it after a successful signature, with or without--db.--no-advance-refturns that off.db migrate --advance-ref dbadvances it after an apply. Plaindb migratenever advances anything, which is deliberate: a deploy or CI apply should not move a repository ref.migration ref set db <contract>sets it by hand.
Usage
bunx prisma@latest migration ref set production 4cb4256
bunx prisma@latest migration ref list
bunx prisma@latest migration ref delete productionSubcommands
| 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
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 productionUse 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>.