마이그레이션 중 사용자에게 영향 없이 진행하기

마이그레이션이 위험한 이유

마이그레이션은 단순히 "스키마를 바꾸고 데이터를 옮기는" 것만이 아니다. 이미 접속 중인 사용자가 있을 때 구 버전 서버가 새 스키마에 접근하거나, 새 서버가 이전 데이터 형식을 기대할 수 있다.

한 번 잘못하면 데이터 손실이나 서비스 중단이 생길 수 있다.

마이그레이션 계획 세우기

먼저 전체 흐름을 써본다.

1. 현재 상태 기록

   -- 데이터 백업
   mysqldump -u root -p mydb > backup_20260630.sql

   -- 기존 데이터 수 확인
   SELECT COUNT(*) FROM users;
   SELECT COUNT(*) FROM orders;

2. 구 버전과 새 버전이 동시에 작동하도록 설정

   • 새 컬럼을 추가하되, 기본값을 설정해서 이전 코드도 작동하게 함
   • 이전 컬럼도 유지

3. 배포 순서

   • 단계 1: 데이터베이스 스키마 변경 (마이그레이션)
   • 단계 2: 애플리케이션 배포 (새 코드)
   • 단계 3: 이전 데이터 형식 제거 (cleanup)

구체적인 예: 사용자 테이블 필드 추가

기존:

CREATE TABLE users (
  id INT PRIMARY KEY,
  email VARCHAR(255),
  name VARCHAR(255)
);

새로 phone 필드를 추가하려면:

-- 단계 1: 새 컬럼 추가 (기본값 설정)
ALTER TABLE users ADD COLUMN phone VARCHAR(20) DEFAULT '';

-- 단계 2: 인덱스 추가 (선택사항)
CREATE INDEX idx_phone ON users(phone);

이렇게 하면 기존 코드도 작동하고, 새 코드도 phone을 사용할 수 있다.

마이그레이션 중 테스트

로컬에서 먼저 테스트:

# 백업 복원
mysql -u root -p mydb < backup_20260630.sql

# 마이그레이션 실행
npm run migrate

# 데이터 검증
npm run validate-migration

스테이징 환경에서 테스트:

# 프로덕션 데이터로 테스트 (읽기 레플리카 사용)
# 또는 최근 백업으로 테스트

배포 중 사용자 영향 최소화

만약 마이그레이션이 오래 걸린다면, 그 시간 동안 읽기만 허용하도록 설정한다.

// 마이그레이션 중 쓰기 요청 차단
if (process.env.MIGRATION_IN_PROGRESS === 'true') {
  throw new Error('시스템 점검 중입니다. 잠시 후 다시 시도해주세요.');
}

또는 점진적으로 배포한다.

# 트래픽의 10%만 새 버전으로 라우팅
# 이슈 없으면 50% → 100%으로 확대

롤백 계획

만약 마이그레이션 후 심각한 버그가 발견되면 빠르게 롤백해야 한다.

# 백업 복원
mysql -u root -p mydb < backup_20260630.sql

# 또는 이전 버전의 코드 배포
git revert [commit_hash]
git push

롤백 시뮬레이션을 미리 해본다.

배포 전 체크리스트

• 현재 데이터를 완전히 백업했는가?
• 로컬과 스테이징에서 마이그레이션을 테스트했는가?
• 이전 코드와 새 코드가 동시에 작동하는가?
• 마이그레이션 후 데이터 개수가 맞는가?
• 롤백 계획을 세웠는가?
• 모니터링 알림을 설정했는가?
• 필요시 사용자에게 공지했는가?

이 항목들을 모두 확인한 후 진행하면 데이터 손실 없이 안전하게 마이그레이션할 수 있다.