Spring Boot 3.3.0 업그레이드 후 Flyway 'Unsupported Database: PostgreSQL 16' 에러 해결하기
Problem
Spring Boot 프로젝트를 3.2.x 버전에서 3.3.0으로 업그레이드한 후, 애플리케이션을 실행할 때 데이터베이스 마이그레이션 도구인 Flyway가 작동하지 않는 문제가 발생할 수 있습니다. 특히 PostgreSQL 16 버전을 사용할 때 org.flywaydb.core.api.FlywayException: Unsupported Database: PostgreSQL 16.2라는 에러 메시지와 함께 애플리케이션 컨텍스트 로드가 중단됩니다. 이는 데이터베이스 연결 정보가 올바름에도 불구하고 Flyway가 해당 DB 버전을 인식하지 못해 발생하는 전형적인 호환성 문제입니다.
Background
이 문제의 근본적인 원인은 Spring Boot 3.3.0에서 채택한 Flyway의 메이저 버전 업데이트(Flyway 10.x)와 관련이 있습니다. 이전 버전의 Flyway는 flyway-core 라이브러리 내부에 주요 데이터베이스(PostgreSQL, MySQL, Oracle 등)에 대한 지원 코드를 모두 포함하고 있었습니다. 하지만 Flyway 측에서 코어 라이브러리를 경량화하고 유지보수성을 높이기 위해, 각 데이터베이스에 대한 지원 모듈을 별도의 의존성으로 분리하는 아키텍처 변경을 단행했습니다. 따라서 Spring Boot 버전을 올리면서 내부적으로 Flyway 버전이 10.x로 올라갔고, 기존처럼 flyway-core만으로는 PostgreSQL을 인식할 수 없게 된 것입니다.
Solution
이 문제를 해결하려면 분리된 PostgreSQL 전용 Flyway 모듈을 프로젝트의 의존성에 명시적으로 추가해야 합니다. 사용하는 빌드 도구에 따라 아래의 설정을 적용하세요.
1. Maven을 사용하는 경우 (pom.xml)
pom.xml 파일의 <dependencies> 블록에 flyway-database-postgresql 의존성을 추가합니다. Spring Boot의 의존성 관리(Dependency Management)가 버전을 자동으로 맞춰주므로 버전 명시는 생략해도 무방합니다.
<dependencies>
<!-- 기존 flyway-core 의존성 (Spring Boot 스타터에 포함되어 있다면 생략 가능) -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-core</artifactId>
</dependency>
<!-- 추가해야 할 PostgreSQL 전용 Flyway 모듈 -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
</dependency>
</dependencies>
2. Gradle을 사용하는 경우 (build.gradle)
Gradle 환경에서는 build.gradle 파일의 dependencies 블록에 아래와 같이 추가합니다.
dependencies {
// 기존 flyway 의존성
implementation 'org.flywaydb:flyway-core'
// PostgreSQL 16 등을 지원하기 위한 전용 데이터베이스 모듈 추가
implementation 'org.flywaydb:flyway-database-postgresql'
}
3. application.yml 설정 확인
의존성을 추가한 후, Flyway가 정상적으로 작동할 수 있도록 application.yml (또는 application.properties) 설정이 올바른지 확인합니다.
spring:
flyway:
enabled: true
# 마이그레이션 스크립트가 위치한 경로 (기본값)
locations: classpath:db/migration
# 기존에 데이터가 있는 DB에 Flyway를 처음 적용할 때 필요한 옵션
baseline-on-migrate: true
위와 같이 의존성을 추가하고 프로젝트를 다시 빌드하면, Flyway가 PostgreSQL 16.2 버전을 정상적으로 인식하고 마이그레이션을 수행합니다.
Deep Dive
Flyway의 데이터베이스 모듈 분리는 프로젝트의 전체 크기를 줄이고 사용하지 않는 데이터베이스 드라이버 코드를 배제할 수 있다는 장점이 있습니다. 하지만 마이그레이션 시 다중 데이터베이스를 사용하는 환경이라면 각각의 전용 모듈(flyway-database-mysql 등)을 모두 추가해야 함을 잊지 말아야 합니다. 프로덕션 환경에서는 메이저 버전 업그레이드 전, Flyway 공식 문서의 데이터베이스 호환성 매트릭스를 확인하여 현재 사용 중인 DB 버전이 지원되는지 검토하는 것이 안전합니다. 또한 baseline-on-migrate: true 옵션은 초기 도입 시에는 유용하지만, 이미 Flyway 히스토리 테이블(flyway_schema_history)이 존재하는 운영 환경에서는 예기치 않은 동작을 방지하기 위해 false로 유지하는 것이 권장되는 베스트 프랙티스입니다.
Conclusion
Spring Boot 3.3.0으로 업그레이드 시 발생하는 Flyway의 PostgreSQL 인식 불가 에러는 Flyway 10.x의 아키텍처 변경으로 인한 정상적인 현상이며, flyway-database-postgresql 의존성을 추가하여 간단히 해결할 수 있습니다. 프레임워크나 라이브러리의 메이저 버전이 올라갈 때는 릴리스 노트를 통해 의존성 분리나 구조 변경 사항이 있는지 미리 확인하는 습관을 들이는 것이 좋습니다.