1-1_DB-DDL-Flyway-마이그레이션

ID: key_26_22_05_25_P1_1_1 Created date: 5월 25 2026 월요일

연관 문서

개발 일정 > Phase 1 DB 설계 | DB (PostgreSQL)

개요

befw\ddl\cira에 이미 작성된 DDL 원본을 기반으로 Flyway 마이그레이션 파일을 생성한다.
마이그레이션 파일은 동일 경로의 migration\ 하위 폴더에서 중앙 관리한다.

예상 소요: 1~2일 (DDL 원본 존재로 단축)
선행 조건: P2_ORM-결정 완료, DB 연결 정보 확보
완료 기준: 서버 기동 시 Flyway 자동 적용 성공 + flyway_schema_history 레코드 확인

현재 DDL 구조

befw\ddl\cira\
  00_run_all.sql                      ← psql 전체 실행 유틸 (유지)
  01_users_and_permissions.sql        ← GS_ 테이블 원본
  02_projects_and_sprints.sql         ← SN_ 테이블 원본
  03_issues_and_workflow.sql
  04_issue_relations.sql
  05_comments_and_collaboration.sql
  06_kanban_board.sql
  07_custom_fields.sql                ← Phase 2~
  ...

테이블 Prefix 규칙

Prefix	소속	설명
`GS_`	`befw-lib-core`	전체 서비스 공용 (GS_USER, GS_ROLE 등)
`SN_CIRA_`	`befw-app-server` (CIRA)	CIRA 서비스 전용

GS_ 테이블은 befw-lib-core가 관리 주체이나, CIRA DB에도 동일하게 생성 필요.
Flyway에서 GS_ / SN_ 구분 없이 동일 migration 폴더에서 순서대로 실행.

Phase 1 마이그레이션 파일 매핑

마이그레이션 파일	원본 SQL	테이블
`V10__gs_users_and_permissions.sql`	`01_users_and_permissions.sql`	GS_USER, GS_ROLE, GS_USER_ROLE, GS_PERMISSION, GS_ROLE_PERMISSION, GS_GROUP, GS_GROUP_MEMBER
`V20__sn_projects_and_sprints.sql`	`02_projects_and_sprints.sql`	SN_CIRA_PROJECT, SN_CIRA_PROJECT_MEMBER, SN_CIRA_SPRINT, SN_CIRA_SPRINT_METRICS
`V30__sn_issues_and_workflow.sql`	`03_issues_and_workflow.sql`	SN_CIRA_ISSUE_TYPE, SN_CIRA_ISSUE_STATUS, SN_CIRA_ISSUE, SN_CIRA_ISSUE_TRANSITION, SN_CIRA_ISSUE_LOG, SN_CIRA_ISSUE_WATCHER
`V40__sn_issue_relations.sql`	`04_issue_relations.sql`	SN_CIRA_ISSUE_LINK, SN_CIRA_ISSUE_SUBTASK
`V50__sn_comments_and_collab.sql`	`05_comments_and_collaboration.sql`	SN_CIRA_COMMENT, SN_CIRA_COMMENT_REACTION, SN_CIRA_ATTACHMENT
`V60__sn_kanban_board.sql`	`06_kanban_board.sql`	SN_CIRA_BOARD, SN_CIRA_BOARD_COLUMN, SN_CIRA_ISSUE_POSITION

목표 폴더 구조

befw\ddl\cira\
  migration\                              ← Flyway가 읽는 폴더 (신규 생성)
    V10__gs_users_and_permissions.sql
    V20__sn_projects_and_sprints.sql
    V30__sn_issues_and_workflow.sql
    V40__sn_issue_relations.sql
    V50__sn_comments_and_collab.sql
    V60__sn_kanban_board.sql
  01_users_and_permissions.sql            ← 원본 (참조/유지)
  02_projects_and_sprints.sql
  ...
  00_run_all.sql                          ← psql 유틸 (유지)

Claude Code 작업 수행서

목표

기존 DDL 원본(01~06.sql)의 내용을 Flyway 마이그레이션 형식으로 변환하여
befw\ddl\cira\migration\ 폴더에 생성하고, befw-app-server가 이를 읽도록 설정한다.

작업 지시

befw\ddl\cira 의 기존 DDL 원본을 Flyway 마이그레이션 파일로 변환해줘.

[경로]
- DDL 원본: C:\workspace\tsh\boilerplate\be\befw\ddl\cira\
- 마이그레이션 출력: C:\workspace\tsh\boilerplate\be\befw\ddl\cira\migration\
- 서버 프로젝트: C:\workspace\tsh\boilerplate\be\befw-app-server\

[테이블 규칙 (원본 기준 그대로 유지)]
- PK: OBJ_ID VARCHAR(100) NOT NULL
- BaseModel 공통 컬럼 (모든 테이블):
    SRV_ID       VARCHAR(50)  NOT NULL DEFAULT 'CIRA'
    TENANT       VARCHAR(50)  NOT NULL DEFAULT 'TAS'
    TRACE_ID     VARCHAR(100) NOT NULL
    USE_STAT_CD  VARCHAR(40)  NOT NULL DEFAULT 'Usable'
    EVNT_NM      VARCHAR(100) NOT NULL
    PREV_EVNT_NM VARCHAR(100)
    ACT_CD       VARCHAR(100)
    ACT_CM       TEXT
    CREATED_BY   VARCHAR(40)
    CREATED_AT   TIMESTAMP    NOT NULL DEFAULT NOW()
    MODIFIED_BY  VARCHAR(40)
    MODIFIED_AT  TIMESTAMP    NOT NULL DEFAULT NOW()
- Soft Delete: USE_STAT_CD = 'Deleted' (deleted_at 컬럼 없음)
- FK: ON DELETE RESTRICT

[수행 작업 1] 마이그레이션 파일 생성
migration\ 폴더를 생성하고 아래 파일들을 작성해줘.
각 파일의 내용은 대응하는 원본 SQL과 동일하게 작성 (내용 수정 없이 파일명만 변환):

- V10__gs_users_and_permissions.sql  ← 01_users_and_permissions.sql 내용
- V20__sn_projects_and_sprints.sql   ← 02_projects_and_sprints.sql 내용
- V30__sn_issues_and_workflow.sql    ← 03_issues_and_workflow.sql 내용
- V40__sn_issue_relations.sql        ← 04_issue_relations.sql 내용
- V50__sn_comments_and_collab.sql    ← 05_comments_and_collaboration.sql 내용
- V60__sn_kanban_board.sql           ← 06_kanban_board.sql 내용

각 파일 상단에 아래 주석 헤더 추가:
-- Flyway Migration: V{버전}__{설명}
-- Source: {원본 파일명}
-- Generated: {날짜}

[수행 작업 2] befw-app-server Flyway 설정
befw-app-server 의 application.yml 에 아래 설정 추가:

spring:
  flyway:
    enabled: true
    locations: filesystem:${DDL_BASE_PATH:C:/workspace/tsh/boilerplate/be/befw/ddl/cira}/migration
    baseline-on-migrate: false
    validate-on-migrate: true
    table: flyway_schema_history

환경변수 DDL_BASE_PATH:
- 로컬 개발: 기본값 C:/workspace/tsh/boilerplate/be/befw/ddl/cira
- CI/CD: 환경변수로 주입 (--DDL_BASE_PATH=/path/to/ddl)

[수행 작업 3] build.gradle 의존성 확인
befw-app-server/build.gradle에 아래 의존성이 없으면 추가:
  implementation 'org.flywaydb:flyway-core'
  implementation 'org.flywaydb:flyway-database-postgresql'

[수행 작업 4] 검증
1. migration\ 폴더의 SQL 파일 6개 생성 확인
2. 서버 기동 후 flyway_schema_history 테이블에서 6건 레코드 확인:
   SELECT version, description, success FROM flyway_schema_history ORDER BY installed_rank;
3. GS_USER, SN_CIRA_PROJECT, SN_CIRA_ISSUE 테이블 존재 확인:
   SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name;

[주의 사항]
- 00_run_all.sql 의 \ir 구문은 psql 전용이므로 마이그레이션 파일에 포함하지 않음
- 원본 SQL 파일(01~06)은 수정하지 않고 그대로 유지
- migration\ 폴더 생성 후 원본 파일과 내용 동기화 책임은 개발자에게 있음
  (원본 수정 시 대응 마이그레이션 파일 신규 버전으로 추가 필요)

완료 기준

항목	기준
migration\ 폴더	V10~V60 파일 6개 생성
Flyway 설정	application.yml DDL_BASE_PATH 설정 완료
서버 기동	Flyway 자동 실행 오류 없음
스키마 검증	flyway_schema_history 6건 success 확인
GS_USER 확인	information_schema 에서 테이블 존재 확인

후행 작업

1-2_서버-Auth-API — GS_USER 테이블 기반 인증 구현
1-3_서버-이슈-CRUD-API — SN_CIRA_ISSUE 테이블 기반 이슈 CRUD

David Brain

Explorer