Skip to main content
The schema-engine binary provides database migration and introspection capabilities for Prisma. It can run as a JSON-RPC server over stdin/stdout or execute standalone CLI commands.

​
Binary Location

After building: 
./target/debug/schema-engine     # Debug build
./target/release/schema-engine   # Release build

​
Interfaces

The schema engine provides two interfaces:
  1. JSON-RPC Server (default) - For interactive communication from the Prisma CLI
  2. CLI Commands - For standalone database operations

​
JSON-RPC Server Mode

When run without arguments, the schema engine starts as a JSON-RPC server: 
schema-engine

​
Command Line Options

​
--datamodels
string[]
default:"[]"
List of paths to Prisma schema files
​
--datasource
JSON
default:"{}"
Optional JSON string to override datasource URLs in the schema. Format:
{
  "url": "postgresql://user:pass@localhost:5432/db",
  "directUrl": "postgresql://...",
  "shadowDatabaseUrl": "postgresql://..."
}
​
--extension-types
JSON
Optional extension type configuration for TypedSQL and other extensions

​
JSON-RPC Methods

The schema engine exposes these JSON-RPC methods:

​
Migration Operations

  • createMigration - Generate a new migration from schema changes
  • applyMigrations - Apply pending migrations to the database
  • unapplyMigration - Revert the last migration
  • listMigrationDirectories - List all migrations in the migrations directory
  • markMigrationApplied - Mark a migration as applied without running it
  • markMigrationRolledBack - Mark a migration as rolled back
  • devDiagnostic - Analyze migration history for development
  • diagnoseMigrationHistory - Check migration history status
  • evaluateDataLoss - Analyze potential data loss in pending migrations

​
Schema Operations

  • schemaPush - Push schema changes without creating migrations
  • reset - Reset the database to a clean state
  • introspect - Generate a Prisma schema from an existing database

​
Database Operations

  • createDatabase - Create a new database
  • dropDatabase - Drop the database
  • ensureConnectionValidity - Test database connection

​
Diffing Operations

  • diff - Compare two schemas and generate a migration script

​
CLI Commands

Standalone commands that don’t require a running server: 
schema-engine cli <SUBCOMMAND>

​
create-database

Create an empty database defined in the connection string: 
schema-engine cli create-database \
  --datasource '{"url":"postgresql://localhost:5432/mydb"}'
Output: Database 'mydb' was successfully created.

​
can-connect-to-database

Test if the database connection string works: 
schema-engine cli can-connect-to-database \
  --datasource '{"url":"postgresql://localhost:5432/mydb"}'
Output: Connection successful

​
drop-database

Drop the database: 
schema-engine cli drop-database \
  --datasource '{"url":"postgresql://localhost:5432/mydb"}'
This permanently deletes all data in the database. Use with caution.
Output: The database was successfully dropped.

​
Logging and Error Reporting

The schema engine outputs structured JSON logs to stderr: 
interface StdErrLine {
  timestamp: string;
  level: "INFO" | "ERROR" | "DEBUG" | "WARN";
  fields: LogFields;
}

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

​
Log Levels

Control logging with the RUST_LOG environment variable: 
# Show all logs
RUST_LOG=debug schema-engine

# Show only schema-core logs
RUST_LOG=schema_core=debug schema-engine

# Show specific module
RUST_LOG=sql_migration=trace schema-engine

​
Exit Codes

​
0
exit code
Normal exit - operation completed successfully
​
1
exit code
Abnormal exit - operation failed with an error
​
101
exit code
Panic - the engine crashed due to an unrecoverable error
Non-zero exit codes are always accompanied by an ERROR-level log message on stderr.

​
Environment Variables

​
PRISMA_GRACEFUL_SHUTDOWN_TIMEOUT
milliseconds
default:"4000"
Timeout for graceful shutdown of async tasks on SIGTERM
​
PRISMA_BLOCKING_TASKS_SHUTDOWN_TIMEOUT
milliseconds
default:"200"
Deadline for blocking background tasks during shutdown
​
RUST_LOG
string
Configure logging verbosity (e.g., debug, schema_core=trace)

​
Building the Binary

1

Build with Cargo

# Debug build
cargo build -p schema-engine-cli

# Release build (optimized)
cargo build --release -p schema-engine-cli
2

Find the binary

# Debug
./target/debug/schema-engine

# Release
./target/release/schema-engine
3

Test it

./target/debug/schema-engine --version

​
Integration with Prisma CLI

The TypeScript Prisma CLI spawns the schema-engine binary and communicates via JSON-RPC: 
// Prisma CLI spawns the process
const schemaEngine = spawn('schema-engine', [
  '--datamodels', schemaPath,
  '--datasource', JSON.stringify(datasourceUrls)
]);

// Send JSON-RPC requests to stdin
schemaEngine.stdin.write(JSON.stringify({
  jsonrpc: '2.0',
  id: 1,
  method: 'createMigration',
  params: { ... }
}));

// Receive responses from stdout
schemaEngine.stdout.on('data', (data) => {
  const response = JSON.parse(data);
  // Handle response
});

Schema Engine Overview

Learn about the schema engine architecture

Migrations

Understand how migrations work

Introspection

Database schema introspection

Schema Core Library

Core API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us