Flyway 실전 도입기 1편: 로컬 DB 초기화 및 V1 스키마 생성하기

1. 서론: 본격적인 Flyway 도입의 첫걸음

지난번 포스팅인 'Flyway 도입 딜레마! 테스트 환경 H2와 PostgreSQL 충돌 해결 과정'에서는 테스트 환경의 H2 데이터베이스와 운영 환경의 PostgreSQL 사이에서 발생하는 스크립트 충돌 문제를 다루었습니다.

2026.05.20 - [기술 스택] - Flyway 도입 딜레마! 테스트 환경 H2와 PostgreSQL 충돌 해결 과정

Flyway 도입 딜레마! 테스트 환경 H2와 PostgreSQL 충돌 해결 과정

 

오늘부터 진행할 전체 작업의 순서는 다음과 같습니다.

1. 로컬 DB 부팅 및 앱 실행 (현재 ddl-auto: update 활용) ← 오늘 다룰 내용
2. pg_dump로 순수 스키마 SQL 추출하기
3. 하이버네이트가 만든 스키마의 5가지 문제점과 V1 스크립트 완벽 정제
4. Spring Boot 연동부터 마이그레이션 검증까지 완벽 가이드

이번 포스팅에서는 그 첫 번째 단계로, 기존 DB를 깨끗하게 비우고 하이버네이트(Hibernate)의 자동 생성 기능을 이용해 베이스가 될 V1 스키마를 로컬 DB에 만들어내는 과정을 차근차근 따라가 보겠습니다.

2. 실행 전 필수 점검 사항

현재 저희 프로젝트의 데이터베이스는 도커(Docker) 컨테이너로 관리되고 있습니다. 컨테이너명은 toktot-db, DB명과 유저는 toktot, 포트는 5432를 사용합니다.

본격적인 컨테이너 구동에 앞서 반드시 확인해야 할 두 가지가 있습니다.

첫째, 환경 변수 파일(.env) 확인 프로젝트 디렉토리 내에 .env 파일이 존재하는지, 그리고 POSTGRES_PASSWORD 값이 제대로 설정되어 있는지 확인해야 합니다. 이 환경 변수가 누락되어 있으면 도커 컴포즈가 정상적으로 실행되지 않습니다.

둘째, 기존 로컬 데이터 볼륨 초기화 여부 현재 postgres_local_data라는 이름의 볼륨에 이전 데이터가 남아있을 수 있습니다. 기존에 생성된 테이블이나 더미 데이터가 섞여 있으면, 깔끔한 V1 스키마를 추출하기 어렵습니다. 지금은 운영 환경이 아닌 학습 및 초기 세팅 목적이므로, 과거의 데이터를 미련 없이 날리고 완벽한 빈 깡통 상태에서 시작하는 것을 권장합니다.

3. 로컬 DB 완전 초기화 및 부팅

이제 터미널을 열고 toktot-server 디렉토리로 이동한 뒤, 아래의 명령어를 순서대로 실행해 보겠습니다.

# 1. 기존 컨테이너 중지 및 관련 볼륨(-v)까지 완전 삭제
docker compose down -v

# 2. PostgreSQL과 Redis 컨테이너만 백그라운드(-d)로 실행
docker compose up -d postgres redis

명령어에 포함된 -v 플래그는 기존에 마운트되어 있던 볼륨까지 확실하게 삭제해 줍니다. 데이터 손실이 걱정될 수 있지만, 로컬 개발 환경이므로 안심하고 지우셔도 됩니다.

컨테이너를 띄웠다면 데이터베이스가 정상적으로 부팅되어 연결 가능한 상태가 되었는지 확인해야 합니다.

docker compose ps

출력되는 목록 중 toktot-db의 상태(STATUS) 항목이 반드시 Up (healthy)로 표시되어야 합니다. 만약 unhealthy 상태이거나 Exited로 나온다면 .env 파일의 비밀번호 설정이나 포트 충돌 여부를 다시 점검해야 합니다.

4. 스프링 부트 앱 실행과 스키마 자동 생성

데이터베이스가 건강한 상태(healthy)로 준비되었다면, 이제 통합 개발 환경(IDE, IntelliJ 등)으로 이동하여 스프링 부트 애플리케이션을 부팅할 차례입니다.

이때 실행 프로필(Profile)이 local로 잘 활성화되어 있는지 확인해 주세요. 현재 저희 프로젝트의 application-local.yml 설정은 ddl-auto: update로 지정되어 있습니다.

앱을 실행(ToktotApplication)하고 콘솔 로그를 유심히 살펴보면, 다음과 같은 재미있는 현상을 볼 수 있습니다.

Hibernate: create table ...
Hibernate: create table ...
... (약 23개의 테이블 생성 쿼리)

텅 비어있던 PostgreSQL 데이터베이스에 하이버네이트가 엔티티(Entity) 클래스들을 스캔하여 23개 남짓한 테이블을 자동으로 촤르륵 생성해 냅니다. 우리는 이 자동 생성된 깨끗한 스키마를 Flyway의 첫 번째 기준점인 V1 버전으로 삼을 계획입니다.

5. 부팅 성공 및 에러 검증

로그가 멈추고 서버가 완전히 올라갔다면, 다음 두 가지를 최종적으로 점검해 주세요.

1. 애플리케이션 부팅 성공 여부: 콘솔 마지막 즈음에 Started ToktotApplication in X seconds 라는 로그가 무사히 찍혔는지 확인합니다.
2. Hibernate DDL 에러 여부: 스크롤을 살짝 올려서, 하이버네이트가 테이블이나 제약조건(FK 등)을 만들면서 발생시킨 SQL Syntax 에러나 경고 로그가 없는지 꼼꼼히 확인합니다.

6. 마치며: 다음 단계를 향하여

여기까지 무사히 따라오셨다면, 여러분의 로컬 도커 DB에는 23개의 테이블이 깔끔하게 세팅된 상태일 것입니다. ddl-auto 기능이 만들어준 이 스키마는 훌륭한 초안이 됩니다.

하지만 이 스키마를 그대로 Flyway 스크립트로 쓸 수는 없습니다. 불필요한 사용자 권한 정보가 섞여 있을 수도 있고, 컬럼의 타입이나 인덱스, 외래 키(FK) 이름 등이 우리가 원하는 명명 규칙과 다를 수 있기 때문입니다.

다음 포스팅에서는 이 23개의 테이블 구조를 pg_dump 명령어를 활용하여 순수 SQL 파일로 추출하고, 실무 기준에 맞게 정제하여 완벽한 V1__init.sql 스크립트를 완성하는 과정을 알아보겠습니다.