sirval/laravel-smart-migrations

Intelligently manage Laravel migrations with safe rollback by table or model, foreign key detection, preview mode, and comprehensive migration analysis tools

v1.0.0 2025-12-28 21:49 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.0||^11.0||^12.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.0.0||^9.0.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.35

MIT

• Ohuka Ikenna

• database
• migrations
• laravel
• rollback
• foreign-keys
• migration-management
• table-rollback
• model-rollback
• batch-rollback
• preview-mode
• migration-tools

README

Intelligently manage Laravel migrations with safe rollback, analysis, validation, and comprehensive tools for table and model-based operations.

A comprehensive Laravel package for intelligent migration management. Roll back migrations by table name or model, with explicit, safe options to prevent accidental data loss. Future versions will include analysis, validation, and optimization tools.

⭐ Give us a Star

If you find this package helpful, please consider giving us a star on GitHub! It helps us continue maintaining and improving this package. Your support means a lot to us! ☕

⭐ Star us on GitHub

Installation

You can install the package via composer:

composer require sirval/laravel-smart-migrations

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-smart-migrations-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-smart-migrations-config"

This is the contents of the published config file:

return [
    'model_namespace' => 'App\\Models',
    'require_confirmation' => true,
    'show_details' => true,
    'prevent_multi_batch_rollback' => true,
    'audit_log_enabled' => false,
    'audit_log_table' => 'smart_migrations_audits',
];

Optionally, you can publish the views using

php artisan vendor:publish --tag="laravel-smart-migrations-views"

Usage

Available Commands

1. Rollback by Table Name

Roll back all migrations for a specific table:

# Rollback latest migration only
php artisan migrate:rollback-table users --latest
php artisan migrate:rollback-table users -L

# Rollback oldest migration only
php artisan migrate:rollback-table users --oldest
php artisan migrate:rollback-table users -O

# Rollback all migrations for this table
php artisan migrate:rollback-table users --all
php artisan migrate:rollback-table users -A

# Rollback migrations from specific batch
php artisan migrate:rollback-table users --batch=5
php artisan migrate:rollback-table users -B 5

# Skip confirmation prompt
php artisan migrate:rollback-table users --force
php artisan migrate:rollback-table users -F

# Interactive mode (choose from available options)
php artisan migrate:rollback-table users --interactive
php artisan migrate:rollback-table users -I

# Preview the changes without executing
php artisan migrate:rollback-table users --preview

# Check for foreign key constraints
php artisan migrate:rollback-table users --check-fk

# Combine options: preview with foreign key check
php artisan migrate:rollback-table users --preview --check-fk

# Rollback multiple tables at once
php artisan migrate:rollback-table users,posts,comments --latest
php artisan migrate:rollback-table users,posts,comments -L
php artisan migrate:rollback-table users posts comments --oldest
php artisan migrate:rollback-table users posts comments -O

2. Rollback by Model Name

Roll back all migrations associated with a specific model:

# Rollback latest migration
php artisan migrate:rollback-model User --latest
php artisan migrate:rollback-model User -L

# Rollback oldest migration
php artisan migrate:rollback-model User --oldest
php artisan migrate:rollback-model User -O

# Rollback all migrations
php artisan migrate:rollback-model User --all
php artisan migrate:rollback-model User -A

# Rollback by batch
php artisan migrate:rollback-model User --batch=5
php artisan migrate:rollback-model User -B 5

# Skip confirmation
php artisan migrate:rollback-model User --force
php artisan migrate:rollback-model User -F

# Interactive mode
php artisan migrate:rollback-model User --interactive
php artisan migrate:rollback-model User -I

# Preview the changes without executing
php artisan migrate:rollback-model User --preview

# Check for foreign key constraints
php artisan migrate:rollback-model User --check-fk

# Combine options: preview with foreign key check
php artisan migrate:rollback-model User --preview --check-fk

# Rollback multiple models at once
php artisan migrate:rollback-model User,Post,Comment --latest
php artisan migrate:rollback-model User,Post,Comment -L
php artisan migrate:rollback-model User Post Comment --oldest
php artisan migrate:rollback-model User Post Comment -O

3. Rollback by Batch Number

Roll back all migrations from a specific batch:

# Rollback all migrations from batch 5
php artisan migrate:rollback-batch 5

# Skip confirmation
php artisan migrate:rollback-batch 5 --force
php artisan migrate:rollback-batch 5 -F

4. List Migrations for Table

View all migrations affecting a specific table:

php artisan migrate:list-table-migrations users

5. List Migrations for Model

View all migrations associated with a specific model:

php artisan migrate:list-model-migrations User

Command Options

Option	Short	Description	Default
--latest	-L	Only rollback the latest migration	false
--oldest	-O	Only rollback the oldest migration	false
--all	-A	Rollback all migrations (ignore batch restrictions)	false
--batch=N	-B	Only rollback migrations from batch N	null
--force	-F	Skip confirmation prompts	false
--interactive	-I	Show options and let user choose	false
--preview	—	Preview changes without executing rollback	false
--check-fk	—	Check and display foreign key constraints	false

Advanced Features

Preview Mode (--preview)

Preview what migrations will be rolled back without making any database changes. This is useful for testing and validation before executing the actual rollback.

# Preview rollback for a table
php artisan migrate:rollback-table users --preview

# Preview with other options
php artisan migrate:rollback-table users --latest --preview

# Preview multiple tables
php artisan migrate:rollback-table users,posts --preview

When you run with --preview, the command will:

• Show all migrations that would be rolled back
• Display any foreign key constraints (if --check-fk is used)
• Return successfully without making any changes to the database

Foreign Key Detection (--check-fk)

Automatically detect and display all foreign key constraints before rolling back migrations. This helps prevent breaking references between tables.

# Check foreign keys for a table
php artisan migrate:rollback-table users --check-fk

# Combine with preview for full safety
php artisan migrate:rollback-table users --check-fk --preview

# Check multiple tables
php artisan migrate:rollback-table users,posts,comments --check-fk

The foreign key check displays:

• Foreign Keys Defined in the Table: Keys that reference other tables
• Dependent Foreign Keys: Other tables that reference this table

Supported Databases:

• MySQL: Uses INFORMATION_SCHEMA queries
• PostgreSQL: Uses information_schema views
• SQLite: Uses PRAGMA foreign_key_list()

Combined Usage

For maximum safety, combine preview mode with foreign key detection:

# Most cautious approach
php artisan migrate:rollback-table users --preview --check-fk

# Works with all other options
php artisan migrate:rollback-table users --latest --preview --check-fk --force

# Multiple tables with full checks
php artisan migrate:rollback-table users,posts,comments --all --preview --check-fk

This allows you to:

1. See all migrations that will be rolled back
2. Identify any foreign key constraints
3. Verify safety without making changes
4. Execute with confidence when ready

Configuration

The package respects these configuration options from config/smart-migrations.php:

return [
    // Default model namespace for model resolution
    'model_namespace' => 'App\\Models',
    
    // Require user confirmation before rollback
    'require_confirmation' => true,
    
    // Show detailed migration information
    'show_details' => true,
    
    // Prevent rolling back multiple batches at once
    'prevent_multi_batch_rollback' => true,
    
    // Enable audit logging for rollbacks
    'audit_log_enabled' => false,
    
    // Table name for audit logs
    'audit_log_table' => 'smart_migrations_audits',
];

Programmatic Usage

Use the SmartMigrations facade for programmatic access:

use Sirval\LaravelSmartMigrations\Facades\SmartMigrations;

// Rollback by table
$results = SmartMigrations::rollbackTable('users', ['latest' => true]);

// Rollback by model
$results = SmartMigrations::rollbackModel('User', ['latest' => true]);

// Rollback by batch
$results = SmartMigrations::rollbackBatch(5);

// List migrations for table
$migrations = SmartMigrations::listMigrationsForTable('users');

// List migrations for model
$migrations = SmartMigrations::listMigrationsForModel('User');

// Get table status
$status = SmartMigrations::getTableStatus('users');

// Get model status
$status = SmartMigrations::getModelStatus('User');

Available Options for Rollback Methods

When calling rollback methods programmatically, pass options as an array:

$options = [
    'latest' => true,      // Rollback latest only
    'oldest' => false,     // Rollback oldest only
    'all' => false,        // Rollback all
    'batch' => null,       // Specific batch number
    'force' => false,      // Skip confirmation
    'dry_run' => false,    // Preview without executing
];

SmartMigrations::rollbackTable('users', $options);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ohuka Ikenna
• All Contributors

License

The MIT License (MIT). Please see License File for more information.