A Node.js library that extends Prisma ORM's migration with automatic rollback capabilities when migrations fail
npm install prisma-migratorA Node.js library that extends Prisma ORM's migration functionality with automatic rollback capabilities when migrations fail.
- š Runs prisma migrate deploy automatically
- š Detects failed migrations by checking _prisma_migrations table
- š Automatically executes rollback when migration fails
- š Safety confirmation prompt before running
- š Supports any rollback.sql file in migration directories
- š Smart project root detection - works from any subdirectory
- šÆ Simple CLI tool with minimal configuration needed
``bash`
npm install prisma-migrator
`bashBasic usage (works from any directory in your project)
npx prisma-migrator
The tool will:
1. Show a confirmation prompt with a random string
2. Run
prisma migrate deploy
3. Check for failed migrations
4. Execute rollback if a migration failed and *.rollback.sql exists$3
`typescript
import { PrismaMigrator } from 'prisma-migrator';// Basic usage
const migrator = new PrismaMigrator();
const result = await migrator.migrate();
// With custom options
const migrator = new PrismaMigrator({
migrationsDir: './custom/migrations'
});
const result = await migrator.migrate();
if (result.success) {
console.log('Migration successful');
} else {
console.log('Migration failed:', result.error);
if (result.rolledBack) {
console.log('Rollback was executed');
}
}
await migrator.disconnect();
`How It Works
1. Project Detection: Automatically finds your project root by looking for
package.json or prisma/schema.prisma
2. Safety Check: Prompts user to enter a random confirmation string
3. Migration: Executes npx prisma migrate deploy synchronously
4. Failure Detection: Queries _prisma_migrations table for entries where finished_at IS NULL
5. Rollback: If failure detected, looks for any *.rollback.sql file in the failed migration directory
6. Execution: Runs the rollback SQL using Prisma's raw query execution$3
The library searches for migrations in this order:
-
{projectRoot}/prisma/migrations
- {projectRoot}/migrations
- {currentDir}/prisma/migrations
- {currentDir}/migrations
- ./prisma/migrations (relative fallback)
- ./migrations (relative fallback)Rollback File Structure
Place your rollback files in the migration directory:
`
prisma/migrations/
āāā 20250806120000_add_users_table/
ā āāā migration.sql
ā āāā rollback.sql # ā This will be executed on failure
āāā 20250806130000_add_posts_table/
ā āāā migration.sql
ā āāā 001.rollback.sql # ā Any *.rollback.sql works
`Example Rollback File
`sql
-- rollback.sql
DROP TABLE IF EXISTS users;
DROP INDEX IF EXISTS users_email_unique;
`Requirements
- Node.js ā„ 16
- Prisma ā„ 5.0.0
- @prisma/client ā„ 5.0.0
TypeScript Support
Full TypeScript support with type definitions included.
`typescript
interface MigrationResult {
success: boolean;
error?: string;
rolledBack?: boolean;
rollbackError?: string;
}
`Safety Features
- Confirmation prompt: Prevents accidental execution
- Random string verification: User must type exact string to proceed
- Error handling: Graceful handling of rollback failures
- Database safety: Uses Prisma's built-in SQL execution
License
MIT
Contributing
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)If you encounter any issues, please file them on the GitHub issues page.