업그레이드를 위한 데이터 이전

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

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

  • 데이터베이스 이전.
  • 고급 검색 이전.

두 가지 유형의 마이그레이션에 대한 자세한 정보는 아래를 참조하세요.

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

  • GitLab 13.12에서 기능 flag execute_batched_migrations_on_schedule가 기본으로 활성화되었습니다.
  • GitLab의 Self-managed 인스턴스의 경우, 관리자는 비활성화할 수 있습니다.

특정 릴리스는 새로운 버전으로 업그레이드하기 전에 마무리해야 할 다양한 마이그레이션을 필요로 합니다. 두 가지 종류의 마이그레이션이 존재하는데, 두 마이그레이션이 모두 완료된 것을 확인하고 GitLab을 업그레이드하기 전에 확인해야 합니다:

이러한 마이그레이션을 완료하는 데 필요한 시간을 줄이기 위해 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. Monitoring > Background migrations을 선택합니다.
  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 NOT IN(3, 6);

또는 다음과 같이 쿼리를 묶어서 실행하여 일괄 백그라운드 마이그레이션의 상태를 확인할 수도 있습니다: 

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로 다음 쿼리를 실행하여 마이그레이션 상태를 확인하세요: 

    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의 경우, 기본적으로 이 기능을 사용할 수 있습니다. 기능을 숨기려면 운영자에게 optimize_batched_migrations이라는 기능 플래그를 비활성화하도록 요청하십시오. GitLab.com의 경우, 이 기능을 사용할 수 있습니다. GitLab Dedicated의 경우, 이 기능을 사용할 수 없습니다.

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

병렬 실행

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

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

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

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

실패한 일괄 백그라운드 마이그레이션 해결

일괄 백그라운드 마이그레이션이 실패한 경우 수정하고 다시 시도하십시오. 마이그레이션이 오류와 함께 계속 실패하는 경우 다음 중 하나 실행할 수 있습니다:

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

모든 실패한 일괄 백그라운드 마이그레이션을 해결해야 GitLab의 새 버전으로 업그레이드할 수 있습니다. 일괄 백그라운드 마이그레이션 상태를 확인하면 일부 마이그레이션이 실패 탭에 표시될 수 있습니다. 마이그레이션이 실패한 이유를 확인하려면 실패 오류 로그를 또는 UI에서 오류 정보를 확인하십시오.

필수 조건:

  • 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
  1. 왼쪽 사이드바에서 아래쪽으로 이동하여 관리를 선택합니다.
  2. 모니터링 > 백그라운드 마이그레이션을 선택합니다.
  3. 실패 탭을 선택합니다. 이렇게 하면 실패한 일괄 백그라운드 마이그레이션 목록이 표시됩니다.
  4. 실패한 마이그레이션을 선택하여 마이그레이션 매개변수와 실패한 작업을 볼 수 있습니다.
  5. 실패한 작업에서 각 ID를 선택하여 작업이 실패한 이유를 볼 수 있습니다.

GitLab 고객인 경우, 일괄 백그라운드 마이그레이션이 실패한 이유를 디버깅하기 위해 지원 요청을 열어보는 것을 고려하십시오.

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

필수 조건:

  • 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
  1. 왼쪽 사이드바에서 아래쪽으로 이동하여 관리를 선택합니다.
  2. 모니터링 > 백그라운드 마이그레이션을 선택합니다.
  3. 실패 탭을 선택합니다. 이렇게 하면 실패한 일괄 백그라운드 마이그레이션 목록이 표시됩니다.
  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"]]와 같은 여러 인수를 처리할 때는, 쉼표를 [backslash]로 이스케이핑하여 각 인수 사이에 유효하지 않은 문자 오류를 방지하십시오. 예를 들어, 이전 단계에서 마이그레이션을 완료하려면 다음과 같은 방법으로 실행하십시오: 

    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"]]와 같은 여러 인수를 처리할 때는, 쉼표를 [backslash]로 이스케이핑하여 각 인수 사이에 유효하지 않은 문자 오류를 방지하십시오. 명령은 이렇게 될 것입니다: 

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

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

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

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'
self-compiled (소스)
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'
self-compiled (소스)

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: 프리미엄, 얼티밋 Offering: Self-managed

이 섹션은 Elasticsearch 통합을 활성화한 경우에만 해당합니다. 주요 릴리스에서는 현재 버전에서 가장 최근의 마이너 릴리스에 대해 모든 고급 검색 마이그레이션 이 완료되어야 하며, 주요 버전 업그레이드 전에 확인해야 합니다. 다음 명령을 실행하여 대기 중인 마이그레이션을 찾을 수 있습니다.

Linux 패키지 (Omnibus)
sudo gitlab-rake gitlab:elastic:list_pending_migrations
self-compiled (소스)
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations