API Reference

Complete reference for Prisma Migrations CLI and Node.js API

Prisma Migrations provides both a CLI interface and a programmatic Node.js API.

CLI Commands

All CLI commands use the following format:

npx prisma-migrations <command> [options]

`init`

Initialize migrations directory with first migration file.

npx prisma-migrations init

Output:

✓ Created migration: 1234567890_initial_migration
  Location: ./prisma/migrations/1234567890_initial_migration

`create [name]`

Create a new migration file with optional name.

npx prisma-migrations create add_users_table

Arguments:

name (optional) - Migration name (kebab-case recommended)

Output:

✓ Created migration: 1234567890_add_users_table
  Location: ./prisma/migrations/1234567890_add_users_table

`up [options]`

Run pending migrations.

# Run all pending migrations
npx prisma-migrations up

# Run next 3 migrations
npx prisma-migrations up --steps 3

# Interactive mode - choose which migrations to run
npx prisma-migrations up --interactive

Options:

--steps <number> - Number of migrations to run
--interactive or -i - Interactive selection mode

Output:

┌──────────┬──────────────────────────────────────────────────┐
│ Status   │ Migrations                                       │
├──────────┼──────────────────────────────────────────────────┤
│ ✓        │ 2 migration(s) applied successfully              │
└──────────┴──────────────────────────────────────────────────┘

`down [options]`

Rollback migrations.

# Rollback last migration
npx prisma-migrations down

# Rollback last 2 migrations
npx prisma-migrations down --steps 2

# Interactive mode - choose which migrations to rollback
npx prisma-migrations down --interactive

Options:

--steps <number> - Number of migrations to rollback (default: 1)
--interactive or -i - Interactive selection mode

Output:

┌──────────┬──────────────────────────────────────────────────┐
│ Status   │ Migrations                                       │
├──────────┼──────────────────────────────────────────────────┤
│ ↓        │ 1 migration(s) rolled back                       │
└──────────┴──────────────────────────────────────────────────┘

`status`

Show migration status (which migrations are applied/pending).

npx prisma-migrations status

`pending`

List all pending (not yet applied) migrations.

npx prisma-migrations pending

Output:

3 pending migration(s):

  1234567890_add_users_table
  1234567891_add_posts_table
  1234567892_add_comments_table

`applied`

List all applied migrations.

npx prisma-migrations applied

Output:

2 applied migration(s):

  ✓ 1234567889_initial_migration
  ✓ 1234567890_add_users_table

`latest`

Show the latest applied migration.

npx prisma-migrations latest

`reset`

Rollback all migrations.

npx prisma-migrations reset

`fresh`

Rollback all migrations and re-run them (fresh start).

npx prisma-migrations fresh

`refresh`

Alias for fresh command.

npx prisma-migrations refresh

`mcp`

Start the MCP (Model Context Protocol) server for AI assistant integration.

npx prisma-migrations mcp

Description: Provides 15 tools for AI assistants to manage both data migrations and Prisma operations:

Data migrations: status, pending, applied, up, down, create, dry-run, reset, fresh, refresh
Prisma operations: migrate dev/deploy/resolve, db push, generate

Use with Claude Desktop or other MCP-compatible AI assistants for AI-assisted database management.

Global Options

These options work with any command:

--verbose or -v - Enable verbose logging
--log-level <level> - Set log level (silent, error, warn, info, debug, trace)

Example:

npx prisma-migrations up --verbose
npx prisma-migrations --log-level debug up

Programmatic API

Use the migrations system from your Node.js/TypeScript code.

Import

import { Migrations } from 'prisma-migrations';
import { PrismaClient } from '@prisma/client';

Constructor

new Migrations(prisma: PrismaClient, config?: MigrationsConfig)

Parameters:

Parameter	Type	Required	Description
`prisma`	`PrismaClient`	Yes	Your Prisma Client instance
`config`	`MigrationsConfig`	No	Optional configuration

Config Options:

interface MigrationsConfig {
  migrationsDir?: string;  // Default: auto-discovered from ./prisma/migrations
  logLevel?: 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
}

Example:

const prisma = new PrismaClient();
const migrations = new Migrations(prisma, {
  migrationsDir: './database/migrations',
  logLevel: 'info'
});

Methods

`up(steps?: number): Promise<number>`

Run pending migrations.

Parameters:

steps (optional) - Number of migrations to run. If omitted, runs all pending migrations.

Returns:

Promise<number> - Number of migrations applied

Example:

// Run all pending migrations
const count = await migrations.up();
console.log(`Applied ${count} migrations`);

// Run next 3 migrations
await migrations.up(3);

`down(steps?: number): Promise<number>`

Rollback migrations.

Parameters:

steps (optional) - Number of migrations to rollback (default: 1)

Returns:

Promise<number> - Number of migrations rolled back

Example:

// Rollback last migration
await migrations.down();

// Rollback last 3 migrations
await migrations.down(3);

`pending(): Promise<MigrationFile[]>`

Get list of pending migrations.

Returns:

Promise<MigrationFile[]> - Array of pending migration objects

MigrationFile Interface:

interface MigrationFile {
  id: string;      // Migration ID (timestamp)
  name: string;    // Migration name
  path: string;    // Full path to migration file
  fileType: 'ts' | 'sql';  // Migration file type
}

Example:

const pending = await migrations.pending();
console.log(`${pending.length} pending migrations:`);
pending.forEach(m => console.log(`  ${m.id}_${m.name}`));

`applied(): Promise<MigrationFile[]>`

Get list of applied migrations.

Returns:

Promise<MigrationFile[]> - Array of applied migration objects

Example:

const applied = await migrations.applied();
console.log(`${applied.length} applied migrations`);

`latest(): Promise<MigrationFile | null>`

Get the latest applied migration.

Returns:

Promise<MigrationFile | null> - Latest migration or null if none applied

Example:

const latest = await migrations.latest();
if (latest) {
  console.log(`Latest: ${latest.id}_${latest.name}`);
}

`status(): Promise<void>`

Display migration status (logs to console).

Example:

await migrations.status();

`reset(): Promise<number>`

Rollback all migrations.

Returns:

Promise<number> - Number of migrations rolled back

Example:

const count = await migrations.reset();
console.log(`Rolled back ${count} migrations`);

`fresh(): Promise<number>`

Rollback all migrations and re-run them.

Returns:

Promise<number> - Number of migrations applied after reset

Example:

await migrations.fresh();

`refresh(): Promise<{ down: number; up: number }>`

Alias for fresh() but returns detailed counts.

Returns:

Promise<{ down: number; up: number }> - Number of migrations rolled back and reapplied

Example:

const result = await migrations.refresh();
console.log(`Rolled back ${result.down}, applied ${result.up}`);

Complete Example

import { Migrations } from 'prisma-migrations';
import { PrismaClient } from '@prisma/client';

async function runMigrations() {
  const prisma = new PrismaClient();
  const migrations = new Migrations(prisma);

  try {
    // Check pending migrations
    const pending = await migrations.pending();
    console.log(`Found ${pending.length} pending migrations`);

    // Run migrations
    const applied = await migrations.up();
    console.log(`Successfully applied ${applied} migrations`);

    // Verify latest migration
    const latest = await migrations.latest();
    if (latest) {
      console.log(`Latest migration: ${latest.name}`);
    }
  } catch (error) {
    console.error('Migration failed:', error);
    process.exit(1);
  } finally {
    await prisma.$disconnect();
  }
}

runMigrations();

Usage Examples

Application Startup

Run migrations when your app starts:

import { Migrations } from 'prisma-migrations';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

async function bootstrap() {
  const migrations = new Migrations(prisma);

  // Run pending migrations on startup
  const count = await migrations.up();
  console.log(`Applied ${count} migrations`);

  // Start your application
  await startServer();
}

bootstrap();

CI/CD Deployment

Run migrations during deployment:

import { Migrations } from 'prisma-migrations';
import { PrismaClient } from '@prisma/client';

async function deploy() {
  const prisma = new PrismaClient();
  const migrations = new Migrations(prisma);

  try {
    // Check for pending migrations
    const pending = await migrations.pending();

    if (pending.length === 0) {
      console.log('No migrations to run');
      return;
    }

    console.log(`Running ${pending.length} migrations...`);
    await migrations.up();
    console.log('✓ Migrations completed successfully');
  } catch (error) {
    console.error('✗ Migration failed:', error);
    process.exit(1);
  } finally {
    await prisma.$disconnect();
  }
}

deploy();

Safe Rollback

Rollback with error handling:

import { Migrations } from 'prisma-migrations';
import { PrismaClient } from '@prisma/client';

async function rollbackLastMigration() {
  const prisma = new PrismaClient();
  const migrations = new Migrations(prisma);

  try {
    const latest = await migrations.latest();
    if (!latest) {
      console.log('No migrations to rollback');
      return;
    }

    console.log(`Rolling back: ${latest.name}`);
    await migrations.down();
    console.log('✓ Rollback successful');
  } catch (error) {
    console.error('✗ Rollback failed:', error);
    process.exit(1);
  } finally {
    await prisma.$disconnect();
  }
}

rollbackLastMigration();

Development Reset

Fresh start for development:

import { Migrations } from 'prisma-migrations';
import { PrismaClient } from '@prisma/client';

async function resetDatabase() {
  const prisma = new PrismaClient();
  const migrations = new Migrations(prisma);

  console.log('Resetting database...');

  // Rollback all migrations
  const rolled = await migrations.reset();
  console.log(`Rolled back ${rolled} migrations`);

  // Re-run all migrations
  const applied = await migrations.up();
  console.log(`Applied ${applied} migrations`);

  console.log('✓ Database reset complete');

  await prisma.$disconnect();
}

resetDatabase();

TypeScript

Prisma Migrations includes full TypeScript support with type safety:

import type {
  PrismaClient,
  MigrationFile,
  MigrationFunction,
  MigrationsConfig
} from 'prisma-migrations';

// Type-safe migration functions
export async function up(prisma: PrismaClient): Promise<void> {
  await prisma.$executeRaw`CREATE TABLE users (id SERIAL PRIMARY KEY)`;
}

export async function down(prisma: PrismaClient): Promise<void> {
  await prisma.$executeRaw`DROP TABLE IF EXISTS users`;
}

// Type-safe configuration
const config: MigrationsConfig = {
  migrationsDir: './database/migrations',
  logLevel: 'info'
};