prisma/prisma

Migrate

Active contributors: jacek-prisma, Oleksii Orlenko

Purpose

packages/migrate implements the prisma migrate and prisma db namespaces — schema migrations, introspection, raw SQL execution, seeding, and reset. It owns the JSON-RPC client that talks to the Schema Engine (a Rust binary downloaded by @prisma/engines).

Despite living in its own package, the CLI dispatches Migrate commands seamlessly: when a user types prisma migrate dev, packages/cli delegates to MigrateCommand here.

Directory layout

packages/migrate/
├── src/
│   ├── bin.ts                         # Standalone Migrate CLI entry (used in dev)
│   ├── CLI.ts                         # Command dispatch for migrate/db namespaces
│   ├── Migrate.ts                     # High-level Migrate facade used by commands
│   ├── SchemaEngine.ts                # Engine contract used by both transports
│   ├── SchemaEngineCLI.ts             # Subprocess + stdio JSON-RPC transport
│   ├── SchemaEngineWasm.ts            # In-process Wasm transport variant
│   ├── commands/
│   │   ├── DbCommand.ts               # The `db` namespace top-level
│   │   ├── DbDrop.ts                  # prisma db drop
│   │   ├── DbExecute.ts               # prisma db execute (raw SQL)
│   │   ├── DbPull.ts                  # prisma db pull (introspection)
│   │   ├── DbPush.ts                  # prisma db push (no-history schema sync)
│   │   ├── DbSeed.ts                  # prisma db seed
│   │   ├── MigrateCommand.ts          # The `migrate` namespace top-level
│   │   ├── MigrateDeploy.ts           # prisma migrate deploy
│   │   ├── MigrateDev.ts              # prisma migrate dev
│   │   ├── MigrateDiff.ts             # prisma migrate diff
│   │   ├── MigrateReset.ts            # prisma migrate reset
│   │   ├── MigrateResolve.ts          # prisma migrate resolve
│   │   └── MigrateStatus.ts           # prisma migrate status
│   ├── types.ts                       # RPC request/response types
│   ├── utils/                         # Shared helpers (config, prompts, output)
│   ├── views/                         # Terminal output rendering
│   └── __tests__/                     # Jest tests + helpers + fixtures
├── fixtures/
│   └── blog/                          # Minimal example project for dev
├── prisma.config.ts
├── schema.prisma
├── jest.config.js
└── package.json

The prisma.config.ts and schema.prisma at the package root drive the dev fixture used by bin.ts.

Subcommand inventory

Command	Implementation	What it does
`prisma migrate dev`	`packages/migrate/src/commands/MigrateDev.ts`	Apply pending dev migrations and create new ones from schema diffs
`prisma migrate deploy`	`packages/migrate/src/commands/MigrateDeploy.ts`	Apply migrations in production (no schema diffing)
`prisma migrate diff`	`packages/migrate/src/commands/MigrateDiff.ts`	Show or emit a diff between two schema sources
`prisma migrate reset`	`packages/migrate/src/commands/MigrateReset.ts`	Drop the database and re-apply all migrations
`prisma migrate resolve`	`packages/migrate/src/commands/MigrateResolve.ts`	Mark a migration as applied or rolled back
`prisma migrate status`	`packages/migrate/src/commands/MigrateStatus.ts`	Report the database's current migration state
`prisma db pull`	`packages/migrate/src/commands/DbPull.ts`	Introspect a database and update the schema
`prisma db push`	`packages/migrate/src/commands/DbPush.ts`	Push the schema directly to the database (no history)
`prisma db drop`	`packages/migrate/src/commands/DbDrop.ts`	Drop the database referenced by the config
`prisma db execute`	`packages/migrate/src/commands/DbExecute.ts`	Run raw SQL or a SQL file against the database
`prisma db seed`	`packages/migrate/src/commands/DbSeed.ts`	Run the project's seed script
`prisma migrate ...` (top-level)	`packages/migrate/src/commands/MigrateCommand.ts`	Dispatch into the migrate subcommands
`prisma db ...` (top-level)	`packages/migrate/src/commands/DbCommand.ts`	Dispatch into the db subcommands

Schema Engine RPC

sequenceDiagram
    participant Cmd as MigrateDev / DbPull / etc.
    participant Migrate as Migrate.ts
    participant Engine as SchemaEngineCLI / SchemaEngineWasm
    participant Bin as schema-engine binary
    participant DB as Database

    Cmd->>Migrate: applyMigrations / introspect / diff
    Migrate->>Engine: rpc(method, params)
    Engine->>Bin: spawn / Wasm call
    Bin->>DB: SQL (DDL + DML)
    DB-->>Bin: results
    Bin-->>Engine: JSON-RPC response
    Engine-->>Migrate: typed result
    Migrate-->>Cmd: terminal output / structured result

Two engine transports share the contract in packages/migrate/src/SchemaEngine.ts:

SchemaEngineCLI — spawns the engine as a subprocess and exchanges JSON-RPC messages over stdio. The default. Largest of the two implementations (~21KB).
SchemaEngineWasm — runs the engine logic in-process via Wasm. Used in environments where spawning subprocesses is impractical (e.g., serverless dev tools).

Both transports speak the same RPC surface: applyMigrations, createMigration, devDiagnostic, diff, getDatabaseVersion, evaluateDataLoss, introspect, markMigrationApplied, markMigrationRolledBack, reset, schemaPush, etc.

How a single `migrate dev` flows

prisma migrate dev is parsed by packages/cli and dispatched to MigrateCommand.ts.
MigrateCommand resolves the dev subcommand to MigrateDev.ts.
MigrateDev loads prisma.config.ts via @prisma/config and the schema via @prisma/internals/@prisma/schema-files-loader.
It instantiates Migrate.ts, which constructs a SchemaEngineCLI connected to the resolved engine binary.
Through Migrate, it issues a sequence of RPC calls: devDiagnostic → optionally evaluateDataLoss and a confirmation prompt → createMigration and/or applyMigrations → optionally prisma generate (handled by spawning the CLI again).
Output is rendered through packages/migrate/src/views/.

Configuration

Prisma 7 connection settings come from prisma.config.ts. SQLite URLs in particular are resolved relative to the config file, not the schema file. Per AGENTS.md:

Migrate fixtures now provide one config per schema variant (e.g. invalid-url.config.ts next to prisma/invalid-url.prisma) and tests swap them via ctx.setConfigFile(...).

ctx.setDatasource() / ctx.resetDatasource() from __tests__/__helpers__/context.ts override the datasource URL for one CLI invocation when needed.

Test scaffolding

packages/migrate/src/__tests__/__helpers__/context.ts is the standard test harness for migrate tests. It exposes:

ctx.fs — virtual file system rooted at the test's temp directory
ctx.setConfigFile(name) — override the next CLI invocation's config; auto-reset
ctx.setDatasource(url) / ctx.resetDatasource() — override the datasource URL
Mocked stdio capture for asserting on terminal output

The same helpers are reused by CLI command tests (packages/cli/src/__tests__/) — Migrate's tests are the de facto pattern for any CLI subcommand test.

Integration points

@prisma/engines — engine binary download/resolution
@prisma/internals — schema loading (loadSchemaContext), DMMF, error rendering, prompts
@prisma/config — prisma.config.ts loader
@prisma/schema-files-loader — multi-file .prisma loading
@prisma/cli — invokes Migrate when the user types prisma migrate ... or prisma db ...

Entry points for modification

New migrate subcommand: add Migrate<Name>.ts in commands/, register in MigrateCommand.ts, add tests under __tests__/
New db subcommand: same pattern under DbCommand.ts
New RPC method: extend SchemaEngine.ts, then implement in both SchemaEngineCLI.ts and SchemaEngineWasm.ts (or add a fallback)
Output rendering: packages/migrate/src/views/