마이그레이션 (Migration)

마이그레이션(Migration)은 기존 소프트웨어나 데이터를 새로운 구조·버전·실행 환경에 맞게 이전하는 작업입니다. 데이터베이스의 열을 바꾸거나 새 버전에 맞춰 코드를 수정하는 일처럼 이전 대상에 따라 작업 범위가 달라집니다. 기존 자료와 동작을 어떻게 이어 갈지 정한 뒤 변경을 적용하며, 변경 파일을 만든 상태와 실제 환경에 적용한 상태를 구분합니다.

이전 대상과 변경 이력

마이그레이션이라는 말은 옮기는 대상과 함께 읽어야 구체적인 작업이 드러납니다. 데이터베이스에서는 테이블이나 열의 구조를 바꾸는 일을, 소프트웨어에서는 새 버전에 맞춰 기존 코드와 의존성을 조정하는 일을 가리킬 수 있습니다. 같은 서버 안에서도 데이터 구조를 바꾸면 마이그레이션이 필요합니다. 파일을 다른 위치로 복사하는 작업만을 뜻하지 않으며, 무엇을 어떤 상태로 바꾸는지가 중심이 됩니다.

Django 5.2의 마이그레이션 문서는 모델에 만든 변경을 데이터베이스 스키마에 반영하는 방법을 설명합니다. 여기서 모델은 데이터의 구조를 코드로 표현한 것이고, 스키마는 실제 데이터베이스의 테이블·열 같은 구조입니다. 코드에 새 필드를 추가해도 저장소의 구조가 저절로 같아지는 것은 아닙니다. 마이그레이션은 모델의 변경을 기록하고 데이터베이스에 적용하는 역할을 합니다.

변경 이력이 있으면 어느 구조에서 다음 구조로 넘어가는지 추적할 수 있습니다. Django는 마이그레이션 파일을 코드와 함께 버전 관리하고 개발·시험·운영 환경에 같은 파일을 적용하는 방식을 설명합니다. 다만 문서가 일관된 결과를 말하는 조건은 같은 데이터와 같은 상황입니다. 개발 환경에서 한 번 적용한 결과만으로 데이터나 이전 이력이 다른 운영 환경의 결과까지 확인했다고 볼 수는 없습니다.

변경 파일 생성과 실제 적용의 차이

Django에서 makemigrations는 모델의 변경을 바탕으로 새 마이그레이션 파일을 만듭니다. migrate는 그 파일의 변경을 데이터베이스에 적용하거나 해제하는 명령입니다. 두 이름이 비슷해도 완료한 단계가 다릅니다. 변경 파일이 만들어졌다는 출력은 실제 테이블까지 바뀌었다는 증거가 아니므로, 파일 생성과 적용 결과를 따로 확인합니다. 이 명령들은 Django의 사례이며 모든 도구가 같은 이름과 절차를 쓰는 것은 아닙니다.

구조를 바꾸는 일과 이미 저장된 값을 바꾸는 일도 구별합니다. 새 열을 만드는 것은 스키마 변경이고, 기존 두 열의 값을 합쳐 새 열에 채우는 것은 데이터 변환입니다. Django 문서는 이런 데이터 마이그레이션을 스키마 마이그레이션과 나누어 작성하는 방식을 권하며, 값의 변환 규칙은 자동으로 생성해 주지 않는다고 설명합니다. 어떤 값을 합치거나 버릴지는 데이터의 의미를 알고 정해야 하기 때문입니다.

변경을 적용하는 순서에도 조건이 있습니다. 다른 테이블을 참조하는 열을 추가하려면 참조 대상 테이블이 먼저 존재해야 합니다. Django는 마이그레이션 파일에 선행 변경과의 의존 관계를 기록하고 이를 바탕으로 순서를 정합니다. 파일 이름에 붙은 번호만 보고 순서를 결정하는 것과는 다릅니다. 여러 사람이 만든 변경을 합칠 때도 어느 변경이 먼저 적용되어야 하는지 확인하면, 없는 구조를 참조하는 문제를 찾기 쉽습니다.

호환성 확인과 복구 조건

소프트웨어 버전을 바꾸는 마이그레이션에서는 설치가 끝난 뒤에도 기존 코드가 동작하는지 확인합니다. Django 5.2의 버전 업그레이드 안내는 대상 버전까지의 릴리스 노트와 호환되지 않는 변경, 사용 중인 의존성의 지원 여부를 살펴보도록 설명합니다. 새 버전이 설치되었다는 사실과 기존 애플리케이션이 새 버전에 맞게 바뀌었다는 사실은 별개입니다. 더 이상 지원되지 않는 기능을 사용했다면 코드 수정이 필요할 수 있습니다.

이전 상태로 되돌리는 롤백도 변경 내용과 도구의 지원 범위에 달려 있습니다. Django 문서는 되돌릴 수 없는 연산이 들어간 마이그레이션은 역방향 실행에 실패한다고 명시합니다. 데이터 변환에 쓰는 RunPython도 역방향 처리를 제공하지 않으면 되돌릴 때 예외가 발생합니다. 적용 명령에 해제 기능이 있다고 해서 삭제한 데이터나 모든 변환 결과를 자동 복구할 수 있다고 판단하지 않습니다.

실제 적용을 준비할 때는 기존 데이터의 보존 방법, 되돌릴 수 있는 변경의 범위, 적용 뒤 확인할 동작을 함께 정합니다. 버전 업그레이드 안내는 새 환경에서 애플리케이션의 전체 테스트를 실행하고 실패를 해결한 뒤 배포하는 흐름을 제시합니다. 데이터베이스 변경이라면 구조뿐 아니라 옮겨진 값과 애플리케이션의 읽기·쓰기 동작도 확인 대상입니다. 변경 이력과 검증 결과를 함께 남겨 두면 어디까지 적용했고 무엇을 확인했는지 구분할 수 있습니다.