업그레이드를 위한 마이그레이션

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

GitLab을 업그레이드할 때 확인해야 할 두 가지 유형의 마이그레이션이 있습니다:

  • 데이터베이스 마이그레이션.
  • 고급 검색 마이그레이션.

아래에서 두 가지 유형의 마이그레이션에 대한 자세한 정보를 읽어보세요.

데이터베이스 백그라운드 마이그레이션

특정 릴리즈는 새로운 버전으로 업데이트하기 전에 완료해야 할 다양한 마이그레이션이 필요할 수 있습니다. 두 가지 종류의 마이그레이션이 있으며, 이들은 다르므로 GitLab을 업그레이드하기 전에 두 가지 모두가 완료되었는지 확인해야 합니다:

  • Batched background migrations는 GitLab 14.0에서 도입되었습니다. GitLab 15.1 이후의 모든 마이그레이션은 이 형식을 독점적으로 사용합니다.
  • Background migrations 중 배치되지 않은 마이그레이션입니다. GitLab 15.0 및 이전 버전에서 사용됩니다.

이 마이그레이션을 완료하는 데 걸리는 시간을 줄이려면 background_migration 큐에서 작업을 처리할 수 있는 Sidekiq 작업자의 수를 늘리세요.

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

데이터베이스 테이블을 배치로 업데이트하기 위해 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에서

전제 조건:

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

배치된 백그라운드 마이그레이션의 상태를 확인하려면:

  1. 왼쪽 사이드바에서 하단의 Admin을 선택합니다.
  2. 모니터링 > 백그라운드 마이그레이션을 선택합니다.
  3. 대기 중 또는 최종화 중을 선택하여 미완료된 마이그레이션을 확인하고, 실패를 선택하여 실패한 마이그레이션을 확인합니다.
데이터베이스에서

전제 조건:

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

배치된 백그라운드 마이그레이션의 상태를 확인하기 위해 데이터베이스를 직접 쿼리하려면:

  1. 인스턴스 설치 방법에 따라 psql 프롬프트에 로그인합니다. 예를 들어, Linux 패키지 설치의 경우 sudo gitlab-psql을 사용합니다.

  2. 미완료된 배치된 백그라운드 마이그레이션의 세부 정보를 보려면 psql 세션에서 다음 쿼리를 실행합니다:

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

또는 쿼리를 gitlab-psql -c "<QUERY>"로 감싸서 배치된 백그라운드 마이그레이션 상태를 확인할 수 있습니다:

gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

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

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

배치된 백그라운드 마이그레이션은 마이그레이션을 사용자화하거나 완전히 일시 중지할 수 있는 기능 플래그를 제공합니다. 이러한 기능 플래그는 이러한 작업의 위험성을 이해하는 고급 사용자에 의해서만 비활성화해야 합니다.

배치된 백그라운드 마이그레이션 일시 중지

경고:
릴리즈된 기능을 비활성화할 때의 위험이 있습니다.
각 기능의 히스토리를 참조하여 자세한 내용을 확인하세요.

진행 중인 배치된 백그라운드 마이그레이션을 일시 중지하려면,
배치된 백그라운드 마이그레이션 기능을 비활성화하세요.
기능을 비활성화하면 현재 배치의 마이그레이션이 완료되고,
기능이 다시 활성화된 이후에 다음 배치를 시작하기 위해 대기합니다.

전제 조건:

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

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

  1. 실행 중인 마이그레이션의 ID를 가져옵니다:

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

  2. 이전 단계에서 얻은 ID로 XX를 바꾸어 이 쿼리를 실행하여
    마이그레이션의 상태를 확인합니다:

    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시간이 걸릴 수 있습니다.

자동 배치 크기 최적화

경고:
릴리즈된 기능을 비활성화할 때의 위험이 있습니다.
이 기능의 히스토리를 참조하여 자세한 내용을 확인하세요.

플래그:
자체 관리 GitLab에서는 기본적으로 이 기능을 사용할 수 있습니다.
기능을 숨기려면 관리자가 기능 플래그를 비활성화 요청하세요.
GitLab.com에서는 이 기능을 사용할 수 있습니다.
GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

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

병렬 실행

경고:
릴리즈된 기능을 비활성화할 때의 위험이 있습니다.
이 기능의 히스토리를 참조하여 자세한 내용을 확인하세요.

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

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

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

실패한 배치 백그라운드 마이그레이션 해결

배치 백그라운드 마이그레이션이 실패한 경우, 수정하고 재시도하세요.

마이그레이션이 오류와 함께 계속 실패하는 경우, 다음 중 하나를 선택하세요:

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

모든 실패한 배치 백그라운드 마이그레이션은 최신 버전의 GitLab로 업그레이드하기 위해 해결되어야 합니다. 배치 백그라운드 마이그레이션의 상태를 확인하면, 일부 마이그레이션이 실패 탭에서 failed 상태로 표시될 수 있습니다:

실패한 배치 백그라운드 마이그레이션 표

배치 백그라운드 마이그레이션이 실패한 이유를 확인하려면, 실패 오류 로그 보기 또는 UI에서 오류 정보를 확인하세요.

사전 조건:

  • 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
  1. 왼쪽 사이드바의 하단에서 Admin을 선택합니다.
  2. 모니터링 > 백그라운드 마이그레이션을 선택합니다.
  3. 실패 탭을 선택합니다. 이 탭은 실패한 배치 백그라운드 마이그레이션 목록을 표시합니다.
  4. 실패한 Migration을 선택하여 마이그레이션 매개변수와 실패한 작업을 확인합니다.
  5. 실패한 작업 아래에서 각 ID를 선택하여 작업이 실패한 이유를 확인합니다.

GitLab 고객인 경우, 배치 백그라운드 마이그레이션이 실패한 이유를 디버깅하기 위해 지원 요청을 여는 것을 고려하세요.

문제를 수정하기 위해 실패한 마이그레이션을 재시도할 수 있습니다.

사전 조건:

  • 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
  1. 왼쪽 사이드바의 하단에서 Admin을 선택합니다.
  2. 모니터링 > 백그라운드 마이그레이션을 선택합니다.
  3. 실패 탭을 선택합니다. 이 탭은 실패한 배치 백그라운드 마이그레이션 목록을 표시합니다.
  4. 재시도 버튼( )를 클릭하여 재시도할 실패한 배치 백그라운드 마이그레이션을 선택합니다.

재시도된 배치 백그라운드 마이그레이션을 모니터링하려면, 정기적으로 배치 백그라운드 마이그레이션의 상태 확인을 할 수 있습니다.

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

오류가 발생하여 실패한 배치 백그라운드 마이그레이션을 수동으로 완료하려면, 실패 오류 로그 또는 데이터베이스의 정보를 사용하세요:

실패 오류 로그에서

  1. 실패 오류 로그 보기 및 오류가 발생했습니다. 모든 이후 마이그레이션이 취소되었습니다라는 오류 메시지를 찾아보세요. 다음과 같이 표시됩니다:

    StandardError: 오류가 발생했습니다. 모든 이후 마이그레이션이 취소되었습니다:

주어진 구성에 대한 배치 백그라운드 마이그레이션이 '완료'로 표시되어야 했으나 '활성'입니다:
  {: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을 참조하세요).

실패한 백그라운드 마이그레이션은 추가 애플리케이션 업그레이드를 방지합니다.

백그라운드 마이그레이션이 스킵하는 것이 “안전하다”고 판단되면, 마이그레이션을 수동으로 완료로 표시할 수 있습니다:

경고:

진행하기 전에 백업을 생성해야 합니다.

# Rails 콘솔 시작

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

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 14 동안 점진적으로 단계적으로 삭제되었으며 마지막으로 GitLab 15.0에서 사용되었습니다.

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

대기 중인 비배치 백그라운드 마이그레이션을 확인하려면:

리눅스 패키지 (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'

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

실패한 비배치 백그라운드 마이그레이션을 확인하려면:

리눅스 패키지 (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'

보류 중인 고급 검색 마이그레이션 확인

Tier: Premium, Ultimate Offering: Self-managed

이 섹션은 Elasticsearch 통합을 활성화한 경우에만 적용됩니다.
주요 릴리즈는 현재 버전의 최신 보조 릴리즈에서 모든 고급 검색 마이그레이션이 완료되어야
주요 버전 업그레이드 전에 가능합니다. 보류 중인 마이그레이션은 다음 명령어를 실행하여 찾을 수 있습니다.

Linux 패키지 (Omnibus)
sudo gitlab-rake gitlab:elastic:list_pending_migrations
자체 컴파일 (소스)
cd /home/git/gitlab  
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations