업그레이드 전 마이그레이션 확인

요약

- Offering: GitLab Self-Managed GitLab은 커맨드 라인에서 백그라운드 마이그레이션을 관리하기 위한 Rake 작업 세트를 제공합니다. 모든 Rake 작업은 모든 데이터베이스(main 및 ci)에 걸쳐 작동하며 통합 마이그레이션 ID 형식 {database}_{id}를 사용합니다.

업그레이드 전 마이그레이션 확인#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab Self-Managed

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

History

GitLab 18.5에서 도입됨.
GitLab 18.7에서 개선됨.
GitLab 18.9에서 개선됨.

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)).

모든 백그라운드 마이그레이션 나열#

모든 데이터베이스에 걸쳐 배치된 백그라운드 마이그레이션을 보려면:

GitLab 18.9 이상

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)

GitLab 18.8 이하

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]

`active` 상태의 마이그레이션만 일시 중지할 수 있습니다. 다른 상태의 마이그레이션을 일시 중지하려고 하면 오류가 발생합니다.

마이그레이션 재개#

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

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

예시:

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

`paused` 상태의 마이그레이션만 재개할 수 있습니다. 다른 상태의 마이그레이션을 재개하려고 하면 오류가 발생합니다.

마이그레이션 실행#

History

GitLab 18.7에서 도입됨.

이 작업은 마이그레이션을 포그라운드에서 동기적으로 실행합니다. 마이그레이션은 완료되거나 실패할 때까지 실행됩니다. 대규모 마이그레이션의 경우 상당한 시간이 걸릴 수 있으며 데이터베이스 성능에 영향을 줄 수 있습니다. 가능하면 유지보수 기간 동안 이 작업을 사용하세요.

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

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>]로 마이그레이션 상태를 확인하여 자세한 내용을 파악하세요.

모든 마이그레이션 실행#

History

GitLab 18.7에서 도입됨.

이 작업은 완료되지 않은 모든 마이그레이션을 포그라운드에서 동기적으로 실행합니다. 매우 오랜 시간이 걸릴 수 있으며 데이터베이스 성능에 상당한 영향을 줄 수 있습니다. 계획된 유지보수 기간 동안만 이 작업을 사용하세요. 개별 마이그레이션이 실패하더라도 작업은 계속 진행되지만 출력에 실패 내용을 보고합니다.

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

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 순서대로 마이그레이션을 처리합니다.
각 마이그레이션이 완료되면 상태를 보고합니다.
일부 마이그레이션이 실패하더라도 나머지 마이그레이션을 계속 처리합니다.

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

History

GitLab 13.12에서 기능 플래그 execute_batched_migrations_on_schedule가 기본값으로 활성화됨.
GitLab Self-Managed의 경우, 관리자가 비활성화하도록 선택할 수 있습니다.

데이터베이스 테이블을 배치로 업데이트하기 위해 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에서#

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.

배치된 백그라운드 마이그레이션 상태를 확인하려면:

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

데이터베이스에서#

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.

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

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

완료되지 않은 배치된 백그라운드 마이그레이션에 대한 세부 정보를 보려면 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);"

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

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

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

배치된 백그라운드 마이그레이션 일시 중지#

[릴리즈된 기능을 비활성화할 때 위험](/19.2/administration/feature_flags/#risks-when-disabling-released-features)이 있을 수 있습니다.

자세한 내용은 각 기능의 히스토리를 참조하세요.

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

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.

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

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

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

이전 단계에서 얻은 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;

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

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

자동 배치 크기 최적화#

History

GitLab 13.2에서 optimize_batched_migrations라는 플래그와 함께 도입됨. 기본값으로 활성화됨.
GitLab 18.4에서 일반적으로 사용 가능해짐. 기능 플래그 optimize_batched_migrations 제거됨.

릴리즈된 기능을 비활성화할 때 위험이 있을 수 있습니다. 자세한 내용은 이 기능의 히스토리를 참조하세요.

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

병렬 실행#

History

GitLab 15.7에서 batched_migrations_parallel_execution이라는 플래그와 함께 도입됨. 기본값으로 비활성화됨.
GitLab 15.11에서 GitLab.com에서 활성화됨.
GitLab 16.1에서 일반적으로 사용 가능해짐. 기능 플래그 batched_migrations_parallel_execution 제거됨.

릴리즈된 기능을 비활성화할 때 위험이 있을 수 있습니다. 자세한 내용은 이 기능의 히스토리를 참조하세요.

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

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

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

실패한 배치된 백그라운드 마이그레이션 해결#

배치된 백그라운드 마이그레이션이 실패하면 수정 후 재시도하세요. 마이그레이션이 계속 오류와 함께 실패하면 다음 중 하나를 선택하세요:

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

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

[

](/19.2/update/img/batched_background_migrations_failed_v14_3.png)

배치된 백그라운드 마이그레이션이 실패한 이유를 확인하려면 실패 오류 로그를 보거나 UI에서 오류 정보를 확인하세요.

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.
오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background migrations를 선택합니다.
Failed 탭을 선택합니다. 실패한 배치된 백그라운드 마이그레이션 목록이 표시됩니다.
실패한 Migration을 선택하여 마이그레이션 파라미터와 실패한 작업들을 확인합니다.
Failed jobs 아래에서 각 ID를 선택하여 작업이 실패한 이유를 확인합니다.

GitLab 고객이라면 배치된 백그라운드 마이그레이션이 실패한 이유를 디버그하기 위해 지원 요청을 여는 것을 고려하세요.

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

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.
오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background migrations를 선택합니다.
Failed 탭을 선택합니다. 실패한 배치된 백그라운드 마이그레이션 목록이 표시됩니다.
재시도 버튼( retry )을 클릭하여 재시도할 실패한 배치된 백그라운드 마이그레이션을 선택합니다.

재시도된 배치된 백그라운드 마이그레이션을 모니터링하려면 일정한 간격으로 배치된 백그라운드 마이그레이션 상태를 확인할 수 있습니다.

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

오류로 실패한 배치된 백그라운드 마이그레이션을 수동으로 완료하려면 실패 오류 로그 또는 데이터베이스의 정보를 사용하세요:

실패 오류 로그에서

실패 오류 로그를 확인하고 다음과 같은 An error has occurred, all later migrations canceled 오류 메시지를 찾습니다:

StandardError: An error has occurred, all later migrations canceled:

Expected batched background migration for the given configuration to be marked as
'finished', but it is 'active':
  {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob",
   :table_name=>"push_event_payloads",
   :column_name=>"event_id",
   :job_arguments=>[["event_id"],
   ["event_id_convert_to_bigint"]]
  }

꺾쇠 괄호 안의 값을 올바른 인수로 대체하여 다음 명령을 실행합니다:

sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']

[["id"],["id_convert_to_bigint"]]와 같이 여러 인수를 처리할 때는 잘못된 문자 오류를 방지하기 위해 각 인수 사이의 쉼표를 백슬래시 \로 이스케이프합니다. 예를 들어 이전 단계의 마이그레이션을 완료하려면:

sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,push_event_payloads,event_id,'[["event_id"]\, ["event_id_convert_to_bigint"]]']

데이터베이스에서

데이터베이스에서 마이그레이션의 상태를 확인합니다.

쿼리 결과를 사용하여 마이그레이션 명령을 작성하고, 꺾쇠 괄호 안의 값을 올바른 인수로 대체합니다:

sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']

예를 들어 쿼리가 다음 데이터를 반환하는 경우:

job_class_name: CopyColumnUsingBackgroundMigrationJob

table_name: events
column_name: id
job_arguments: [["id"], ["id_convert_to_bigint"]]

[["id"],["id_convert_to_bigint"]]와 같이 여러 인수를 처리할 때는 잘못된 문자 오류를 방지하기 위해 각 인수 사이의 쉼표를 백슬래시 \로 이스케이프합니다. job_arguments 파라미터 값의 모든 쉼표는 백슬래시로 이스케이프해야 합니다.

예시:

sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds,id,'[["id"\, "stage_id"]\,["id_convert_to_bigint"\,"stage_id_convert_to_bigint"]]']

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

이 안내를 사용하기 전에 [GitLab 지원팀에 문의](https://support.gitlab.com/hc/en-us/articles/11626483177756-GitLab-Support#contact-support)하세요. 이 작업은 데이터 손실을 일으킬 수 있으며 인스턴스를 복구하기 어려운 방식으로 실패하게 만들 수 있습니다.

너무 많은 버전 업그레이드를 건너뛰거나 이전 버전과 호환되지 않는 데이터베이스 스키마 변경으로 인해 백그라운드 마이그레이션이 실패하는 경우가 있을 수 있습니다. (예시는 이슈 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)
상태 전환(pending, running, succeeded 또는 failed)

마이그레이션 실행 추적#

특정 배치된 백그라운드 마이그레이션을 추적하려면:

Sidekiq 로그 항목에서 Database::BatchedBackgroundMigrationWorker의 correlation_id를 찾습니다.
해당 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 통합을 활성화한 경우에만 해당됩니다. 메이저 릴리즈에서는 메이저 버전 업그레이드 전에 현재 버전의 가장 최근 마이너 릴리즈에서 모든 고급 검색 마이그레이션이 완료되어야 합니다. 다음 명령을 실행하여 대기 중인 마이그레이션을 찾을 수 있습니다.

Linux package (Omnibus)

sudo gitlab-rake gitlab:elastic:list_pending_migrations

Self-compiled (source)

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 설정으로 고급 검색을 비활성화할 수도 있습니다.

대규모 인스턴스 인덱싱에는 위험이 따릅니다.

자세한 내용은 대규모 인스턴스를 효율적으로 인덱싱을 참조하세요.

업그레이드 전 마이그레이션 확인

GitLab v19.2

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-06-19

요약

업그레이드 전 마이그레이션 확인#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab Self-Managed

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

History

GitLab 18.5에서 도입됨.
GitLab 18.7에서 개선됨.
GitLab 18.9에서 개선됨.

활성 마이그레이션의 경우, 가능하면 progress 칼럼에 예상 남은 시간이 표시됩니다(예: 42.50% (estimated time remaining: 5 minutes)).

모든 백그라운드 마이그레이션 나열#

모든 데이터베이스에 걸쳐 배치된 백그라운드 마이그레이션을 보려면:

GitLab 18.9 이상

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)

GitLab 18.8 이하

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]

`active` 상태의 마이그레이션만 일시 중지할 수 있습니다. 다른 상태의 마이그레이션을 일시 중지하려고 하면 오류가 발생합니다.

마이그레이션 재개#

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

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

예시:

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

`paused` 상태의 마이그레이션만 재개할 수 있습니다. 다른 상태의 마이그레이션을 재개하려고 하면 오류가 발생합니다.

마이그레이션 실행#

History

GitLab 18.7에서 도입됨.

이 작업은 마이그레이션을 포그라운드에서 동기적으로 실행합니다. 마이그레이션은 완료되거나 실패할 때까지 실행됩니다. 대규모 마이그레이션의 경우 상당한 시간이 걸릴 수 있으며 데이터베이스 성능에 영향을 줄 수 있습니다. 가능하면 유지보수 기간 동안 이 작업을 사용하세요.

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

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.

모든 마이그레이션 실행#

History

GitLab 18.7에서 도입됨.

이 작업은 완료되지 않은 모든 마이그레이션을 포그라운드에서 동기적으로 실행합니다. 매우 오랜 시간이 걸릴 수 있으며 데이터베이스 성능에 상당한 영향을 줄 수 있습니다. 계획된 유지보수 기간 동안만 이 작업을 사용하세요. 개별 마이그레이션이 실패하더라도 작업은 계속 진행되지만 출력에 실패 내용을 보고합니다.

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

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 순서대로 마이그레이션을 처리합니다.
각 마이그레이션이 완료되면 상태를 보고합니다.
일부 마이그레이션이 실패하더라도 나머지 마이그레이션을 계속 처리합니다.

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

History

GitLab 13.12에서 기능 플래그 execute_batched_migrations_on_schedule가 기본값으로 활성화됨.
GitLab Self-Managed의 경우, 관리자가 비활성화하도록 선택할 수 있습니다.

이러한 마이그레이션 완료에 필요한 시간을 줄이려면 background_migration 큐에서 작업을 처리할 수 있는 Sidekiq 워커 수를 늘리세요.

배치된 백그라운드 마이그레이션 상태 확인#

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

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

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

GitLab UI에서#

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.

배치된 백그라운드 마이그레이션 상태를 확인하려면:

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

데이터베이스에서#

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.

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

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

완료되지 않은 배치된 백그라운드 마이그레이션에 대한 세부 정보를 보려면 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);"

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

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

배치된 백그라운드 마이그레이션 일시 중지#

[릴리즈된 기능을 비활성화할 때 위험](/19.2/administration/feature_flags/#risks-when-disabling-released-features)이 있을 수 있습니다.

자세한 내용은 각 기능의 히스토리를 참조하세요.

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.

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

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

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

이전 단계에서 얻은 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;

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

자동 배치 크기 최적화#

History

GitLab 13.2에서 optimize_batched_migrations라는 플래그와 함께 도입됨. 기본값으로 활성화됨.
GitLab 18.4에서 일반적으로 사용 가능해짐. 기능 플래그 optimize_batched_migrations 제거됨.

릴리즈된 기능을 비활성화할 때 위험이 있을 수 있습니다. 자세한 내용은 이 기능의 히스토리를 참조하세요.

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

병렬 실행#

History

GitLab 15.7에서 batched_migrations_parallel_execution이라는 플래그와 함께 도입됨. 기본값으로 비활성화됨.
GitLab 15.11에서 GitLab.com에서 활성화됨.
GitLab 16.1에서 일반적으로 사용 가능해짐. 기능 플래그 batched_migrations_parallel_execution 제거됨.

릴리즈된 기능을 비활성화할 때 위험이 있을 수 있습니다. 자세한 내용은 이 기능의 히스토리를 참조하세요.

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

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

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

실패한 배치된 백그라운드 마이그레이션 해결#

배치된 백그라운드 마이그레이션이 실패하면 수정 후 재시도하세요. 마이그레이션이 계속 오류와 함께 실패하면 다음 중 하나를 선택하세요:

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

[

](/19.2/update/img/batched_background_migrations_failed_v14_3.png)

배치된 백그라운드 마이그레이션이 실패한 이유를 확인하려면 실패 오류 로그를 보거나 UI에서 오류 정보를 확인하세요.

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.
오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background migrations를 선택합니다.
Failed 탭을 선택합니다. 실패한 배치된 백그라운드 마이그레이션 목록이 표시됩니다.
실패한 Migration을 선택하여 마이그레이션 파라미터와 실패한 작업들을 확인합니다.
Failed jobs 아래에서 각 ID를 선택하여 작업이 실패한 이유를 확인합니다.

GitLab 고객이라면 배치된 백그라운드 마이그레이션이 실패한 이유를 디버그하기 위해 지원 요청을 여는 것을 고려하세요.

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

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.
오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background migrations를 선택합니다.
Failed 탭을 선택합니다. 실패한 배치된 백그라운드 마이그레이션 목록이 표시됩니다.
재시도 버튼( retry )을 클릭하여 재시도할 실패한 배치된 백그라운드 마이그레이션을 선택합니다.

재시도된 배치된 백그라운드 마이그레이션을 모니터링하려면 일정한 간격으로 배치된 백그라운드 마이그레이션 상태를 확인할 수 있습니다.

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

오류로 실패한 배치된 백그라운드 마이그레이션을 수동으로 완료하려면 실패 오류 로그 또는 데이터베이스의 정보를 사용하세요:

실패 오류 로그에서

실패 오류 로그를 확인하고 다음과 같은 An error has occurred, all later migrations canceled 오류 메시지를 찾습니다:

StandardError: An error has occurred, all later migrations canceled:

Expected batched background migration for the given configuration to be marked as
'finished', but it is 'active':
  {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob",
   :table_name=>"push_event_payloads",
   :column_name=>"event_id",
   :job_arguments=>[["event_id"],
   ["event_id_convert_to_bigint"]]
  }

꺾쇠 괄호 안의 값을 올바른 인수로 대체하여 다음 명령을 실행합니다:

sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']

sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,push_event_payloads,event_id,'[["event_id"]\, ["event_id_convert_to_bigint"]]']

데이터베이스에서

데이터베이스에서 마이그레이션의 상태를 확인합니다.

쿼리 결과를 사용하여 마이그레이션 명령을 작성하고, 꺾쇠 괄호 안의 값을 올바른 인수로 대체합니다:

sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']

예를 들어 쿼리가 다음 데이터를 반환하는 경우:

job_class_name: CopyColumnUsingBackgroundMigrationJob

table_name: events
column_name: id
job_arguments: [["id"], ["id_convert_to_bigint"]]

예시:

sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds,id,'[["id"\, "stage_id"]\,["id_convert_to_bigint"\,"stage_id_convert_to_bigint"]]']

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

이 안내를 사용하기 전에 [GitLab 지원팀에 문의](https://support.gitlab.com/hc/en-us/articles/11626483177756-GitLab-Support#contact-support)하세요. 이 작업은 데이터 손실을 일으킬 수 있으며 인스턴스를 복구하기 어려운 방식으로 실패하게 만들 수 있습니다.

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

진행하기 전에 백업을 생성하세요.

# 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 로그#

애플리케이션 로그#

특정 배치된 백그라운드 마이그레이션의 클래스 이름(job_class_name)
상태 전환(pending, running, succeeded 또는 failed)

마이그레이션 실행 추적#

특정 배치된 백그라운드 마이그레이션을 추적하려면:

Sidekiq 로그 항목에서 Database::BatchedBackgroundMigrationWorker의 correlation_id를 찾습니다.
해당 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": []
}

대기 중인 고급 검색 마이그레이션 확인#

Linux package (Omnibus)

sudo gitlab-rake gitlab:elastic:list_pending_migrations

Self-compiled (source)

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

대규모 인스턴스 인덱싱에는 위험이 따릅니다.

자세한 내용은 대규모 인스턴스를 효율적으로 인덱싱을 참조하세요.