문제 해결

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

배치된 백그라운드 마이그레이션이 완료되지 않아 데이터베이스 마이그레이션이 실패하는 경우

GitLab 버전 14.2 이상으로 업데이트할 때 데이터베이스 마이그레이션이 다음과 같은 메시지로 실패할 수 있습니다. 

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"]]
  }

먼저 14.2 버전별 업그레이드 지침을 따랐는지 확인하세요. 만약 따랐다면 배치된 백그라운드 마이그레이션을 매뉴얼으로 완료할 수 있습니다. 만약 따르지 않았다면, 다음 방법 중 하나를 선택하세요:

  1. 14.2+로 업데이트하기 전에 필요한 버전 중 하나로 롤백 및 업그레이드합니다.
  2. 현재 버전에 머무르면서 롤 포워드하여 배치된 마이그레이션이 성공적으로 완료되도록 매뉴얼으로 확인하세요.

롤백 및 필요한 업그레이드 경로 따르기

  1. 이전에 설치된 버전으로 롤백 및 복원합니다.
  2. 14.2+로 업데이트하기 전에 14.0.5 또는 14.1로 업데이트합니다.
  3. 배치된 백그라운드 마이그레이션의 상태를 확인하고 업그레이드를 다시 시도하기 전에 모두 완료되었는지 확인하세요. 만약 아직 활성화된 상태로 남아 있다면, 매뉴얼으로 완료할 수 있습니다.

롤 포워드 및 업그레이드된 버전에서 마이그레이션 완료

다운타임이 있는 배포의 경우

배치된 백그라운드 마이그레이션을 모두 실행하려면 GitLab 설치 크기에 따라 상당한 시간이 소요될 수 있습니다.

  1. 데이터베이스에서 배치된 백그라운드 마이그레이션의 상태를 확인하고 적절한 인수로 매뉴얼으로 실행하여 상태 쿼리가 더 이상 행을 반환하지 않도록 합니다.
  2. 모든 마이그레이션이 완료된 상태라면, 설치별 마이그레이션을 다시 실행합니다.

  3. GitLab 업그레이드를 완료하기 위해 데이터베이스 마이그레이션을 완료합니다: 

    sudo gitlab-rake db:migrate

  4. 재구성을 실행합니다: 

    sudo gitlab-ctl reconfigure
  5. 설치별 업그레이드를 완료합니다.

다운타임이 없는 배포의 경우

실패한 마이그레이션이 배포 이후 마이그레이션인 경우, 업그레이드된 버전의 실행 중인 인스턴스에 머무를 수 있으며, 배치된 백그라운드 마이그레이션이 완료될 때까지 기다릴 수 있습니다.

  1. 오류 메시지의 배치된 백그라운드 마이그레이션 상태를 확인하고 완료되었는지 확인합니다. 아직 활성 상태인 경우, 완료될 때까지 기다리거나 매뉴얼으로 완료할 수 있습니다.
  2. 설치별 마이그레이션을 다시 실행하여 남은 배포 이후 마이그레이션이 완료되도록 합니다.

BackfillNamespaceIdForNamespaceRoute 배치된 마이그레이션 작업 실패

GitLab 14.8에서 BackfillNamespaceIdForNamespaceRoute 배치된 백그라운드 마이그레이션 작업이 완료되지 못할 수 있습니다. 다시 시도하면 500 서버 오류가 반환될 수 있습니다. 이 문제는 GitLab 14.9에서 해결되었습니다.

이 문제를 해결하려면, 14.8에서 14.9로 GitLab 업그레이드하세요. GitLab 14.9로 업데이트한 후에 실패한 배치 마이그레이션을 무시할 수 있습니다.

백그라운드 마이그레이션이 Sidekiq 대기열에 남아 있는 경우

caution
다음 작업은 GitLab 성능에 영향을 줄 수 있습니다. 다양한 데이터베이스 또는 파일 업데이트를 수행하는 여러 Sidekiq 작업을 실행합니다.

다음 검사를 실행하고, 결과가 0이 아니거나 시간이 지나도 숫자가 줄어들지 않으면, 이 섹션의 나머지 단계를 따르세요. 

# Linux 패키지 설치의 경우:
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'

# 소스에서 직접 컴파일한 경우:
cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'

특히 런타임 메모리를 초과할 가능성이 높은 1000개 이상의 보류 중인 작업이 있는 경우, 다음 명령을 다시 실행해도 무방합니다.

Linux 패키지 (Omnibus)
# Rails 콘솔 시작
sudo gitlab-rails c

# Rails 콘솔에서 다음을 실행
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "백그라운드마이그레이션워커" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }
소스에서 직접 컴파일한 경우
# Rails 콘솔 시작
sudo -u git -H bundle exec rails RAILS_ENV=production

# Rails 콘솔에서 다음을 실행
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "백그라운드마이그레이션워커" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }

‘대기 중’ 상태에 있는 백그라운드 마이그레이션

caution
다음 작업은 GitLab 성능에 영향을 줄 수 있습니다. 다양한 데이터베이스 또는 파일 업데이트를 수행하는 여러 Sidekiq 작업을 실행합니다.
  • GitLab 14.2에서 ‘대기 중’ 상태로 영구적으로 남아 있는 BackfillDraftStatusOnMergeRequests 백그라운드 마이그레이션 문제가 발생할 수 있습니다. 이러한 남은 마이그레이션을 정리하려면, 14.2.0 버전별 지침을 참조하세요.
  • GitLab 14.4에서 ‘대기 중’ 상태로 영구적으로 남아 있는 PopulateTopicsTotalProjectsCountCache 백그라운드 마이그레이션 문제가 발생할 수 있습니다. 이러한 남은 마이그레이션을 정리하려면, 14.4.0 버전별 지침을 참조하세요.
  • GitLab 14.5에서 ‘대기 중’ 상태로 영구적으로 남아 있는 UpdateVulnerabilityOccurrencesLocation 백그라운드 마이그레이션 문제가 발생할 수 있습니다. 이러한 남은 마이그레이션을 정리하려면, 14.5.0 버전별 지침을 참조하세요.
  • GitLab 14.8에서 ‘대기 중’ 상태로 영구적으로 남아 있는 PopulateTopicsNonPrivateProjectsCount 백그라운드 마이그레이션 문제가 발생할 수 있습니다. 이러한 남은 마이그레이션을 정리하려면, 14.8.0 버전별 지침을 참조하세요.
  • GitLab 14.9에서 ‘대기 중’ 상태로 영구적으로 남아 있는 ResetDuplicateCiRunnersTokenValuesOnProjects 백그라운드 마이그레이션 문제가 발생할 수 있습니다. 이러한 남은 마이그레이션을 정리하려면, 14.9.0 버전별 지침을 참조하세요.

기타 대기 중인 백그라운드 마이그레이션이 있을 경우, 다음 검사를 실행하세요. 결과가 0이 아니거나 시간이 지나도 숫자가 줄어들지 않으면, 이 섹션의 나머지 단계를 따르세요. 

# Linux 패키지 설치의 경우:
sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending.count'

# 소스에서 직접 컴파일한 경우:
cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending.count'

대기 중인 상태를 클리어하기 위해 다음 마이그레이션을 다시 시도해도 무방합니다:

Linux 패키지 (Omnibus)
# Rails 콘솔 시작
sudo gitlab-rails c

# Rails 콘솔에서 다음을 실행
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "보류 중인 작업 '#{job.class_name}'를 인수 '#{job.arguments}'로 실행 중"
  result = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "결과: #{result}"
end
소스에서 직접 컴파일한 경우
# Rails 콘솔 시작
sudo -u git -H bundle exec rails RAILS_ENV=production

# Rails 콘솔에서 다음을 실행
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "보류 중인 작업 '#{job.class_name}'를 인수 '#{job.arguments}'로 실행 중"
  result = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "결과: #{result}"
end