prisma/prisma

Schema Engine RPC

The transport layer between prisma migrate / prisma db and the schema-engine binary. Both subprocess and in-process Wasm transports share a single contract.

Transports

graph LR
    Cmd[Migrate command] --> Migrate[Migrate.ts]
    Migrate --> Iface[SchemaEngine.ts<br/>contract]
    Iface --> CLI[SchemaEngineCLI.ts]
    Iface --> Wasm[SchemaEngineWasm.ts]
    CLI -->|spawn + stdio| Bin[schema-engine binary<br/>downloaded by @prisma/engines]
    Wasm -->|in-process| Mod[schema-engine-wasm module]
    Bin --> DB[(Database)]
    Mod --> DB

packages/migrate/src/SchemaEngine.ts defines the methods every transport implements. SchemaEngineCLI.ts (~~21KB, the production default) spawns the binary; SchemaEngineWasm.ts (~~11KB) runs the schema engine in-process via Wasm.

Both speak the same JSON-RPC method surface, so the rest of @prisma/migrate doesn't care which is in use.

JSON-RPC over stdio

SchemaEngineCLI uses Node's child_process.spawn:

sequenceDiagram
    participant Migrate as Migrate.ts
    participant CLI as SchemaEngineCLI
    participant Bin as schema-engine

    Migrate->>CLI: instantiate (spawn)
    CLI->>Bin: spawn(['--datamodel-source-file', ...])
    Bin-->>CLI: ready
    Migrate->>CLI: rpc('introspect', {...})
    CLI->>Bin: stdin: {jsonrpc:'2.0', id:1, method:'introspect', params:{...}}
    Bin->>Bin: introspect database
    Bin-->>CLI: stdout: {jsonrpc:'2.0', id:1, result:{...}}
    CLI-->>Migrate: typed result
    Migrate->>CLI: dispose
    CLI->>Bin: SIGTERM

Per-method input/output types are in packages/migrate/src/types.ts. The transport handles ID assignment, error mapping (RPC errors → typed exceptions), and process lifecycle.

Methods

The full list, defined in packages/migrate/src/types.ts:

Method	Used by
`applyMigrations`	`migrate dev`, `migrate deploy`
`createMigration`	`migrate dev`
`devDiagnostic`	`migrate dev`
`diff`	`migrate diff`
`evaluateDataLoss`	`migrate dev` / `migrate reset`
`getDatabaseVersion`	`migrate status`
`introspect`	`db pull`
`markMigrationApplied`	`migrate resolve --applied`
`markMigrationRolledBack`	`migrate resolve --rolled-back`
`reset`	`migrate reset`, `migrate dev` (when needed)
`schemaPush`	`db push`

The Wasm transport supports the same set, with one caveat: methods that write SQL files (createMigration) need the host environment to provide a filesystem; the CLI subprocess writes files directly.

Error semantics

RPC errors come back as JSON-RPC error objects. Migrate.ts translates well-known engine error codes into typed exceptions; unmapped codes propagate as generic engine errors. The CLI subcommands render them through packages/migrate/src/views/.

Engine resolution

The binary path comes from @prisma/engines.getEnginesPath(), which (via @prisma/fetch-engine and @prisma/get-platform) resolves to the platform-appropriate downloaded binary. If you have a development override in packages/fetch-engine/package.json's enginesOverride, it points to a local build instead. See engines.

Forced panics for testing

From CONTRIBUTING.md, environment variables can force panics in the engine for testing the error paths:

FORCE_PANIC_SCHEMA_ENGINE=1 npx prisma migrate dev
FORCE_PANIC_PRISMA_SCHEMA=1 npx prisma format
FORCE_PANIC_GET_DMMF=1 npx prisma validate
FORCE_PANIC_GET_CONFIG=1 npx prisma validate

These are useful when verifying that Migrate.ts and packages/internals correctly handle hard engine failures.