Add helper to delete queued background migrations when rescheduling

doc/development/background_migrations.md

@@ -142,6 +142,14 @@ migration performing the scheduling. Otherwise the background migration would be
 scheduled multiple times on systems that are upgrading multiple patch releases at
 once.
 
+When you start the second post-deployment migration, you should delete any
+previously queued jobs from the initial migration with the provided
+helper:
+
+```ruby
+delete_queued_jobs('BackgroundMigrationClassName')
+```
+
 ## Cleaning Up
 
 NOTE:

lib/gitlab/database/migrations/background_migration_helpers.rb

@@ -236,6 +236,14 @@ module Gitlab
           Gitlab::ApplicationContext.with_context(caller_id: self.class.to_s, &block)
         end
 
+        def delete_queued_jobs(class_name)
+          Gitlab::BackgroundMigration.steal(class_name) do |job|
+            job.delete
+
+            false
+          end
+        end
+
         private
 
         def track_in_database(class_name, arguments)

spec/lib/gitlab/database/migrations/background_migration_helpers_spec.rb

@@ -431,4 +431,21 @@ RSpec.describe Gitlab::Database::Migrations::BackgroundMigrationHelpers do
       model.bulk_migrate_in(10.minutes, [%w(Class hello world)])
     end
   end
+
+  describe '#delete_queued_jobs' do
+    let(:job1) { double }
+    let(:job2) { double }
+
+    it 'deletes all queued jobs for the given background migration' do
+      expect(Gitlab::BackgroundMigration).to receive(:steal).with('BackgroundMigrationClassName') do |&block|
+        expect(block.call(job1)).to be(false)
+        expect(block.call(job2)).to be(false)
+      end
+
+      expect(job1).to receive(:delete)
+      expect(job2).to receive(:delete)
+
+      model.delete_queued_jobs('BackgroundMigrationClassName')
+    end
+  end
 end