Source URL: https://docs.bullmq.io/guide/migration-to-newer-versions

마이그레이션

BullMQ 팀은 버그 수정, 새로운 기능, 또는 때때로 호환성이 깨지는 변경 사항이 포함된 새 버전을 정기적으로 릴리스합니다. 프로덕션 환경에서 운영하는 사용자라면 서비스 연속성을 유지하면서 이러한 새 버전으로 업그레이드하는 일이 어렵게 느껴질 수 있습니다. 이 가이드는 전환을 더 수월하게 만드는 팁과 권장 사항을 제공합니다.

필요한 전략은 업그레이드의 성격에 따라 달라집니다. 그럼에도 어떤 업그레이드를 진행하든 이 가이드를 끝까지 읽을 것을 권장합니다.

일반 조언

BullMQ를 업그레이드할 때는 항상 Changelog를 확인하세요. 변경 범위를 파악하고 업그레이드 전에 중요한 고려 사항을 식별하는 데 도움이 됩니다.

버전 간 큰 폭의 점프는 피하세요. 예를 들어 현재 버전이 1.3.7이라면 4.2.6으로 한 번에 올리는 것은 바람직하지 않을 수 있습니다. 가능하면 점진적으로 업그레이드하세요. 먼저 가능한 한 많은 버그 수정 릴리스를 적용하고, 그다음 새 기능 릴리스로, 마지막으로 호환성이 깨지는 변경이 포함된 메이저 릴리스로 진행하세요.

버그 수정 업그레이드

버그 수정 릴리스는 SemVer (Semantic Versioning)에 따라 마이크로 버전 번호만 증가합니다(예: 3.14.4에서 3.14.7로 업그레이드). 버그 수정 업그레이드에는 특별한 전략이 필요 없으며, 코드나 배포를 바꾸지 않고 인스턴스를 최신 버전으로 업데이트하면 됩니다. 모든 인스턴스가 동일한 버전을 실행해야 하는 것은 아니지만, 일관성을 위해 동일 버전 사용을 권장합니다.

새 기능 업그레이드

SemVer 사양에 따르면 새 기능이 추가되면 마이너 버전 번호가 증가합니다(예: 3.14.7에서 3.20.5로). 일반적으로 기능 업그레이드는 버그 수정 업그레이드처럼 처리할 수 있으며, 모든 인스턴스를 최신 버전으로 업데이트하면 됩니다.

다만 새 기능을 활용하기 위해 코드도 함께 업그레이드한다면, 이전 BullMQ 버전과 하위 호환되도록 해야 합니다. 그렇지 않으면 새 Queue가 이전 Worker가 이해하지 못하는 기능을 사용하는 작업을 추가할 때, 이전 Worker가 동작을 멈출 수 있습니다.

이 경우의 전략은 먼저 새 기능이 포함된 버전으로 모든 인스턴스를 업그레이드하는 것입니다. 모든 인스턴스가 새 버전을 실행 중임을 확인한 뒤, 해당 새 기능에 의존하는 코드를 배포하세요.

호환성이 깨지는 변경 사항

때때로 이전 버전과 호환되지 않는 불가피한 변경이 발생합니다. 우리는 이를 최소화하려고 하며, 크게 API 호환성 파괴 변경과 데이터 구조 호환성 파괴 변경의 두 가지로 분류합니다.

API 호환성 파괴 변경

API 호환성 파괴 변경에는 메서드 파라미터 변경, 제거, 또는 동작 방식 변경이 포함될 수 있습니다. 이런 변경은 보통 적용이 비교적 간단합니다. BullMQ 의존 유닛 테스트를 실행하고 변경 사항에 따라 문제를 해결하면 됩니다. TypeScript를 사용 중이라면 컴파일 오류가 나타날 가능성이 큽니다. 이러한 변경에 대한 핵심 정보를 위해 항상 changelog를 읽으세요.

데이터 구조 호환성 파괴 변경

큐의 내부 구조를 바꾸는 데이터 구조 변경은 더 까다롭습니다. 이는 다음 두 가지 중 하나일 수 있습니다.

additive(추가형): 이전 BullMQ 버전이 이해하지 못하는 새 데이터 구조를 도입
destructive(파괴형): 기존 데이터 구조를 변경하거나 제거

추가형 변경의 경우, 모든 인스턴스를 새 버전으로 업그레이드하면 변경이 적용된 뒤 문제 없이 계속 동작해야 하며, 새 기능 업그레이드와 유사합니다.

파괴형 변경은 가장 까다롭습니다. 이러한 근본적 변경으로 인해 이전 버전이 동작 불가능해질 수 있어, 업그레이드가 실패했을 때 롤백이 불가능해질 수 있기 때문입니다. 이 유형의 업그레이드를 진행할 때는 changelog가 중요한 안내 정보를 제공합니다.

몇 가지 일반 전략

가장 까다로운 업그레이드에서는 다음 전략이 유용할 수 있습니다.

일시 중지/업그레이드/재개

BullMQ는 전역 일시 중지를 지원하므로, 비즈니스 요구사항에 맞는다면 가능한 전략 중 하나는 큐를 일시 중지하고 현재 큐에 있는 모든 작업이 처리될 때까지 기다린 뒤 업그레이드를 수행하는 것입니다. BullMQ를 실행하는 모든 인스턴스 업그레이드가 완료되면, 일시 중지를 해제하고 새 작업이 새 워커에서 처리되도록 할 수 있습니다. 다만 호환성이 깨지는 변경이 Queue 인스턴스에 영향을 주는 경우에는 이 전략의 효용이 떨어질 수 있습니다. 이 유형의 정보는 항상 changelog를 확인하세요.

새로운 큐를 아예 사용

이 급진적인 방법은 기존 큐 사용을 중단하고 새 큐를 만드는 것입니다. 예를 들어 기존 큐 이름을 변경하거나(예: “myQueueV2”), 새 Redis 호스트를 사용하거나, 서비스 두 버전을 병행 운영할 수 있습니다. 하나는 이전 BullMQ 버전과 기존 큐를 사용하고, 다른 하나는 최신 BullMQ와 별도 큐 세트를 사용합니다. 이전 버전이 더 이상 처리할 작업이 없어지면 종료하고, 업그레이드된 버전만 남기면 됩니다.