춘배투어 Flyway 도입! 기초 개념부터 실전 사용까지

1. Flyway란?

Flyway는 데이터베이스(Database) 스키마 변경 이력을 버전으로 관리하는 도구이다.

쉽게 말하면 Git이 소스코드를 버전 관리하듯이, Flyway는 데이터베이스 구조를 버전 관리한다.

예를 들어 프로젝트를 진행하다 보면 다음과 같은 일이 자주 발생한다.

• users 테이블 생성
• notifications 테이블 생성
• messages 테이블에 컬럼 추가
• 인덱스 추가
• 제약조건 변경

이러한 변경 사항을 SQL 파일로 기록하고 관리하는 것이 Flyway의 역할이다.

---

2. Flyway가 필요한 이유

기존 방식의 문제

팀원 A

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

실행

↓

DB 변경 완료

---

팀원 B

위 SQL을 실행하지 않음

↓

users 테이블 없음

↓

애플리케이션 실행 실패

---

팀원 C

users 테이블을 직접 수정

↓

DB 구조가 모두 달라짐

↓

"내 컴퓨터에서는 되는데?" 발생

---

Flyway 사용 시

모든 DB 변경 이력을 SQL 파일로 관리한다.

V1__create_users.sql
V2__create_chat_rooms.sql
V3__create_notifications.sql

애플리케이션 실행 시

Flyway가 자동으로 확인 후

아직 실행되지 않은 SQL만 실행한다.

따라서 모든 개발자의 DB 구조가 동일하게 유지된다.

---

3. Flyway 동작 원리

예를 들어 다음과 같은 파일이 있다고 가정한다.

db/migration

V1__create_users.sql
V2__create_chat_rooms.sql
V3__create_notifications.sql

애플리케이션 실행

↓

Flyway가 순서대로 실행

V1
V2
V3

↓

DB에 적용

↓

Flyway는 실행 이력을 저장하기 위해

flyway_schema_history

테이블을 자동 생성한다.

예시

versiondescription

1	create_users
2	create_chat_rooms
3	create_notifications

---

다음 실행 시

Flyway는

V1 적용됨
V2 적용됨
V3 적용됨

을 확인하고

다시 실행하지 않는다.

---

4. 가장 중요한 개념 - Migration

Flyway에서는 DB 변경 작업 하나를

Migration(마이그레이션)이라고 부른다.

예시

V1__create_users.sql

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL
);

이 파일 하나가 하나의 Migration이다.

---

5. 파일 이름 규칙

Flyway는 정해진 규칙을 따라야 한다.

기본 형식

V버전__설명.sql

예시

V1__create_users.sql
V2__create_wallets.sql
V3__create_chat_rooms.sql

---

잘못된 예

V1_create_users.sql

언더바 1개

❌

create_users.sql

버전 없음

❌

---

올바른 예

V1__create_users.sql

✅

---

6. 실제 동작 예시

V1

V1__create_users.sql

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL
);

실행

↓

users 생성

↓

history 기록

---

새로운 요구사항 발생 했을 경우에는 기존 파일을 수정하면 절대 안 된다.

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255),
    nickname VARCHAR(50)
);

---

올바른 방법

새 Migration 생성

V2__add_nickname_to_users.sql

ALTER TABLE users
ADD COLUMN nickname VARCHAR(50);

실행

↓

Flyway가 V2만 실행

↓

DB 반영

ex)

V1 : users 테이블 생성
V2 : chat_rooms 테이블 생성
V3 : faqs 테이블 생성
V4 : users.nickname 추가
V5 : users.language 추가
V6 : users.email 인덱스 추가

---

7. 왜 기존 파일을 수정하면 안 될까?

Flyway는 V1 적용 완료라고 기록해 둔다.

 

만약 V1 파일을 수정하면 로컬 A의 V1과 로컬 B의 V1내용이 달라진다.

 

그러면 같은 버전인데 내용이 달라지는 상황이 발생한다.

이를 방지하기 위해 배포되거나 공유된 Migration은 수정하지 않는다.

 

변경이 필요하면 새 버전을 만든다.

---

8. 자주 사용하는 SQL

테이블 생성

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL
);

컬럼 추가

ALTER TABLE users
ADD COLUMN nickname VARCHAR(50);

컬럼 삭제

ALTER TABLE users
DROP COLUMN nickname;

컬럼 타입 변경

ALTER TABLE users
MODIFY COLUMN nickname VARCHAR(100);

인덱스 추가

CREATE INDEX idx_users_email
ON users(email);

유니크 제약조건 추가

ALTER TABLE users
ADD CONSTRAINT uk_users_email
UNIQUE(email);

---

9. Spring Boot에서 사용하는 방법

의존성 추가

Gradle

implementation 'org.flywaydb:flyway-mysql'

application.yml

spring:
  flyway:
    enabled: true

Migration 위치

src
└── main
    └── resources
        └── db
            └── migration

예시

src/main/resources/db/migration

V1__create_users.sql
V2__create_chat_rooms.sql
V3__create_notifications.sql

---

10. 춘배투어에 Flyway 적용 

우리 프로젝트는 Flyway를 프로젝트 시작 시점이 아니라 MVP 개발이 상당 부분 진행된 이후에 도입하였다.

 

Flyway는 데이터베이스 변경 이력을 버전 단위로 관리하는 도구인데, 일반적으로는 프로젝트 시작 단계부터 V1, V2, V3 형태로 스키마 변경 내역을 누적 관리한다.

 

하지만 우리 프로젝트는 이미 여러 도메인의 개발이 진행된 상태였기 때문에, Flyway 도입 이전에도 다양한 테이블과 컬럼이 존재하고 있었다.

 

이 상태에서 Flyway를 도입한다고 해서 과거의 모든 스키마 변경 이력을 다시 추적하여 V1, V2, V3 형태로 복원하는 것은 현실적으로 어렵다.

따라서 Flyway 도입 시점의 데이터베이스 구조 전체를 하나의 기준점(Baseline)으로 설정하였다.

즉, 우리 프로젝트의 V1은 프로젝트의 첫 번째 DB 상태가 아니라, Flyway를 처음 적용한 시점의 DB 상태인 것이다.

 

이를 통해 Flyway는 기존에 존재하던 테이블들을 이미 적용된 스키마로 인식할 수 있게 된다.

이후 발생하는 모든 스키마 변경은 기존 파일을 수정하지 않고 새로운 버전으로 추가한다.

 

---

11. 협업 시 주의사항

문제 상황

팀원 A

V15__create_notifications.sql

생성

---

팀원 B

V15__create_wallet.sql

생성

---

둘 다 같은 버전

↓

Git 충돌 발생

---

해결

한 명이 번호 변경

V16__create_wallet.sql

 

주의 사항

버전이 1, 2, 3이 반드시 연속일 필요는 없지만,

새로운 버전은 항상 현재 존재하는 가장 큰 버전보다 크게 만드는 것이 안전한 운영 방식이다.

---

12. 간단 정리

Flyway란?

DB 변경 이력을 버전으로 관리하는 도구

장점

• DB 구조를 Git처럼 관리 가능
• 모든 개발자의 DB 상태 통일
• 배포 시 자동 적용
• 변경 이력 추적 가능
• 롤백 및 유지보수 용이

핵심 원칙

1. 모든 DB 변경은 Migration 파일로 작성한다.
2. 이미 적용된 Migration은 수정하지 않는다.
3. 변경 사항은 새 버전으로 추가한다.
4. 파일명은 V버전__설명. sql 형식을 따른다.

한 줄 요약

Flyway는 데이터베이스 변경 이력을 SQL 파일로 관리하고, 애플리케이션 실행 시 버전 순서대로 자동 적용하여 모든 환경의 DB 스키마를 일관되게 유지해 주는 데이터베이스 마이그레이션 도구이다.