Skip to content

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:

  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.