Spring Boot와 Flyway로 데이터베이스 마이그레이션 관리

소개

애플리케이션이 성장하면 데이터베이스 스키마 변경이 필수다. 수작업 SQL 적용은 오류와 버전 불일치를 초래한다. Flyway는 버전 기반 마이그레이션을 제공해 이 문제를 해결한다. Spring Boot와 결합하면 설정이 간단해지고 자동화된 배포 파이프라인에 통합하기 용이하다.

기본 개념

Flyway는 SQL 또는 자바 기반 마이그레이션 파일을 순차적으로 적용한다. 각 파일은 고유한 버전 번호를 갖는다. 적용 이력은 flyway_schema_history 테이블에 기록된다. 이를 통해 여러 환경에서 일관된 마이그레이션을 보장할 수 있다.

사전 준비

• Java와 Spring Boot 프로젝트
• 데이터베이스 접근 정보 (JDBC URL, 사용자, 비밀번호)
• 빌드 툴(Maven 또는 Gradle)

의존성 추가

Maven 또는 Gradle에 Flyway 의존성을 추가한다. 아래는 Maven 예시이다.

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

Spring Boot 설정

application.yml 또는 application.properties에 데이터베이스와 Flyway 설정을 추가한다. 기본값만으로도 자동 마이그레이션이 동작한다. 중요한 설정 몇 가지는 아래와 같다.

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: myuser
    password: secret
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true

마이그레이션 파일 작성 규칙

Flyway의 기본 위치는 classpath:db/migration 이다. 파일명 규칙은 V{버전}__{설명}.sql 형식이다. 예를 들어 V1__create_user_table.sql 처럼 작성한다. 파일은 순차적으로 적용되므로 의도한 버전 체계를 유지해야 한다.

예시 SQL 파일

-- V1__create_user_table.sql
CREATE TABLE users (
  id BIGSERIAL PRIMARY KEY,
  username VARCHAR(50) NOT NULL,
  email VARCHAR(100) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- V2__add_status_to_users.sql
ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'ACTIVE';

실행 흐름

• 애플리케이션 시작 시 Flyway가 마이그레이션을 검사한다.
• 적용되지 않은 버전을 순서대로 실행한다.
• 성공 시 flyway_schema_history에 기록한다.
• 실패 시 롤백 또는 에러 상태가 되며 재시도 전에 원인 해결이 필요하다.

운영 시 고려사항

• 데이터 손실 위험이 있는 변경은 별도 절차로 관리한다.
• 대용량 테이블 변경은 온라인 변경 방식 또는 분할 적용을 검토한다.
• 테스트 환경에서 먼저 마이그레이션을 검증한다.
• CI/CD 파이프라인에 flyway migration spring boot 실행 단계를 포함한다.

문제 해결 팁

마이그레이션 충돌이나 실패는 주로 파일 버전 충돌, 권한 부족, SQL 오류 때문이다. 기본적인 점검 순서는 다음과 같다.

• flyway_schema_history 테이블을 확인해 적용 이력을 검토한다.
• 로그에서 실패한 스텝과 에러 메시지를 확인한다.
• 필요 시 실패한 마이그레이션을 repair 명령으로 정리한다. 다만 repair는 신중히 사용해야 한다.

실무 적용 예시

프로젝트 초기에는 작은 변경을 자주 커밋하는 방식이 안정적이다. 마이그레이션 파일을 기능별로 분리하면 롤백과 추적이 쉬워진다. 또한 데이터 마이그레이션(데이터 변환)과 스키마 마이그레이션을 명확히 구분하는 것이 바람직하다.

마무리

Spring Boot와 Flyway를 함께 사용하면 데이터베이스 버전 관리를 자동화할 수 있다. 설정은 단순하지만 운영과 확장에는 설계가 필요하다. 이상적으로는 CI 환경에 통합해 일관된 배포를 확보한다. 본문에서 소개한 설정과 절차를 통해 database migration spring boot flyway 환경을 안정적으로 구성할 수 있다.