Method: Gitlab::Database::Migrations::BatchedBackgroundMigrationHelpers#queue_batched_background_migration

Defined in:
lib/gitlab/database/migrations/batched_background_migration_helpers.rb

#queue_batched_background_migration(job_class_name, batch_table_name, batch_column_name, *job_arguments, job_interval: BATCH_MIN_DELAY, batch_min_value: BATCH_MIN_VALUE, batch_max_value: nil, batch_class_name: BATCH_CLASS_NAME, batch_size: BATCH_SIZE, pause_ms: MINIMUM_PAUSE_MS, max_batch_size: nil, sub_batch_size: SUB_BATCH_SIZE, gitlab_schema: nil, min_cursor: nil, max_cursor: nil) ⇒ Object

Creates a batched background migration for the given table. A batched migration runs one job at a time, computing the bounds of the next batch based on the current migration settings and the previous batch bounds. Each job's execution status is tracked in the database as the migration runs. The given job class must be present in the Gitlab::BackgroundMigration module, and the batch class (if specified) must be present in the Gitlab::BackgroundMigration::BatchingStrategies module.

If a migration with same job_class_name, table_name, column_name, and job_arguments already exists, this helper will log a warning and not create a new one.

job_class_name - The background migration job class as a string batch_table_name - The name of the table the migration will batch over batch_column_name - The name of the column the migration will batch over job_arguments - Extra arguments to pass to the job instance when the migration runs job_interval - The pause interval between each job's execution, minimum of 2 minutes, defaults to BATCH_MIN_DELAY batch_min_value - The value in the column the batching will begin at batch_max_value - The value in the column the batching will end at, defaults to SELECT MAX(batch_column) batch_class_name - The name of the class that will be called to find the range of each next batch batch_size - The maximum number of rows per job sub_batch_size - The maximum number of rows processed per "iteration" within the job

Returns the created BatchedMigration record

Example:

queue_batched_background_migration(
  'CopyColumnUsingBackgroundMigrationJob',
  :events,
  :id,
  other_job_arguments: ['column1', 'column2'])

Where the background migration exists:

class Gitlab::BackgroundMigration::CopyColumnUsingBackgroundMigrationJob
  def perform(start_id, end_id, batch_table, batch_column, sub_batch_size, *other_args)
    # do something
  end
end



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/gitlab/database/migrations/batched_background_migration_helpers.rb', line 71

def queue_batched_background_migration( # rubocop:disable Metrics/ParameterLists
  job_class_name,
  batch_table_name,
  batch_column_name,
  *job_arguments,
  job_interval: BATCH_MIN_DELAY,
  batch_min_value: BATCH_MIN_VALUE,
  batch_max_value: nil,
  batch_class_name: BATCH_CLASS_NAME,
  batch_size: BATCH_SIZE,
  pause_ms: MINIMUM_PAUSE_MS,
  max_batch_size: nil,
  sub_batch_size: SUB_BATCH_SIZE,
  gitlab_schema: nil,
  min_cursor: nil,
  max_cursor: nil
)
  Gitlab::Database::QueryAnalyzers::RestrictAllowedSchemas.require_dml_mode!

  gitlab_schema ||= gitlab_schema_from_context
  queued_migration_version = version

  Gitlab::Database::BackgroundMigration::BatchedMigration.reset_column_information

  if migration_already_exists?(gitlab_schema, job_class_name, batch_table_name, batch_column_name, job_arguments)
    return
  end

  job_interval = normalize_job_interval(job_interval)

  migration = Gitlab::Database::BackgroundMigration::BatchedMigration.new(
    job_class_name: job_class_name,
    table_name: batch_table_name,
    column_name: batch_column_name,
    interval: job_interval,
    pause_ms: pause_ms,
    batch_class_name: batch_class_name,
    batch_size: batch_size,
    sub_batch_size: sub_batch_size
  )

  migration.tap do |m|
    if cursor_based_migration?(m)
      setup_cursor_based_migration!(m, batch_table_name, job_arguments, min_cursor, max_cursor)
    else
      setup_legacy_migration!(m, batch_table_name, batch_min_value, batch_max_value, job_arguments)
    end
  end

  validate_job_arguments!(migration, job_arguments)

  assign_attributes_safely(
    migration,
    max_batch_size,
    batch_table_name,
    gitlab_schema,
    queued_migration_version
  )

  migration.save!
  migration
end