Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prisma/prisma-next/llms.txt

Use this file to discover all available pages before exploring further.

prisma-next migration apply executes previously planned migrations against a live database. It does not plan new migrations — run migration plan first to produce the packages. The command reads all attested packages from disk, reconstructs the migration graph, finds the shortest path from the current database marker to the destination hash, and executes each pending migration in order. Every migration runs in its own transaction with prechecks, postchecks, and idempotency checks enabled.

​
Options

​
--db
string
Database connection string. Defaults to config.db.connection if set in prisma-next.config.ts. Required if not set in config.
​
--ref
string
Target a named ref from migrations/refs.json instead of the current contract hash. Enables multi-environment workflows where staging and production track different points in the migration graph.
​
--config
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts in the current working directory.
​
--json
boolean
Emit a machine-readable JSON envelope instead of the default TTY output.
​
-q
boolean
Quiet mode — suppresses all output except errors.
​
-v
boolean
Verbose output — includes debug info and timings.

​
Config requirements

The migration apply command requires a driver in prisma-next.config.ts to connect to the database. A db.connection value or a --db flag must also be provided. 
import { defineConfig } from '@prisma-next/cli/config-types';
import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
import postgresAdapter from '@prisma-next/adapter-postgres/control';
import postgresDriver from '@prisma-next/driver-postgres/control';
import postgres from '@prisma-next/target-postgres/control';
import sql from '@prisma-next/family-sql/control';
import { contract } from './prisma/contract';

export default defineConfig({
  family: sql,
  target: postgres,
  adapter: postgresAdapter,
  driver: postgresDriver,
  extensionPacks: [],
  contract: typescriptContract(contract, 'src/prisma/contract.json'),
  db: {
    connection: process.env.DATABASE_URL,
  },
  migrations: {
    dir: 'migrations', // optional, defaults to 'migrations/'
  },
});

​
What it does

1

Load and verify migration packages

Reads every migration package from config.migrations.dir. Each package is attested — the loader rehashes (metadata, ops) and confirms the result matches the stored migrationHash. If a package has been hand-edited or partially written since emit, loading fails with MIGRATION.HASH_MISMATCH.
2

Reconstruct the migration graph

Builds a directed graph from all loaded packages using their start and end contract hashes as edges.
3

Determine the destination hash

If --ref <name> is provided, resolves the ref’s hash from migrations/refs.json. Otherwise reads the destination hash directly from contract.json.
4

Connect and read current marker

Opens a database connection using config.driver.create(url) and reads the current marker hash to determine where the database currently sits in the migration graph.
5

Find the path

Uses graph pathfinding to determine the shortest sequence of migration edges from the current marker hash to the destination hash.
6

Execute pending migrations

Runs each pending migration in order. Each migration executes in its own transaction with prechecks, postchecks, and idempotency checks enabled. After each migration the runner verifies the schema and updates the marker and ledger.

​
Hash attestation

Every migration package on disk is content-addressed. When migration apply loads a package, it independently recomputes the hash over (metadata, ops) and compares it against the stored migrationHash. If they differ — because the file was hand-edited, partially written, or corrupted — the load fails immediately: 
✖ MIGRATION.HASH_MISMATCH
  Migration at migrations/20240115120000-migration/ has been modified since it was emitted.
  Restore the original file from version control or re-run:
  node migrations/20240115120000-migration/migration.ts
Never hand-edit ops.json or migration.json directly. If you need to change the operations in a migration, edit migration.ts and re-run node migrations/<dir>/migration.ts to re-attest the package.

​
Resume semantics

If a migration fails mid-run, previously applied migrations are preserved. Re-running migration apply resumes from the last successfully applied migration — it will not re-execute migrations that already advanced the database marker.

​
Ref-based routing

--ref <name> targets the hash associated with a named ref rather than the current contract hash. This is the primary mechanism for multi-environment workflows: 
# Apply migrations up to the point tracked by the 'staging' ref
prisma-next migration apply --ref staging --db $STAGING_DATABASE_URL

# Apply migrations up to the point tracked by the 'production' ref
prisma-next migration apply --ref production --db $PRODUCTION_DATABASE_URL
Refs are managed with migration ref set/get/delete/list. See migration ref for details.

​
Examples

prisma-next migration apply --db postgresql://user:pass@localhost/mydb

​
Output format

TTY (migrations applied): 
prisma-next migration apply ➜ Apply pending migrations to the database
  config:     prisma-next.config.ts
  migrations: migrations/
  db:         postgresql://localhost/mydb

Applying 2 pending migration(s)...
  → [1/2] 20240115120000-add-user-roles  sha256:def456...
  → [2/2] 20240116090000-backfill-roles  sha256:789abc...
✔ Applied 2 migration(s)
  Database is now at: sha256:789abc...
TTY (already up to date): 
✔ No pending migrations — database is up to date
  Current marker: sha256:789abc...
JSON output: 
{
  "ok": true,
  "migrationsApplied": 2,
  "destination": "sha256:789abc...",
  "migrations": [
    {
      "dir": "migrations/20240115120000-add-user-roles",
      "migrationHash": "sha256:def456...",
      "status": "applied"
    },
    {
      "dir": "migrations/20240116090000-backfill-roles",
      "migrationHash": "sha256:789abc...",
      "status": "applied"
    }
  ],
  "timings": { "total": 312 }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us