DB 마이그레이션 실패를 피하는 방법: 젤리핀 리포트 분석

새해 복 많이 받으셨나요. 개발자에게 새해란 그저 커밋 연도가 바뀌는 날일 뿐입니다. 오늘은 오픈소스 미디어 서버 젤리핀(Jellyfin)이 내놓은 'State of the Fin 2026-01-06' 리포트를 뜯어보려 합니다.

단순한 업데이트 공지처럼 보이지만, 행간을 읽어보면 '대규모 레거시 청산 과정에서 발생하는 피 튀기는 사투'가 담겨 있습니다. 특히 백엔드 개발자라면 등골이 서늘해질 포인트가 한두 군데가 아닙니다. 이들이 겪은 시행착오를 타산지석 삼아, 우리의 프로덕션 환경을 지키는 방법을 정리했습니다.

1. 대규모 DB 리팩터링은 '재앙'을 동반한다 (10.11 사태)

젤리핀 7주년 자축보다 눈에 띄는 건 10.11 버전의 후폭풍입니다. 이번 업데이트의 핵심은 EF Core 리팩터링을 통한 데이터베이스 통합이었습니다. 기존 library.db를 단일 jellyfin.db로 합치는 작업이었죠.

개발자 입장에서 이 문장만 봐도 식은땀이 흐릅니다. 수년 묵은 데이터 스키마를 건드리는 건, 돌아가는 엔진의 부품을 주행 중에 교체하는 것과 같습니다.

[문제 상황]

6개월의 개발, 6개월의 RC(Release Candidate) 테스트를 거쳤음에도 불구하고 정식 릴리스 후 문제가 터졌습니다.

마이그레이션 실패: 데이터셋이 방대하거나 꼬여있는 경우 DB 통합 중 오류 발생.
성능 저하: 대용량 데이터 필터링 시 쿼리 성능 이슈.
데이터 정합성 깨짐: 미디어 교체/이름 변경 시 시청 기록 증발.

[생존 포인트]

테스트 기간이 아무리 길어도 '사용자 데이터의 다양성'을 100% 커버할 순 없습니다. 특히 오픈소스는 사용자의 하드웨어와 데이터 상태가 제각각입니다.

교훈: 메이저 DB 스키마 변경이 포함된 업데이트는 절대 'Day 1'에 올리지 마세요. 젤리핀 팀도 이미 4번의 핫픽스(Point Release)를 배포했습니다. 안정화 버전(x.x.4 이상)이 나올 때까지 기다리는 게 리스크 관리의 기본입니다.

2. 버전 넘버링에 속지 마라 (SemVer의 배신)

사용자들은 "마이너 업데이트(10.11)"라고 하니 가벼운 마음으로 업데이트 버튼을 눌렀을 겁니다. 하지만 내부는 완전히 갈아엎어진 상태였죠. 이에 대한 항의가 빗발치자 젤리핀 팀은 버전 체계 변경을 고민하고 있습니다.

"다음 메이저 릴리스에서 10 버전을 아예 건너뛰고 12.0으로 가는 방안도 고려 중입니다."

[현실적 조언]

버전 번호는 개발팀의 '약속'일 뿐, 코드의 '안전성'을 보장하지 않습니다. 특히 10년 차쯤 되면 시멘틱 버저닝(SemVer)을 맹신하지 않게 됩니다.

Breaking Change 확인: 릴리스 노트에서 'Refactoring', 'Migration', 'Drop Support' 키워드를 먼저 검색하세요. 이 단어가 보이면 마이너 업데이트라도 메이저급의 주의가 필요합니다.

3. 클라이언트 파편화: 의존성 지옥 (Dependency Hell)

서버가 안정화되어도 클라이언트가 말썽이면 서비스는 멈춥니다. 이번 리포트에서 각 클라이언트(Desktop, Xbox, Android TV)가 겪는 고통은 '크로스 플랫폼 개발'의 어두운 면을 적나라하게 보여줍니다.

[Jellyfin Desktop: Qt6 마이그레이션]

상황: 'Jellyfin Media Player'에서 'Jellyfin Desktop'으로 리브랜딩 하며 프레임워크를 Qt5에서 Qt6로 올렸습니다.
결과: 성능은 좋아졌으나 메모리 누수(Memory Leak) 발생. 게다가 Ubuntu 24.04 LTS는 Qt 버전 호환성 문제로 지원 불가.
분석: 프레임워크 버전 업은 언제나 '새로운 버그'를 선물합니다. 메모리 누수는 C++ 기반 애플리케이션의 고질병이자, 해결하기 가장 까다로운 부채 중 하나입니다.

[Xbox: 강제된 변화]

상황: 게임패드 내비게이션을 기본값으로 변경. 하지만 앱 실행 중 입력 모드 전환 불가.
제약: 서버 버전 10.11 이상 필수. 구버전 서버 사용자는 앱 사용 불가.
분석: 하위 호환성을 포기하는 건 개발자 입장에선 편하지만, 사용자 입장에선 청천벽력입니다. 4K/HDR 지원을 위해 백그라운드 재생을 포기했다는 대목에서는 '리소스 트레이드오프'의 비정함을 느낍니다.