xrlms/prisma/README.md

# Prisma 데이터베이스 관리 가이드

## 📋 개요

이 문서는 Prisma를 사용한 데이터베이스 스키마 관리 및 마이그레이션 워크플로우를 설명합니다.

## 🚀 개발 환경 워크플로우

### 1. 스키마 변경 후 데이터베이스 최신화

#### 방법 A: 마이그레이션 생성 및 적용 (권장)
```bash
# 1. 스키마 변경 (prisma/schema.prisma 수정)

# 2. 마이그레이션 생성 및 적용
npm run db:migrate

# 마이그레이션 이름을 지정하려면:
npx prisma migrate dev --name add_new_field
```

이 명령어는:
- 마이그레이션 파일 생성
- 데이터베이스에 마이그레이션 적용
- Prisma Client 자동 재생성

#### 방법 B: 개발 중 빠른 프로토타이핑 (데이터 손실 가능)
```bash
# 스키마 변경 후 즉시 적용 (마이그레이션 파일 생성 안 함)
npm run db:push
```

⚠️ **주의**: `db:push`는 프로덕션 환경에서는 사용하지 마세요!

### 2. Seed 데이터 재실행

```bash
# Seed 데이터 삽입
npm run db:seed

# 또는 마이그레이션 리셋 후 자동으로 seed 실행
npm run db:migrate:reset
```

### 3. 전체 초기화 (개발 환경 전용)

```bash
# 데이터베이스 완전히 리셋 + 마이그레이션 재적용 + seed 실행
npm run db:migrate:reset
```

⚠️ **주의**: 모든 데이터가 삭제됩니다!

## 📦 프로덕션 환경 워크플로우

### 1. 마이그레이션 배포

```bash
# 생성된 마이그레이션 파일들을 프로덕션 DB에 적용
npm run db:migrate:deploy
```

이 명령어는:
- 마이그레이션 파일만 적용 (새로운 마이그레이션 생성 안 함)
- 안전하게 프로덕션에 적용 가능

### 2. Prisma Client 재생성

```bash
npm run db:generate
```

## 🔄 일반적인 워크플로우 시나리오

### 시나리오 1: 새로운 필드 추가

```bash
# 1. schema.prisma에 필드 추가
# 예: model User { ... newField String? }

# 2. 마이그레이션 생성 및 적용
npm run db:migrate --name add_new_field

# 3. (선택) Seed 데이터 업데이트 필요 시
npm run db:seed
```

### 시나리오 2: 관계 추가/변경

```bash
# 1. schema.prisma에 관계 추가
# 2. 마이그레이션 생성
npm run db:migrate --name add_relation

# 3. 기존 데이터 마이그레이션 필요 시 수동으로 처리
```

### 시나리오 3: 개발 중 스키마 실험

```bash
# 빠르게 스키마 변경 테스트 (마이그레이션 파일 생성 안 함)
npm run db:push

# 만족스러우면 마이그레이션 생성
npm run db:migrate --name experimental_changes
```

## 🛠️ 유용한 명령어

### Prisma Studio (데이터베이스 GUI)

```bash
npm run db:studio
```

브라우저에서 데이터베이스를 시각적으로 확인하고 편집할 수 있습니다.

### 기존 데이터베이스에서 스키마 가져오기

```bash
npm run db:pull
```

기존 데이터베이스 구조를 분석하여 `schema.prisma`를 생성합니다.

## 📝 마이그레이션 파일 관리

- 마이그레이션 파일은 `prisma/migrations/` 폴더에 저장됩니다
- 각 마이그레이션은 타임스탬프와 이름으로 식별됩니다
- 마이그레이션 파일은 Git에 커밋해야 합니다
- 팀원들과 마이그레이션을 공유하여 동일한 스키마를 유지합니다

## ⚠️ 주의사항

1. **프로덕션 환경**에서는 절대 `db:push`나 `db:migrate:reset`을 사용하지 마세요
2. **마이그레이션 파일**은 항상 Git에 커밋하세요
3. **스키마 변경 전**에 백업을 권장합니다
4. **Seed 데이터**는 개발 환경에서만 사용하세요

## 🔍 문제 해결

### 마이그레이션 충돌 시

```bash
# 마이그레이션 상태 확인
npx prisma migrate status

# 문제 해결 후
npm run db:migrate:resolve
```

### Prisma Client가 최신이 아닐 때

```bash
npm run db:generate
```

## 📚 추가 리소스

- [Prisma 마이그레이션 가이드](https://www.prisma.io/docs/concepts/components/prisma-migrate)
- [Prisma CLI 참조](https://www.prisma.io/docs/reference/api-reference/command-reference)