Get started with 33% off your first certification using code: 33OFFNEW

When and how to squash migrations

3 min read
Published on 2nd April 2024

In this tutorial we'll be focussing on migrations in Laravel. The concepts here are the same in any backend framework, but the exact steps and tools used to squash and implement migrations will differ from framework-to-framework.

Laravel's migration system is an elegant way to version-control your database schema, allowing for straightforward updates and team collaboration. However, over time, as your application grows, so does the number of migration files. This accumulation can lead to slower execution times when running migrations and can clutter your project. Squashing migrations in Laravel helps mitigate these issues by consolidating your migration files into a single SQL file. This tutorial explores the scenarios warranting migration squashing and guides you through the process.

Understanding the Need for Squashing Migrations

When to Consider Squashing Migrations:

  1. Project Maturity: As a project transitions from development to production, the number of migrations can become unwieldy. Squashing them can simplify deployment and setup for new environments.

  2. Performance Optimization: Running hundreds of migrations can significantly slow down the setup process for a new development environment or CI/CD pipeline. Squashing can reduce setup times.

  3. Cleanup and Maintainability: Squashing migrations can help clean up your migrations directory, making it easier to understand the current database schema without trawling through numerous files.

Preparation for Squashing Migrations

Before squashing migrations, ensure your database schema is up-to-date by running any pending migrations. Also, it's wise to backup your database as a precaution.

php artisan migrate

How to Squash Migrations in Laravel

Step 1: Squashing Existing Migrations

Starting from Laravel 8, you can squash your existing migrations into a single file using the schema:dump command, which creates a schema file reflecting the current state of your database:

php artisan schema:dump

By default, this command generates a schema file in the database/schema directory. The file name includes the database connection and timestamp, e.g., mysql-schema.dump. This schema file will be used automatically when running migrations in a new environment, significantly speeding up the process.


  • --prune: Using this option with the command deletes all existing migration files, leaving only the newly created schema dump and any migrations created after the dump.
php artisan schema:dump --prune

Step 2: Moving Forward After Squashing

After squashing, you continue to create new migration files for future database schema changes as usual. Laravel will manage these new migrations alongside the schema file created during the squashing process.

Step 3: Running Migrations After Squashing

When you run migrations (php artisan migrate), Laravel first checks for a schema file. If found, it uses this file to set up the database schema, then applies any migrations that were created after the schema file. This approach ensures that your database is always in sync with the project's migrations.

Best Practices for Migration Squashing

  • Regular Squashing: Consider squashing migrations at major release intervals or after significant database schema changes to keep the migration history manageable.

  • Version Control: Commit the schema dump file to your version control system. This ensures that new team members or CI/CD pipelines benefit from the squashed migrations.

  • Local Development: After squashing migrations and before deleting old migration files (if using --prune), ensure that every team member has updated their local development database to avoid conflicts or missing migrations.

Squashing migrations in Laravel is a powerful technique for maintaining the efficiency and clarity of your project's migration history. It streamlines the setup of new development environments and CI/CD pipelines while keeping your migrations directory clean and focused. By following the outlined steps and adhering to best practices, you can effectively implement migration squashing in your Laravel projects, ensuring a smooth development process and optimal performance.