Laravel Migrate Check Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require erjanmx/laravel-migrate-check
   

   No additional configuration is needed due to Laravel’s package auto-discovery.

2. First Use Case: Integrate into a CI/CD pipeline or deployment script to verify pending migrations before proceeding. Example:

   php artisan migrate:check --exit-code
   

   • Returns 0 (success) if no pending migrations.
   • Returns 1 (failure) if migrations are pending.

3. Where to Look First:

   • README for basic usage.
   • Changelog for version-specific changes.

Implementation Patterns

Usage Patterns

1. CI/CD Integration:

   • Use in pre-deploy hooks to block deployments if migrations exist:

     # Example GitHub Actions step
     - name: Check for pending migrations
       run: php artisan migrate:check --exit-code || exit 1
     

   • Combine with migrate in a single step:

     php artisan migrate:check --exit-code && php artisan migrate --force
     

2. Automated Maintenance Mode:

   • Check migrations before enabling maintenance mode:

     // In a deployment script
     $exitCode = Artisan::call('migrate:check --exit-code');
     if ($exitCode !== 0) {
         throw new \RuntimeException('Pending migrations detected!');
     }
     Artisan::call('down');
     

3. Custom Database Support:

   • Specify a database connection (e.g., for multi-database setups):

     php artisan migrate:check --database=secondary_db
     

4. Silent Mode:

   • Suppress output for logging/CLI tools:

     php artisan migrate:check --quiet
     

Workflows

• Zero-Downtime Deployments:
  • Run migrate:check in a pre-flight script to ensure no migrations are pending before switching traffic.
• Rollback Verification:
  • Use after rollbacks to confirm migrations are up-to-date:

    php artisan migrate:check --exit-code || php artisan migrate:fresh
    

Integration Tips

• Laravel Forge/Envoyer:
  • Add to deploy scripts as a validation step.
• Docker:
  • Use in entrypoint.sh to fail fast if migrations are pending:

    if ! php artisan migrate:check --exit-code; then
      echo "Migrations pending! Exiting."
      exit 1
    fi
    

• Testing:
  • Mock the command in PHPUnit tests:

    $this->artisan('migrate:check')
         ->expectsQuestion('Continue?', 'no')
         ->assertExitCode(1);
    

Gotchas and Tips

Pitfalls

1. Exit Code Misuse:

   • Forgetting --exit-code will always return 0, even with pending migrations.
   • Fix: Always include --exit-code in scripts.

2. Database Connection Issues:

   • The command uses the default Laravel connection. If your .env is misconfigured, it may fail silently.
   • Fix: Explicitly specify a connection:

     php artisan migrate:check --database=mysql
     

3. Race Conditions:

   • In high-concurrency deployments, another process might run migrations between migrate:check and migrate.
   • Fix: Use transactions or locks (e.g., php artisan migrate --force --pretend first).

4. Custom Migration Paths:

   • The package respects Laravel’s migration paths but may not handle custom paths in config/database.php correctly.
   • Fix: Use --path to override:

     php artisan migrate:check --path=database/migrations/custom
     

Debugging

• Verbose Output:
  • Use --verbose to debug connection/migration issues:

    php artisan migrate:check --verbose
    

• Dry Run:
  • Test without exiting:

    php artisan migrate:check --pretend
    

Config Quirks

• Environment-Specific Behavior:

  • The command respects APP_ENV (e.g., testing environment may behave differently).
  • Tip: Test in staging with APP_ENV=staging.

• No Configuration File:

  • Unlike some packages, this one has no config file. All options are CLI flags.

Extension Points

1. Custom Logic:

   • Extend the command by publishing it (though it’s minimal):

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

   • Override app/Console/Commands/MigrateCheckCommand.php.

2. Event Listeners:

   • Trigger actions on migration status changes (e.g., Slack alerts):

     // In EventServiceProvider
     protected $listen = [
         'migrate.check.failed' => [YourAlertHandler::class],
     ];
     

3. Integration with Laravel Packages:

   • Use with spatie/laravel-backup to skip backups if migrations are pending:

     if (Artisan::call('migrate:check --exit-code') !== 0) {
         Backup::withoutMigrations();
     }