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.
• 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:

1. You can load migrations from additional folders. For example, migrations are loaded from both the db/post_migrate folder and the db/migrate folder, which you need when using Post-Deployment migrations.
2. If you set the environment variable SKIP_POST_DEPLOYMENT_MIGRATIONS, migrations are not loaded from any post_migrate folder.
3. You must provide a GitLab minor version, or “milestone”, on all new migrations.

17.1+ logic

Migrations are executed in the following order:

1. Migrations without milestone defined are executed first, ordered by their timestamp.
2. Migrations with milestone defined are executed in milestone order:
   1. Regular migrations are executed before post-deployment migrations.
   2. Migrations of the same type and milestone are executed in order specified by their timestamp.

Example:

1. Any migrations without milestone defined.
2. 17.1 regular migrations.
3. 17.1 post-deployment migrations.
4. 17.2 regular migrations.
5. 17.2 post-deployment migrations.
6. 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.