-
Notifications
You must be signed in to change notification settings - Fork 1
ADR 0005 External Flyway Migrations
SANGMIN PARK edited this page Jul 17, 2026
·
1 revision
- 상태: Accepted
- 결정일: 2026-06-01
- 마지막 검증: 2026-07-18
로컬의 Hibernate ddl-auto=update는 개발 편의에는 유용하지만 실행 시점과 순서가 보장된 운영 스키마 이력이 아닙니다. Lambda가 시작될 때마다 마이그레이션을 실행하면 동시 콜드 스타트, DB Lock, 권한 확대로 인해 애플리케이션 기동이 불안정해질 수 있습니다.
이미 데이터가 있는 dev·prod DB를 Flyway에 편입할 때 자동 baseline을 허용하면 잘못된 DB도 정상 준비된 것으로 기록될 수 있습니다.
- dev·prod DDL의 기준은
src/main/resources/db/migration의 순차 Flyway SQL입니다. - 이미 적용된 마이그레이션은 수정하지 않고 다음 Version의 새 파일로 보정합니다.
- Spring Boot 내부 Flyway 실행은 모든 런타임 프로필에서 비활성화합니다.
- dev·prod는 Hibernate
ddl-auto=validate로 코드와 적용된 스키마의 불일치만 검사합니다. - GitHub Actions의 별도 마이그레이션 Job이 Flyway
info와migrate를 실행하며 같은 환경의 실행을 직렬화합니다. - Lambda 배포는 마이그레이션 성공 후에만 테스트와 코드 게시를 진행합니다.
- 기존 비어 있지 않은 DB의 최초 baseline은 운영자가 한 번만 명시적으로 수행하며
baseline-on-migrate는 사용하지 않습니다.
변경은 빠르지만 실행 결과와 순서가 명시적인 파일로 남지 않습니다. 삭제, 제약 조건, 데이터 보정과 롤백 호환성을 검토하기도 어렵습니다.
별도 워크플로가 필요 없지만 Lambda 인스턴스가 동시에 시작될 수 있고 API 런타임에 DDL 권한이 필요합니다. 마이그레이션 실패가 전체 콜드 스타트 실패로 이어집니다.
긴급 대응에는 사용할 수 있지만 실행 이력, 환경별 일관성, 재현 가능한 테스트가 부족합니다. 정상 변경 경로로 사용하지 않습니다.
- 스키마 변경 순서와 적용 이력을 코드 리뷰와
flyway_schema_history에서 확인할 수 있습니다. - API Lambda는 DDL 권한 없이 실행할 수 있고 마이그레이션 실패가 코드 게시 전에 드러납니다.
- 환경별 마이그레이션을 직렬화해 같은 DB의 동시 DDL 실행을 줄입니다.
- 새 DB에 전체 마이그레이션을 적용하는 테스트로 누락과 순서 문제를 검증할 수 있습니다.
- 배포 전에 DB 자격 증명과 Docker 기반 Flyway 워크플로가 정상이어야 합니다.
- 마이그레이션 적용 후 코드 배포가 실패하면 DB만 새 상태가 될 수 있습니다.
- Alias 코드 롤백이 DB 마이그레이션을 되돌리지 않으므로 하위 호환 가능한 DDL이 필요합니다.
- local
ddl-auto=update에서만 성공한 변경을 dev·prod 완료로 판단할 수 없습니다.
- 엔티티, 컬럼, 테이블, 인덱스, 제약 조건 변경에는 새 마이그레이션 SQL을 추가합니다.
- prod 마이그레이션 전 백업과 이전 코드의 새 스키마 호환성을 확인합니다.
- checksum mismatch가 발생하면 적용된 파일을 임의 수정하거나
repair부터 실행하지 않습니다. -
./gradlew test --tests 'com.chukchuk.haksa.global.db.FlywayMigrationTest'와 전체 테스트를 실행합니다.
- 별도 배포 오케스트레이터가 마이그레이션과 애플리케이션 배포를 하나의 검증 가능한 릴리스로 관리합니다.
- 무중단 배포를 위해 expand-contract 마이그레이션 정책을 자동 검사해야 합니다.
- DB가 여러 스키마나 서비스로 분리돼 현재 단일 마이그레이션 경로로 관리할 수 없습니다.