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

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

- 배치된 백그라운드 마이그레이션은 GitLab 13.11에서 도입되었으며 execute_batched_migrations_on_schedule이라는 플래그로 동기화되었습니다. 기본적으로 비활성화됩니다. - 피처 플래그 execute_batched_migrations_on_schedule이 GitLab 13.12에서 기본적으로 활성화되었습니다. - GitLab Self-managed 인스턴스의 경우, GitLab 관리자는 이를 비활성화할 수 있습니다.

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

이러한 마이그레이션을 완료하는 데 필요한 시간을 줄이기 위해 Sidekiq 워커의 수를 늘릴 수 있습니다. 이 워커들은 background_migration 큐에서 작업을 처리할 수 있습니다.

배치된 백그라운드 마이그레이션

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

일부 설치에서는 그 업그레이드에 의해 도입된 데이터베이스 변경 사항을 완료하려면 GitLab 14.0을 적어도 하루동안 실행해야 할 수 있습니다.

배치된 백그라운드 마이그레이션은 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에서

사전 요구 사항:

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

배치된 백그라운드 마이그레이션의 상태를 확인하려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 가장 아래쪽으로 이동하여 관리 영역을 선택합니다.
  2. Monitoring > 배경 마이그레이션을 선택합니다.
  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 <> 3;

대신, 배치된 백그라운드 마이그레이션의 상태를 확인하기 위해 gitlab-psql -c "<쿼리>"로 해당 쿼리를 래핑할 수 있습니다. 

gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status <> 3;"

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

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

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

GitLab 14.x에서 배치된 백그라운드 마이그레이션 일시 중지하기

caution
릴리스된 기능을 비활성화할 때 위험 요소가 발생할 수 있습니다. 자세한 내용은 각 기능의 이력을 참조하세요.

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

사전 요구 사항:

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

현재 진행 중인 배치된 백그라운드 마이그레이션의 상태를 확인하기 위해 다음 데이터베이스 쿼리를 사용하세요:

  1. 실행 중인 마이그레이션의 ID를 확인합니다: 

    SELECT
 id,
 job_class_name,
 table_name,
 column_name,
 job_arguments
FROM batched_background_migrations
WHERE status <> 3;

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

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

  4. 마이그레이션이 일시 중지되었다는 것을 확인한 후에 (위의 enable 명령어를 사용하여) 준비가 되면 배치를 계속할 수 있도록 마이그레이션을 다시 시작합니다. 큰 인스턴스의 경우, 백그라운드 마이그레이션은 각 배치마다 최대 48시간이 소요될 수 있습니다.

자동 배치 사이즈 최적화

caution
릴리스된 기능 비활성화 시 리스크가 발생할 수 있습니다. 자세한 내용은 해당 기능의 이력을 참조하십시오.

플래그: Self-managed GitLab의 경우, 기본적으로 이 기능을 사용할 수 있습니다. 기능을 숨기려면 관리자에게 optimize_batched_migrations라는 플래그를 비활성화할 것을 요청하십시오. GitLab.com의 경우 이 기능을 사용할 수 있습니다. GitLab Dedicated의 경우 이 기능을 사용할 수 없습니다.

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

병렬 실행

  • GitLab 15.7에 도입되었습니다. 기본으로 비활성화된 batched_migrations_parallel_execution라는 플래그로 활성화됩니다.
  • GitLab 15.11에 GitLab.com에서 활성화되었습니다.
  • GitLab 16.1에서 일반적으로 사용할 수 있습니다. 피처 플래그 batched_migrations_parallel_execution가 제거되었습니다.
caution
릴리스된 기능 비활성화 시 리스크가 발생할 수 있습니다. 자세한 내용은 해당 기능의 이력을 참조하십시오.

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

GitLab 관리자는 GitLab Rails 콘솔에 액세스할 수 있습니다. 이를 통해 동시에 실행되는 일괄 배경 마이그레이션의 수를 변경할 수 있습니다: 

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

실패한 일괄 배경 마이그레이션 해결

일괄 배경 마이그레이션이 실패하면, 수정하고 다시 시도하십시오. 마이그레이션이 오류로 계속 실패하는 경우:

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

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

failed batched background migrations table

일괄 배경 마이그레이션이 실패한 이유를 확인하려면 실패 오류 로그를 확인하거나 UI에서 오류 정보를 확인하십시오.

전제 조건:

  • 인스턴스에 관리자 액세스해야 합니다.
  1. 왼쪽 사이드바에서 아래쪽에서 관리 영역을 선택합니다.
  2. 모니터링 > 배경 마이그레이션을 선택합니다.
  3. Failed 탭을 선택합니다. 이렇게하면 실패한 일괄 배경 마이그레이션의 디렉터리이 표시됩니다.
  4. 실패한 Migration을 선택하여 마이그레이션 매개변수 및 실패한 작업을 볼 수 있습니다.
  5. Failed jobs에서 각 ID를 선택하여 작업 실패 이유를 확인합니다.

만약 GitLab 고객이라면, 일괄 배경 마이그레이션이 실패한 원인을 찾기 위해 지원 요청을 열어보는 것을 고려하십시오.

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

전제 조건:

  • 인스턴스에 관리자 액세스해야 합니다.
  1. 왼쪽 사이드바에서 아래쪽에서 관리 영역을 선택합니다.
  2. 모니터링 > 배경 마이그레이션을 선택합니다.
  3. Failed 탭을 선택합니다. 이렇게하면 실패한 일괄 배경 마이그레이션의 디렉터리이 표시됩니다.
  4. 재시도할 실패한 일괄 배경 마이그레이션을 선택하여 재시도 버튼을 클릭합니다 ().

재시도한 일괄 배경 마이그레이션을 모니터링하려면, 일정한 간격으로 일괄 배경 마이그레이션의 상태를 확인할 수 있습니다.

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

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

실패 오류 로그에서

  1. 실패 오류 로그를 확인하고 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"]]
  }

  2. 다음 명령을 실행하고 꺽쇠 괄호 안의 값을 올바른 인수로 바꿉니다: 

    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"]]']
데이터베이스에서
  1. 일괄 배경 마이그레이션의 상태를 확인합니다.

  2. 쿼리 결과를 사용하여 올바른 매개변수로 마이그레이션 명령을 작성합니다: 

    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,events,id,'[["id"]\, ["id_convert_to_bigint"]]']

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

caution
이 지침을 사용하기 전에 GitLab 지원팀에 문의하십시오. 이 작업은 데이터 손실을 유발하고 복구하기 어려운 방식으로 인스턴스를 실패하게 할 수 있습니다.

백그라운드 마이그레이션이 실패하는 경우가 있을 수 있습니다: 너무 많은 버전 업그레이드를 건너뛸 때 또는 하위 호환되지 않는 데이터베이스 스키마 변경시. (예: 이슈 393216 참조). 실패한 백그라운드 마이그레이션은 추가적인 응용프로그램 업그레이드를 방해합니다.

백그라운드 마이그레이션이 “건너뛰기”가 안전하다고 판단된 경우, 마이그레이션을 매뉴얼으로 완료로 표시할 수 있습니다:

caution
진행하기 전에 반드시 백업을 만들어 주십시오.
# 레일스 콘솔 시작

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

백그라운드 마이그레이션

GitLab 13에서 백그라운드 마이그레이션이 배치 처리되지 않았습니다. GitLab 14 이상에서는 이 유형의 마이그레이션이 배치 처리된 백그라운드 마이그레이션에 의해 대체되었습니다.

대기 중인 백그라운드 마이그레이션 확인

배치 처리되지 않은 백그라운드 마이그레이션을 확인하려면:

Linux 패키지 (Omnibus)
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'
직접 컴파일 (소스)
cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'

실패한 백그라운드 마이그레이션 확인

배치 처리되지 않은 실패한 백그라운드 마이그레이션을 확인하려면:

Linux 패키지 (Omnibus)

GitLab 버전 14.10 이상인 경우: 

sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.with_status(:failed).count'

GitLab 버전 14.0-14.9인 경우: 

sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count'
직접 컴파일 (소스)

GitLab 버전 14.10 이상인 경우: 

cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.with_status(:failed).count'

GitLab 버전 14.0-14.9인 경우: 

cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count'