DB 스키마 관리 정책

1. 개요 및 배경

1.1 배경 및 목적

본 정책은 모든 스키마 변경을 코드화하고, 검증된 절차를 통해 반영함으로써 서비스의 안정성과 데이터 무결성을 보장하는 것을 목적으로 합니다.

1.2 핵심 원칙

• 이력의 불변성: 한 번 상위 브랜치에 반영된 마이그레이션 파일은 절대 수정하거나 삭제하지 않습니다.
• 선 검증 후 반영: 모든 변경사항은 로컬 및 스테이징 환경에서 검증된 후 운영에 반영됩니다.
• 무중단 배포 지향: 스키마 변경이 애플리케이션의 가용성에 미치는 영향을 최소화합니다.

2. 데이터베이스 관리 구조

본 프로젝트는 모노레포 환경에서 데이터 일관성과 관리 효율성을 위해 다음과 같은 구조적 설계를 따릅니다.

2.1 스키마 관리

• Shared Library 기반: 모든 데이터베이스 스키마 정의와 마이그레이션 이력은 공통 라이브러리(libs/core/database)에서 중앙 집중 관리합니다.
• 다중 앱 공유: dta-wide-api, dta-wir-api-universal 등 여러 애플리케이션 서비스는 이 공통 라이브러리를 참조하여 동일한 데이터 모델과 데이터베이스 인스턴스를 공유합니다.

2.2 논리적 격리 및 통합 (Logical Isolation)

• 하나의 물리적 DB 내에서 auth, private, operation, log 등 논리적 스키마를 분리하여 데이터의 성격에 따른 권한 제어와 격리를 수행합니다.

2.3 모듈형 스키마 설계 (Modular Schema Design)

• 단일 명세의 한계 극복: 수천 줄에 달하는 거대 스키마 파일의 가독성 문제를 해결하기 위해, 도메인별로 분리된 스키마 파일을 작성합니다.
• 빌드 파이프라인: 작성한 개별 모듈은 빌드 스크립트(build-schema.js)를 통해 하나의 스키마 파일로 병합되며, 이 최종 결과물이 모든 마이그레이션과 클라이언트 생성의 기준이 됩니다.

3. 마이그레이션 파일 도입 전략

기존의 즉시 반영(db push) 방식에서 벗어나, 물리적인 마이그레이션 파일(SQL)을 기반으로 스키마 변경을 관리하는 전략입니다.

3.1 도입 목적

1. 변경 이력의 투명한 추적: 누가, 언제, 어떤 이유로 스키마를 변경했는지 SQL 파일 단위로 영구 기록하여, 문제 발생 시 원인 파악을 용이하게 합니다.
2. 환경 간 일관성 보장: 개발, 스테이징, 운영 환경에 동일한 SQL 파일을 순차적으로 적용함으로써, "내 로컬에서는 되는데 운영에서는 안 되는" 스키마 불일치(Drift) 문제를 원천 차단합니다.
3. 안전한 롤백 및 복구: 명시적인 변경 파일이 존재하므로, 실패 시 특정 시점으로의 복구나 원인 분석이 명확해집니다.

3.2 주요 과제 및 해결 방안 (단점 극복)

마이그레이션 파일 도입 시 발생하는 운영상의 어려움(단점)과 이를 해결하기 위한 방안은 다음과 같습니다.

구분	주요 과제 (단점)	해결 방안
관리 복잡도	단순 수정에도 파일을 생성하고 관리해야 하는 번거로움 증가	• 자동화: build-schema 스크립트를 통해 모듈화된 스키마를 자동 병합 • CI 지원: PR 생성 시 봇이 자동으로 스키마 Diff를 분석하여 리뷰 지원
충돌 발생	다수 개발자가 동시에 스키마 변경 시 파일 충돌 및 순서 꼬임 발생	• 로컬 검증 강화: 로컬에서 반드시 마이그레이션 파일을 생성(create-only)하고 테스트 후 커밋 • Locking: 배포 시 DB Lock을 활용하여 동시 실행 방지
배포 리스크	잘못된 SQL이 운영 DB에 반영될 위험 존재	• 정책적 통제: db push 사용 금지 및 migrate deploy만 허용 • 사전 검증: Staging 환경에서 선 배포 후 검증, Expand-Contract 패턴 적용

4. 스키마 관리 및 형상 관리 정책

4.1 스키마 모듈화

• 디렉토리 구조: libs/core/database/schemas/ 하위에 도메인별(스키마별) 폴더를 구성하여 관리합니다.

libs/
├── core/
│   └── database/
│       └── schemas/

3.2 형상 관리 (Git)

• 통합 스키마: 빌드된 통합 파일은 항상 최신 상태로 Git에 커밋되어야 하며, 이는 DB의 **'현재 목표 상태(Desired State)'**를 의미합니다.
• 형상 불일치(Drift) 금지: 실제 DB 상태와 Git에 저장된 스키마 상태가 다를 경우, 즉시 원인을 파악하고 마이그레이션을 통해 동기화해야 합니다.

4. 마이그레이션 이력 관리 정책

4.1 이력 생성 및 명명 규칙

• 생성 시점: 기능 개발 완료 후 PR 생성 전 로컬에서 반드시 마이그레이션 파일을 생성해야 합니다.
• 명명 규칙: ${timestamp}_${action}_${description} 형식을 엄격히 준수합니다.
  • 예시: 20260105074340_add_auth_site
• SQL 리뷰 기준: 마이그레이션 파일 생성 시 다음 항목을 반드시 체크합니다.
  • DROP TABLE, DROP COLUMN 등 데이터 삭제 쿼리 포함 여부
  • ALTER TABLE 시 Table Lock 발생 가능성이 큰 대량 데이터 테이블 여부
  • 기본값(Default Value) 추가 시 전체 레코드 업데이트에 따른 부하

4.2 하위 호환성 및 자동 생성 안전 수칙

Workflow를 통한 마이그레이션 자동 생성 시 발생할 수 있는 데이터 유실(예: 단순 컬럼명 변경을 DROP & ADD로 오판)을 방지하기 위해 다음 원칙을 철저히 준수합니다.

4.2.1 Expand-Contract 패턴 (필수 준수)

파괴적인 변경(컬럼 삭제, 컬럼명 변경, 데이터 타입 변경 등)은 절대 한 번의 배포로 처리하지 않으며, 반드시 단계적으로 진행합니다.

1. Expand (확장): 신규 컬럼을 추가합니다. (기존 컬럼 유지)
   • 데이터 복제가 필요한 경우 애플리케이션 레벨 또는 별도 스크립트로 처리합니다.
2. Migrate & Verify: 애플리케이션이 신규 컬럼을 바라보도록 배포하고 검증합니다.
3. Contract (축소): 구 버전 컬럼을 삭제하는 마이그레이션을 별도로 생성하여 배포합니다.

4.2.2 Feature CI Check (사전 감지)

PR 단계에서 Workflow가 실행하는 prisma migrate diff 결과를 반드시 확인해야 합니다.

• Data Loss Warning: Prisma가 "데이터 손실 가능성(Data Loss)" 경고를 출력하면, 마이그레이션 생성을 중단하고 스키마 변경 방식을 재검토해야 합니다.
• Diff 리뷰: 자동 생성된 SQL이 의도한 변경(ALTER)인지, 파괴적 변경(DROP)인지 개발자가 직접 눈으로 확인한 후 승인해야 합니다.

5. 배포 및 승인 프로세스

5.1 단계별 환경 배포 원칙

환경	반영 방식	승인 권한	비고
Local	개발자 자율 실행	본인	migrate dev 사용 가능
Dev	CI 자동 반영	담당 개발자	PR 머지 시 자동 반영
Stage	ChatOps 명령	관리자	운영 배포 전 최종 검증 단계
Prod	ChatOps 명령	관리자	승인된 작업 시간에만 수행

5.2 리뷰

리뷰어는 PR 검토 시 다음 사항을 확인해야 합니다.

• 마이그레이션 파일이 규칙에 맞게 생성되었는가?
• 통합 스키마 파일이 함께 업데이트되었는가?
• 변경사항이 기존 데이터의 정합성을 해치지 않는가?
• (운영 환경의 경우) 롤백 시나리오가 준비되었는가?

6. 장애 대응 및 복구 정책

6.1 기본 원칙

• 데이터 무결성 최우선: 모든 복구 조치는 데이터 유실 및 정합성 보장을 최우선으로 합니다.
• 수동 개입 원칙: 마이그레이션 실패 시 자동 롤백 스크립트보다는 상황 분석 후 수동 복구를 원칙으로 합니다.

6.2 마이그레이션 실패 대응 절차

6.2.1 즉시 조치 (Immediate Response)

배포 스크립트에서 마이그레이션 실패 감지 시:

1. 프로세스 즉시 중단: 추가 변경사항 적용을 차단합니다.
2. Slack 긴급 알림 발송: 실패 환경, 시간, 마이그레이션 파일명, 에러 메시지, 후속 조치 가이드를 포함한 상세 알림을 전송합니다.

6.2.2 상태 진단 (Diagnosis)

1. DB 상태 확인:
   • _prisma_migrations 테이블을 조회하여 마이그레이션 이력 상태를 확인합니다.
   • ORM 도구를 통해 DB 인식 상태를 확인합니다.
2. 영향 범위 분석:
   • 부분 적용된 DDL/DML이 있는지 확인합니다.
   • Dirty State(이력과 실제 스키마 불일치) 여부를 판단합니다.

6.2.3 복구 전략 수립

실패 원인 및 DB 상태에 따라 다음 중 하나를 선택합니다:

• 백업본 복구 (최우선 권장): 운영 환경의 경우 반드시 배포 전 백업본을 준비하고, 실패 시 즉시 복구합니다.
• 수동 상태 보정: _prisma_migrations 테이블 상태만 수정하여 ORM 인식을 바로잡되, 실제 스키마는 변경하지 않습니다.
• Hotfix 마이그레이션 작성: 실패 원인이 명확하고 간단한 경우, 수정된 마이그레이션을 새로 생성하여 재배포합니다.

6.3 백업 및 복구 정책

6.3.1 사전 백업 (Pre-deployment Backup)

• 운영 환경(Prod): 마이그레이션 실행 전 반드시 DB 전체 스냅샷 또는 논리 백업을 수행합니다.
• 스테이징 환경(Stage): 대규모 스키마 변경(테이블 재구성, 데이터 마이그레이션 포함) 시 백업을 권장합니다.
• 백업 보관 기간: 최소 7일 이상 보관하며, 정기적으로 백업 유효성을 검증합니다.

6.3.2 롤백 전략

• 역방향 마이그레이션(Reverse Migration):
  • 단순한 컬럼 추가/삭제와 같이 명확하게 되돌릴 수 있는 경우에만 Reverse SQL 작성을 고려합니다.
  • 복잡한 데이터 변환이나 다중 테이블 조인 로직이 포함된 경우 Reverse SQL 작성은 지양합니다.
• 백업본 완전 복구:
  • 복잡한 마이그레이션 실패 시에는 백업본을 완전히 복구한 후 원인을 분석하고 재시도합니다.
  • 복구 시 서비스 중단 시간과 데이터 유실 구간을 명확히 관계자에게 전달합니다.

6.4 실패 이력 관리

• 포스트모템(Postmortem) 문서 작성: 모든 마이그레이션 실패 사례는 원인, 복구 과정, 재발 방지 대책을 포함한 문서로 기록하고 팀 내 공유합니다.

7. 정책 준수 모니터링

• 경고 시스템: 배포 파이프라인에서 마이그레이션 없이 스키마 파일만 변경된 경우 배포를 차단합니다.

변경 이력

버전	날짜	작성자	변경 내용
0.64.0	2026-01-07	pibi@weltcorp.com	최초 문서 작성