7.1. Flyway 개요 및 파일 규칙

7.1. Flyway 개요

7.1.1. DDL 관리 원칙

데이터베이스 스키마의 모든 변경은 Flyway 마이그레이션 파일을 통해 관리합니다.

항목	규칙
스키마 변경 방법	Flyway 마이그레이션 파일만 허용
수동 DDL 실행	금지 (운영 DB 직접 변경 불가)
마이그레이션 파일 수정	적용 완료된 파일은 절대 수정 금지
롤백	새로운 마이그레이션 파일로 롤백 처리

7.1.2. 의존성

<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-database-postgresql</artifactId>
</dependency>

Spring Boot BOM에서 버전을 관리하므로 별도의 버전 명시는 불필요합니다.

7.2. 마이그레이션 파일 규칙

7.2.1. 파일 위치

src/main/resources/
└── db/
    └── migration/
        ├── V1__create_users_table.sql
        ├── V2__create_orders_table.sql
        ├── V3__add_phone_to_users.sql
        └── V4__create_documents_table.sql

7.2.2. 파일명 규칙

V{버전번호}__{설명}.sql

구성 요소	규칙	예시
접두사	V (대문자)	V1, V10
버전 번호	순차 정수	1, 2, 3
구분자	__ (밑줄 2개)
설명	snake_case, 영문	create_users_table
확장자	.sql

올바른 예시:

V1__create_users_table.sql
V2__create_orders_table.sql
V3__add_phone_to_users.sql
V4__create_idx_users_email.sql
V5__insert_initial_roles.sql

잘못된 예시:

V1_create_users.sql        # 밑줄 1개 (2개 필요)
v1__create_users.sql       # 소문자 v
V1__CreateUsers.sql        # CamelCase 사용
V1__사용자_테이블_생성.sql     # 한글 사용

7.2.3. 버전 넘버링 전략

순차 정수 방식을 사용합니다.

V1, V2, V3, ... V10, V11, ...

• 팀 규모가 크거나 충돌이 잦은 경우 타임스탬프 방식도 허용합니다: V20260228100000__description.sql
• 프로젝트 초기에 방식을 정하고 일관되게 유지합니다.

7.2.4. 수정 금지 원칙

절대 금지

이미 flyway_schema_history 테이블에 기록된 마이그레이션 파일은 내용을 수정하거나 삭제할 수 없습니다.

잘못된 마이그레이션을 수정해야 하는 경우, 새로운 버전의 마이그레이션 파일을 작성하여 변경 사항을 적용합니다.