Migrate DB Skill

호출 시 메시지: 이 Skill이 호출되면 반드시 [SEMO] Skill: migrate-db 호출 - {service_name} 시스템 메시지를 첫 줄에 출력하세요.

Migrate DB Skill

Prisma/​SQL 마이그레이션 안전 관리

지원 기술 스택

워크플로우

Phase 0: 환경 확인 (NON-NEGOTIABLE)

# 현재 브랜치 확인
git branch --show-current

# 미커밋 변경사항 확인
git status --porcelain

# 기술 스택 감지
if [ -f "prisma/​schema.prisma" ]; then
  MIGRATION_TOOL="prisma"
elif [ -f "go.mod" ]; then
  MIGRATION_TOOL="sql"
else
  MIGRATION_TOOL="unknown"
fi
echo "마이그레이션 도구: $MIGRATION_TOOL"

경고: 프로덕션 환경에서는 반드시 백업 후 진행하세요.

---

Phase 1: 마이그레이션 상태 확인

Prisma

# 현재 마이그레이션 상태
npx prisma migrate status

# 스키마 유효성 검사
npx prisma validate

# 스키마 포맷 확인
npx prisma format --check

SQL (Go 서비스)

# 마이그레이션 파일 목록
ls -la db/​migrations/ 2>/​dev/​null || ls -la migrations/

# 적용된 마이그레이션 확인 (schema_migrations 테이블)
psql -c "SELECT * FROM schema_migrations ORDER BY version DESC LIMIT 10"

---

Phase 2: 마이그레이션 생성

Prisma - 개발 환경

# 스키마 변경 후 마이그레이션 생성
npx prisma migrate dev --name {migration_name}

# 예시: 새 필드 추가
npx prisma migrate dev --name add_user_email

Prisma - 프로덕션 환경

# 마이그레이션 파일만 생성 (적용하지 않음)
npx prisma migrate dev --create-only --name {migration_name}

# 생성된 SQL 검토 후 수동 적용
cat prisma/​migrations/​{timestamp}_{name}/​migration.sql

SQL 수동 마이그레이션

# 마이그레이션 파일 생성
TIMESTAMP=$(date +%Y%m%d%H%M%S)
touch db/​migrations/​${TIMESTAMP}_{migration_name}.sql

# 예시 내용
cat << 'EOF' > db/​migrations/​${TIMESTAMP}_add_user_email.sql
-- Up
ALTER TABLE users ADD COLUMN email VARCHAR(255);

-- Down
ALTER TABLE users DROP COLUMN email;
EOF

---

Phase 3: 마이그레이션 적용

Prisma

# 개발 환경
npx prisma migrate dev

# 프로덕션 환경 (CI/​CD에서 사용)
npx prisma migrate deploy

SQL (golang-migrate)

# 적용
migrate -path db/​migrations -database "$DATABASE_URL" up

# 특정 버전까지만 적용
migrate -path db/​migrations -database "$DATABASE_URL" up 1

---

Phase 4: 롤백 (주의 필요)

경고: 롤백은 데이터 손실을 유발할 수 있습니다. 반드시 백업 후 진행하세요.

Prisma

# Prisma는 직접적인 롤백을 지원하지 않음
# 대신 새 마이그레이션으로 변경 사항 되돌리기

# 1. 되돌릴 스키마 변경 작성
# 2. 새 마이그레이션 생성
npx prisma migrate dev --name revert_{previous_migration}

SQL (golang-migrate)

# 마지막 마이그레이션 롤백
migrate -path db/​migrations -database "$DATABASE_URL" down 1

# 모든 마이그레이션 롤백 (위험!)
# migrate -path db/​migrations -database "$DATABASE_URL" down

---

Phase 5: Prisma 클라이언트 재생성

# 스키마 변경 후 클라이언트 재생성
npx prisma generate

# 타입 확인
npx tsc --noEmit

출력 포맷

마이그레이션 성공

[SEMO] Skill: migrate-db 호출 - ms-{service}

=== 마이그레이션 결과 ===

## 환경
- 서비스: ms-{service}
- 도구: Prisma
- 환경: development

## 실행 내역
| 단계 | 상태 | 상세 |
|------|------|------|
| 상태 확인 | ✅ | 대기 중인 마이그레이션 1건 |
| 스키마 검증 | ✅ | 유효 |
| 마이그레이션 적용 | ✅ | 20250122_add_user_email |
| 클라이언트 생성 | ✅ | @prisma/​client 재생성 |

## 적용된 마이그레이션
- `20250122143000_add_user_email`
  - ALTER TABLE `users` ADD COLUMN `email` VARCHAR(255)

## 다음 단계
1. `npx tsc --noEmit`로 타입 확인
2. 테스트 실행: `npm test`
3. 커밋: `git add prisma/ && git commit -m "db: add user email field"`

마이그레이션 실패

[SEMO] Skill: migrate-db 호출 - ms-{service}

=== 마이그레이션 실패 ===

## 오류

Error: P3009 migrate found failed migrations in the target database.

## 원인
- 이전 마이그레이션이 실패한 상태로 남아있음

## 해결 방법
1. 실패한 마이그레이션 확인:
   ```bash
   npx prisma migrate status

1. 수동으로 실패한 마이그레이션 해결:

   npx prisma migrate resolve --rolled-back {migration_name}
   

2. 재시도:

   npx prisma migrate dev
   

## 안전 체크리스트

### 개발 환경

- [ ] 로컬 DB 백업 불필요 (재생성 가능)
- [ ] 스키마 변경 검토
- [ ] 테스트 통과 확인

### 스테이징/프로덕션 환경

- [ ] DB 백업 완료
- [ ] 마이그레이션 SQL 검토
- [ ] 롤백 계획 수립
- [ ] 다운타임 영향도 확인
- [ ] 팀 공유 및 승인

## 서비스별 스키마 정보

| 서비스 | 스키마명 | Prefix | 주요 테이블 |
|--------|---------|--------|------------|
| ms-notifier | notifier | nf_ | notifications, channels, jobs |
| ms-scheduler | scheduler | sc_ | schedules, executions, job_queue |
| ms-ledger | ledger | lg_ | accounts, transactions, subscriptions |
| ms-allocator | allocator | al_ | tracked_subjects, snapshots, aggregates |
| ms-gamer | public | ladder_ | round, bet, pattern |

## Related Skills

- [setup-prisma](../setup-prisma/SKILL.md) - Prisma 초기 설정
- [debug-service](../debug-service/SKILL.md) - DB 연결 디버깅

## References

- [Prisma Migrate](https://www.prisma.io/docs/concepts/components/prisma-migrate)
- [golang-migrate](https://github.com/golang-migrate/migrate)
- [Microservices Context](/.claude/memory/microservices.md) - 서비스별 스키마 정보