We have two migration directories: db/migrate and db/post_migrate. If a migration adds something (e.g. a table or a column) or migrates data that existing code can deal with (e.g. populating a new table) then it goes in db/migrate. If a migration removes or updates something that first requires a code deploy, it goes in db/post_migrate. We combine this with a variety of helpers in various places to allow for zero downtime upgrades (if you're using PostgreSQL). For example, to remove a column we take these steps:
1. Deploy a new version of the code that ignores the column we will drop (this is a matter of adding `ignore_column :column_name` in the right class).
2. Run a post-deployment migration that removes said column.
3. In the next release we can remove the `ignore_column` line (we require that users upgrade at most one minor version for online upgrades).
The migrations in db/post_migrate are executed by default but you can opt-out by setting an environment variable. In case of GitLab.com this results in the following deployment procedure:
1. Deploy code with this variable set (so we don't run the post-deployment migrations)
2. Re-run `rake db:migrate` on a particular host without setting this environment variable.
For big data migrations we use Sidekiq to run them in the background. This removes the need for a deployment procedure taking hours, though it comes with some additional complexity.
More information about this can be found at the following places:
1. https://docs.gitlab.com/ee/update/README.html#upgrading-with...
2. https://docs.gitlab.com/ee/development/what_requires_downtim...
3. https://docs.gitlab.com/ee/development/background_migrations...