Migration ordering
Starting with GitLab 17.1, migrations are executed using a custom ordering scheme that conforms to the GitLab release cadence. This change simplifies the upgrade process, and eases both maintenance and support.
Pre 17.1 logic
Migrations are executed in an order based upon the 14-digit timestamp given in the file name of the migration itself. This behavior is the default for a Rails application.
GitLab also features logic to extend standard migration behavior in these important ways:
- You can load migrations from additional folders. For example, migrations are
loaded from both the
db/post_migrate
folder and thedb/migrate
folder, which you need when using Post-Deployment migrations. - If you set the environment variable
SKIP_POST_DEPLOYMENT_MIGRATIONS
, migrations are not loaded from anypost_migrate
folder. - You must provide a GitLab minor version, or “milestone”, on all new migrations.
17.1+ logic
Migrations are executed in the following order:
- Migrations without
milestone
defined are executed first, ordered by their timestamp. - Migrations with
milestone
defined are executed in milestone order:- Regular migrations are executed before post-deployment migrations.
- Migrations of the same type and milestone are executed in order specified by their timestamp.
Example:
- Any migrations without
milestone
defined. 17.1
regular migrations.17.1
post-deployment migrations.17.2
regular migrations.17.2
post-deployment migrations.- Repeat for each milestone in the upgrade.
New behavior for post-deployment migrations
This change causes post-deployment migrations to always be sorted at the end
of a given milestone. Previously, post-deployment migrations were
interleaved with regular ones, provided SKIP_POST_DEPLOYMENT_MIGRATIONS
was not set.
When SKIP_POST_DEPLOYMENT_MIGRATIONS
is set, post-deployment migrations are not executed.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support