Rake 작업으로 백그라운드 마이그레이션 관리#

GitLab은 명령줄에서 백그라운드 마이그레이션을 관리하기 위한 Rake 작업 세트를 제공합니다. 이 작업들은 다운타임 업그레이드 또는 유지 관리 창 중에 Admin UI를 사용할 수 없는 경우처럼 백그라운드 마이그레이션을 관리해야 하는 Self-Managed 관리자에게 특히 유용합니다.

모든 Rake 작업은 모든 데이터베이스(main 및 ci)에서 작동하며 통합된 마이그레이션 ID 형식을 사용합니다: {database}_{id}. 예를 들어, main_85는 main 데이터베이스의 마이그레이션 ID 85를 나타내고, ci_10은 ci 데이터베이스의 마이그레이션 ID 10을 나타냅니다.

활성 마이그레이션의 경우, progress 열에는 가능한 경우 예상 남은 시간이 포함됩니다(예: 42.50% (estimated time remaining: 5 minutes)).

모든 백그라운드 마이그레이션 목록 표시#

모든 데이터베이스에 걸친 일괄 백그라운드 마이그레이션을 모두 보려면:

sudo gitlab-rake gitlab:background_migrations:list

id      | table_name                       | job_class_name                                | status    | progress
--------|----------------------------------|-----------------------------------------------|-----------|----------------------------------------------------------
main_1  | namespace_settings               | UpdateRequireDpopForManageApiEndpointsToFalse | finished  | 100.00%
main_2  | resource_iteration_events        | BackfillResourceIterationEventsNamespaceId    | finalized | 100.00%
main_3  | identities                       | DeleteTwitterIdentities                       | finalized | 100.00%
main_4  | software_license_policies        | BackfillLicensesOutsideSpdxCatalogue          | finalized | 100.00%
main_5  | security_policies                | BackfillPipelineExecutionPoliciesMetadata     | active    | 42.50% (estimated time remaining: 5 minutes)
ci_1    | ci_runners                       | MarkAdminBotRunnersAsHosted                   | finalized | 100.00%
ci_2    | p_ci_build_trace_metadata        | BackfillUpsertedCiBuildTraceMetadataProjectId | finalized | 100.00%
ci_3    | ci_runners                       | BackfillOrganizationIdOnCiRunners             | active    | 78.30% (estimated time remaining: about 1 hour)

sudo gitlab-rake gitlab:background_migrations:status

마이그레이션 상세 정보 표시#

특정 마이그레이션에 대한 자세한 정보를 보려면:

sudo gitlab-rake gitlab:background_migrations:show[<migration_id>]

예를 들어:

sudo gitlab-rake gitlab:background_migrations:show[ci_1]

출력 예시:

id                       | ci_1
created_at               | 2025-05-06 22:40:08 UTC
updated_at               | 2025-08-20 22:29:07 UTC
min_value                | 1
max_value                | 30
batch_size               | 1000
sub_batch_size           | 100
interval                 | 120
status                   | finalized
job_class_name           | MarkAdminBotRunnersAsHosted
batch_class_name         | PrimaryKeyBatchingStrategy
table_name               | ci_runners
column_name              | id
job_arguments            | []
total_tuple_count        |
pause_ms                 | 100
max_batch_size           |
started_at               | 2025-05-06 22:40:08 UTC
on_hold_until            |
gitlab_schema            | gitlab_ci
finished_at              | 2025-05-06 22:40:13 UTC
queued_migration_version | 20250505095336
min_cursor               |
max_cursor               |

마이그레이션 일시 중지#

활성 백그라운드 마이그레이션을 일시 중지하려면:

sudo gitlab-rake gitlab:background_migrations:pause[<migration_id>]

예를 들어:

sudo gitlab-rake gitlab:background_migrations:pause[main_85]

마이그레이션 재개#

일시 중지된 백그라운드 마이그레이션을 재개하려면:

sudo gitlab-rake gitlab:background_migrations:resume[<migration_id>]

예를 들어:

sudo gitlab-rake gitlab:background_migrations:resume[main_85]

마이그레이션 실행#

특정 백그라운드 마이그레이션을 즉시 실행하려면:

sudo gitlab-rake gitlab:background_migrations:execute[<migration_id>]

예를 들어:

sudo gitlab-rake gitlab:background_migrations:execute[ci_10]

출력 예시:

Are you sure you want to execute this migration? yes
Executing background migration `ci_10`...
Done.

작업은 실행 전에 확인을 요청합니다. 마이그레이션이 완료되지 않으면 gitlab:background_migrations:show[<migration_id>]로 마이그레이션 상태를 확인하여 자세한 내용을 확인하십시오.

모든 마이그레이션 실행#

모든 데이터베이스에서 완료되지 않은 백그라운드 마이그레이션을 모두 실행하려면:

sudo gitlab-rake gitlab:background_migrations:execute_all

출력 예시:

Are you sure you want to execute all unfinished migrations? yes
[main] Executing 6 background migrations...
[main_85]: Start.
[main_85]: Done.
[main_86]: Start.
[main_86]: Done.
[main_87]: Start.
[main_87]: Done.
[main_88]: Start.
[main_88]: Done.
[main_89]: Start.
[main_89]: Done.
[main_90]: Start.
[main_90]: Done.
[ci] Executing 3 background migrations...
[ci_8]: Start.
[ci_8]: Done.
[ci_9]: Start.
[ci_9]: Done.
[ci_10]: Start.
[ci_10]: Done.

작업은:

• 실행 전에 확인을 요청합니다.
• ID 순서로 마이그레이션을 처리합니다.
• 각 마이그레이션이 완료될 때 상태를 보고합니다.
• 일부가 실패해도 나머지 마이그레이션 처리를 계속합니다.

보류 중인 데이터베이스 백그라운드 마이그레이션 확인#

데이터베이스 테이블을 일괄적으로 업데이트하기 위해 GitLab은 일괄 백그라운드 마이그레이션을 사용할 수 있습니다. 이러한 마이그레이션은 GitLab 개발자가 만들고 업그레이드 시 자동으로 실행됩니다. 그러나 이러한 마이그레이션은 일부 테이블의 정수 오버플로를 방지하기 위해 일부 integer 데이터베이스 열을 bigint로 마이그레이션하는 데 도움이 되는 범위로 제한됩니다.

일괄 백그라운드 마이그레이션은 Sidekiq에 의해 처리되며 격리되어 실행되므로 마이그레이션이 처리되는 동안 인스턴스가 계속 작동할 수 있습니다. 그러나 일괄 백그라운드 마이그레이션이 실행되는 동안 많이 사용되는 대규모 인스턴스에서는 성능이 저하될 수 있습니다. 모든 마이그레이션이 완료될 때까지 Sidekiq 상태를 적극적으로 모니터링해야 합니다.

이러한 마이그레이션을 완료하는 데 필요한 시간을 줄이려면 background_migration 큐의 작업을 처리할 수 있는 Sidekiq 작업자 수를 늘리십시오.

일괄 백그라운드 마이그레이션 상태 확인#

GitLab UI에서 또는 데이터베이스를 직접 쿼리하여 일괄 백그라운드 마이그레이션의 상태를 확인할 수 있습니다. GitLab을 업그레이드하기 전에 모든 마이그레이션이 Finished 상태여야 합니다.

마이그레이션이 완료되지 않은 상태에서 GitLab을 업그레이드하려고 하면 다음 오류가 발생할 수 있습니다:

Expected batched background migration for the given configuration to be marked
as 'finished', but it is 'active':

이 오류가 발생하면 GitLab 업그레이드에 필요한 일괄 백그라운드 마이그레이션을 완료하는 방법에 대한 옵션을 검토하십시오.

GitLab UI에서#

전제 조건:

• 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.

일괄 백그라운드 마이그레이션의 상태를 확인하려면:

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Monitoring > Background migrations을 선택합니다.
3. 완료되지 않은 마이그레이션을 보려면 Queued 또는 Finalizing을 선택하고, 실패한 마이그레이션을 보려면 Failed를 선택합니다.

데이터베이스에서#

전제 조건:

• 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.

일괄 백그라운드 마이그레이션의 상태를 데이터베이스에서 직접 쿼리하려면:

1. 인스턴스의 설치 방법에 따라 psql 프롬프트에 로그인합니다. 예를 들어 Linux 패키지 설치의 경우 sudo gitlab-psql.

2. 완료되지 않은 일괄 백그라운드 마이그레이션에 대한 세부 정보를 보려면 psql 세션에서 다음 쿼리를 실행합니다:

   SELECT
     job_class_name,
     table_name,
     column_name,
     job_arguments
   FROM batched_background_migrations
   WHERE status NOT IN(3, 6);
   

또는 gitlab-psql -c ""로 쿼리를 래핑하여 일괄 백그라운드 마이그레이션의 상태를 확인할 수 있습니다:

gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

쿼리가 행을 반환하지 않으면 모든 일괄 백그라운드 마이그레이션이 완료된 것입니다.

고급 기능 활성화 또는 비활성화#

일괄 백그라운드 마이그레이션은 마이그레이션을 사용자 정의하거나 완전히 일시 중지할 수 있는 기능 플래그를 제공합니다. 이러한 기능 플래그는 위험을 이해하는 고급 사용자만 비활성화해야 합니다.

일괄 백그라운드 마이그레이션 일시 중지#

진행 중인 일괄 백그라운드 마이그레이션을 일시 중지하려면 일괄 백그라운드 마이그레이션 기능을 비활성화합니다. 기능을 비활성화하면 현재 마이그레이션 배치가 완료된 후 기능이 다시 활성화될 때까지 다음 배치 시작이 대기합니다.

전제 조건:

• 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.

다음 데이터베이스 쿼리를 사용하여 현재 일괄 백그라운드 마이그레이션의 상태를 확인합니다:

1. 실행 중인 마이그레이션의 ID를 가져옵니다:

   SELECT
    id,
    job_class_name,
    table_name,
    column_name,
    job_arguments
   FROM batched_background_migrations
   WHERE status NOT IN(3, 6);
   

2. 이전 단계에서 가져온 ID로 XX를 교체하여 다음 쿼리를 실행하면 마이그레이션 상태를 볼 수 있습니다:

   SELECT
    started_at,
    finished_at,
    finished_at - started_at AS duration,
    min_value,
    max_value,
    batch_size,
    sub_batch_size
   FROM batched_background_migration_jobs
   WHERE batched_background_migration_id = XX
   ORDER BY id DESC
   limit 10;
   

3. 몇 분 내에 쿼리를 여러 번 실행하여 새 행이 추가되지 않았는지 확인합니다. 새 행이 추가되지 않았으면 마이그레이션이 일시 중지된 것입니다.

4. 마이그레이션이 일시 중지되었음을 확인한 후, 준비가 되면 (이전에 언급한 enable 명령을 사용하여) 마이그레이션을 다시 시작하여 배치를 진행합니다. 대규모 인스턴스에서는 백그라운드 마이그레이션이 각 배치를 완료하는 데 최대 48시간이 걸릴 수 있습니다.

자동 배치 크기 최적화#

일괄 백그라운드 마이그레이션의 처리량(단위 시간당 업데이트된 튜플 수 기준)을 최대화하기 위해 이전 배치가 완료되는 데 걸린 시간을 기반으로 배치 크기가 자동으로 조정됩니다.

병렬 실행#

일괄 백그라운드 마이그레이션의 실행 속도를 높이기 위해 두 개의 마이그레이션이 동시에 실행됩니다.

GitLab Rails 콘솔에 접근할 수 있는 GitLab 관리자는 병렬로 실행되는 일괄 백그라운드 마이그레이션 수를 변경할 수 있습니다:

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

실패한 일괄 백그라운드 마이그레이션 해결#

일괄 백그라운드 마이그레이션이 실패하면 수정하고 재시도합니다. 마이그레이션이 계속 오류와 함께 실패하면 다음 중 하나를 수행합니다:

• 실패한 마이그레이션을 수동으로 완료
• 실패한 마이그레이션을 완료로 표시

마이그레이션 수정 및 재시도#

GitLab의 최신 버전으로 업그레이드하려면 실패한 모든 일괄 백그라운드 마이그레이션을 해결해야 합니다. 일괄 백그라운드 마이그레이션 상태를 확인하면 일부 마이그레이션이 Failed 탭에 failed 상태로 표시될 수 있습니다:

일괄 백그라운드 마이그레이션이 실패한 이유를 확인하려면 실패 오류 로그를 보거나 UI에서 오류 정보를 확인합니다.

전제 조건:

• 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. Monitoring > Background migrations를 선택합니다.
3. Failed 탭을 선택합니다. 실패한 일괄 백그라운드 마이그레이션 목록이 표시됩니다.
4. 실패한 Migration을 선택하여 마이그레이션 매개변수와 실패한 작업을 확인합니다.
5. Failed jobs 아래에서 각 ID를 선택하여 작업이 실패한 이유를 확인합니다.

GitLab 고객인 경우 일괄 백그라운드 마이그레이션이 실패한 이유를 디버그하기 위해 지원 요청을 열어 보십시오.

문제를 수정하려면 실패한 마이그레이션을 다시 시도할 수 있습니다.

전제 조건:

• 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. Monitoring > Background migrations를 선택합니다.
3. Failed 탭을 선택합니다. 실패한 일괄 백그라운드 마이그레이션 목록이 표시됩니다.
4. 재시도 버튼([retry])을 클릭하여 재시도할 실패한 일괄 백그라운드 마이그레이션을 선택합니다.

재시도된 일괄 백그라운드 마이그레이션을 모니터링하려면 정기적인 간격으로 일괄 백그라운드 마이그레이션의 상태를 확인합니다.

실패한 마이그레이션 수동 완료#

오류와 함께 실패한 일괄 백그라운드 마이그레이션을 수동으로 완료하려면 실패 오류 로그 또는 데이터베이스의 정보를 사용합니다:

실패한 마이그레이션을 완료로 표시#

백그라운드 마이그레이션이 실패하는 경우가 있을 수 있습니다: 너무 많은 버전 업그레이드를 건너뛰거나 이전 버전과 호환되지 않는 데이터베이스 스키마 변경의 경우. (예를 들어 이슈 393216을 참조하십시오). 실패한 백그라운드 마이그레이션은 추가 애플리케이션 업그레이드를 방지합니다.

백그라운드 마이그레이션을 건너뛰는 것이 "안전"하다고 판단되면 마이그레이션을 수동으로 완료로 표시할 수 있습니다:

# Start the rails console

connection = ApplicationRecord.connection # or Ci::ApplicationRecord.connection, depending on which DB was the migration scheduled

Gitlab::Database::SharedModel.using_connection(connection) do
  migration = Gitlab::Database::BackgroundMigration::BatchedMigration.find_for_configuration(
    Gitlab::Database.gitlab_schemas_for_connection(connection),
    'BackfillUserDetailsFields',
    :users,
    :id,
    []
  )

  # mark all jobs completed
  migration.batched_jobs.update_all(status: Gitlab::Database::BackgroundMigration::BatchedJob.state_machine.states['succeeded'].value)
  migration.update_attribute(:status, Gitlab::Database::BackgroundMigration::BatchedMigration.state_machine.states[:finished].value)
end

모든 백그라운드 마이그레이션 동기적으로 실행#

유지 관리 창 동안 백그라운드 마이그레이션을 강제로 포그라운드에서 실행하려는 경우가 있을 수 있습니다.

이 스크립트는 모든 마이그레이션이 완료되기 전에 타임아웃/종료될 수 있습니다. 모든 마이그레이션이 완료될 때까지 다시 실행할 수 있습니다.

# Start the rails console

databases = ActiveRecord::Tasks::DatabaseTasks.setup_initial_database_yaml

Gitlab::Database.database_base_models.each do |database_name, model|
  Gitlab::Database::SharedModel.using_connection(model.connection) do
    Gitlab::Database::BackgroundMigration::BatchedMigration.with_status([:paused, :active]).find_each(batch_size: 100) do |migration|
      puts "#{database_name}: Finalizing migration #{migration.job_class_name} (ID: #{migration.id})... "
      Gitlab::Database::BackgroundMigration::BatchedMigrationRunner.finalize(
        migration.job_class_name,
        migration.table_name,
        migration.column_name,
        Gitlab::Json.parse(migration.job_arguments),
        connection: model.connection
      )
      puts("done!\n")
    end
  end
end

일괄 백그라운드 마이그레이션 로그 보기#

일괄 백그라운드 마이그레이션 문제를 해결할 때 여러 위치에서 자세한 실행 로그를 볼 수 있습니다.

Sidekiq 로그#

Sidekiq 로그는 Database::BatchedBackgroundMigrationWorker 작업이 실행될 때를 보여줍니다. 이러한 로그는 작업 실행을 표시하지만 어떤 특정 마이그레이션이 실행 중인지는 식별하지 않습니다.

애플리케이션 로그#

어떤 일괄 백그라운드 마이그레이션이 실행 중인지 확인하려면 애플리케이션 로그를 확인합니다. 애플리케이션 로그에는 다음을 포함한 자세한 정보가 포함됩니다:

• 특정 일괄 백그라운드 마이그레이션의 클래스 이름 (job_class_name)
• 상태 전환 (보류 중, 실행 중, 성공 또는 실패)

마이그레이션 실행 추적#

특정 일괄 백그라운드 마이그레이션을 추적하려면:

1. Database::BatchedBackgroundMigrationWorker에 대한 Sidekiq 로그 항목에서 correlation_id를 찾습니다.
2. 해당 correlation_id로 애플리케이션 로그를 검색하여 자세한 상태 전환을 확인합니다.

애플리케이션 로그 항목 예시:

{
  "severity": "INFO",
  "time": "2025-08-27T22:52:07.806Z",
  "meta.caller_id": "Database::BatchedBackgroundMigration::MainExecutionWorker",
  "correlation_id": "74d0295cbe4bb6147230a7d481fb0f8a",
  "message": "BatchedJob transition",
  "batched_job_id": 725,
  "previous_state": "pending",
  "new_state": "running",
  "batched_migration_id": 638,
  "job_class_name": "BackfillSentNotificationsAfterPartition",
  "job_arguments": []
},
{
  "severity": "INFO",
  "time": "2025-08-27T22:52:14.293Z",
  "meta.caller_id": "Database::BatchedBackgroundMigration::MainExecutionWorker",
  "correlation_id": "74d0295cbe4bb6147230a7d481fb0f8a",
  "message": "BatchedJob transition",
  "batched_job_id": 725,
  "previous_state": "running",
  "new_state": "succeeded",
  "batched_migration_id": 638,
  "job_class_name": "BackfillSentNotificationsAfterPartition",
  "job_arguments": []
}

보류 중인 고급 검색 마이그레이션 확인#

이 섹션은 Elasticsearch 통합을 활성화한 경우에만 해당됩니다. 주요 릴리스에서는 주요 버전 업그레이드 전에 현재 버전의 가장 최근 마이너 릴리스에서 모든 고급 검색 마이그레이션이 완료되어야 합니다. 다음 명령을 실행하여 보류 중인 마이그레이션을 찾을 수 있습니다.

sudo gitlab-rake gitlab:elastic:list_pending_migrations

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations

오랜 업그레이드 경로를 사용 중이고 많은 보류 중인 마이그레이션이 있는 경우 인덱싱 속도를 높이기 위해 Requeue indexing workers 및 Number of shards for non-code indexing을 구성할 수 있습니다. 또 다른 옵션은 보류 중인 마이그레이션을 무시하고 GitLab을 대상 버전으로 업그레이드한 후 인스턴스를 다시 인덱싱하는 것입니다. Search with advanced search 설정으로 이 프로세스 중에 고급 검색을 비활성화할 수도 있습니다.