[Tooling] Flyway 기반 DB 스키마·Migration 문서 자동 공유 구성

[hywznn]

왜 필요한가요?

현재 DB 구조의 기준은 src/main/resources/db/migration의 Flyway SQL이지만, Client·AI·Knowledge·기획 팀원이 테이블·컬럼·관계를 확인하려면 SQL과 ERD를 따로 찾아야 합니다. 수동 ERD는 실제 Migration과 달라질 수 있으므로, main에 병합된 Flyway를 빈 PostgreSQL에 적용한 결과에서 문서를 자동 생성합니다.

쉽게 말하면 DB용 Swagger 사이트를 만드는 작업입니다.

목표

팀원이 링크 하나로 다음 정보를 확인할 수 있게 합니다.

• 전체 ERD와 테이블 관계
• 컬럼 타입·Nullable·기본값
• PK·FK·UNIQUE·CHECK·INDEX
• 적용된 Flyway 버전과 성공·대기 상태
• 문서를 생성한 Git commit과 시각

최종 구조

main의 db/migration 변경
→ GitHub Actions
→ 일회용 빈 PostgreSQL
→ Flyway migrate + validate
→ SchemaSpy HTML·ERD 생성
→ Flyway Migration report 생성
→ GitHub Pages 배포

정식 문서는 main만 배포하고, PR에서는 GitHub Actions Artifact로 미리 봅니다.

구현 범위

1. 재현 가능한 DB 구성

• GitHub Actions에서 빈 PostgreSQL service를 시작한다.
• 저장소의 Flyway Migration을 버전 순서대로 적용한다.
• flyway validate 실패 시 문서를 배포하지 않고 CI를 실패시킨다.
• Flyway·SchemaSpy·PostgreSQL 도구 버전을 명시적으로 고정한다.

2. SchemaSpy 문서

• 실제 적용된 빈 DB에서 SchemaSpy HTML을 생성한다.
• 전체 ERD, 테이블, 컬럼, 관계, 제약조건, Index가 표시된다.
• 홈에서 비개발자도 테이블 구조 보기와 Migration 이력 보기를 찾을 수 있다.
• 생성 Git SHA와 UTC 생성 시각을 표시한다.

3. Flyway 이력 문서

• 적용·대기·실패 Migration을 확인할 수 있는 HTML 또는 JSON 기반 페이지를 생성한다.
• flyway_schema_history의 비밀번호·접속정보·CI secret은 노출하지 않는다.
• 이미 적용된 Migration의 checksum 불일치를 validate에서 검출한다.

4. GitHub 자동화·공유

• main의 src/main/resources/db/migration/** 변경 또는 수동 실행 시 문서를 재생성한다.
• 정식 산출물을 GitHub Pages에 배포한다.
• PR에서는 배포하지 않고 다운로드 가능한 Artifact를 남긴다.
• README와 Wiki에 문서 링크와 갱신 규칙을 추가한다.
• 실패 원인과 로컬 생성 방법을 짧게 문서화한다.

공개 사이트 제안

https://fowoco.github.io/server/
├── index.html                 # 안내·전체 ERD
├── schema/                    # SchemaSpy 테이블 문서
└── migrations/               # Flyway 적용 상태

실제 URL은 GitHub Pages 활성화 결과를 기준으로 README와 Wiki에 기록합니다.

보안 기준

• 운영·Staging DB에 직접 연결하지 않는다.
• CI가 생성한 일회용 빈 PostgreSQL만 사용한다.
• Demo Seed와 실제 사용자·근로자 데이터는 넣지 않는다.
• DB 비밀번호는 CI 내부 임시값만 사용하고 산출물·로그에 남기지 않는다.
• GITHUB_TOKEN 외 Personal Access Token을 새로 만들지 않는다.
• Pages에는 데이터가 아니라 공개 저장소의 Migration으로 재현 가능한 스키마 구조만 게시한다.
• 민감한 구조를 향후 비공개로 전환해야 하면 Pages 배포를 중지하고 Actions Artifact 또는 접근제어된 내부 Hosting으로 바꾼다.

필요한 GitHub 권한

저장소 관리자 또는 Organization 관리자가 최초 1회 확인합니다.

1. Settings → Pages → Build and deployment → Source를 GitHub Actions로 설정
2. Settings → Actions → General에서 이 저장소의 Actions 실행 허용
3. Workflow에 최소 권한만 선언

permissions:
  contents: read
  pages: write
  id-token: write

4. github-pages Environment가 생성되면 배포 보호 규칙 확인

관리자 권한을 바로 받을 수 없다면 Pages 단계만 보류하고, 우선 PR·main CI의 Artifact까지 구현합니다. 별도 DB나 Cloud 비밀키 권한은 필요하지 않습니다.

완료 기준

• 새 Migration을 main에 병합하면 별도 수동 편집 없이 문서가 갱신된다.
• 현재 최신 Migration까지 적용된 테이블·FK·제약조건이 문서와 일치한다.
• 잘못된 Migration 또는 checksum 불일치에서는 Pages가 갱신되지 않는다.
• PR 작성자가 Artifact에서 변경된 ERD를 확인할 수 있다.
• 팀원이 로그인 절차 없이 공유 링크에서 문서를 열 수 있다. 단, Organization 정책상 공개 Pages가 불가능하면 저장소 멤버용 Artifact를 공식 대안으로 기록한다.
• 산출물과 Actions 로그에 DB 비밀번호·실제 데이터가 없다.
• README·Wiki에 사용법과 책임 범위가 반영된다.

비범위

• 운영 DB 실시간 모니터링
• 운영 데이터 조회
• Migration 자동 작성
• Flyway Pipelines·Atlas·dbdocs 같은 외부 SaaS 도입
• SchemaSpy 산출물을 Git에 직접 커밋

구현 메모

SchemaSpy는 실제 DB metadata를 읽으므로, SQL을 직접 해석해 ERD를 만드는 방식보다 Flyway 결과와 정합성이 높습니다. 문서는 DB 계약을 이해하기 위한 보조 수단이며, 변경의 최종 기준은 계속 Flyway Migration과 ADR입니다.

[hywznn]

구현 PR을 연결했습니다: #46

완료한 범위:

• 일회용 PostgreSQL에 Flyway 12.4.0 migrate·validate
• SchemaSpy 7.0.2 ERD·테이블·제약조건 HTML 생성
• Migration 상태·Git commit·생성 시각 문서화
• PR Artifact 14일 제공, main에서만 GitHub Pages 배포
• 운영 DB·실제 데이터·PAT 사용 금지와 전용 DB 실행 guard
• 로컬 한 명령 생성 스크립트와 초보자용 README·상세 문서

검증 결과:

• Build database documentation 통과
• Test and build 통과
• Artifact 246개 파일·HTML 22개 생성
• Flyway v5까지 Success 5, Pending 0
• Artifact에 CI 비밀번호·JDBC URL·환경변수명 없음
• Artifact의 Git commit이 실제 PR head와 일치

현재 #46은 리뷰 대기 상태입니다. 병합 후 main Pages 배포와 실제 URL을 확인하고 Wiki 링크를 반영한 다음 #45를 완료 처리합니다.