API Reference

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) - Lowercase letters, numbers, and underscores

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
• --dry-run - List migrations without applying them

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

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

Prisma 7 CLI Configuration

Programmatic use accepts any compatible generated Prisma client. CLI database commands on Prisma 7 need a factory in prisma-migrations.config.js:

import { createDatabaseClient } from "./src/database.js";

export default {
  clientFactory: createDatabaseClient,
};

The CLI disconnects the returned client after the command finishes.

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, options?: MigrationsOptions)

Parameters:

Config Options:

interface MigrationsOptions {
  migrationsDir?: string;
  disableLocking?: boolean;
  skipChecksumValidation?: boolean;
  lockTimeout?: number;
  lockLeaseDuration?: number;
  hooks?: MigrationHooks;
}

Example:

const prisma = new PrismaClient();
const migrations = new Migrations(prisma, {
  migrationsDir: "./database/migrations",
  lockTimeout: 60_000,
  lockLeaseDuration: 1_800_000,
});

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;
  name: string;
  path: string;
  downPath?: string;
  format?: "prisma" | "legacy";
}

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<MigrationStatus[]>

Return the applied state of every migration. The CLI formats this result for display.

Example:

const statuses = await migrations.status();
statuses.forEach(({ migration, applied }) => {
  console.log(applied, migration.name);
});

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,
  MigrationStatus,
  MigrationsOptions,
} from "prisma-migrations";

const config: MigrationsOptions = {
  migrationsDir: "./database/migrations",
  lockTimeout: 60_000,
};