diff options
author | Sean McGivern <sean@gitlab.com> | 2018-06-19 18:39:34 +0300 |
---|---|---|
committer | Sean McGivern <sean@gitlab.com> | 2018-06-19 18:41:35 +0300 |
commit | 9a65af63e050ce1a44ef3c9feed35a4e1b96929d (patch) | |
tree | b79af4887ab7ad49611ecd0f6fc1eded5473a7a1 /doc/development | |
parent | c0f0ccf222a2b8896aeb94b7a50b3923c7684125 (diff) |
Add docs for the cleanup step of a background column type change
A background column type change needs a cleanup step, like any background
migration. We should call that out explicitly in the documentation.
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/what_requires_downtime.md | 47 |
1 files changed, 47 insertions, 0 deletions
diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index b8be8daa157..f502866333e 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -252,6 +252,53 @@ Keep in mind that the relation passed to `change_column_type_using_background_migration` _must_ include `EachBatch`, otherwise it will raise a `TypeError`. +This migration then needs to be followed in a separate release (_not_ a patch +release) by a cleanup migration, which should steal from the queue and handle +any remaining rows. For example: + +```ruby +class MigrateRemainingIssuesClosedAt < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + + DOWNTIME = false + + disable_ddl_transaction! + + class Issue < ActiveRecord::Base + self.table_name = 'issues' + include EachBatch + end + + def up + Gitlab::BackgroundMigration.steal('CopyColumn') + Gitlab::BackgroundMigration.steal('CleanupConcurrentTypeChange') + + migrate_remaining_rows if migrate_column_type? + end + + def down + # Previous migrations already revert the changes made here. + end + + def migrate_remaining_rows + Issue.where('closed_at_for_type_change IS NULL AND closed_at IS NOT NULL').each_batch do |batch| + batch.update_all('closed_at_for_type_change = closed_at') + end + + cleanup_concurrent_column_type_change(:issues, :closed_at) + end + + def migrate_column_type? + # Some environments may have already executed the previous version of this + # migration, thus we don't need to migrate those environments again. + column_for('issues', 'closed_at').type == :datetime # rubocop:disable Migration/Datetime + end +end +``` + +For more information, see [the documentation on cleaning up background +migrations](background_migrations.md#cleaning-up). + ## Adding Indexes Adding indexes is an expensive process that blocks INSERT and UPDATE queries for |