# db update (/docs/cli/db-update)

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

Update a database to match the current Prisma ORM contract.

Location: CLI > db update

`db update` compares the live database with the emitted contract and applies the changes that close the gap, whether or not the database was bootstrapped with `db init`.

Use it for direct reconciliation when you do not need a checked-in migration package.

## Usage [#usage]

  

#### bun

```bash
bunx prisma db update --db "$DATABASE_URL"
```

#### pnpm

```bash
pnpm prisma db update --db "$DATABASE_URL"
```

#### yarn

```bash
yarn prisma db update --db "$DATABASE_URL"
```

#### npm

```bash
npx prisma db update --db "$DATABASE_URL"
```

## Options [#options]

| Option                 | What it does                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--db <url>`           | Connects to the database.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--dry-run`            | Shows planned operations without applying them.                                                                                                                                                                                                                                                                                                                                                                                |
| `--to <contract>`      | Updates to a specific contract state. Accepts a [contract reference](https://www.prisma.io/docs/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`<dir>^`](#contract-references). It refuses `@contract`, `@db`, and `@empty` with the error code `MIGRATION.REF_WRONG_GRAMMAR`. To update to the contract in `contract.json`, leave out `--to`. |
| `--rename <old>:<new>` | Renames a model or a field and keeps its rows, instead of dropping and creating its table or column. Repeatable. See [Renames and data loss](#renames-and-data-loss).                                                                                                                                                                                                                                                          |
| `--delete <subject>`   | Lets the update lose the data of a model, a field, or a table no model stores. Repeatable.                                                                                                                                                                                                                                                                                                                                     |
| `--allow <Model>`      | Lets one operation widen who can read or write the model's rows. Repeatable.                                                                                                                                                                                                                                                                                                                                                   |
| `--advance-ref <name>` | Advances the named [ref](https://www.prisma.io/docs/cli/migration-ref) to the post-command contract hash. Without it, `db update` advances `db` when `--db` is omitted, and advances nothing when `--db` is passed.                                                                                                                                                                                                                                      |
| `--config <path>`      | Read this config file instead of `./prisma.config.ts`.                                                                                                                                                                                                                                                                                                                                                                         |
| `--json`               | Prints a machine-readable result.                                                                                                                                                                                                                                                                                                                                                                                              |

### Contract references [#contract-references]

A ref name is a name you gave a contract state with [`migration ref set`](https://www.prisma.io/docs/cli/migration-ref), such as `prod`. `<dir>^` is a migration directory name followed by `^`, and it names the contract state before that migration, while the directory name alone names the state after it. [Contract references each command accepts](https://www.prisma.io/docs/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command.

## How the db ref moves [#how-the-db-ref-moves]

Run without `--db`, `db update` takes the connection from `db.connection` in `prisma.config.ts` and advances the [ref](https://www.prisma.io/docs/cli/migration-ref) named `db` to the contract it just applied. Pass `--db` and that advancement is suppressed, even when the URL is the same one the config holds. Pass `--advance-ref db` alongside `--db` to get it back.

The `db` ref is what [`migration plan`](https://www.prisma.io/docs/cli/migration-plan) uses as its starting point when you do not pass `--from`. Passing `--db` only suppresses the advancement; it never removes a `db` ref that already exists. So a loop that always passes `--db` without `--advance-ref db` leaves the ref wherever it was last set, and the next `migration plan` starts from that stale contract. If the ref was never created, `migration plan` plans from an empty database while `migrations/app/` is empty, and refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN` once migrations exist on disk.

## Renames and data loss [#renames-and-data-loss]

Before it applies anything, `db update` asks one question for each model, field or table whose data the update would lose, such as a dropped column or a type change that can change values. Answer each one on the command line:

* `--delete <subject>` lets the data go. A subject is `Model`, `Model.field`, or, for data no model stores, its storage name, such as `public.audit_log`.
* `--rename <old>:<new>` keeps the data. The update renames the table or column, and the constraints and indexes named after it, instead of dropping and creating it. Each side is `Model`, `namespace.Model`, `Model.field` or `namespace.Model.field`, and a field's model is named as the new contract names it: `--rename Profile:User --rename User.name:User.fullName`.

It also asks before each operation that widens who can read or write a model's rows, such as dropping a row-level-security policy or disabling row-level security. Answer each with `--allow <Model>`; two such operations on one model take `--allow User --allow User`.

  

#### bun

```bash
bunx prisma db update --db "$DATABASE_URL" --advance-ref db --no-interactive --delete Legacy --rename User.name:User.fullName
```

#### pnpm

```bash
pnpm prisma db update --db "$DATABASE_URL" --advance-ref db --no-interactive --delete Legacy --rename User.name:User.fullName
```

#### yarn

```bash
yarn prisma db update --db "$DATABASE_URL" --advance-ref db --no-interactive --delete Legacy --rename User.name:User.fullName
```

#### npm

```bash
npx prisma db update --db "$DATABASE_URL" --advance-ref db --no-interactive --delete Legacy --rename User.name:User.fullName
```

In a terminal, the command asks the questions you did not answer with a flag. In a CI job or a run with `--no-interactive`, it fails with [`CLI.CONSENT_REQUIRED`](https://www.prisma.io/docs/cli/error-reference#CLI.CONSENT_REQUIRED) instead. The error lists each question still unanswered, and its next actions give the flags to add. A `--delete` or `--allow` that answers no question fails the run with `CLI.CONSENT_UNUSED`. To list the questions without applying anything, run with `--dry-run --json` and read `dataLoss` and `accessChanges`. `--confirm` answers none of these questions.

Dropping an index, a unique or foreign-key constraint, a check, a default or a native enum type loses no data, so the update asks nothing about it.

`db update` names each subject by model and field from the contract the database was last updated to, which it stores when it advances a ref. With `--db`, pass `--advance-ref <name>` on every run so that contract is stored for the next run. Without a stored contract, each subject is its storage name, and a run with `--rename` fails with `MIGRATION.STATEMENT_ORIGIN_UNKNOWN`. Adding `--advance-ref` to that run does not help, because the missing contract is the one the database is at before it. To store it, emit the contract the database is at, run `db update --advance-ref db --dry-run` with the same `--db`, and check that it plans no operations. Then run it again without `--dry-run`, which changes nothing in the database and stores the contract. Then emit the new contract and run the rename.

On MongoDB, a model rename renames its collection and keeps its documents, indexes and validator, and a field rename renames the field in every document that holds it. `--rename` and `--delete` name fields by their names in the schema, not by the names they are stored under. Removing a field from a model removes it from every document that holds it, so the update asks about it: answer with `--delete <Model>.<field>`, or with `--rename`. Without a stored contract, the field is named by its collection, as in `--delete profiles.nickname`.

On PostgreSQL and SQLite, a type change that can lose values is answered with `--delete <Model.field>`, which lets the database's own cast run; it may cut or round values, and a value it cannot cast fails the update. To write the conversion yourself, use [`migration plan --convert`](https://www.prisma.io/docs/cli/migration-plan#type-changes-and-required-fields) instead.

## Recommended flow [#recommended-flow]

  

#### bun

```bash
bunx prisma contract emit
bunx prisma db update --db "$DATABASE_URL" --dry-run
bunx prisma db update --db "$DATABASE_URL" --advance-ref db
bunx prisma db verify --db "$DATABASE_URL"
```

#### pnpm

```bash
pnpm prisma contract emit
pnpm prisma db update --db "$DATABASE_URL" --dry-run
pnpm prisma db update --db "$DATABASE_URL" --advance-ref db
pnpm prisma db verify --db "$DATABASE_URL"
```

#### yarn

```bash
yarn prisma contract emit
yarn prisma db update --db "$DATABASE_URL" --dry-run
yarn prisma db update --db "$DATABASE_URL" --advance-ref db
yarn prisma db verify --db "$DATABASE_URL"
```

#### npm

```bash
npx prisma contract emit
npx prisma db update --db "$DATABASE_URL" --dry-run
npx prisma db update --db "$DATABASE_URL" --advance-ref db
npx prisma db verify --db "$DATABASE_URL"
```

Use `--dry-run` before applying changes in shared environments.

## When to use migrations instead [#when-to-use-migrations-instead]

For reviewable database changes in version control, use [`migration plan`](https://www.prisma.io/docs/cli/migration-plan) and [`db migrate`](https://www.prisma.io/docs/cli/db-migrate).

Use `db update` for local development, preview environments, and workflows where direct reconciliation is acceptable.

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