• 중지가 필요한 일반적인 시나리오
  • 실행 중인 마이그레이션 최종화
  • 제대로 최종화되지 않은 백그라운드 마이그레이션
  • 마이그레이션 제거
  • 마이그레이션 타임스탬프가 매우 오래됨
  • 마이그레이션 관련 도구의 버그
• 필수 중지점이 릴리스되기 전에
• 필수 중지점 이후 릴리스에서

필수 중지점 추가

필수 중지점은 고객들에게 혼란을 주기 때문에 절대적으로 필요할 때에만 추가해야 합니다. 필수 중지점을 추가하기 전에 다른 대안이 있는지 고려해보세요. 때로는 필수 중지점을 피할 수 없을 때가 있습니다. 그런 경우에는 아래 지침에 따르세요.

중지가 필요한 일반적인 시나리오

실행 중인 마이그레이션 최종화

만약 마이그레이션이 오랜 시간이 걸린다면 많은 고객이 업그레이드 중에 타임아웃을 경험할 수 있습니다. 증가된 지원 볼륨은 필수 중지점을 도입할 수 있습니다. 어떤 백그라운드 마이그레이션이 특히 큰 고객에게 이러한 문제를 일으킬 수 있지만, 일반적으로 영향이 넓게 퍼지면 중지를 도입합니다.

• 원인: 업그레이드에 1시간 이상이 걸리면 Omnibus가 시간 초과됨.
• 완화책: 다음 필수 중지점 이후 첫 번째 마이너 버전에 최종화 일정을 예약하세요.

제대로 최종화되지 않은 백그라운드 마이그레이션

백그라운드 마이그레이션이 최종화되지 않으면 필수 중지점을 위해 중단할 필요가 있을 수 있습니다. 이 때는 다음과 같을 때입니다:

• 백그라운드 마이그레이션이 최종화되지 않았고,

• 그 백그라운드 마이그레이션에 의존하는 마이그레이션이 작성되었을 때.

• 원인: 의존하는 마이그레이션이 백그라운드 마이그레이션 미완료 시 실패할 수 있음.
• 완화책: 모든 백그라운드 마이그레이션이 최종화되어 있는지 확인한 후 의존하는 마이그레이션을 작성하세요.

마이그레이션 제거

마이그레이션이 제거되면 필요한 변경사항을 놓치지 않도록 필수 중지점을 도입해야 할 수 있습니다.

• 원인: 의존하는 마이그레이션은 실패할 수 있으며, 필수 마이그레이션이 제거되었기 때문에 애플리케이션이 제대로 기능하지 않을 수 있음.
• 완화책: 마이그레이션은 계획된 필수 중지점에 포함된 후에만 제거되도록 보장하세요.

마이그레이션 타임스탬프가 매우 오래됨

마이그레이션 타임스탬프가 매우 오래될 경우(> 3주, 또는 마지막 중지점 이후), 다음과 같은 시나리오가 문제를 일으킬 수 있습니다:

• 만약 마이그레이션이 이전 릴리스에서 필수 중지점 이후에 소개된 더 새로운 타임스탬프를 가진 다른 마이그레이션에 의존한다면 새 마이그레이션이 선행 마이그레이션보다 더 빨리 순차적으로 실행되어 실패할 수 있음.

• 마이그레이션 타임스탬프 ID가 마지막 타임스탬프보다 이전이라면, 팀이 다른 마이그레이션을 필수 중지점에서 묶을 때 그것이 우연히 묶일 수 있음.

• 원인: 다른 버전에서 소개된 이후에 필수 중지점에서 소개된 마이그레이션에 의존하는 경우 마이그레이션이 실패할 수 있음. 또는 필수 중지점 이후에 마이그레이션이 우연히 묶일 수 있음.
• 완화책: 마이그레이션 타임스탬프가 릴리스 날짜 내에 속하도록 하고, 마지막 필수 중지점 이전에 날짜가 되어 있는지 확인하세요.

마이그레이션 관련 도구의 버그

마이그레이션 관련 도구에서 버그가 발생한 경우 몇 가지 상황에서 우리는 중지점을 도입할 필요가 있었습니다. 우리는 테스트에서 이를 방지하려고 노력하지만 때로는 발생할 수 있습니다.

• 원인: 우리는 이러한 문제들을 뒤늦게까지 인식한 경우가 있었습니다.
• 완화책: 보통은 마이그레이션에 대한 수정을 백포트하려고 노력하지만 어떤 경우에는 이것이 불가능할 수 있습니다.

필수 중지점이 릴리스되기 전에

알려진 필수 중지점을 릴리스하기 전에 다음 단계를 완료하세요. 필수 중지점이 릴리스 후에 식별되면 아래 단계를 반드시 완료해야 합니다:

1. 업그레이드 경로를 업데이트하여 새로운 필수 중지점을 포함시킵니다.
2. 고객 지원 및 릴리스 관리 팀과 변경 사항을 의사소통합니다.

3. 데이터베이스 그룹에 이슈를 등록하여 다음 릴리스에서 해당 버전까지의 마이그레이션을 묶도록 합니다. 이 템플릿을 사용하세요:

   제목: `<필수 중지점 버전>에 대한 마이그레이션 묶기`
   <필수 중지점 버전>을 위해 추가된 필수 중지점으로 인해 마이그레이션을 해당 버전까지 묶고, 최소 스키마 버전을 업데이트해야 합니다.
   
   결과물:
   - [ ] <필수 중지점 버전>까지 마이그레이션이 묶였음
   - [ ] `Gitlab::Database::MIN_SCHEMA_VERSION`이 init schema 버전과 일치함
   
   /label ~"group::database" ~"section::enablement" ~"devops::data_stores" ~"Category:Database" ~"type::maintenance"
   /cc @gitlab-org/database-team/triage
   

필수 중지점 이후 릴리스에서

1. lib/gitlab/database.rb의 Gitlab::Database::MIN_SCHEMA_GITLAB_VERSION을 새 필수 중지점 버전으로 업데이트하세요. Gitlab::Database::MIN_SCHEMA_VERSION은 변경하지 마세요.
2. charts 프로젝트에서 업그레이드 체크 후크를 필수 중지점 버전으로 업데이트하세요.
3. omnibus-gitlab 프로젝트에서 프리-설치 버전 체크를 필수 중지점 버전으로 업데이트하세요.