Schema Engine CLI

Command-line interface and JSON-RPC API for the Prisma Schema Engine binary

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
});

Related Documentation

Schema Engine Overview

Learn about the schema engine architecture

Migrations

Understand how migrations work

Introspection

Database schema introspection

Schema Core Library

Core API reference