Spring Boot Flyway에서 PostgreSQL 17 'Unsupported Database' 에러 해결 방법
Problem
Spring Boot 프로젝트에서 Flyway를 사용하여 PostgreSQL 17.0 (또는 16 등 최신 버전)으로 데이터베이스 마이그레이션을 시도할 때 Unsupported Database 에러가 발생하는 경우가 있습니다. 개발자는 문제를 해결하기 위해 flyway-core 의존성의 버전을 최신(예: 10.20.1)으로 올려보지만, 여전히 동일한 에러 메시지가 출력되며 애플리케이션이 실행되지 않습니다. 이는 데이터베이스 버전이 올라가면서 Flyway 설정 방식에 변경이 생겼다는 사실을 인지하지 못했을 때 흔히 겪는 시나리오입니다.
Background
Flyway는 버전 10.x로 메이저 업데이트가 되면서 아키텍처에 큰 변화가 있었습니다. 이전 버전(Flyway 9 이하)에서는 flyway-core 라이브러리 하나에 PostgreSQL, MySQL, Oracle 등 주요 데이터베이스를 지원하는 코드가 모두 포함되어 있었습니다. 하지만 Flyway 10부터는 코어 라이브러리를 경량화하고 유지보수성을 높이기 위해, 각 데이터베이스 지원 기능을 별도의 모듈로 분리했습니다. 따라서 flyway-core만 의존성에 추가하면 최신 버전의 데이터베이스를 인식하기 위한 코드가 없어 “Unsupported Database” 에러가 발생하게 되는 것입니다.
Solution
문제를 해결하려면 기존의 flyway-core 의존성 대신, 사용 중인 데이터베이스에 맞는 전용 의존성인 flyway-database-postgresql을 추가해야 합니다.
Gradle 환경에서 해결하기
build.gradle (또는 build.gradle.kts) 파일에서 의존성을 다음과 같이 수정합니다.
dependencies {
// 기존의 flyway-core는 제거하거나 주석 처리합니다.
// implementation("org.flywaydb:flyway-core")
// PostgreSQL 전용 Flyway 모듈을 추가합니다.
implementation("org.flywaydb:flyway-database-postgresql")
}
Maven 환경에서 해결하기
pom.xml 파일에서 기존 flyway-core를 찾아 아래와 같이 교체합니다.
<dependencies>
<!-- 기존 flyway-core 의존성을 아래 코드로 교체합니다 -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
<!-- Spring Boot를 사용 중이라면 버전은 의존성 관리에 의해 자동 지정되므로 생략 가능합니다 -->
</dependency>
</dependencies>
이렇게 데이터베이스 전용 모듈을 추가하면 내부적으로 flyway-core도 함께 가져오게 됩니다. 따라서 기존의 마이그레이션 기능은 그대로 사용할 수 있으며, 최신 PostgreSQL 버전까지 정상적으로 인식하여 마이그레이션 스크립트가 성공적으로 실행됩니다.
Deep Dive
Flyway의 이러한 모듈화 정책은 프로젝트의 빌드 크기를 줄이고, 특정 데이터베이스의 드라이버 업데이트가 필요할 때 해당 모듈만 독립적으로 패치할 수 있다는 장점을 제공합니다. 만약 PostgreSQL 외에 MySQL이나 SQL Server를 사용한다면, 각각 flyway-mysql, flyway-sqlserver와 같이 해당 DB에 맞는 모듈을 추가해야 합니다. 프로덕션 환경에 적용할 때는 Spring Boot의 버전에 따라 기본적으로 관리되는 Flyway의 버전이 다를 수 있으므로, Spring Boot 의존성 관리(Dependency Management)가 제공하는 버전을 사용하는 것이 호환성 측면에서 가장 안전합니다. 부득이하게 Flyway 버전만 강제로 올려야 한다면, Spring Boot의 flyway.version 프로퍼티를 오버라이드하여 버전을 명시적으로 맞춰주어야 예기치 않은 충돌을 예방할 수 있습니다.
Conclusion
Flyway 10.x 버전부터는 데이터베이스 지원이 개별 모듈로 분리되었기 때문에, flyway-core만으로는 최신 데이터베이스를 인식하지 못합니다. “Unsupported Database” 에러가 발생한다면, 사용 중인 데이터베이스에 맞는 전용 모듈(flyway-database-postgresql 등)이 의존성에 올바르게 추가되어 있는지 가장 먼저 확인해 보시기 바랍니다.