앱 MVP Android Room 데이터베이스 마이그레이션: 스키마·경로·테스트를 나누는 5가지 기준
앱 MVP의 로컬 데이터베이스를 바꿀 때 화면에 새 필드 하나를 추가하는 일과, 이미 설치된 앱의 데이터를 새 구조로 열 수 있게 하는 일은 다릅니다. 기존 사용자는 이전 버전의 스키마와 데이터로 앱을 실행할 수 있습니다. 그래서 변경 전에는 무엇이 바뀌는지, 어떤 이전 버전에서 어느 새 버전으로 이동하는지, 테스트에서 무엇을 확인할지를 따로 결정해야 합니다.
Android Developers는 Room 스키마 변경 시 자동 마이그레이션과 수동 마이그레이션을 모두 제공한다고 설명합니다(C001). 다만 모든 변경을 자동으로 판단할 수 있는 것은 아닙니다. 이 글은 특정 앱의 데이터 보존·출시 성공을 보장하지 않으며, 팀이 Room 변경을 제품 요구사항과 테스트 기록으로 연결하는 일반적인 판단 기준입니다.
먼저 구분할 것: 새 설치와 기존 설치의 데이터베이스는 출발점이 다릅니다
새로 설치한 앱은 최신 스키마에서 시작하지만, 기존 사용자의 기기는 과거 버전의 테이블과 데이터가 남아 있을 수 있습니다. 둘 다 최신 화면이 열렸다는 사실만으로 마이그레이션이 맞았다고 볼 수는 없습니다. 어떤 변경이 신규 설치에만 필요한지, 기존 데이터에서 변환이 필요한지, 이전 버전이 얼마나 남아 있는지를 기록하세요.
Room은 앱 업데이트로 데이터베이스 스키마가 바뀔 때 점진적 마이그레이션을 지원합니다(C002). 이때 version 번호를 올리는 일과 실제 이전 경로를 정의하는 일은 별개입니다. 제품 문서에는 최소한 시작 버전, 목표 버전, 영향을 받는 테이블·열, 기존 값의 처리 방법을 같은 변경 묶음으로 남기는 편이 좋습니다.
기준 1: 스키마 변경의 이유와 데이터 처리 규칙을 먼저 적습니다
열을 추가·이름 변경·삭제하거나 테이블을 분리·병합하는 일은 모두 사용자 데이터에 다른 질문을 만듭니다. 예를 들어 새 열이 비어 있어도 되는지, 이전 값을 새 형식으로 바꿀 수 있는지, 더 이상 쓰지 않는 값을 제거해도 되는지는 화면 설계만으로 정해지지 않습니다. 기능 요구사항과 데이터 처리 규칙을 한 문장씩 분리하세요.
Room 공식 문서는 복잡한 변경에서는 수동 Migration이 필요할 수 있다고 안내합니다(C001). 따라서 “자동으로 되겠지”라는 가정 대신, 변경 내용을 Room이 판별할 수 있는 단순 변경인지, 개발팀이 변환 로직을 직접 작성해야 하는 변경인지 검토해야 합니다. 특히 테이블·열의 삭제나 이름 변경처럼 모호성이 생길 수 있는 경우에는 변환 의도를 코드와 검토 기록에 같이 남기세요.
기준 2: 자동 마이그레이션과 수동 마이그레이션을 같은 위험도로 보지 않습니다
자동 마이그레이션은 생성된 이전·이후 스키마 정보를 바탕으로 동작합니다. Android Developers는 스키마를 내보내지 않았거나 상위 버전 스키마를 컴파일하지 않은 경우 자동 마이그레이션이 실패한다고 설명합니다(C001). 따라서 자동이라는 표현은 “검토가 필요 없다”는 뜻이 아니라, 어떤 입력과 범위에서 코드 생성이 가능한지 확인해야 한다는 뜻입니다.
수동 마이그레이션은 시작 버전과 종료 버전 사이의 변환 경로를 명시합니다. 팀은 이 경로를 버전 이름만으로 관리하지 말고, 변경된 데이터의 기본값·분리 기준·폐기 기준을 함께 검토하세요. 동일한 버전 구간에 자동과 수동 경로가 함께 정의되면 수동 경로가 우선될 수 있다는 Room 문서의 설명도 확인 대상입니다(C001).
기준 3: 내보낸 스키마 이력은 테스트 자산으로 보관합니다
Room은 컴파일 시점에 데이터베이스 스키마 정보를 JSON 파일로 내보낼 수 있으며, 공식 문서는 이 파일을 버전 관리에 저장해 과거 버전을 재현하고 자동 마이그레이션 생성 및 테스트에 활용하라고 안내합니다(C001). 단순히 최신 스키마 파일만 남기면 이전 설치 상태를 다시 만들 때 근거가 부족해집니다.
이력에는 스키마 파일 위치, 앱 버전과 데이터베이스 버전의 대응, 변경 PR 또는 작업 번호, 테스트에 사용한 시작 버전을 기록하세요. 개인정보가 들어간 실사용 DB를 저장하라는 뜻은 아닙니다. 구조 이력과 테스트용 최소 데이터는 분리하고, 실제 사용자 데이터는 사내 보안 기준에 따라 다루어야 합니다.
MVP 데이터 변경 범위와 출시 전 검증 항목을 함께 정리하기
기준 4: 스키마 검증과 데이터 검증을 둘 다 통과시킵니다
마이그레이션 테스트에서 테이블 구조가 열렸다고 해도 사용자 데이터가 기대한 값으로 옮겨졌다는 증거는 아닙니다. Android Developers의 MigrationTestHelper 예시는 이전 버전 DB를 만들고, 테스트 데이터를 넣은 뒤, 마이그레이션과 스키마 검증을 수행하고, 이어서 데이터가 남았는지를 별도로 확인합니다(C001). 이 순서를 참고해 구조와 데이터 검증을 두 개의 체크로 나누세요.
최소 테스트 표본에는 빈 값, 필수값, 변경 대상 값, 여러 행, 이전 화면에서 만든 데이터처럼 변환 규칙을 확인할 수 있는 상태를 넣습니다. 실제 서비스에서 필요한 보존·삭제 기준은 서비스 정책과 법적 의무에 따라 달라지므로, 공식 예제의 테스트 데이터만으로 개별 앱의 기준을 확정하지는 마세요.
로컬 저장·공유 파일의 수명 구분은 기존 앱 MVP 저장공간 기준과도 이어집니다. 저장공간 글이 파일의 위치와 삭제 경계를 다룬다면, 이 글은 앱 안의 Room 스키마가 바뀔 때 기존 DB를 어떤 경로와 검증으로 열 것인지에 초점을 둡니다.
기준 5: 파괴적 재생성은 편의 옵션이 아니라 데이터 결정입니다
Room에서 정의된 마이그레이션 경로를 찾지 못했을 때 예외가 발생할 수 있으며, fallbackToDestructiveMigration은 테이블을 다시 만들어 기존 테이블 데이터를 영구 삭제할 수 있다고 Android Developers는 경고합니다(C001). 따라서 이 옵션을 단순한 장애 회피책으로 넣기보다, 어떤 사용자·어떤 버전·어떤 데이터에서 삭제가 허용되는지 먼저 제품 책임자가 결정해야 합니다.
삭제가 허용되지 않는 데이터라면 누락된 경로를 발견하고 보완하는 것이 우선입니다. 삭제가 허용될 수 있는 캐시성 데이터라도 사용자가 다시 내려받거나 재생성할 수 있는지, 실패 안내는 무엇인지, QA에서 어느 시작 버전을 시험했는지는 별도 기록이 필요합니다. 옵션을 적용했다고 데이터 보존이나 앱 안정성이 자동으로 증명되는 것은 아닙니다.
출시 전 Room 변경 기록 5칸
시작 DB 버전과 목표 DB 버전
테이블·열별 변경 이유와 기존 값 처리 규칙
자동 또는 수동 경로를 고른 이유와 스키마 이력 위치
이전 버전에서 만든 테스트 데이터와 구조·데이터 검증 결과
누락 경로·삭제 허용 여부·실패 안내의 최종 결정
이 다섯 칸이 있으면 기능 추가, 장애 재현, 새 개발자 인수인계 때 “버전만 올렸다”는 기록보다 훨씬 구체적으로 다시 검토할 수 있습니다. 다만 실제 데이터 변경은 앱 구조, 사용자 약속, 개인정보 처리 기준에 따라 달라지므로 배포 후보에서 별도 검증해야 합니다.
자주 묻는 질문
Room 자동 마이그레이션이면 테스트하지 않아도 되나요?
아닙니다. 공식 문서는 자동 마이그레이션도 내보낸 이전·이후 스키마 정보에 의존한다고 설명하며, 마이그레이션 테스트를 안내합니다(C001). 자동 여부와 별개로 이전 버전 데이터가 최신 구조와 원하는 값으로 열리는지 검증하세요.
새 설치에서 정상 동작하면 기존 사용자도 문제없나요?
아닙니다. 새 설치는 최신 스키마에서 시작하지만 기존 사용자는 이전 스키마와 데이터에서 출발합니다. 최소 하나 이상의 이전 버전 DB를 만들고, 마이그레이션 뒤 구조와 데이터 결과를 따로 검사해야 합니다.
누락된 경로에서 destructive migration을 켜도 되나요?
그 설정은 관리되는 테이블의 기존 데이터를 영구 삭제할 수 있습니다(C001). 데이터 삭제가 제품 약속과 정책상 허용되는지, 복구·재다운로드 경로가 있는지, 사용자 안내가 필요한지를 먼저 검토한 뒤 결정하세요.
Room 기준을 정리하면 출시 오류가 없어지나요?
아닙니다. 이 글은 변경 범위와 검증 기록을 정리하는 가이드입니다. 실제 호환성, 데이터 보존, 배포 결과는 앱의 코드·테스트 기기·기존 설치 상태에서 별도로 확인해야 합니다.
앱 MVP의 데이터 변경과 QA 기준을 유인어스와 점검하기
공식 출처
Android Developers: Migrate your Room database