Laravel Migrate Fresh Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require spatie/laravel-migrate-fresh
   

   (Note: Since Laravel 5.5+, this is built into core as migrate:fresh. This package is a legacy wrapper for older versions.)

2. First Use Case: Run the command to wipe and rebuild the database from scratch:

   php artisan migrate:fresh
   

   • For testing: Combine with --seed to populate fresh data:

     php artisan migrate:fresh --seed
     

3. Where to Look First:

   • Laravel Docs (Core Feature) (since 5.5+).
   • Package GitHub Issues (for pre-5.5 quirks).

Implementation Patterns

Usage Patterns

1. CI/CD Workflows:

   • Use in deployment pipelines to ensure a clean slate before testing/production updates:

     # Example GitHub Actions step
     - name: Reset DB
       run: php artisan migrate:fresh --env=testing
     

2. Testing:

   • Reset database between test suites (faster than migrate:refresh for large apps):

     // In phpunit.xml
     <env name="DB_CONNECTION" value="sqlite_testing"/>
     <env name="DB_DATABASE" value=":memory:"/>
     

     php artisan migrate:fresh --env=testing
     

3. Integration with Factories/Seeders:

   • Chain with db:seed for reproducible test environments:

     php artisan migrate:fresh --seed --class=TestDatabaseSeeder
     

4. Environment-Specific Flags:

   • Use --env to target specific .env files (e.g., staging, production):

     php artisan migrate:fresh --env=staging
     

Workflows

• Pre-Migration Hooks:

  • Override the command to add logic (e.g., backup tables before nuking):

    // app/Console/Kernel.php
    protected $commands = [
        \Spatie\MigrateFresh\Console\MigrateFreshCommand::class,
        \App\Console\Commands\BackupBeforeFresh::class,
    ];
    

• Post-Migration Tasks:

  • Use --execute to run arbitrary commands after migration:

    php artisan migrate:fresh --execute="php artisan optimize:clear"
    

Integration Tips

• With Laravel Forge/Envoyer:
  • Add to deployment scripts to ensure migrations are fresh on server pushes.
• With Laravel Telescope:
  • Monitor migrate:fresh executions in the "Commands" tab for debugging.

Gotchas and Tips

Pitfalls

1. No Rollback Safety:

   • Unlike migrate:refresh, migrate:fresh drops all tables unconditionally. Ensure:
     • No critical data is lost (use backups or --execute to archive data first).
     • Foreign keys are handled via ON DELETE CASCADE or manual cleanup.

2. Seed Order Dependencies:

   • Seeding after migrate:fresh may fail if models rely on each other. Use explicit seeders:

     php artisan db:seed --class=UsersTableSeeder --class=PostsTableSeeder
     

3. Schema Changes in Production:

   • Never run migrate:fresh in production unless absolutely necessary (e.g., catastrophic corruption). Use migrate or migrate:refresh instead.

4. Legacy Package Note:

   • This package is obsolete for Laravel ≥5.5. Use the built-in migrate:fresh command instead.

Debugging

• Failed Migrations:

  • Check migrations table for stuck migrations:

    SELECT * FROM migrations WHERE batch = (SELECT MAX(batch) FROM migrations);
    

  • Manually rollback problematic migrations before running migrate:fresh.

• Permission Errors:

  • Ensure the database user has DROP privileges:

    GRANT DROP ON *.* TO 'laravel_user'@'%';
    

Config Quirks

• Custom Database Connections:

  • Specify the connection with --database:

    php artisan migrate:fresh --database=mysql_secondary
    

• Soft Deletes:

  • migrate:fresh does not handle soft deletes. Use Model::query()->forceDelete() in seeders if needed.

Extension Points

1. Custom Command Logic:

   • Publish the command and extend it:

     php artisan vendor:publish --tag=migrate-fresh
     

   • Override handle() in app/Console/Commands/MigrateFresh.php.

2. Pre/Post Hooks:

   • Use Laravel’s events to trigger actions before/after:

     // In EventServiceProvider
     protected $listen = [
         'migrate.fresh.starting' => [
             \App\Listeners\BackupDatabase::class,
         ],
     ];
     

3. Conditional Execution:

   • Skip migrate:fresh if the database is empty (e.g., in CI):

     if [ -z "$(php artisan db:table --name=migrations | tail -n +2)" ]; then
         php artisan migrate:fresh
     fi