누적된 DB 마이그레이션을 스키마에 통합해 혼동 해소

마이그레이션 파일이 50개, 100개 쌓이면서 schema.sql이 현재 운영 DB와 맞지 않기 시작했다. 이번에 누적된 마이그레이션을 모두 schema.sql에 통합하는 폴드인 작업을 진행했다.

왜 이런 문제가 발생했는가

처음엔 간단했다. 초기 schema.sql에 전체 스키마를 정의하고, 이후 변경사항마다 migration_XXX.sql 파일을 추가하는 방식. 명확하고 git으로 이력 추적도 깔끔했다.

하지만 시간이 지나면서 차이가 누적됐다:
- 마이그레이션 파일이 한두 개씩 쌓여 점점 많아진다
- schema.sql은 초기 상태 그대로 멈춰있다
- 새로운 환경(로컬, 테스트 서버, 프리뷰)을 셋업할 때마다 schema.sql 적용 후 모든 마이그레이션을 순차 재생해야 한다
- 팀원들이 "현재 스키마가 정확히 뭐야?"라고 물어도 명확히 답하기 어렵다
- schema.sql과 실제 운영 DB 상태의 차이가 커지면서 혼동이 생긴다

결국 schema.sql이 "옛날 스냅샷"처럼 느껴지기 시작했다.

폴드인의 의미

폴드인(fold-in)은 단순한 작업이다: 지금까지의 모든 마이그레이션을 schema.sql에 통합해서 schema.sql이 현재 운영 DB의 정확한 상태를 반영하도록 정렬하는 것.

-- 폴드인 전
-- schema.sql
CREATE TABLE users (
  id INT PRIMARY KEY,
  name VARCHAR(255)
);

-- migration_001_add_email.sql
ALTER TABLE users ADD COLUMN email VARCHAR(255);

-- migration_002_add_indexes.sql
CREATE INDEX idx_users_email ON users(email);

이를 폴드인하면:

-- 폴드인 후 schema.sql (모든 변경사항 통합)
CREATE TABLE users (
  id INT PRIMARY KEY,
  name VARCHAR(255),
  email VARCHAR(255)
);

CREATE INDEX idx_users_email ON users(email);

이제 새 환경을 셋업할 때 schema.sql 한 번이면 끝난다. 마이그레이션 파일 100개를 순차 재생할 필요가 없다.

언제 필요한가

여러 신호가 있었다:

폴드인 후 이런 혼동들이 거의 사라진다. schema.sql이 "진실의 원천"이 되기 때문이다.

실제 작업 과정

1. 현재 운영 DB 상태를 명확히 파악 (schema 추출)
2. schema.sql에 모든 최신 정의 반영
3. 테스트 환경에서 schema.sql만으로 재구성 후 실제 DB와 비교 검증
4. 기존 마이그레이션 파일 비활성화 또는 보관
5. 팀 공지 (향후 스키마 변경 방식 안내)

주의할 점:
- schema.sql 적용 후 실제 운영 DB와 정확히 일치하는지 여러 번 확인
- 마이그레이션 파일 삭제 전 git 히스토리가 안전하게 보관되는지 확보
- 팀원 모두가 로컬 DB를 최신 상태로 업데이트했는지 확인

회고

이 작업을 통해 몇 가지를 배웠다.

유지보수성은 주기적 정리가 필요하다. 마이그레이션 방식은 처음엔 깔끔하지만, 일정 수준 이상 쌓이면 번거로워진다. 팀의 성장에 맞춰 이런 "정리 작업"을 의도적으로 계획할 필요가 있다.

팀 소통이 스키마 정의보다 중요할 수도 있다. schema.sql이 현재 상태를 반영하지 못하면 팀원 간 혼동이 생긴다. 특히 새로 합류한 팀원이 "현재 스키마가 뭐라고 되어 있어요?"라고 물을 때 명확히 답할 수 없으면 신뢰가 깨진다.

개발자 경험도 작은 곳부터. 새 팀원 입장에선 "마이그레이션 100개를 재생해야 합니다" vs "schema.sql 한 번으로 끝입니다" 의 차이가 크다. 온보딩 시간 단축과 스트레스 감소는 예상보다 중요한 신호다.

다음엔 마이그레이션이 일정 수(20-30개?) 이상 쌓이면 자동으로 폴드인하는 기준을 팀과 정해두는 게 좋을 것 같다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.