Skip to main content

Documentation Index

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

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

The Schema Engine is the core component behind Prisma Migrate, responsible for managing database schemas, generating migrations, and performing introspection across all supported databases.

​
Architecture

The Schema Engine follows a Core/Connector architecture that enables consistent behavior across different database systems.

​
Core Layer

The schema-core crate (located in schema-engine/core) provides the high-level API exposed to all consumers. It’s a thin orchestration layer that:
  • Defines the unified API surface
  • Routes operations to appropriate connectors
  • Handles cross-connector concerns
  • Manages the JSON-RPC interface

​
Connector Layer

Each supported database has a dedicated connector implementing the SchemaConnector trait defined in the schema-connector crate. Most of the actual migration and introspection logic lives in these connectors:
  • SQL Schema Connector - PostgreSQL, MySQL, SQL Server, SQLite, CockroachDB
  • MongoDB Schema Connector - MongoDB (limited support in Prisma 7)
Connectors are currently built-in and live in schema-engine/connectors/.
All connectors implement the same API, ensuring consistent behavior regardless of the underlying database system.

​
Communication Interfaces

The Schema Engine can be invoked in two ways:

​
1. JSON-RPC API (Primary)

The default mode when running the schema-engine binary. The TypeScript CLI communicates with the engine over stdio using JSON-RPC, allowing:
  • Multiple commands on the same connection
  • Bidirectional communication
  • State management across operations
  • Real-time result streaming
# Start JSON-RPC server
schema-engine --datasource '{"url": "..."}'
See Schema Engine CLI for the complete list of available methods and commands.

​
2. CLI Commands (Legacy)

Direct CLI commands for operations that don’t require a database connection: 
schema-engine cli create-database
schema-engine cli drop-database
schema-engine cli can-connect-to-database
The CLI subcommand interface is legacy. The JSON-RPC API now connects lazily, eliminating most use cases for direct CLI commands.

​
Core Functionality

The Schema Engine provides two main blocks of functionality:

​
1. Traditional Migrations System

Like ActiveRecord migrations or Flyway, it manages migration files and tracks application state:
  • Creates and applies migration files (plain SQL on SQL databases)
  • Tracks migration history in the _prisma_migrations table
  • Detects failed migrations and drift
  • Supports migration resolution with migrate resolve

​
2. Schema Diffing & Generation

Like tools such as skeema, it understands database schemas and can generate migrations:
  • Compares Prisma schema (state A) with database schema (state B)
  • Generates migration to transform B → A
  • Powers migrate dev workflow
  • Enables schema introspection from existing databases
Diffing is the process of generating a migration between two schemas. The Schema Engine:
  1. Loads both the “from” schema and “to” schema
  2. Uses connector-specific logic to compare structures
  3. Generates DDL statements to transform one into the other
  4. Detects potentially destructive changes (data loss warnings)
  5. Renders the migration as SQL or a summary
The diffing algorithm is database-specific and lives in each connector.

​
Logging and Diagnostics

The Schema Engine outputs structured JSON logs to stderr. Each line contains: 
interface StdErrLine {
  timestamp: string;
  level: LogLevel;  // "INFO" | "ERROR" | "DEBUG" | "WARN"
  fields: LogFields;
}

interface LogFields {
  message: string;
  
  // Only for ERROR level messages
  is_panic?: boolean;
  error_code?: string;
  
  [key: string]: any;
}

​
Exit Codes

CodeMeaning
0Normal exit
1Abnormal (error) exit
101Panic (unrecoverable error)
All non-zero exit codes are accompanied by an ERROR-level log message on stderr.

​
Data Sources and Connection

In Prisma 7, datasource URLs are no longer embedded in the Prisma schema. Instead:
  • The --datasource CLI flag accepts a JSON payload with connection strings
  • The Prisma Config file (prisma.config.ts) supplies URLs at runtime
  • Schema Engine receives URLs as overrides, bypassing PSL parsing
schema-engine --datasource '{"url": "postgresql://...", "shadowDatabaseUrl": "postgresql://..."}'
The directUrl and shadowDatabaseUrl properties are invalid in the Prisma Schema Language (PSL) as of Prisma 7. These must be supplied via CLI overrides or the Prisma Config file.

​
Directory Structure

schema-engine/
├── cli/                    # Binary entry point and CLI commands
├── core/                   # Core orchestration logic
├── commands/               # Command implementations
├── connectors/
│   ├── schema-connector/   # Connector trait definitions
│   ├── sql-schema-connector/
│   └── mongodb-schema-connector/
├── json-rpc-api/           # JSON-RPC type definitions
├── sql-migration-tests/    # Integration tests (requires DBs)
└── sql-introspection-tests/

Migration System

Deep dive into the _prisma_migrations table and migration tracking

Introspection

Learn how database introspection works

Schema Diffing

Understand migration generation and schema comparison

CLI Reference

Complete CLI and JSON-RPC API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us