clickhouse:migrate:multi-version-upgrade job
GitLab v19.6요약
이 job은 실제 GitLab 업그레이드가 마이그레이션을 실행하는 방식 그대로 ClickHouse 마이그레이션을 실행하여, 데이터가 들어 있는 테이블에서 마이그레이션이 동작하는지 검증합니다. 기존 clickhouse:check-schema job은 모든 마이그레이션을 빈 데이터베이스에서 처음부터 한 번에 실행합니다.
이 job은 실제 GitLab 업그레이드가 마이그레이션을 실행하는 방식 그대로 ClickHouse 마이그레이션을 실행하여,
데이터가 들어 있는 테이블에서 마이그레이션이 동작하는지 검증합니다. PostgreSQL용
db:migrate:multi-version-upgrade에 대응하는
ClickHouse용 job입니다.
기존 clickhouse:check-schema job은 모든 마이그레이션을 빈 데이터베이스에서 처음부터 한 번에 실행합니다.
이 방식으로는 실제 업그레이드에서 나타나는 다음 세 가지 조건을 재현할 수 없습니다.
- 스키마가 현재 버전이 아니라 이전 필수 업그레이드 중단점에서 시작합니다.
- post-deployment 마이그레이션이 이미 새로운 일반 마이그레이션으로 테이블이 바뀐 뒤에 실행됩니다. Omnibus와 Helm 업그레이드는 이 두 단계로 나누어 마이그레이션을 실행합니다.
- 테이블에 이미 행이 들어 있으므로, 스왑, 프로젝션 재구축, 칼럼 삭제가 다시 써야 하는 파트가 디스크에 존재합니다.
이슈 #593129는 이 세 조건이 모두 필요했고, 이를 다루는 job이 없어서 고객에게까지 영향을 주었습니다.
job이 하는 일#
scripts/click_house/multi_version_upgrade.sh는 다음을 수행합니다.
Gitlab::Utils::UpgradePath로 최신 필수 업그레이드 중단점을 확인한 다음, 해당 릴리스에서 패치 번호가 가장 높은 태그를 선택합니다.- 해당 태그 시점의 ClickHouse 스키마를 불러옵니다.
db/click_house/main.sql과db/click_house/schema_migrations/는 커밋되어 있으므로, 두 경로에 대한git checkout으로 충분하며 데이터베이스 덤프가 필요하지 않습니다. - ClickHouse
generateRandom테이블 함수로AggregatingMergeTree테이블을 제외한 모든 MergeTree 테이블에 행 10개를 채웁니다. 이 함수는 테이블에서 구조를 가져옵니다. 일괄 데이터 마이그레이션은 고정된 단위로 ID 범위를 순회하므로, 정수 칼럼은 실제 ID처럼 작은 값으로 유지합니다.AggregatingMergeTree테이블은 프로덕션과 마찬가지로 구체화된 뷰에서 행을 받습니다. 무작위 원본 행이 뷰의WHERE필터를 통과하지 못하면 집계 테이블은 비어 있게 됩니다. - 일반 마이그레이션을
SKIP_POST_DEPLOYMENT_MIGRATIONS=true로 한 로그 섹션에서 실행한 다음, post-deployment 마이그레이션을 두 번째 로그 섹션에서 실행합니다. clickhouse:check-schema와 같은 검사인scripts/validate_clickhouse_schema.rb를 실행하여, 덤프된 스키마, 스키마 캐시, 마이그레이션 마커 파일이 모두 커밋된 내용과 일치하는지 확인합니다.
시드 데이터는 직접 작성한 픽스처가 아니라 스키마에서 만들어 냅니다. 검증 대상 구간의 마이그레이션이 릴리스마다 바뀌므로, 고정된 픽스처 집합은 실제로 마이그레이션되는 테이블과 점점 어긋나기 때문입니다.
실행 시점#
config/upgrade_path.yml, VERSION, db/click_house/**, db/siphon/**, lib/click_house/**,
lib/tasks/gitlab/click_house/**, scripts/click_house/** 또는 job 정의 자체를 변경하는
머지 리퀘스트 파이프라인에서 실행됩니다. 포크, 안정 브랜치를 대상으로 하는 머지 리퀘스트,
긴급(expedited) 파이프라인에서는 건너뜁니다.
이 job은 안정성이 입증될 때까지 실패해도 되도록 허용되어 있으므로, 실패해도 머지가 차단되지 않습니다. 이슈 635169에서 이 job을 필수로 만드는 작업을 추적합니다.
실행을 강제하려면 ~"pipeline:run-all-rspec"를 적용합니다.
문제 해결#
관련 없는 머지 리퀘스트에서 job이 실패하는 경우#
어느 단계가 실패했는지 확인합니다.
- 업그레이드 중단점 확인:
git ls-remote또는git fetch실패는 대개 일시적입니다. 오류에는 Git의 출력이 포함됩니다. job을 다시 실행합니다. - 시드:
WARNING: could not seed <table>줄에 ClickHouse 오류가 포함됩니다. job은 해당 테이블을 건너뛰고 계속 진행하며, 행이 하나도 채워지지 않은 경우에만 실패합니다. 해당 테이블에서 데이터를 받는 구체화된 뷰의 경고는 예상된 동작입니다. 뷰가 무작위 값을 거부할 수 있기 때문입니다. - 마이그레이션: 데이터가 들어 있는 테이블에서 발생한 실제 마이그레이션 실패이며, 이 job이 잡아내려는 대상입니다. 두 로그 섹션을 보면 일반 단계와 post-deployment 단계 중 어느 쪽에서 실패했는지 알 수 있습니다. 아래 단계로 로컬에서 재현합니다.
- 검증: 스키마가
db/click_house/main.sql에서 벗어났습니다. 거짓 양성으로 확인된 경우clickhouse:check-schema와 마찬가지로~"pipeline:skip-check-clickhouse-schema"레이블을 여기에도 적용할 수 있습니다.
수정을 준비하는 동안 job을 끄려면 프로젝트 CI/CD 설정에서
DISABLE_CLICKHOUSE_MULTI_VERSION_UPGRADE를 true로 설정하고, #master-broken에 공지합니다.
로컬에서 실행#
test ClickHouse 구성이 임시 데이터베이스를 가리키도록 한 다음 실행합니다.
CLICKHOUSE_URL=http://localhost:8123 \
CLICKHOUSE_DATABASE=gitlab_clickhouse_upgrade_test \
RAILS_ENV=test DISABLE_WEBMOCK=true ENABLE_CLICKHOUSE_DB_DUMP=true \
bash scripts/click_house/multi_version_upgrade.sh
스크립트는 종료할 때 브랜치의 main.sql과 마커 파일을 복원하므로, 중단된 실행이
작업 트리를 업그레이드 중단점의 스키마 상태로 남겨 두지 않습니다.
CI에서만 --depth 1로 중단점 태그를 가져옵니다. 전체 로컬 clone에 얕은 fetch를 하면
해당 clone이 얕은 clone으로 표시되기 때문입니다.