ddl-auto=update에서 Flyway로: 개발·운영 DB 스키마 불일치를 정리하고 안전하게 전환하기

spring:
  jpa:
    hibernate:
      ddl-auto: update

엔티티에 필드 추가
→ 애플리케이션 실행
→ Hibernate가 컬럼 추가

어떤 SQL이 실행되었는가
언제 실행되었는가
어느 서버까지 적용되었는가
환경별로 같은 순서로 실행되었는가

개발·운영 DB 스키마 비교
→ 데이터 백업 및 복구 리허설
→ 기존 스키마 정합화
→ 운영 DB 기준 V1 baseline 작성
→ V2·V3 migration 작성
→ Flyway 도입
→ Hibernate ddl-auto=validate 전환
→ 개발 서버 최초 배포 및 검증

애플리케이션 시작
  ↓
Hibernate가 엔티티와 DB 비교
  ↓
필요하다고 판단한 DDL 실행
  ↓
애플리케이션 시작

@Column(name = "evaluation_data_deleted_at")
private LocalDateTime evaluationDataDeletedAt;

개발 DB: evaluation_data_deleted_at 존재
운영 DB: evaluation_data_deleted_at 없음

의도된 차이인가?
운영 배포가 누락된 것인가?
삭제된 엔티티 필드의 잔존 컬럼인가?
누군가 DB 콘솔에서 직접 변경한 것인가?

로컬 PC
  ↓ localhost 포트
AWS SSM Session
  ↓
EC2 또는 사설 DB
  ↓
MariaDB 3306

mariadb-dump \
  --host=host.docker.internal \
  --port=<포워딩 포트> \
  --user=<DB 사용자> \
  --password \
  --no-data \
  --skip-triggers \
  --skip-comments \
  --skip-dump-date \
  --skip-add-drop-table \
  --skip-lock-tables \
  <DB 이름>

schema-compare/
├─ production/
│  └─ schema.sql
└─ development/
   └─ schema.sql

Get-Item .\production\schema.sql
Get-FileHash .\production\schema.sql -Algorithm SHA256

git diff --no-index -- .\production\schema.sql .\development\schema.sql

운영 DB 정의가 올바른 항목
→ 개발 DB를 운영 기준으로 정합화
 
현재 코드에 필요하지만 운영에 아직 없는 항목
→ 새로운 migration으로 운영까지 전달
 
코드에서 제거됐지만 DB에 남은 항목
→ 새로운 migration으로 제거
 
AUTO_INCREMENT 현재값과 같은 데이터 상태 차이
→ 스키마 불일치에서 제외

SELECT s3_key, COUNT(*) AS duplicate_count
FROM application_files
GROUP BY s3_key
HAVING COUNT(*) > 1;

중복 데이터 존재
→ UNIQUE 제약조건 추가 시도
→ Duplicate entry 오류

SELECT s3_key, COUNT(*)
FROM application_files
GROUP BY s3_key
HAVING COUNT(*) > 1;

ALTER TABLE application_files
    ADD CONSTRAINT UKq8pqe7k4n85n3faa6b7a14354
    UNIQUE (s3_key);

변경 전 데이터가 새 제약조건을 만족하는가?
NULL 데이터가 타입 변경을 방해하지 않는가?
기존 데이터 길이가 새 타입에 들어가는가?
외래 키 관계에 영향을 주지 않는가?

dev-ssuport-full.sql

개발 DB 전체 dump
  ↓
로컬 MariaDB 10.11 복원
  ↓
테이블·외래 키·데이터 확인
  ↓
ALTER TABLE 실행
  ↓
스키마 재덤프
  ↓
운영 스키마와 다시 비교

복구 종료 코드: 0
애플리케이션 테이블: 18개
외래 키: 19개

s3_key 중복 여부
terms.content NULL 여부
scholarship_cycles의 기존 값 존재 여부

백업 파일이 실제로 복구되는가?
복구된 데이터에서 DDL이 성공하는가?
변경 후 목표 스키마와 일치하는가?

기존 DB에 테이블 존재
→ V1 CREATE TABLE 실행
→ Table already exists 오류

기존 DB
→ V1을 이미 적용된 버전으로 등록
→ V2부터 실제 실행
 
새로운 빈 DB
→ V1부터 실제 실행
→ V2, V3 순서대로 실행

src/main/resources/db/migration/V1__baseline_schema.sql

dump session 설정문
현재 AUTO_INCREMENT 카운터
dump 생성 시각 및 주석
DROP TABLE 문

SET FOREIGN_KEY_CHECKS = 0;
 
-- CREATE TABLE ...
 
SET FOREIGN_KEY_CHECKS = 1;

ALTER TABLE scholarship_cycles
    ADD COLUMN IF NOT EXISTS evaluation_data_deleted_at
    TIMESTAMP(6) NULL DEFAULT NULL;
 
ALTER TABLE scholarship_cycles
    DROP COLUMN IF EXISTS review_phase;

V2__update_scholarship_cycles.sql

ALTER TABLE post
    MODIFY COLUMN content LONGTEXT NOT NULL;

V3__post_content_type.sql

implementation 'org.flywaydb:flyway-core'
implementation 'org.flywaydb:flyway-mysql'

spring:
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        format_sql: true
    open-in-view: false
 
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-version: 1
    baseline-on-migrate: ${FLYWAY_BASELINE_ON_MIGRATE:false}
    validate-on-migrate: true
    out-of-order: false
    clean-disabled: true

Flyway
→ 아직 적용되지 않은 migration 실행
 
Hibernate validate
→ migration 적용 결과와 엔티티가 일치하는지 검사

이 DB는 이미 V1 상태라고 간주한다

빈 MariaDB
→ V1 실행
→ V2 실행
→ Hibernate validate
→ 애플리케이션 기동

@Lob
@Column(
    name = "content",
    nullable = false,
    columnDefinition = "LONGTEXT"
)
private String content;

Flyway migration 검증 성공
현재 스키마 버전 확인
Hibernate EntityManagerFactory 초기화
Tomcat 실행
Spring Boot 애플리케이션 기동

baseline-on-migrate: true

기존 개발 DB 확인
→ V1을 BASELINE으로 등록
→ V2 실행
→ Hibernate validate

1 | 1 | << Flyway Baseline >>       | BASELINE | 성공
2 | 2 | update scholarship cycles   | SQL      | 성공

Schema-validation:
wrong column type encountered in column [content] in table [post]
found [tinytext]
expecting [longtext]

V3 post content type 적용 성공
Hibernate ddl-auto=validate 통과
JPA EntityManagerFactory 초기화 성공
Tomcat 8080 기동 성공
애플리케이션 정상 시작

1 | 1 | << Flyway Baseline >>       | BASELINE | 1
2 | 2 | update scholarship cycles   | SQL      | 1
3 | 3 | post content type           | SQL      | 1

baseline-on-migrate: false

잘못된 DB 주소 설정
또는 flyway_schema_history가 없는 다른 스키마 연결
  ↓
baseline-on-migrate=true
  ↓
해당 DB를 V1 상태로 자동 등록할 가능성

true
→ 기존 DB 최초 등록을 위한 일회성 옵션
 
false
→ 등록 완료 후 유지하는 안전한 기본값

baseline-on-migrate: ${FLYWAY_BASELINE_ON_MIGRATE:false}

FLYWAY_BASELINE_ON_MIGRATE 미설정
→ 기본값 false
→ V1, V2, V3 실제 실행
→ Hibernate validate

FLYWAY_BASELINE_ON_MIGRATE=true

V1 baseline 등록
→ V2, V3 실행
→ Hibernate validate

로컬 DB: TINYTEXT NOT NULL
엔티티·V1: LONGTEXT NOT NULL

SELECT COUNT(*)
FROM terms
WHERE content IS NULL;
 
ALTER TABLE terms
    MODIFY COLUMN content LONGTEXT NOT NULL;

엔티티 수정
→ develop 배포
→ Hibernate가 개발 DB 자동 변경
→ main 배포
→ Hibernate가 운영 DB 자동 변경
→ 실제로 어떤 DDL이 실행됐는지 이력 없음

엔티티 수정
+ 새로운 migration 작성
→ 같은 PR에서 검토
→ 빈 로컬 DB migration 검증
→ 기존 데이터가 있는 DB 검증
→ 개발 서버 배포
→ flyway_schema_history 확인
→ Hibernate validate 확인
→ 동일한 커밋을 운영 배포
→ 운영 migration 이력과 서비스 상태 확인

로컬: V1 → V2 → V3 → V4 ...
개발: V1 → V2 → V3 → V4 ...
운영: V1 → V2 → V3 → V4 ...

잘못된 SQL을 작성하면
→ 잘못된 SQL도 정확한 순서로 실행됨

변경 전 데이터 사전 조건 확인
백업 및 복구 리허설
빈 DB 전체 migration 실행
기존 데이터 DB에서 신규 migration 실행
Hibernate validate
개발 서버 선배포

스키마 dump
→ diff
→ 불일치 분류
→ 데이터 사전 조건 확인
→ 백업 복구 리허설
→ 정합화

V1: 운영 DB 기준 초기 스키마
V2: scholarship_cycles 변경
V3: post.content 타입 정합화

기존:
Hibernate가 DB 구조를 자동으로 변경
 
개선:
Flyway가 명시된 변경만 실행
+ Hibernate가 결과를 검증

스키마 변경을 코드처럼 버전 관리하고
동일한 변경을 모든 환경에 같은 순서로 적용하며
누가 보더라도 DB가 현재 상태에 도달한 과정을 확인할 수 있게 하는 것