Batched background migrations
배경 마이그레이션
- 대기 중인 배경 마이그레이션 확인
- 실패한 백그라운드 마이그레이션 확인

배경 마이그레이션 및 업그레이드

Tier: Free, Premium, Ultimate Offering: Self-Managed

기능 플래그 execute_batched_migrations_on_schedule은 GitLab 13.12에서 기본으로 활성화되었습니다.
GitLab Self-Managed 인스턴스의 경우, GitLab 관리자는 비활성화할 수 있습니다.

특정 릴리스는 더 높은 버전으로 업데이트하기 전에 완료해야 하는 다른 마이그레이션을 필요로 할 수 있습니다. 두 종류의 마이그레이션이 존재합니다. 이들은 다르며, GitLab을 업그레이드하기 전에 둘 다 완료되었는지 확인해야 합니다.

Batched background migrations은 GitLab 14.0에서 도입되었습니다. GitLab 15.1 및 이후의 모든 마이그레이션은 이 형식만 사용합니다.
배치되지 않은 Background migrations은 GitLab 15.0 이전에 사용되었습니다.

이러한 마이그레이션을 완료하는 데 필요한 시간을 줄이려면, background_migration 대기열에서 작업을 처리할 수 있는 Sidekiq worker의 수를 늘릴 수 있습니다.

Batched background migrations

데이터베이스 테이블을 일괄 처리하여 업데이트하려면, GitLab은 배치된 백그라운드 마이그레이션을 사용할 수 있습니다. 이러한 마이그레이션은 GitLab 개발자에 의해 생성되며 업그레이드시 자동으로 실행됩니다. 그러나 이러한 마이그레이션은 정수 오버플로를 방지하기 위해 일부 integer 데이터베이스 열을 bigint로 마이그레이션하는 데 도움을 주기 위해 범위가 제한됩니다.

배치된 백그라운드 마이그레이션은 Sidekiq에 의해 처리되며 격리된 환경에서 실행되므로, 마이그레이션이 진행되는 동안 인스턴스는 작동 중인 상태를 유지할 수 있습니다. 그러나, 배치된 배경 마이그레이션이 실행되는 동안 많이 사용되는 대형 인스턴스의 성능이 저하될 수 있습니다. 모든 마이그레이션이 완료될 때까지 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에서

전제 조건:

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

배치된 배경 마이그레이션 상태를 확인하려면:

왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
모니터링 > 배경 마이그레이션을 선택합니다.
미완료된 마이그레이션을 보려면 대기 중 또는 완료 중을 선택하고, 완료되지 않은 마이그레이션에 대해서는 실패함을 선택합니다.

데이터베이스에서

전제 조건:

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

배치된 배경 마이그레이션 상태를 직접 쿼리하여 확인하려면:

인스턴스 설치 방법에 따라 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 "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

쿼리가 0개의 행을 반환하면, 모든 배치된 배경 마이그레이션이 완료된 상태입니다.

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

배치된 배경 마이그레이션은 마이그레이션을 사용자 정의하거나 일시 중지할 수 있는 피처 플래그를 제공합니다. 이러한 피처 플래그는 그 위험을 이해하는 고급 사용자에 의해서만 비활성화되어야 합니다.

배치된 배경 마이그레이션 일시 중지

발매된 기능을 비활성화할 때 위험이 있을 수 있습니다. 자세한 내용은 각 기능의 이력을 참조하십시오.

진행 중인 배치된 배경 마이그레이션을 일시 중지하려면 배치된 배경 마이그레이션 기능을 비활성화하세요. 기능을 비활성화하면 현재의 마이그레이션을 완료한 후에 다음 배치를 시작하기까지 대기하게 됩니다.

전제 조건:

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

현재 진행 중인 마이그레이션의 ID를 얻으려면 다음 쿼리를 실행합니다.

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

이전 단계에서 얻은 ID로 이전 단계의 쿼리를 대체하여 마이그레이션의 상태를 확인합니다.

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;

마이그레이션이 일시 중지되었는지 확인하려면 몇 분 내에 쿼리를 여러 번 실행하세요. 새로운 행이 추가되지 않으면, 마이그레이션이 일시 중지된 것입니다.

일시 중지된 마이그레이션이 확인된 후, 이 쿼리를 다시 시작하려면 (위의 명령을 사용) 대기한 후 다음 배치를 시작하세요. 대형 인스턴스의 경우, 배경 마이그레이션은 각 배치당 최대 48시간이 소요될 수 있습니다.

배치 크기 자동 최적화

GitLab 13.2에서 flagoptimize_batched_migrations와 함께 도입되었습니다. 기본적으로 활성화됨.

발매된 기능을 비활성화할 때 위험이 있을 수 있습니다. 자세한 내용은 해당 기능의 이력을 참조하십시오.

Self-Managed GitLab을 기본적으로 이 기능이 사용 가능합니다. 해당 기능을 숨기려면 인스턴스의 관리자에게 피처 플래그인 optimize_batched_migrations을 비활성화하라고 요청하세요. GitLab.com에서는 이 기능이 사용 가능합니다. GitLab Dedicated에서는 이 기능이 사용할 수 없습니다.

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

병렬 실행

GitLab 15.7에서 flagbatched_migrations_parallel_execution와 함께 도입되었습니다. 기본적으로 비활성화됨.
GitLab.com에서 활성화됨 in GitLab 15.11.
GitLab 16.1에서 일반 사용 가능. 피처 플래그 batched_migrations_parallel_execution이 제거되었습니다.

발매된 기능을 비활성화할 때 위험이 있을 수 있습니다. 자세한 내용은 해당 기능의 이력을 참조하십시오.

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

GitLab 관리자는 GitLab Rails 콘솔에 액세스할 수 있습니다, 배치된 백그라운드 마이그레이션을 병렬로 실행하는 수를 변경할 수 있습니다:

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

실패한 배치 배경 마이그레이션 해결하기

배치 배경 마이그레이션이 실패하면 수정 및 다시 시도하세요. 마이그레이션이 계속하여 오류로 실패하면 다음 중 하나를 수행하세요:

매뉴얼으로 실패한 마이그레이션 완료
실패한 마이그레이션 완료로 표시

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

실패한 배치 배경 마이그레이션을 해결해야 GitLab의 최신 버전으로 업그레이드할 수 있습니다. 배치 배경 마이그레이션 상태를 확인하면 일부 마이그레이션은 Failed 탭에 failed 상태로 표시될 수 있습니다:

왜 배치 배경 마이그레이션이 실패했는지 확인하려면 실패한 오류 로그를 확인하거나 UI에서 오류 정보를 확인하세요.

전제 조건:

인스턴스에 관리자 액세스해야 합니다.

왼쪽 사이드바에서 아래쪽으로 이동하여 Admin Area를 선택합니다.
Monitoring > Background Migrations를 선택합니다.
Failed 탭을 선택합니다. 이렇게 하면 실패한 배치 배경 마이그레이션 디렉터리이 표시됩니다.
실패한 Migration을 선택하여 마이그레이션 매개변수 및 실패한 작업을 확인합니다.
Failed jobs 아래에서 각 ID를 선택하여 작업 실패 이유를 확인합니다.

GitLab 고객이라면, 배치 배경 마이그레이션이 실패한 이유를 디버그하기 위해 지원 요청을 열어 고려해보십시오.

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

전제 조건:

인스턴스에 관리자 액세스해야 합니다.

왼쪽 사이드바에서 아래쪽으로 이동하여 Admin Area를 선택합니다.
Monitoring > Background Migrations를 선택합니다.
Failed 탭을 선택합니다. 이렇게 하면 실패한 배치 배경 마이그레이션 디렉터리이 표시됩니다.
재시도할 실패한 배치 배경 마이그레이션을 선택하고, 다시 시도 버튼을 클릭합니다 ().

재시도된 배치 배경 마이그레이션을 모니터링하기 위해 정기적으로 배치 배경 마이그레이션 상태를 확인할 수 있습니다.

매뉴얼으로 실패한 마이그레이션 완료

오류로 실패한 배치 배경 마이그레이션을 매뉴얼으로 완료하려면, 실패한 오류 로그나 데이터베이스의 정보를 사용하세요:

실패한 오류 로그에서

실패한 오류 로그를 확인하여 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"]]와 같은 여러 인수를 처리할 때는, 각 인수 사이의 쉼표를 backslash \로 이스케이프하여 잘못된 문자 오류를 방지하세요. 예를 들어, 이전 단계의 마이그레이션을 완료하려면:
```
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"]]와 같은 여러 인수를 처리할 때는, 각 인수 사이의 쉼표를 backslash \로 이스케이프하여 잘못된 문자 오류를 방지하세요. 명령은 다음과 같아야 합니다:

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

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

이 지시사항을 사용하기 전에 GitLab 지원팀에 문의하세요. 이 작업은 데이터 손실을 야기할 수 있으며, 인스턴스를 복구하기 어려운 방법으로 실패하게 만들 수 있습니다.

배경 마이그레이션이 너무 많은 버전 업그레이드를 거치거나, 하위 호환되지 않는 데이터베이스 스키마 변경으로 실패하는 경우가 있습니다. (예: 이슈 393216 참조) 실패한 배경 마이그레이션은 더 이상 애플리케이션 업그레이드를 방지합니다.

배경 마이그레이션이 “안전”하게 건너뛰기로 결정되면, 마이그레이션을 매뉴얼으로 완료할 수 있습니다:

진행하기 전에 백업을 만들어야 합니다.

# Rails 콘솔 시작

connection = ApplicationRecord.connection # 또는 Ci::ApplicationRecord.connection, 마이그레이션이 예약된 DB에 따라 다름

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,
    []
  )
  
  # 모든 작업 완료로 표시
  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