데이터베이스

dictionary-api가 사용하는 데이터베이스 구성과 Flyway 마이그레이션 정책입니다.

프로파일별 DB

local

MySQL — 개발자 개인 MySQL 서버, log4jdbc로 SQL 로깅

test

H2(in-memory, MODE=MySQL) — 매번 새로 마이그레이션됨

prod

H2(in-memory) — 무료 호스팅 데모 배포용

docker

MySQL(컨테이너) — docker-compose가 매번 새로 만드는 MySQL

마이그레이션 디렉토리 구조

src/main/resources/db/migration/
├── mysql/         # local 프로파일
│   ├── ddl/        # V1_01_x — 테이블 생성
│   └── data/        # V1_02_x — 테스트/초기 데이터
└── h2/            # test/prod 프로파일
    ├── ddl/
    └── data/

mysql과 h2 두 디렉토리는 파일명(버전)을 동일하게 맞추고 문법만 DB에 맞게 변환한다.
- ENGINE=InnoDB ... 절 제거
- ALTER TABLE ... COMMENT = '...' → COMMENT ON TABLE ... IS '...'
- ALTER TABLE ... AUTO_INCREMENT = N → ALTER TABLE ... ALTER COLUMN <pk> RESTART WITH N
버전 번호는 ddl(V1_01_x)과 data(V1_02_x) 계열을 각각 독립적으로 순서대로 채번한다.
테이블/컬럼을 새로 추가할 때는 mysql·h2 양쪽 ddl/data를 함께 추가하고, h2/ddl/V1_01_001__drop_tables.sql(공용 DROP 목록)에도 반영한다.

마이그레이션 수정 규칙

이미 로컬 MySQL에 적용된 마이그레이션 파일도 자유롭게 수정한다 — 체크섬 유지를 위해 새 버전 파일을 추가하는 일반적인 방식을 따르지 않는다.
파일을 수정한 뒤(또는 outOfOrder 오류가 났을 때) 로컬 MySQL의 flyway_schema_history 메타테이블을 삭제하고 애플리케이션을 재기동하면 Flyway가 처음부터 다시 생성한다.
테스트는 항상 test 프로파일(H2, in-memory)로 실행되므로 이 이슈와 무관하다 — local 프로파일로 로컬 MySQL을 기동할 때만 나타난다.

컬럼 컨벤션

Y/N 플래그 컬럼(use_yn, admin_yn, lock_yn, guest_yn 등)은 VARCHAR(1)이 아니라 **CHAR(1)**을 쓴다 — 값 길이가 항상 고정이라는 의미를 컬럼 타입에 드러내기 위함이다.
등록/수정 감사 컬럼(create_dt, create_user_id, create_ip, update_dt, update_user_id, update_ip)은 JPA AbstractEntity(@MappedSuperclass)가 @PrePersist/@PreUpdate로 자동 세팅한다. 새 엔티티는 이 클래스를 상속한다.

세션 스키마

spring-session-jdbc가 쓰는 SPRING_SESSION/SPRING_SESSION_ATTRIBUTES 테이블도 위와 동일하게 Flyway로 관리한다(spring.session.jdbc.initialize-schema: never로 Spring Session 자체 자동 생성은 꺼둔다).

자세한 내용은 dictionary-api 저장소의 .claude/CLAUDE.md/README.md를 참고한다.