Migration Squashing

Migration squashing

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

When to use migration squashing

Use migration squashing at the following times:

• At the start of each major release cycle
• After a required stop
• When the number of migrations has grown significantly (typically more than 200 migrations)

Squash migrations

To squash migrations 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 the schema version references in relevant files
3. Cleans up finalized batched background migrations

Parameters

Update CI configuration for database rollbacks

After squashing the migrations, we need to update the migration version used in the CI job that tests migration rollbacks.

To find the first migration version after the InitSchema migration, run:

bundle exec rake db:migrate:status | grep '^\s*up' | awk 'NR==2 {print $2}'

Update the CI script with this version.

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