Conditional Migration in Laravel 11 Using shouldRun() – Step-by-Step Guide

Laravel 11 introduces a powerful feature: the shouldRun() method in migration classes. It allows you to conditionally execute a migration based on custom logic.

This is especially useful when:

• ✅ You want to avoid duplicate column additions.
• ✅ Your migration depends on the presence of another table.
• ✅ You want to ensure foreign keys or indexes don’t already exist.

---

🛠️ Step 1: Install Laravel 11

composer create-project "laravel/laravel:^11.0" conditional-migration

🗄️ Step 2: Configure Database

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

📦 Step 3: Run Default Migrations

php artisan migrate

✏️ Step 4: Create a New Migration

php artisan make:migration add_profile_completed_to_users_table

Edit the migration file to use shouldRun():

public function shouldRun(): bool
{
    return !Schema::hasColumn('users', 'profile_completed');
}

public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->boolean('profile_completed')->default(false);
    });
}

🚀 Step 5: Run the Migration

php artisan migrate

🔁 Step 6: Test Conditional Behavior

php artisan migrate

The migration is skipped if already applied.

🧪 Bonus: Manual Test

1. Remove the entry from the migrations table.
2. Run php artisan migrate again.

---

✅ Conclusion

The shouldRun() method in Laravel 11 helps create smarter, idempotent migrations with safe checks. It’s a great addition for complex applications with evolving schemas.

🔗 GitHub Repository: Laravel 11 Conditional Migration Demo