Repository navigation
DB Migration
wcorn edited this page Apr 5, 2026
·
1 revision
Liquibase를 사용한 스키마 버전 관리 및 배포 전략.
| 환경 | DDL 관리 방식 | 이유 |
|---|---|---|
| prod | Liquibase | 변경 이력·롤백·재현성 보장 |
| local | Hibernate ddl-auto: update
|
빠른 프로토타이핑, 개발 생산성 |
| test | Hibernate ddl-auto: create-drop
|
테스트 격리 (TestContainers) |
prod만 Liquibase로 엄격 관리. 로컬 개발 편의성을 위해 개발 단계는 Hibernate 자동 관리.
be/orino-app-api/src/main/resources/db/changelog/
├── db.changelog-master.yaml # 마스터 (include 순서 관리)
└── changes/
├── 001-create-member.yaml
├── 002-create-category.yaml
├── ...
└── 014-create-indexes.yaml
파일명 규칙: {순번 3자리}-{동작}-{대상}.yaml
- 순번: 단조 증가 3자리
- 동작:
create,add,alter,drop,rename - 대상: 테이블·컬럼·인덱스명
databaseChangeLog:
- changeSet:
id: 001-1
author: wcorn
changes:
- createTable:
tableName: member
columns:
- column: {name: id, type: BIGINT, autoIncrement: true, constraints: {primaryKey: true}}
- column: {name: login_id, type: VARCHAR(50), constraints: {nullable: false, unique: true}}- 한 파일당 여러 changeSet:
001-1,001-2… - 파일 순번과 일치시켜 추적 용이
- 모두
wcorn통일
-
이미 배포된 changeSet 수정 금지: Liquibase가
DATABASECHANGELOG테이블의 checksum으로 검증. 수정 시 배포 실패 - id 재사용 금지: 파일 삭제 후 동일 id 사용 불가
- include 순서 변경 금지: 마스터 파일의 include 순서가 실행 순서
새 엔티티 추가 시.
# changes/015-create-new-entity.yaml
databaseChangeLog:
- changeSet:
id: 015-1
author: wcorn
changes:
- createTable:
tableName: new_entity
columns:
- column: {name: id, type: BIGINT, autoIncrement: true, constraints: {primaryKey: true}}
- column: {name: member_id, type: BIGINT, constraints: {nullable: false}}
- column: {name: created_at, type: DATETIME, constraints: {nullable: false}}
- column: {name: updated_at, type: DATETIME, constraints: {nullable: false}}
- addForeignKeyConstraint:
baseTableName: new_entity
baseColumnNames: member_id
constraintName: fk_new_entity_member
referencedTableName: member
referencedColumnNames: id- changeSet:
id: 016-1
author: wcorn
changes:
- addColumn:
tableName: goal
columns:
- column: {name: expected_completion_date, type: DATE}기본값 있는 NOT NULL 컬럼 추가 (기존 데이터 존재 시):
- addColumn:
tableName: goal
columns:
- column:
name: pace_status
type: VARCHAR(20)
defaultValue: "ON_TRACK"
constraints: {nullable: false}기존 컬럼 타입 변경은 데이터 손실 위험. "확장 → 마이그레이션 → 축소" 3단계 분할:
- 확장: 새 컬럼 추가 (NULL 허용)
- 마이그레이션: 애플리케이션에서 양쪽 쓰기 → 기존 데이터 변환 → 읽기 전환
- 축소: 기존 컬럼 제거
한 릴리즈에 몰아 하지 않는다.
온라인 인덱스 추가 (MySQL 8+ 기본 지원).
- createIndex:
tableName: block
indexName: idx_block_date_member
columns:
- column: {name: block_date}
- column: {name: member_id}대용량 테이블은 생성 중 서비스 영향 측정.
스키마와 함께 필요한 초기 데이터.
- changeSet:
id: 017-1
author: wcorn
changes:
- insert:
tableName: priority_rule
columns:
- column: {name: rule_type, value: "OVERDUE_REVIEW"}
- column: {name: priority, valueNumeric: 1}복잡한 데이터 변환은 별도 배치 또는 관리 스크립트 권장.
코드 작성 → Liquibase changeSet 추가 → local에서 Entity 검증
│
▼
ddl-auto: validate가 prod에서 schema 일치 확인
│
▼
PR 머지 → CD → 새 BE 이미지 배포
│
▼
BE Pod 시작 시 Liquibase가 미적용 changeSet 실행
│
▼
DATABASECHANGELOG 테이블에 실행 이력 기록
주의: ddl-auto: validate이므로 Entity와 실제 스키마가 불일치하면 애플리케이션 시작 실패. Liquibase changeSet 없이 Entity만 변경하면 배포 실패한다.
Liquibase의 rollback 태그로 역방향 변경 정의 가능.
- changeSet:
id: 015-1
author: wcorn
changes:
- createTable: {...}
rollback:
- dropTable:
tableName: new_entity현실적 방침:
- 단순 변경 (createTable, addColumn): rollback 작성
- 복잡한 변경 (데이터 이관): rollback보다 forward fix(새 changeSet으로 복구)
- prod 긴급 롤백: 데이터 손실 시 백업 복원이 더 안전 (Backup-Recovery §5)
로컬은 ddl-auto: update로 Entity 변경이 자동 반영되지만, prod는 Liquibase changeSet이 있어야만 반영된다.
Entity 변경 시 체크리스트:
- Entity 클래스 수정
- 대응하는 Liquibase changeSet 추가 (
changes/하위) -
db.changelog-master.yaml에 include 추가 - 로컬에서
spring.liquibase.enabled=true로 임시 전환 → 실제 적용 확인 - 테스트 코드에서 Entity 변경 반영 확인
신규 환경 구축 시.
1. MySQL 빈 DB 생성 (DB명: orino)
2. BE 애플리케이션 실행
3. Liquibase가 모든 changeSet 순차 적용
4. DATABASECHANGELOG, DATABASECHANGELOGLOCK 테이블 자동 생성
- BE 코드 아키텍처
- 백업·복구 전략
- Study Planner 데이터 모델링 — 전체 ERD