diff --git a/apps/docs/content/docs/cli/db-migrate.mdx b/apps/docs/content/docs/cli/db-migrate.mdx index be9af296f05..d36f967f885 100644 --- a/apps/docs/content/docs/cli/db-migrate.mdx +++ b/apps/docs/content/docs/cli/db-migrate.mdx @@ -23,7 +23,7 @@ npx prisma db migrate --db "$DATABASE_URL" | Option | What it does | | --- | --- | | `--db ` | Connects to the database. | -| `--to ` | Applies migrations up to a target contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`^`](#contract-references). With `--show`, it also accepts the tokens [`@contract`](#contract-references) and [`@empty`](#contract-references). | +| `--to ` | Applies migrations up to a target contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`^`](#contract-references), [`@contract`](#contract-references), [`@db`](#contract-references), or [`@empty`](#contract-references). | | `--advance-ref ` | Advances the named [ref](/cli/migration-ref) to the post-apply marker after success. | | `--show` | Previews the migration route without applying (read-only). | | `--from ` | Use it with `--show`, where it sets the starting state for the preview. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`^`](#contract-references), [`@contract`](#contract-references), [`@db`](#contract-references), or [`@empty`](#contract-references). | @@ -34,7 +34,7 @@ npx prisma db migrate --db "$DATABASE_URL" A ref name is a name you gave a contract state with [`migration ref set`](/cli/migration-ref), such as `prod`. `^` 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](/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command. -`@contract` names the contract in `contract.json`, which `contract emit` writes. The database stores a marker, a row that says which contract state it matches. `@db` names that state. `@empty` names the empty database, before any migration. +`@contract` names the contract in `contract.json`, which `contract emit` writes. The database stores a marker, a row that says which contract state it matches. `@db` names that state, or the empty database when the database has no marker. `@empty` names the empty database, before any migration. ## Recommended flow diff --git a/apps/docs/content/docs/cli/db-sign.mdx b/apps/docs/content/docs/cli/db-sign.mdx index 905a56f7b79..28c4df99934 100644 --- a/apps/docs/content/docs/cli/db-sign.mdx +++ b/apps/docs/content/docs/cli/db-sign.mdx @@ -22,7 +22,7 @@ npx prisma db sign --db "$DATABASE_URL" | Argument or option | What it does | | --- | --- | -| `[contract]` | Signs against a specific contract state instead of the emitted contract. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`^`](#contract-references). | +| `[contract]` | Signs against a specific contract state instead of the emitted contract. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`^`](#contract-references). It refuses `@contract`, `@db`, and `@empty` with the error code `MIGRATION.REF_WRONG_GRAMMAR`. To sign against the contract in `contract.json`, leave the argument out. | | `--db ` | Connects to the database. | | `--contract ` | The same value as `[contract]`, passed as an option in place of the argument. | | `--advance-ref ` | Advances this ref instead of `db` after a successful signature. | diff --git a/apps/docs/content/docs/cli/db-update.mdx b/apps/docs/content/docs/cli/db-update.mdx index 9eb34c949f9..203ed0964d0 100644 --- a/apps/docs/content/docs/cli/db-update.mdx +++ b/apps/docs/content/docs/cli/db-update.mdx @@ -22,7 +22,7 @@ npx prisma db update --db "$DATABASE_URL" | --- | --- | | `--db ` | Connects to the database. | | `--dry-run` | Shows planned operations without applying them. | -| `--to ` | Updates to a specific contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`^`](#contract-references). | +| `--to ` | Updates to a specific contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`^`](#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`. | | `--advance-ref ` | Advances the named [ref](/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 ` | Read this config file instead of `./prisma.config.ts`. | | `--json` | Prints a machine-readable result. | diff --git a/apps/docs/content/docs/cli/migration-status.mdx b/apps/docs/content/docs/cli/migration-status.mdx index 166d305c63d..59ffa92e206 100644 --- a/apps/docs/content/docs/cli/migration-status.mdx +++ b/apps/docs/content/docs/cli/migration-status.mdx @@ -22,8 +22,8 @@ npx prisma migration status --db "$DATABASE_URL" | --- | --- | | `--db ` | Connects to the database. | | `--space ` | Narrows output to a single [contract space](#contract-spaces), named by its directory under `migrations/`. | -| `--to ` | Sets the target contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`^`](#contract-references), or [`@empty`](#contract-references). | -| `--from ` | Sets the origin contract state, and accepts the same forms as `--to`. With `--from`, the command computes the path offline and does not need a database. | +| `--to ` | Sets the target contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`^`](#contract-references), [`@contract`](#contract-references), [`@db`](#contract-references), or [`@empty`](#contract-references). | +| `--from ` | Sets the origin contract state, and accepts the same forms as `--to`. With `--from`, the command computes the path offline and does not need a database. It needs one when `--from` or `--to` is `@db`, because it then reads the marker from the database. | | `--legend` | Prints a key to the symbols in the rows (`○`, the arrows, `✓`, `⧗`, `∅`) and to the labels. | | `--ascii` | Uses ASCII glyphs (pipe-friendly). | | `--config ` | Read this config file instead of `./prisma.config.ts`. | @@ -35,7 +35,7 @@ Prisma ORM keeps one migration history for your own models, called the `app` spa ### Contract references [#contract-references] -A ref name is a name you gave a contract state with [`migration ref set`](/cli/migration-ref), such as `prod`. `^` 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. `@empty` names the empty database, before any migration. [Contract references each command accepts](/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command. +A ref name is a name you gave a contract state with [`migration ref set`](/cli/migration-ref), such as `prod`. `^` 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` names the contract in `contract.json`, which `contract emit` writes. `@db` names the contract state that the database's marker records. `@empty` names the empty database, before any migration. [Contract references each command accepts](/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command. ## Examples @@ -69,7 +69,7 @@ Read the drawing from the bottom up, because the earliest state is the bottom ro The last line suggests the command to run next. It names the pending state by the first 12 characters of its hash, `a4c3fa7fc3b2`, which is the same hash the drawing shortens to 7 characters, `a4c3fa7`. -With `--db`, status reads the marker from the database and compares it with the target. With `--from`, it starts from the state you name instead and needs no database. +With `--db`, status reads the marker from the database and compares it with the target. With `--from`, it starts from the state you name instead. It then needs no database, unless `--from` or `--to` is `@db`. ### Warnings diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx index ba21e80df5a..0820418708e 100644 --- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx +++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx @@ -145,10 +145,8 @@ Not every command accepts every form. This table lists what each one accepts: | `migration plan --to` | a hash, a hash prefix, a ref name, a migration directory name, or `^` | | `migration new --from` | a hash, or a prefix of one, that an existing migration ends at | | `migration ref set ` | a hash, a hash prefix, a ref name, a migration directory name, or `^` | -| `migration status --from`, `--to` | a hash, a hash prefix, a ref name, a migration directory name, `^`, or `@empty` | -| `db migrate --to` | a hash, a hash prefix, a ref name, a migration directory name, or `^` | -| `db migrate --show --to` | a hash, a hash prefix, a ref name, a migration directory name, `^`, `@contract`, or `@empty` | -| `db migrate --show --from` | a hash, a hash prefix, a ref name, a migration directory name, `^`, `@contract`, `@db`, or `@empty` | +| `migration status --from`, `--to` | a hash, a hash prefix, a ref name, a migration directory name, `^`, `@contract`, `@db`, or `@empty` | +| `db migrate --to`, and `--from` with `--show` | a hash, a hash prefix, a ref name, a migration directory name, `^`, `@contract`, `@db`, or `@empty` | | `db update --to` | a hash, a hash prefix, a ref name, a migration directory name, or `^` | | `db sign [contract]`, `--contract` | a hash, a hash prefix, a ref name, a migration directory name, or `^` |