Skip to content

Warn if a BBM is finalized earlier than expected

Prabakaran Murugesan requested to merge 480729-warn-ealry-finalization-of-bbm into master

What does this MR do and why?

All batched migration enqueued will be run (for sure) on each required stops. So it's the safest to finalize them after at-least 1 required stop from enqueuing.

Allowing early finalization has the potential to break upgrades in self-manged instances.

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Screenshots or screen recordings

Screenshots are required for UI changes, and strongly recommended for all other merge requests.

Before After

How to set up and validate locally

Note: Upgrade path can be found in https://gitlab.com/gitlab-org/gitlab/blob/0991939b43d87bea5deed62a98498d3f1432f78e/config/upgrade_path.yml

Unhappy Flow

  1. Enqueue a BBM migration and set it's milestone to next required stop (eg: 17.5)

    rails g batched_background_migration test_batched_migration --table_name=users --column_name=id --feature_category=database

  2. And change it's milestone key in the data dictionary

    ---
migration_job_name: TestBatchedMigration
description: 'test'
feature_category: database
introduced_by_url: 'https://gitlab.com/gitlab-org/gitlab/-/merge_requests/test'
milestone: '17.5'
queued_migration_version: 20240909104556
# Replace with the approximate date you think it's best to ensure the completion of this BBM.
finalize_after: '2024-10-22'
finalized_by: # version of the migration that finalized this BBM

  3. Create a post-deployment-migration to finalize the above BBM, on the same stop (17.5)

    # frozen_string_literal: true

class FinalizeTestBatchedMigration < Gitlab::Database::Migration[2.2]
  milestone '17.5'
  disable_ddl_transaction!
  restrict_gitlab_migration gitlab_schema: :gitlab_main

  MIGRATION = 'TestBatchedMigration'
  TABLE_NAME = :users
  COLUMN_NAME = :id

  def up
    ensure_batched_background_migration_is_finished(
      job_class_name: MIGRATION,
      table_name: TABLE_NAME,
      column_name: COLUMN_NAME,
      job_arguments: [],
      finalize: true
    )
  end

  def down
    # no-op
  end
end

  4. Running bundle exec rails db:migrate should throw below Error

     Batched migration should be finalized only after at-least one required stop from queuing it.
 This is to ensure that we are not breaking the upgrades for self-managed instances.

 For more info visit: https://docs.gitlab.com/ee/development/database/batched_background_migrations.html#finalize-a-batched-background-migration

Happy Flow

  1. Change the milestone of above finalization migration to be greater than the next-required-stop (eg: 17.6)

    # frozen_string_literal: true

class FinalizeTestBatchedMigration < Gitlab::Database::Migration[2.2]
  milestone '17.6'
  ...
  ...
end

  2. And re-run the migration. It should pass now without any exception.

Related to #480729

Edited by Prabakaran Murugesan

Merge request reports