[요약] Part 1. 마이그레이션의 3대 원칙

첫 번째 원칙: 수작업 변경 절대 금지

운영 환경의 데이터베이스를 GUI 툴이나 일회성 쿼리로 직접 수정하는 것은 시한폭탄을 심는 것과 같습니다. 수작업을 피해야 하는 치명적인 이유는 다음과 같습니다.

• 추적 불가능 (No History)
• 변경 이력이 남지 않아 문제 발생 시 원인을 파악하기 힘듭니다.
• 시간이 지나면 왜 만들어졌는지 모르는 '좀비 컬럼'들이 생겨 스파게티 DB가 됩니다.
• 환경 간 불일치 (Environment Drift)
• 로컬, 테스트, 운영 서버 간의 데이터베이스 구조가 조금씩 어긋나게 됩니다.
• 이 불일치는 새로운 코드 배포 시 곧바로 대형 서버 장애로 직결됩니다.
• 협업의 붕괴 (Collaboration Conflicts)
• 여러 명이 동시에 스키마를 수정하면 덮어쓰기 현상이 발생합니다.
• 구두로 스키마 변경 사항을 공유하는 것은 실수와 누락을 낳습니다.

두 번째 원칙: 파일과 버전을 통한 코드화

수작업의 반대말은 자동화된 코드 형상 관리입니다. 데이터베이스 변경은 반드시 투명한 파일 시스템을 거쳐야 합니다.

• 독립적인 파일 단위 작성
• 스키마 변경 사항(테이블 생성, 컬럼 추가 등)을 단일 `.sql` 파일에 명시적으로 작성합니다.
• 이를 통해 Git 같은 버전 관리 시스템에 데이터베이스 변경 이력을 영구 보존합니다.
• 엄격한 고유 버전 번호 부여
• 파일명 앞에 타임스탬프(예: `20260712120000_`)나 일련번호를 붙여 실행 순서를 엄격하게 보장합니다.
• 순서가 꼬이면 DB 생성 과정이 완전히 망가지기 때문입니다.
• 메타 테이블을 통한 상태 추적
• 마이그레이션 도구는 DB 내부에 `schema_migrations` 같은 특별한 장부 테이블을 생성합니다.
• 이 장부를 통해 중복 실행을 막고, 어떤 환경에서든 알아서 누락된 스키마만 순차적으로 적용(Sync)합니다.

세 번째 원칙: 검증된 도구의 일관된 사용

파일 관리를 수작업으로 쉘 스크립트로 짜지 말고, 잘 만들어진 전용 도구를 사용해야 합니다.

• 전용 도구의 필수 기능 혜택
• 도구는 여러 서버가 동시에 마이그레이션을 시도할 때 충돌을 막는 락(Lock) 기능을 제공합니다.
• 오류 발생 시 롤백(Rollback)을 쉽게 할 수 있는 체계를 갖추고 있습니다.
• 생태계의 표준 도구 활용
• Go 생태계의 경우 `golang-migrate`, `Goose` 등 파일 기반의 명시적 쿼리 도구를 선호합니다.
• 무거운 복잡도를 피하고 쿼리를 투명하게 유지하기 위함입니다.
• 일관성 유지
• 프로젝트 중간에 마이그레이션 도구를 바꾸거나, 여러 도구를 섞어 쓰는 것은 재앙을 부릅니다.
• "하나의 데이터베이스에는 하나의 도구만 일관되게 접근하게 하라"는 규칙을 절대 어겨서는 안 됩니다.