Prisma Cli

Prisma CLI Reference

Complete reference for Prisma ORM CLI commands. This skill provides guidance on command usage, options, and best practices for current Prisma releases.

Boundary: Compute

Do not use this skill for Prisma Compute app deployment. Use prisma-compute for @prisma/cli app deploy, compute:deploy, create-prisma --deploy, Compute apps, deployments, logs, domains, and framework deploy readiness.

When to Apply

Reference this skill when:

• Setting up a new Prisma project (prisma init)
• Generating Prisma Client (prisma generate)
• Running database migrations (prisma migrate)
• Managing database state (prisma db push/pull)
• Using local development database (prisma dev)
• Debugging Prisma issues (prisma debug)

Rule Categories by Priority

Command Categories

Quick Reference

Project Setup

# Initialize new project (creates prisma/ folder and prisma.config.ts)
prisma init

# Bootstrap a Prisma Postgres project or starter
prisma bootstrap

# Initialize with specific database
prisma init --datasource-provider postgresql
prisma init --datasource-provider mysql
prisma init --datasource-provider sqlite

# Initialize with Prisma Postgres (cloud)
prisma init --db

# Initialize with an example model
prisma init --with-model

# Link an existing local project to Prisma Postgres
prisma postgres link

Client Generation

# Generate Prisma Client
prisma generate

# Watch mode for development
prisma generate --watch

# Generate specific generator only
prisma generate --generator client

Bun Runtime

When using Bun, always add the --bun flag so Prisma runs with the Bun runtime (otherwise it falls back to Node.js because of the CLI shebang):

bunx --bun prisma init
bunx --bun prisma generate

Local Development Database

# Start local Prisma Postgres
prisma dev

# Start with specific name
prisma dev --name myproject

# Start in background (detached)
prisma dev --detach

# List all local instances
prisma dev ls

# Stop instance
prisma dev stop myproject

# Remove instance data
prisma dev rm myproject

Database Operations

# Pull schema from existing database
prisma db pull

# Push schema to database (no migrations)
prisma db push

# Seed database
prisma db seed

# Execute raw SQL
prisma db execute --file ./script.sql

Migrations (Development)

# Create and apply migration
prisma migrate dev

# Create migration with name
prisma migrate dev --name add_users_table

# Create migration without applying
prisma migrate dev --create-only

# Reset database and apply all migrations
prisma migrate reset

Migrations (Production)

# Apply pending migrations (CI/CD)
prisma migrate deploy

# Check migration status
prisma migrate status

# Compare schemas and generate diff
prisma migrate diff --from-config-datasource --to-schema schema.prisma --script

Utility Commands

# Open Prisma Studio (database GUI)
prisma studio

# Start Prisma's MCP server for AI tools
prisma mcp

# Show version info
prisma version
prisma -v

# Debug information
prisma debug

# Validate schema
prisma validate

# Format schema
prisma format

Current Prisma CLI Setup

New Configuration File

Use prisma.config.ts for CLI configuration:

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

Current Command Behavior

• The current migrate dev implementation applies migrations and does not call prisma generate or prisma db seed; run those explicitly when needed.
• The current migrate reset implementation resets and reapplies migrations; run prisma generate and prisma db seed explicitly when needed.
• Use prisma db execute --file ... for raw SQL scripts

Environment Variables

Load environment variables explicitly in prisma.config.ts, commonly with dotenv:

// prisma.config.ts
import 'dotenv/config'

Rule Files

See individual rule files for detailed command documentation:

references/init.md           - Project initialization
references/bootstrap.md      - Prisma Postgres project bootstrap
references/generate.md       - Client generation
references/dev.md            - Local development database
references/db-pull.md        - Database introspection
references/db-push.md        - Schema push
references/db-seed.md        - Database seeding
references/db-execute.md     - Raw SQL execution
references/migrate-dev.md    - Development migrations
references/migrate-deploy.md - Production migrations
references/migrate-reset.md  - Database reset
references/migrate-status.md - Migration status
references/migrate-resolve.md - Migration resolution
references/migrate-diff.md   - Schema diffing
references/studio.md         - Database GUI
references/mcp.md            - Prisma MCP server
references/postgres-link.md  - Prisma Postgres project linking
references/validate.md       - Schema validation
references/format.md         - Schema formatting
references/debug.md          - Debug info

How to Use

Use the command categories above for navigation, then open the specific command reference file you need.

prisma bootstrap

Bootstraps a Prisma Postgres project from scratch or connects an existing project.

Command

prisma bootstrap [options]

Options

When using --api-key, also provide --database.

Examples

Interactive bootstrap

prisma bootstrap

Non-interactive link

prisma bootstrap --api-key "<your-api-key>" --database "db_..."

With starter template

prisma bootstrap --template nextjs

Behavior

The command can initialize a Prisma project, scaffold a supported starter template, link to Prisma Postgres, install dependencies, run generation, run migrations, and run seed steps when applicable.

Supported template names in the current source include nextjs, express, hono, fastify, nuxt, sveltekit, remix, react-router-7, astro, and nest.

prisma db execute

Execute native commands (SQL) to your database.

Command

prisma db execute [options]

What It Does

• Connects to your database using the configured datasource
• Executes a script provided via file (--file) or stdin (--stdin)
• Useful for running raw SQL, maintenance tasks, or applying diffs from migrate diff
• Not supported on MongoDB

Options

Current Option Surface

prisma db execute uses the datasource configured in prisma.config.ts. Use --config if you need a separate config file for another environment.

Examples

Execute from file

prisma db execute --file ./script.sql

Execute from stdin

echo "TRUNCATE TABLE User;" | prisma db execute --stdin

Execute migrate diff output

Pipe the output of migrate diff directly to the database:

prisma migrate diff \
  --from-empty \
  --to-schema prisma/schema.prisma \
  --script \
| prisma db execute --stdin

Configuration

Uses datasource from prisma.config.ts:

export default defineConfig({
  datasource: {
    url: env('DATABASE_URL'),
  },
})

Use Cases

• Manual Migrations: Applying raw SQL changes
• Data Maintenance: Truncating tables, cleaning up data
• Schema Synchronization: Applying migrate diff scripts
• Debugging: Running test queries (though typically not for fetching data)

Limitations

• No Data Return: The command reports success/failure, not query results (rows). Use Prisma Client or prisma studio to view data.
• SQL Only: Primarily for SQL databases.

prisma db pull

Introspects an existing database and updates your Prisma schema to reflect its structure.

Command

prisma db pull [options]

What It Does

• Connects to your database
• Reads the database schema (tables, columns, relations, indexes)
• Updates schema.prisma with corresponding Prisma models
• For MongoDB, samples data to infer schema

Options

Examples

Basic introspection

prisma db pull

Preview without writing

prisma db pull --print

Outputs schema to terminal for review.

Force overwrite

prisma db pull --force

Replaces schema file, losing any manual customizations.

Prerequisites

Configure database connection in prisma.config.ts:

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

Workflow

Starting from existing database

1. Initialize Prisma:

   prisma init

2. Configure database URL

3. Pull schema:

   prisma db pull

4. Review and customize generated schema

5. Generate client:

   prisma generate

Syncing changes from database

When database changes are made outside Prisma:

prisma db pull
prisma generate

Generated Schema Example

Database tables become Prisma models:

-- Database tables
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(100)
);

CREATE TABLE posts (
  id SERIAL PRIMARY KEY,
  title VARCHAR(255) NOT NULL,
  author_id INTEGER REFERENCES users(id)
);

Becomes:

model users {
  id    Int     @id @default(autoincrement())
  email String  @unique @db.VarChar(255)
  name  String? @db.VarChar(100)
  posts posts[]
}

model posts {
  id        Int    @id @default(autoincrement())
  title     String @db.VarChar(255)
  author_id Int?
  users     users? @relation(fields: [author_id], references: [id])
}

Post-Introspection Cleanup

After db pull, consider:

1. Rename models to PascalCase:

   model User {  // Was: users
     @@map("users")
   }

2. Rename fields to camelCase:

   authorId Int? @map("author_id")

3. Add relation names for clarity:

   author User? @relation("PostAuthor", fields: [authorId], references: [id])

4. Add documentation:

   /// User account information
   model User {
     /// Primary email for authentication
     email String @unique
   }

MongoDB Introspection

For MongoDB, db pull samples documents to infer schema:

prisma db pull

May require manual refinement since MongoDB is schemaless.

Warning

db pull overwrites your schema file. Always:

• Commit current schema before pulling
• Use --print to preview first
• Backup customizations you want to keep

prisma db push

Pushes schema changes directly to database without creating migrations. Ideal for prototyping.

Command

prisma db push [options]

What It Does

• Syncs your Prisma schema to the database
• Creates database if it doesn't exist
• Does NOT create migration files
• Does NOT track migration history

Options

Follow-up Command

• Run prisma generate explicitly when you need refreshed client output

Examples

Basic push

prisma db push

Accept data loss

prisma db push --accept-data-loss

Required when changes would delete data (dropping columns, etc.)

Force reset

prisma db push --force-reset

Completely resets database and applies schema.

Full workflow

prisma db push
prisma generate

When to Use

• Prototyping - Rapid schema iteration
• Local development - Quick schema changes
• MongoDB - Primary workflow (migrations not supported)
• Testing - Setting up test databases

When NOT to Use

• Production - Use migrate deploy
• Team collaboration - Use migrations for trackable changes
• When you need rollback - Migrations provide history

Comparison with migrate dev

MongoDB Workflow

MongoDB doesn't support migrations. Use db push exclusively:

# Schema changes for MongoDB
prisma db push
prisma generate

Common Patterns

Prototyping workflow

# Make schema changes
# ...

# Push to database
prisma db push

# Generate client
prisma generate

# Test your changes
# Repeat as needed

Reset and start fresh

prisma db push --force-reset
prisma db seed

Handling conflicts

If db push can't apply changes safely:

Error: The following changes cannot be applied:
  - Removing field `email` would cause data loss
  
Use --accept-data-loss to proceed

Decide whether data loss is acceptable, then:

prisma db push --accept-data-loss

Transition to Migrations

When ready for production, switch to migrations:

# Create baseline migration from current schema
prisma migrate dev --name init

Then use migrate dev for future changes.

prisma db seed

Runs your database seed script to populate data.

Command

prisma db seed [options]

What It Does

• Executes your configured seed script
• Populates database with initial/test data
• Runs independently (not auto-run by migrations in v7)

Options

Configuration

Configure seed script in prisma.config.ts:

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',  // Your seed command
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

Common seed commands

// TypeScript with tsx
seed: 'tsx prisma/seed.ts'

// TypeScript with ts-node
seed: 'ts-node prisma/seed.ts'

// JavaScript
seed: 'node prisma/seed.js'

Seed Script Example

// prisma/seed.ts
import { PrismaClient } from '../generated/client'

const prisma = new PrismaClient()

async function main() {
  // Create users
  const alice = await prisma.user.upsert({
    where: { email: 'alice@prisma.io' },
    update: {},
    create: {
      email: 'alice@prisma.io',
      name: 'Alice',
      posts: {
        create: {
          title: 'Hello World',
          published: true,
        },
      },
    },
  })

  const bob = await prisma.user.upsert({
    where: { email: 'bob@prisma.io' },
    update: {},
    create: {
      email: 'bob@prisma.io',
      name: 'Bob',
    },
  })

  console.log({ alice, bob })
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

Examples

Run seed

prisma db seed

With custom arguments

prisma db seed -- --environment development

Arguments after -- are passed to your seed script.

Current Workflow

Run seeding explicitly after migrations when you need seed data:

prisma migrate dev --name init
prisma generate
prisma db seed  # Must run explicitly

Idempotent Seeding

Use upsert to make seeds re-runnable:

// Good: Can run multiple times
await prisma.user.upsert({
  where: { email: 'alice@prisma.io' },
  update: {},  // Don't change existing
  create: { email: 'alice@prisma.io', name: 'Alice' },
})

// Bad: Fails on second run
await prisma.user.create({
  data: { email: 'alice@prisma.io', name: 'Alice' },
})

Common Patterns

Development reset

prisma migrate reset --force
prisma db seed

Conditional seeding

// prisma/seed.ts
const count = await prisma.user.count()
if (count === 0) {
  // Only seed if empty
  await seedUsers()
}

Environment-specific seeds

// prisma/seed.ts
const env = process.env.NODE_ENV || 'development'

if (env === 'development') {
  await seedDevData()
} else if (env === 'test') {
  await seedTestData()
}

Best Practices

1. Use upsert for idempotent seeds 2. Keep seeds focused and minimal 3. Use realistic but fake data 4. Document required seed data 5. Version control your seed scripts

prisma debug

Prints information helpful for debugging and bug reports.

Command

prisma debug [options]

What It Does

Outputs debugging context from the current project and process:

• Prisma schema path or schema lookup error
• Local engine cache directory
• Relevant environment variables, grouped by purpose
• Whether the terminal is interactive
• Whether CI was detected

Options

Example Output Shape

-- Prisma schema --
Path: prisma/schema.prisma

-- Local cache directory for engines files --
Path: ...

-- Environment variables --
...

-- Terminal is interactive? --
true

-- CI detected? --
false

When to Use

• Troubleshooting: Checking version mismatches
• Reporting Issues: Including environment info in GitHub issues
• Verifying Installation: Ensuring correct binaries are downloaded

prisma dev

Starts a local Prisma Postgres database for development. Provides a PostgreSQL-compatible database that runs entirely on your machine.

Command

prisma dev [options]

What It Does

• Starts a local PostgreSQL-compatible database
• Runs in your terminal or as a background process
• Perfect for development and testing
• Easy migration to Prisma Postgres cloud in production

Options

Examples

Start local database

prisma dev

Interactive mode with keyboard shortcuts:

• q - Quit
• h - Show HTTP URL
• t - Show TCP URLs

Named instance

prisma dev --name myproject

Useful for multiple projects.

Background mode

prisma dev --detach

Frees your terminal for other commands.

Custom ports

prisma dev --port 5000 --db-port 5432

Instance Management

List all instances

prisma dev ls

Shows all local Prisma Postgres instances with status.

Start existing instance

prisma dev start myproject

Starts a previously created instance in background.

Stop instance

prisma dev stop myproject

Stop with glob pattern

prisma dev stop "myproject*"

Stops all instances matching pattern.

Remove instance

prisma dev rm myproject

Removes instance data from filesystem.

Force remove (stops first)

prisma dev rm myproject --force

Configuration

Configure your prisma.config.ts to use local Prisma Postgres:

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    // Local Prisma Postgres URL (from prisma dev output)
    url: env('DATABASE_URL'),
  },
})

Workflow

1. Start local database:

   prisma dev

2. In another terminal, run migrations:

   prisma migrate dev

3. Generate client:

   prisma generate

4. Run your application

Production Migration

When ready for production, switch to Prisma Postgres cloud:

prisma init --db

Update your DATABASE_URL to the cloud connection string.

prisma format

Formats your Prisma schema file.

Command

prisma format [options]

What It Does

• Fixes formatting (indentation, spacing)
• Adds missing back-relations (e.g., adds the other side of a relation)
• Adds missing relation arguments (e.g., fields, references)
• Sorts fields and attributes (opinionated)

Options

Examples

Format default schema

prisma format

Format specific schema

prisma format --schema=./custom/schema.prisma

Check formatting

prisma format --check

Behavior

prisma format modifies the file in place. It is equivalent to "Prettier for Prisma schemas" but also has semantic understanding to fix/add missing schema definitions.

Use in Editor

Most Prisma editor extensions (VS Code, WebStorm) run prisma format automatically on save. This command is useful for:

• CI pipelines (check formatting)
• CLI-based workflows
• Fixing large schema refactors

prisma generate

Generates assets based on the generator blocks in your Prisma schema, most commonly Prisma Client.

Command

prisma generate [options]

Bun Runtime

If you're using Bun, run Prisma with bunx --bun so it doesn't fall back to Node.js:

bunx --bun prisma generate

What It Does

1. Reads your schema.prisma file 2. Generates a customized Prisma Client based on your models 3. Outputs to the directory specified in the generator block

Options

Examples

Basic generation

prisma generate

Watch mode (development)

prisma generate --watch

Auto-regenerates when schema.prisma changes.

Specific generator

prisma generate --generator client

Multiple generators

prisma generate --generator client --generator zod_schemas

Typed SQL generation

prisma generate --sql

Schema Configuration

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

Current Generator Behavior

• prisma-client is the standard generator
• output is required when using prisma-client
• prisma-client supports both ESM and CommonJS via moduleFormat
• compilerBuild supports fast and small query compiler artifacts
• Use TypeScript satisfies for typed query fragments with prisma-client
• Import Prisma Client from your generated output path, for example:

import { PrismaClient } from '../generated/prisma/client'

Compiler Build Tuning

Use compilerBuild when you need to trade artifact size against the default build:

generator client {
  provider      = "prisma-client"
  output        = "../generated"
  compilerBuild = "small"
}

• fast is the default build for most targets
• small is useful for size-constrained targets
• Prisma defaults vercel-edge targets to small

Common Patterns

After schema changes

prisma migrate dev --name my_migration
prisma generate

Run prisma generate whenever you need refreshed client code after schema-changing commands.

CI/CD pipeline

prisma generate

Run before building your application.

Multiple generators

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

generator zod {
  provider = "zod-prisma-types"
  output   = "../generated/zod"
}

prisma generate  # Runs all generators

Output Structure

After running prisma generate, your output directory contains:

generated/
├── browser.ts
├── client.ts
├── commonInputTypes.ts
├── models/
├── enums.ts
├── models.ts
└── ...

Import the client:

import { PrismaClient, Prisma } from '../generated/prisma/client'

Import browser-safe types:

import { Prisma } from '../generated/prisma/browser'
import { Role } from '../generated/prisma/enums'
import type { UserModel } from '../generated/prisma/models/User'

prisma init

Bootstraps a fresh Prisma ORM project in the current directory.

Command

prisma init [options]

Bun Runtime

If you're using Bun, run Prisma with bunx --bun so it doesn't fall back to Node.js:

bunx --bun prisma init

What It Creates

• prisma/schema.prisma - Your Prisma schema file
• prisma.config.ts - TypeScript configuration for Prisma CLI
• .env - Environment variables (DATABASE_URL)
• .gitignore - Ensures .env is ignored and appends the generated client path

Options

Examples

Basic initialization

prisma init

Creates a PostgreSQL project setup.

SQLite project

prisma init --datasource-provider sqlite

MySQL with custom URL

prisma init --datasource-provider mysql --url "mysql://user:password@localhost:3306/mydb"

Prisma Postgres (cloud)

prisma init --db

Opens browser for authentication, creates cloud database instance.

Add an example model

prisma init --with-model

Adds a starter model to the generated schema.

With preview features

prisma init --preview-feature relationJoins --preview-feature fullTextSearch

Generated Schema

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

Generated Config (Node.js default)

// prisma.config.ts
import "dotenv/config";
import { defineConfig } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: process.env['DATABASE_URL'],
  },
})

Generated Config (Bun)

import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

Next Steps After Init

1. Configure DATABASE_URL in .env (and let prisma.config.ts read it) 2. Define your models in prisma/schema.prisma 3. Run prisma dev for local development or connect to remote DB 4. Run prisma migrate dev to create migrations 5. Run prisma generate to generate Prisma Client 6. Run prisma db seed explicitly if you want seed data

prisma mcp

Starts Prisma's MCP server for AI development tools.

Command

prisma mcp

What It Does

• Starts a Model Context Protocol (MCP) server for your Prisma project
• Wraps selected Prisma CLI workflows for compatible AI tools
• Exposes tools for migration status, development migrations, migration reset, and Prisma Studio

Usage

prisma mcp

The current help surface also accepts:

prisma mcp --early-access

Typical Use Cases

• Connect Prisma to ChatGPT, Claude, or other MCP-aware tools
• Let an AI assistant run Prisma migration and Studio workflows through MCP
• Help an agent inspect migration status and apply development migrations with project context

Notes

• Run this from the project that contains your Prisma schema and prisma.config.ts
• The command is separate from Prisma Studio and does not open a browser UI
• The MCP server wraps Prisma CLI commands. For exact behavior of commands like migrate dev or migrate reset, follow the underlying CLI command docs rather than relying only on the MCP tool descriptions.

References

• Prisma CLI `mcp` command
• Prisma MCP Server

prisma migrate deploy

Applies pending migrations in production/staging environments.

Command

prisma migrate deploy

What It Does

• Applies all pending migrations from prisma/migrations/
• Updates _prisma_migrations table
• Does NOT generate new migrations
• Does NOT run seed scripts
• Safe for CI/CD and production

Options

When to Use

• Production deployments
• Staging environments
• CI/CD pipelines
• Any non-development environment

Examples

Basic deployment

prisma migrate deploy

In CI/CD pipeline

# GitHub Actions example
- name: Apply migrations
  run: npx prisma migrate deploy
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

Docker deployment

# Run migrations before starting app
CMD npx prisma migrate deploy && node dist/index.js

Comparison with migrate dev

Production Workflow

1. Development: Create migrations locally

   prisma migrate dev --name add_feature

2. Commit: Include migration files in version control

   git add prisma/migrations
   git commit -m "Add feature migration"

3. Deploy: Apply in production

   prisma migrate deploy

Error Handling

Failed migration

If a migration fails, migrate deploy exits with error. The failed migration is marked as failed in _prisma_migrations.

To fix: 1. Resolve the issue (fix SQL, database state, etc.) 2. Mark as resolved: prisma migrate resolve --applied <migration_name> 3. Re-run: prisma migrate deploy

Check status first

prisma migrate status

Shows pending and applied migrations before deploying.

Configuration

Ensure prisma.config.ts has the production database URL:

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  datasource: {
    url: env('DATABASE_URL'),
  },
})

Best Practices

1. Always run migrate status before migrate deploy in CI 2. Have a rollback plan (backup before migrations) 3. Test migrations in staging first 4. Never use migrate dev in production

prisma migrate dev

Creates and applies migrations during development. Requires a shadow database.

Command

prisma migrate dev [options]

What It Does

1. Runs existing migrations in shadow database to detect drift 2. Applies any pending migrations 3. Generates new migration from schema changes 4. Applies new migration to development database 5. Updates _prisma_migrations table

Options

Follow-up Commands

• Run prisma generate explicitly when you need refreshed client output
• Run prisma db seed explicitly when you need seed data

Note: the official CLI help still says migrate dev "trigger[s] generators", but the current implementation applies migrations and returns without invoking prisma generate or prisma db seed. Treat both as explicit follow-up commands when you need generated artifacts or seed data.

Examples

Create and apply migration

prisma migrate dev

Prompts for migration name if schema changed.

Named migration

prisma migrate dev --name add_users_table

Create without applying

prisma migrate dev --create-only

Useful for reviewing migration SQL before applying.

Full workflow

prisma migrate dev --name my_migration
prisma generate
prisma db seed

Migration Files

Created in prisma/migrations/:

prisma/migrations/
├── 20240115120000_add_users_table/
│   └── migration.sql
├── 20240116090000_add_posts/
│   └── migration.sql
└── migration_lock.toml

Schema Drift Detection

If migrate dev detects drift (manual database changes or edited migrations), it prompts to reset:

Drift detected: Your database schema is not in sync.

Do you want to reset your database? All data will be lost.

When to Use

• Local development
• Adding new models/fields
• Changing relations
• Creating indexes

When NOT to Use

• Production deployments (use migrate deploy)
• CI/CD pipelines (use migrate deploy)
• MongoDB (use db push instead)

Common Patterns

After schema changes

// schema.prisma - Add new field
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())  // New field
}

prisma migrate dev --name add_created_at

Handling data loss warnings

When a migration would cause data loss:

prisma migrate dev --name remove_field
# Warning: You are about to delete data...
# Confirm interactively, or use --create-only and review/edit the SQL first.

Shadow Database

migrate dev requires a shadow database for drift detection. Configure in prisma.config.ts:

export default defineConfig({
  datasource: {
    url: env('DATABASE_URL'),
    shadowDatabaseUrl: env('SHADOW_DATABASE_URL'),
  },
})

For local Prisma Postgres (prisma dev), shadow database is handled automatically.

prisma migrate diff

Compares database schemas and generates diffs (SQL or summary).

Command

prisma migrate diff [options]

What It Does

• Compares two sources (--from-... and --to-...)
• Sources can be:
• Empty (empty)
• Schema file (schema)
• Migrations directory (migrations)
• Configured datasource (config-datasource)
• Outputs the difference:
• Human-readable summary (default)
• SQL script (--script)

Options

Sources (Must provide one from and one to)

• --from-empty, --to-empty
• --from-schema <path>, --to-schema <path>
• --from-migrations <path>, --to-migrations <path>
• --from-config-datasource, --to-config-datasource (uses prisma.config.ts)

Removed older URL flags such as --from-url and --to-url are parsed only to show a help error. Use --from-config-datasource or --to-config-datasource with prisma.config.ts instead.

Examples

Generate SQL for a schema change

Compare the configured datasource to your local schema:

prisma migrate diff \
  --from-config-datasource \
  --to-schema ./prisma/schema.prisma \
  --script

Review pending migrations

Compare database state to migrations directory:

prisma migrate diff \
  --from-config-datasource \
  --to-migrations ./prisma/migrations

Create baseline migration

Compare empty state to current schema:

prisma migrate diff \
  --from-empty \
  --to-schema ./prisma/schema.prisma \
  --script > prisma/migrations/0_init/migration.sql

Check for drift (CI)

Check if database matches schema:

prisma migrate diff \
  --from-config-datasource \
  --to-schema ./prisma/schema.prisma \
  --exit-code

Use Cases

• Forward-generating migrations: Creating SQL without migrate dev.
• Drift detection: Checking if DB is in sync.
• Baselining: Creating initial migration from existing DB.
• Debugging: Understanding what migrate dev would do.

prisma migrate reset

Resets your database and re-applies all migrations.

Command

prisma migrate reset [options]

What It Does

1. Drops the database (if possible) or deletes all data/tables 2. Re-creates the database 3. Applies all migrations from prisma/migrations/ 4. Stops there - run seed and generate explicitly if needed

Warning: All data will be lost.

Options

Examples

Basic reset

prisma migrate reset

Prompts for confirmation in interactive terminals.

Force reset (CI/Automation)

prisma migrate reset --force

With custom schema

prisma migrate reset --schema=./custom/schema.prisma

When to Use

• Development: When you want a fresh start
• Testing: Resetting test database before suites
• Drift Recovery: When the database is out of sync and you can't migrate

Follow-up Steps

Run prisma generate and prisma db seed explicitly when you need refreshed client output or seed data after a reset.

Configuration

Configure the seed script in prisma.config.ts, then run it explicitly after reset:

export default defineConfig({
  migrations: {
    seed: 'tsx prisma/seed.ts',
  },
})

Typical workflow:

prisma migrate reset --force
prisma generate
prisma db seed

prisma migrate resolve

Resolves issues with database migrations, such as failed migrations or baselining.

Command

prisma migrate resolve [options]

What It Does

Updates the _prisma_migrations table to manually change the state of a migration. This is a recovery tool.

Options

You must provide exactly one of --applied or --rolled-back.

Examples

Mark as Applied (Baselining)

If you have existing tables and want to initialize migrations without running the SQL:

prisma migrate resolve --applied 20240101000000_initial_migration

This tells Prisma "Assume this migration has already run".

Mark as Rolled Back (Fixing Failures)

If a migration failed (e.g., syntax error) and you fixed the SQL or want to retry:

prisma migrate resolve --rolled-back 20240115120000_failed_migration

This tells Prisma "Forget this migration run, let me try applying it again".

Use Cases

1. Baselining: Adopting Prisma Migrate on an existing production database. 2. Failed Migrations: Recovering from a failed migrate deploy in production. 3. Hotfixes: reconciling manual database changes (rare).

References

• Baselining
• Troubleshooting

prisma migrate status

Checks the status of your database migrations.

Command

prisma migrate status [options]

What It Does

• Connects to the database
• Checks the _prisma_migrations table
• Compares applied migrations with local migration files
• Reports:
• Status: Database is up-to-date or behind
• Unapplied migrations: Count of pending migrations
• Missing migrations: Migrations present in DB but missing locally
• Failed migrations: Any migrations that failed to apply

Options

Examples

Check status

prisma migrate status

Output example (Up to date):

Database schema is up to date!

Output example (Pending):

Following migration have not yet been applied:
  20240115120000_add_user

To apply migrations in development, run:
  prisma migrate dev

To apply migrations in production, run:
  prisma migrate deploy

When to Use

• Debugging: Why is migrate dev complaining about drift?
• CI/CD: Verify database state before deploying
• Production: Check if migrations are needed (migrate deploy) or if a deployment failed

Exit Codes

• 0: Database schema is up to date
• 1: Error or migration state is not in sync, including pending migrations, divergent histories, missing baselines, or failed migrations

To check for pending migrations programmatically, parse the output or use migrate diff --exit-code for diff-style status checks.

prisma postgres link

Links a local project to a Prisma Postgres database.

Command

prisma postgres link [options]

Options

When using --api-key, also provide --database.

Examples

Interactive link

prisma postgres link

Non-interactive link

prisma postgres link --api-key "<your-api-key>" --database "db_..."

Behavior

The command authenticates with Prisma Console when needed, lets you select a project and ready database interactively, creates a development connection, and writes local project files for Prisma Postgres.

If the project is already linked, use --force to re-link.

prisma studio

Opens a visual database browser for viewing and editing data.

Command

prisma studio [options]

What It Does

• Starts a web-based database GUI
• View all your models and records
• Create, update, and delete records
• Filter and sort data
• Navigate relations

Options

Examples

Open Studio

prisma studio

Opens on the default Studio port, currently 51212 when available.

Custom port

prisma studio --port 3000

Specific browser

prisma studio --browser firefox

Don't open browser

BROWSER=none prisma studio

Useful for remote servers.

Features

View Records

• See all records in table format
• Pagination for large datasets
• Column sorting

Filter Data

• Filter by any field
• Multiple conditions
• Relation filtering

Edit Records

• Click to edit inline
• Add new records
• Delete records (with confirmation)

Navigate Relations

• Click relations to view related records
• See counts of related items
• Follow relation links

Recent Studio Capabilities

Recent Prisma Studio releases added richer editor workflows:

• multi-cell selection and editing
• full-table search and more intuitive filtering
• command palette shortcuts
• dark mode
• copy selections as Markdown
• back-relation navigation
• SQL workflows including raw SQL queries

Some recent builds also expose AI-assisted SQL authoring. Treat these as interactive Studio features rather than a replacement for checked-in migrations or application queries.

Use Cases

• Development: Quick data inspection
• Debugging: Check data state
• Testing: Verify seed data
• Demo: Show data to stakeholders

Limitations

• Development tool only
• Not for production use
• Limited to configured database
• Prisma Studio in Prisma 7 currently targets PostgreSQL, MySQL, and SQLite first
• For reproducible application logic, prefer Prisma Client and checked-in SQL scripts

Common Workflow

1. Run migrations:

   prisma migrate dev

2. Seed data:

   prisma db seed

3. Open Studio to verify:

   prisma studio

4. Make manual edits if needed

Security Note

Studio provides direct database access. Only run on:

• Local development machines
• Secure internal networks
• Never expose publicly

prisma validate

Validates your Prisma schema file.

Command

prisma validate [options]

What It Does

• Parses the schema.prisma file
• Checks for syntax errors
• Validates model definitions, relations, and types
• Reports any errors or warnings without generating code

Options

Examples

Validate default schema

prisma validate

Validate specific schema

prisma validate --schema=./custom/schema.prisma

Use in CI

Run validate in your CI pipeline to catch schema errors early:

- name: Validate Schema
  run: npx prisma validate

Common Errors

• Missing @relation fields
• Invalid types
• Duplicate model names
• Syntax errors (missing braces, etc.)