정정지용
기술스택 목록
데이터베이스

Flyway

프로젝트 5개에서 사용했습니다. 각 프로젝트에서 어떤 역할로 썼는지 아래에 정리했습니다.

이 기술은 무엇인가요?

데이터베이스 스키마의 버전을 관리하고 자동으로 마이그레이션하는 오픈소스 도구

Flyway는 데이터베이스 스키마 변경 이력을 SQL 파일로 관리하고, 애플리케이션 배포 시 자동으로 적용해주는 마이그레이션 도구입니다. Git으로 코드를 관리하듯 데이터베이스 스키마도 버전 관리가 필요한데, Flyway는 각 변경사항을 순서대로 실행하며 어떤 마이그레이션이 이미 적용되었는지 추적합니다. 여러 개발자가 협업하거나 운영 환경에 배포할 때 스키마 불일치 문제를 방지할 수 있습니다.

이럴 때 사용합니다

  • 팀원 간 로컬 DB 스키마를 일관되게 유지하고 싶을 때
  • 개발·스테이징·운영 환경에 스키마를 자동으로 동기화하고 싶을 때
  • CI/CD 파이프라인에서 배포 시 DB 마이그레이션을 자동화하고 싶을 때
  • 스키마 변경 이력을 코드처럼 Git에 남겨 추적하고 싶을 때

핵심 개념

Migration
데이터베이스 스키마 변경을 담은 SQL 파일 또는 Java 코드. 파일명에 버전 번호를 붙여 실행 순서를 보장합니다.
Versioned Migration
V1__init.sql 같은 형식으로, 한 번만 실행되는 마이그레이션. 테이블 생성, 컬럼 추가 등 스키마 변경에 사용됩니다.
Repeatable Migration
R__로 시작하며, 내용이 바뀔 때마다 다시 실행되는 마이그레이션. 뷰나 프로시저처럼 덮어쓰기가 가능한 객체에 사용됩니다.
Schema History Table
Flyway가 어떤 마이그레이션을 언제 실행했는지 기록하는 메타데이터 테이블. 기본 이름은 flyway_schema_history입니다.
Baseline
이미 운영 중인 데이터베이스에 Flyway를 처음 도입할 때, 특정 버전을 시작점으로 설정하는 작업.

기본 마이그레이션 파일 구조

V로 시작하는 파일은 버전 순서대로 한 번만 실행되고, R로 시작하는 파일은 내용이 바뀔 때마다 재실행됩니다. Flyway는 애플리케이션 시작 시 자동으로 미적용 마이그레이션을 탐지해 실행합니다.

SQL
-- V1__create_user_table.sql
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    email VARCHAR(255) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- V2__add_user_name.sql
ALTER TABLE users ADD COLUMN name VARCHAR(100);

-- R__refresh_user_stats_view.sql
CREATE OR REPLACE VIEW user_stats AS
SELECT COUNT(*) as total FROM users;

처음 쓸 때 흔한 함정

  • 이미 적용된 마이그레이션 파일을 수정하면 체크섬 오류가 발생합니다
  • 파일명 규칙(V숫자__설명.sql)을 지키지 않으면 인식되지 않습니다
  • 운영 DB에 처음 도입할 때는 baseline 명령으로 시작점을 설정해야 합니다

위 개요는 기술 학습을 돕기 위해 자동 생성된 일반 설명입니다. 정확한 사양과 최신 정보는 공식 문서를 확인하세요.

프로젝트별 활용 방식

위 개념이 실제 프로젝트에서 어떻게 쓰였는지 보여줍니다.

함께 사용한 기술

위 프로젝트들에서 같이 쓰인 다른 기술입니다.

Docker5Java5PostgreSQL5Spring Boot5Spring Security5Spring Data JPA4AWS S33Firebase Admin SDK3Gradle3Swagger3Prometheus2GitHub Actions