Introducing a new database migration version
At GitLab we’ve added many helpers for the database migrations to help developers manipulate
the schema and data of tables on a large scale like on GitLab.com. To avoid the repetitive task
of including the helpers into each database migration, we use a subclass of the Rails ActiveRecord::Migration
class that we use for all of our database migrations. This subclass is Gitlab::Database::Migration
, and it already
includes all the helpers that developers can use. You can see many use cases of helpers built
in-house in Avoiding downtime in migrations.
Sometimes, we need to add or modify existing an helper’s functionality without having a reverse effect on all the
previous database migrations. That’s why we introduced versioning to Gitlab::Database::Migration
. Now,
each database migration can inherit the latest version of this class at the time of the writing the database migration.
After we add a new feature, those old database migrations are no longer affected. We usually
refer to the version using Gitlab::Database::Migration[2.1]
, where 2.1
is the current version.
Because we are chasing a moving target, adding a new migration and deprecating older versions can be challenging. Database migrations are introduced every day, and this can break the pipeline. In this document, we explain a two-step method to add a new database migration version.
- Introduce a new version, and keep the older version allowed
- Prevent the usage of the older database migration version
Introduce a new version, and keep the older version allowed
The new version can be added to the
migration.rb
class, along with any new helpers that should be included in the new version. Make sure thatcurrent_version
refers to this new version. For example:class V2_2 < V2_1 # rubocop:disable Naming/ClassAndModuleCamelCase include Gitlab::Database::MigrationHelpers::ANY_NEW_HELPER end def self.current_version 2.2 end
Update all the examples in the documentation to refer to the new database migration version
Gitlab::Database::Migration[2.2]
.Make sure that
migration_spec.rb
doesn’t fail for the new database migrations by adding an open date rate for the new database version.
Prevent the usage of the older database migration version
After some time passes, and ensuring all developers are using the new database migration version in their merge requests, prevent the older version from being used:
- Close the date range in
migration_spec.rb
for the older database version. - Modify the
RuboCop::Cop::Migration::VersionedMigrationClass
and its owned tests. - Communicate this change on our Slack
#backend
and#database
channels and Engineering Week-in-Review document.
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