Migration Squashing

Migration squashing

{{< history >}}

• Introduced in GitLab 16.3.
• Automated in GitLab 18.9.

{{< /history >}}

Migration squashing combines multiple database migrations into a single schema definition to improve database setup performance and maintain a manageable migration history.

Automation

Migration squashing is automated through GitLab Housekeeper. The Keeps::SquashMigrations keep creates MRs automatically at scheduled milestones.

The automation runs via a scheduled pipeline job in the Engineering Productivity team's CI configuration.

Schedule

Squashing occurs at milestones ending in .2, .5, .8, and .11. These align with required stops.

The target branch is two required stops prior to the current milestone:

For example, at the 18.8 required stop, migrations are squashed up to origin/18-2-stable-ee.

Manual execution

To squash migrations manually from a previous version (such as 16.10), run:

bundle exec rake "gitlab:db:squash[origin/16-10-stable-ee]"

This Rake task:

1. Removes all migrations from the previous version
2. Updates db/init_structure.sql with the squashed schema
3. Updates schema version references in relevant files
4. Removes associated migration specs and RuboCop TODOs
5. Cleans up finalized batched background migrations

Parameters

Troubleshooting

Missing schema references

If you encounter errors related to missing schema references, check:

• Migration spec files that might reference old migrations
• Background migration files that might need manual updates
• Documentation that references specific migration versions

Related documentation

• Migration style guide
• Required stops