배경 마이그레이션과 업그레이드
- GitLab 13.11에서 도입된 배치 배경 마이그레이션은 기본적으로
execute_batched_migrations_on_schedule
라는 플래그를 사용하여 사용자 지정 배경 마이그레이션 프로세스가 가능합니다. 기본적으로 비활성화됩니다.- GitLab 13.12에서는
execute_batched_migrations_on_schedule
기능 플래그가 기본적으로 활성화되었습니다.- GitLab 자체 관리 인스턴스의 경우, GitLab 관리자는 비활성화할 수 있습니다.
특정 릴리스는 새 버전으로 업데이트하기 전에 다양한 마이그레이션을 완료해야 할 수 있습니다. 두 가지 종류의 마이그레이션이 존재하며 GitLab을 업그레이드하기 전에 두 가지가 모두 완료되었는지 확인해야 합니다.
- 주로 GitLab 14.0 이후에 사용되는 배치 배경 마이그레이션.
- 배치 처리되지 않는 배경 마이그레이션은 주로 GitLab 13.11 이전에 사용됩니다.
이러한 마이그레이션을 완료하는 데 필요한 시간을 줄이기 위해 background_migration
대기열에서 작업을 처리할 수 있는 Sidekiq workers의 수를 늘릴 수 있습니다.
배치 배경 마이그레이션
데이터베이스 테이블을 일괄로 업데이트하려면 GitLab이 배치 배경 마이그레이션을 사용할 수 있습니다. 이러한 마이그레이션은 GitLab 개발자에 의해 생성되며 업그레이드시 자동으로 실행됩니다. 그러나 이러한 마이그레이션은 특정 테이블의 integer
데이터베이스 열을 bigint
로 마이그레이션하는 데 도움을 주기 위해 범위가 제한됩니다. 이는 일부 테이블의 정수 오버플로우를 방지하기 위해 필요합니다.
일부 설치에서는 그 업그레이드에 의한 데이터베이스 변경을 완료하기 위해 GitLab 14.0을 하루 이상 실행해야 할 수 있습니다.
배치 배경 마이그레이션은 Sidekiq에서 처리되며 격리되어 실행되므로 마이그레이션이 진행되는 동안 해당 인스턴스는 운영 상태로 남아 있을 수 있습니다. 그러나 배치 배경 마이그레이션이 실행되는 동안 활발하게 사용되는 큰 인스턴스에서는 성능이 저하될 수 있습니다. 모든 마이그레이션이 완료될 때까지 Sidekiq 상태를 적극적으로 모니터링해야 합니다.
배치 배경 마이그레이션의 상태 확인
GitLab UI에서 배치 배경 마이그레이션의 상태를 확인할 수 있으며, 데이터베이스를 질의하여 확인할 수도 있습니다. GitLab을 업그레이드하기 전에 모든 마이그레이션이 Finished
상태여야 합니다.
만약 마이그레션이 완료되지 않은 상태에서 GitLab을 업그레이드하려고 하면 다음과 같은 오류가 발생할 수 있습니다:
주어진 구성에 대한 배치 배경 마이그레이션을 '완료됨'으로 표시했지만 '활성' 상태입니다:
만약 이 오류가 발생하면, GitLab 업그레이드에 필요한 배치 배경 마이그레이션을 완료하는 방법에 대한 옵션을 검토하십시오.
GitLab UI에서
전제 조건:
- 인스턴스에 대한 관리자 액세스해야 합니다.
배치 배경 마이그레이션의 상태를 확인하려면:
- 왼쪽 사이드바에서 가장 아래에 있는 관리 영역(Admin Area) 을 선택합니다.
- 모니터링(Monitoring) > 배경 마이그레이션(Background Migrations)을 선택합니다.
- 미완료된 마이그레이션을 보려면 대기 중(Queued) 또는 완료 중(Finalizing)을 선택하고, 실패한 마이그레이션을 보려면 실패(Failed)을 선택합니다.
데이터베이스에서
전제 조건:
- 인스턴스에 대한 관리자 액세스해야 합니다.
배치 배경 마이그레이션의 상태를 직접 데이터베이스에서 질의하려면:
- 해당 인스턴스의 설치 방법에 따라
psql
프롬프트에 로그인합니다. 예를 들어, 리눅스 패키지 설치의 경우sudo gitlab-psql
을 사용합니다. -
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에서 배치 배경 마이그레이션 일시 중지
경고: 릴리스된 기능을 비활성화하는 경우 위험이 있을 수 있습니다. 자세한 내용은 각 기능의 이력을 확인하십시오.
진행 중인 배치 배경 마이그레이션을 일시 중지하려면, 배치 배경 마이그레이션 기능 비활성화하기를 참조하십시오. 해당 기능을 비활성화하면 현재 배치 마이그레이션을 완료한 후 해당 기능이 다시 활성화될 때까지 다음 배치가 시작되지 않습니다.
전제 조건:
- 인스턴스에 대한 관리자 액세스해야 합니다.
현재 진행 중인 배치 배경 마이그레이션 상태를 확인하는 데 필요한 데이터베이스 쿼리:
-
실행 중인 마이그레이션의 ID를 가져옵니다:
SELECT id, job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status <> 3;
-
이전 단계에서 얻은 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;
-
수 분 내에 여러 번 쿼리를 실행하여 새로운 행이 추가되지 않았는지 확인합니다. 새로운 행이 추가되지 않았다면 마이그레이션이 일시 중지된 것입니다.
-
마이그레이션이 일시 중지되었는지 확인한 후에 (이전 명령과 함께) 해당 배치가 준비되면 마이그레이션을 재시작해야 합니다. 큰 인스턴스에서는 배경 마이그레이션은 각 배치마다 최대 48시간이 소요될 수 있습니다.
자동 일괄 크기 최적화
경고: 릴리스된 기능을 비활성화하는 경우에는 위험이 있습니다. 자세한 내용은 이 기능의 이력을 참조하십시오.
플래그: 자체 관리형 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 상태로 표시될 수 있습니다:
일괄 배경 마이그레이션이 실패한 이유를 확인하려면 실패한 오류 로그를 보거나 UI에서 오류 정보를 확인하십시오.
전제 조건:
- 인스턴스에 대한 관리자 액세스해야 합니다.
- 왼쪽 사이드바에서 아래쪽에서 관리 영역을 선택합니다.
- 감시 > 배경 마이그레이션을 선택합니다.
- 실패 탭을 선택합니다. 이렇게 하면 실패한 일괄 배경 마이그레이션의 목록이 표시됩니다.
- 실패한 마이그레이션을 선택하여 마이그레이션 매개 변수와 실패한 작업을 볼 수 있습니다.
- 실패한 작업에서 각 ID를 선택하여 작업이 실패한 이유를 확인합니다.
GitLab 고객이라면 지원 요청을 열어 일괄 배경 마이그레이션이 실패한 원인을 디버깅하는 것을 고려하십시오.
문제를 해결하려면 실패한 마이그레이션을 다시 시도할 수 있습니다.
전제 조건:
- 인스턴스에 대한 관리자 액세스해야 합니다.
- 왼쪽 사이드바에서 아래쪽에서 관리 영역을 선택합니다.
- 감시 > 배경 마이그레이션을 선택합니다.
- 실패 탭을 선택합니다. 이렇게 하면 실패한 일괄 배경 마이그레이션의 목록이 표시됩니다.
- 재시도 버튼을 클릭하여 다시 시도할 실패한 일괄 배경 마이그레이션을 선택합니다.
재시도된 일괄 배경 마이그레이션을 모니터링하려면 정기적으로 일괄 배경 마이그레이션의 상태를 확인할 수 있습니다.
수동으로 실패한 마이그레이션 완료
- GitLab 14.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"]] }
-
다음 명령을 실행하고 꺽쇠 괄호 내의 올바른 인수로 값을 대체하십시오:
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"]]']
- 일괄 배경 마이그레이션의 상태를 확인하십시오.
-
결과를 사용하여 올바른 인수로 값을 대체하여 마이그레이션 명령을 작성하십시오.
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 이상에서는 이 유형의 마이그레이션이 일괄 처리 백그라운드 마이그레이션으로 대체되었습니다.
보류 중인 백그라운드 마이그레이션 확인
일괄 처리되지 않은 백그라운드 마이그레이션을 확인하려면:
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'
실패한 백그라운드 마이그레이션 확인
백그라운드 마이그레이션에서 실패한 작업을 확인하려면:
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'