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

Tier: Free, Premium, Ultimate Offering: Self-Managed
  • GitLab 13.11에서 도입된 배치 배경 마이그레이션은 기본적으로 execute_batched_migrations_on_schedule라는 플래그를 사용하여 사용자 지정 배경 마이그레이션 프로세스가 가능합니다. 기본적으로 비활성화됩니다.
  • GitLab 13.12에서는 execute_batched_migrations_on_schedule 기능 플래그가 기본적으로 활성화되었습니다.
  • GitLab 자체 관리 인스턴스의 경우, GitLab 관리자는 비활성화할 수 있습니다.

특정 릴리스는 새 버전으로 업데이트하기 전에 다양한 마이그레이션을 완료해야 할 수 있습니다. 두 가지 종류의 마이그레이션이 존재하며 GitLab을 업그레이드하기 전에 두 가지가 모두 완료되었는지 확인해야 합니다.

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

배치 배경 마이그레이션

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

일부 설치에서는 그 업그레이드에 의한 데이터베이스 변경을 완료하기 위해 GitLab 14.0을 하루 이상 실행해야 할 수 있습니다.

배치 배경 마이그레이션은 Sidekiq에서 처리되며 격리되어 실행되므로 마이그레이션이 진행되는 동안 해당 인스턴스는 운영 상태로 남아 있을 수 있습니다. 그러나 배치 배경 마이그레이션이 실행되는 동안 활발하게 사용되는 큰 인스턴스에서는 성능이 저하될 수 있습니다. 모든 마이그레이션이 완료될 때까지 Sidekiq 상태를 적극적으로 모니터링해야 합니다.

배치 배경 마이그레이션의 상태 확인

GitLab UI에서 배치 배경 마이그레이션의 상태를 확인할 수 있으며, 데이터베이스를 질의하여 확인할 수도 있습니다. GitLab을 업그레이드하기 전에 모든 마이그레이션이 Finished 상태여야 합니다.

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

주어진 구성에 대한 배치 배경 마이그레이션을 '완료됨'으로 표시했지만 '활성' 상태입니다:

만약 이 오류가 발생하면, GitLab 업그레이드에 필요한 배치 배경 마이그레이션을 완료하는 방법에 대한 옵션을 검토하십시오.

GitLab UI에서

전제 조건:

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

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

  1. 왼쪽 사이드바에서 가장 아래에 있는 관리 영역(Admin Area) 을 선택합니다.
  2. 모니터링(Monitoring) > 배경 마이그레이션(Background Migrations)을 선택합니다.
  3. 미완료된 마이그레이션을 보려면 대기 중(Queued) 또는 완료 중(Finalizing)을 선택하고, 실패한 마이그레이션을 보려면 실패(Failed)을 선택합니다.

데이터베이스에서

전제 조건:

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

배치 배경 마이그레이션의 상태를 직접 데이터베이스에서 질의하려면:

  1. 해당 인스턴스의 설치 방법에 따라 psql 프롬프트에 로그인합니다. 예를 들어, 리눅스 패키지 설치의 경우 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에서 배치 배경 마이그레이션 일시 중지

경고: 릴리스된 기능을 비활성화하는 경우 위험이 있을 수 있습니다. 자세한 내용은 각 기능의 이력을 확인하십시오.

진행 중인 배치 배경 마이그레이션을 일시 중지하려면, 배치 배경 마이그레이션 기능 비활성화하기를 참조하십시오. 해당 기능을 비활성화하면 현재 배치 마이그레이션을 완료한 후 해당 기능이 다시 활성화될 때까지 다음 배치가 시작되지 않습니다.

전제 조건:

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

현재 진행 중인 배치 배경 마이그레이션 상태를 확인하는 데 필요한 데이터베이스 쿼리:

  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. 마이그레이션이 일시 중지되었는지 확인한 후에 (이전 명령과 함께) 해당 배치가 준비되면 마이그레이션을 재시작해야 합니다. 큰 인스턴스에서는 배경 마이그레이션은 각 배치마다 최대 48시간이 소요될 수 있습니다.

자동 일괄 크기 최적화

  • GitLab 13.2에 도입되었으며 ‘optimize_batched_migrations’이라는 플래그로 기능 플래그가 있습니다. 기본적으로 활성화됩니다.

경고: 릴리스된 기능을 비활성화하는 경우에는 위험이 있습니다. 자세한 내용은 이 기능의 이력을 참조하십시오.

플래그: 자체 관리형 GitLab에서는 기본적으로이 기능을 사용할 수 있습니다. 기능을 숨기려면 관리자에게 ‘optimize_batched_migrations’이라는 기능 플래그를 비활성화하도록 요청하십시오. GitLab.com에서는이 기능을 사용할 수 있습니다. GitLab Dedicated에서는이 기능을 사용할 수 없습니다.

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

병렬 실행

  • GitLab 15.7에 도입되었으며 ‘batched_migrations_parallel_execution’이라는 플래그로 기능 플래그가 있습니다. 기본적으로 비활성화됩니다.
  • GitLab.com에서 GitLab 15.11에서 활성화되었습니다.
  • GitLab 16.1에서 일반적으로 사용 가능합니다. 기능 플래그 ‘batched_migrations_parallel_execution’이 제거되었습니다.

경고: 릴리스된 기능을 비활성화하는 경우에는 위험이 있습니다. 자세한 내용은 이 기능의 이력을 참조하십시오.

일괄 배경 마이그레이션의 실행을 가속화하려면 두 개의 마이그레이션이 동시에 실행됩니다.

GitLab 관리자가 GitLab Rails 콘솔에 액세스할 수 있으며 병렬로 실행되는 일괄 배경 마이그레이션의 수를 변경할 수 있습니다: 

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

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

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

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

  • GitLab 14.3에 도입되었습니다.

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

failed batched background migrations table

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

전제 조건:

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

GitLab 고객이라면 지원 요청을 열어 일괄 배경 마이그레이션이 실패한 원인을 디버깅하는 것을 고려하십시오.

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

전제 조건:

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

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

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

  • GitLab 14.1에 도입되었습니다.

오류로 실패한 일괄 배경 마이그레이션을 수동으로 완료하려면 실패한 오류 로그 또는 데이터베이스의 정보를 사용하십시오:

실패한 오류 로그에서

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

[["id"],["id_convert_to_bigint"]]와 같이 여러 인수를 다룰 때는 각 인수 사이의 쉼표를 역슬래시 \로 이스케이핑하여 잘못된 문자 오류를 방지하십시오. 명령은 다음과 같아아합니다: 

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

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

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

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

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

경고: 진행하기 전에 반드시 백업을 만드십시오. 

# 레일즈 콘솔 시작

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'