문제 해결

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 대기열에 남아 있는 경우

경고: 다음 작업은 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)
# 레일스 콘솔 시작
sudo gitlab-rails c

# 레일스 콘솔에서 다음을 실행
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }
직접 컴파일 (원본)
# 레일스 콘솔 시작
sudo -u git -H bundle exec rails RAILS_ENV=production

# 레일스 콘솔에서 다음을 실행
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }

백그라운드 마이그레이션을 “대기 중” 상태로 만듦

경고: 다음 작업들은 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이 아닌 값을 반환하고 시간이 지나도 감소하지 않는 경우, 이 섹션의 나머지 단계를 따르십시오. 

# 리눅스 패키지 설치의 경우:
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'

대기 중인 상태에서 이러한 마이그레이션을 다시 시도해도 안전합니다:

리눅스 패키지 (Omnibus)
# 레일즈 콘솔을 시작합니다
sudo gitlab-rails c

# 다음을 레일즈 콘솔에서 실행합니다
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "대기 중인 '#{job.class_name}' 작업을 인수와 함께 실행 중: #{job.arguments}"
  결과 = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "결과: #{result}"
end
직접 컴파일 (소스)
# 레일즈 콘솔을 시작합니다
sudo -u git -H bundle exec rails RAILS_ENV=production

# 다음을 레일즈 콘솔에서 실행합니다
Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
  puts "대기 중인 '#{job.class_name}' 작업을 인수와 함께 실행 중: #{job.arguments}"
  결과 = Gitlab::BackgroundMigration.perform(job.class_name, job.arguments)
  puts "결과: #{result}"
end