DB 네이밍 및 Flyway 마이그레이션 컨벤션

프론트엔드와 백엔드 간의 명확한 데이터 소통, 그리고 운영 DB의 안정적인 관리를 위해 데이터베이스 명명 규칙과 마이그레이션 스크립트 작성 기준을 엄격하게 통제합니다.

1. 기본 네이밍 규칙 (General Naming Rules)

표기법: 모든 DB 객체(테이블, 컬럼, 제약조건 등)는 소문자 스네이크 케이스(snake_case)를 사용합니다.
테이블명: 반드시 단수형 명사를 사용합니다. (❌ members / ✅ member)
데이터 타입 (PostgreSQL 기준):
- PK는 BIGINT GENERATED BY DEFAULT AS IDENTITY를 기본으로 사용합니다.
- 복잡한 구조화 데이터는 JSONB 타입을 적극 활용합니다. (예: usage_monthly의 상세 사용량)
공통 컬럼 (Audit): 모든 엔티티 테이블에는 생성일시와 수정일시를 필수로 포함합니다.
- created_at TIMESTAMP NOT NULL DEFAULT NOW()
- updated_at TIMESTAMP NOT NULL DEFAULT NOW()
논리적 삭제 및 상태값:
- Boolean 타입 컬럼은 is_ 또는 has_ 접두사를 피하고 상태 자체를 나타내는 단어(예: status, is_used 대신 사용처에 맞게)를 쓰거나, 가급적 명확한 ENUM 타입을 사용합니다.
- ENUM 타입 정의 시 {테이블명}_{컬럼명}_type 또는 enum 접미사를 붙입니다. (예: member_status_type, product_type_enum)

2. 제약조건 및 인덱스 명명 규칙 (Constraints & Index)

JPA(Hibernate)가 무작위로 생성하는 해시값 이름(예: FK_a1b2c3...)을 방지하고, 에러 로그 발생 시 어떤 제약조건에서 터졌는지 즉각적으로 파악하기 위해 아래의 접두사 규칙을 무조건 준수합니다.

종류	Prefix	네이밍 규칙 (Format)	적용 예시
Primary Key	`pk_`	`pk_{테이블명}`	`pk_member`
Unique Key	`uk_`	`uk_{테이블명}_{컬럼명}`	`uk_member_email`
Foreign Key	`fk_`	`fk_{현재테이블}_to_{대상테이블}`	`fk_subscription_to_member`
Index	`idx_`	`idx_{테이블명}_{주요컬럼명}`	`idx_subscription_member_id`
Check	`ck_`	`ck_{테이블명}_{목적}`	`ck_auth_method`

3. Flyway 마이그레이션 스크립트 작성 가이드

DB 형상 관리는 Flyway를 통해 수행합니다. “JPA가 자동으로 생성해주는 DDL을 우리가 직접 통제하고 작성한다”는 마인드로 작업해 주세요.

📍 파일 생성 경로 및 포맷

경로: src/main/resources/db/migration
파일 명명 규칙: {Prefix}{Version}__{Description}.sql
- Prefix: 대문자 V 필수
- Version: 숫자와 점(.)으로 관리 또는 날짜 기반 (예: V1.1, V20260324_1)
- Separator: 언더바 2개(__) 필수! (Flyway 파싱 기준)
- Description: 작업 내용 요약 (공백이나 언더바 사용 가능)
올바른 파일명 예시:
- V1__init_table.sql
- V20260324_1__add_subscription_index.sql

📍 DDL 일괄 작성 순서 (Order of Execution)

스크립트 가독성과 참조 무결성 충돌(테이블이 없는데 FK를 맺으려는 현상)을 방지하기 위해 파일 내 쿼리 작성 순서를 통일합니다.

ENUM 타입 정의 (CREATE TYPE ... AS ENUM)
Table 본문 생성 (기본 컬럼 및 CONSTRAINT pk_... PRIMARY KEY 포함)
Unique Key (UK) 제약조건 추가 (ALTER TABLE ... ADD CONSTRAINT uk_...)
Foreign Key (FK) 제약조건 추가 (ALTER TABLE ... ADD CONSTRAINT fk_...)
Index 생성 (CREATE INDEX ...) - 가장 마지막에 배치

⚠️ DDL 작성 시 주의사항 (Idempotency)

여러 환경(Local, Dev, Prod)에서 마이그레이션 스크립트가 여러 번 실행되거나 핫픽스와 겹치더라도 에러가 나지 않도록(멱등성 유지), 객체 생성 시 반드시 IF NOT EXISTS 구문을 포함해야 합니다. (단, PostgreSQL에서 테이블 생성 시 제외하고 제약조건이나 인덱스에 주로 활용)

작성 예시 (V1__init_member.sql):

SQL

-- 1. Table & PK
CREATE TABLE IF NOT EXISTS member (
    member_id       BIGINT GENERATED BY DEFAULT AS IDENTITY,
    email           VARCHAR(100) NOT NULL,
    created_at      TIMESTAMP NOT NULL DEFAULT NOW(),
    CONSTRAINT pk_member PRIMARY KEY (member_id)
);

-- 2. UK
ALTER TABLE member 
    ADD CONSTRAINT uk_member_email UNIQUE (email);

-- 3. FK (address 테이블이 먼저 생성되어 있어야 함)
ALTER TABLE member 
    ADD CONSTRAINT fk_member_to_address 
        FOREIGN KEY (address_id) REFERENCES address (address_id);

-- 4. Index (가장 마지막)
CREATE INDEX IF NOT EXISTS idx_member_email ON member (email);