# DB Migration Review

> 마이그레이션 파일의 위험 패턴 탐지 (락, 대규모 ALTER, 데이터 손실)

- Skill: `gaebalai-claude-code-kit-ko/db-migration-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/db-migration-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/db-migration-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/db-migration-review

---


당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

## 목적

마이그레이션 파일을 정적 분석하여 운영(프로덕션) 환경에서 문제를 유발할 수 있는 위험 패턴을 탐지한다.  
테이블 락, 대규모 ALTER TABLE, 데이터 손실, 무결성 훼손 등의 리스크를 사전에 식별하고, 안전한 대체 방안을 제시한다.

## 입력

- 마이그레이션 파일 (SQL / ORM 마이그레이션 파일)
- 마이그레이션 디렉터리 (여러 파일 일괄 리뷰)
- 관련 스키마 정의 파일 (선택 사항)

## 절차

### 1. 마이그레이션 파일 수집 및 분석

1-1. 지정된 경로에서 마이그레이션 파일을 식별한다  
1-2. SQL 구문 또는 ORM 마이그레이션 정의를 분석한다  
1-3. 각 마이그레이션의 작업 유형(DDL / DML)을 분류한다  
1-4. 실행 순서 간 의존 관계를 확인한다  

### 2. 위험 패턴 탐지

다음 패턴을 빠짐없이 점검한다:

### **테이블 락 관련**

2-1. `ALTER TABLE`로 인해 배타 락(Exclusive Lock)이 발생하는 구간 식별  
2-2. `LOCK TABLES` / `LOCK TABLE`의 명시적 사용 탐지  
2-3. 장시간 트랜잭션 내부에서 DDL 실행 여부 탐지  
2-4. 인덱스 생성 시 `ALGORITHM=COPY`에 해당하는 작업 탐지  

### **데이터 손실 관련**

2-5. `DROP TABLE` / `DROP COLUMN`으로 인한 데이터 삭제 탐지  
2-6. `TRUNCATE TABLE`로 인한 전체 데이터 삭제 탐지  
2-7. 데이터 타입 축소 변경 (예: VARCHAR(255) → VARCHAR(100)) 탐지  
2-8. NOT NULL 제약 추가 시 기존 NULL 데이터 손실 가능성 탐지  
2-9. `DELETE FROM`을 통한 조건부 데이터 삭제 탐지  

### **성능 관련**

2-10. 대규모 테이블에서 `ADD COLUMN` + DEFAULT 동시 지정 탐지  
2-11. 복합 인덱스 컬럼 순서가 비효율적인 경우 탐지  
2-12. 불필요한 `FORCE INDEX` / `USE INDEX` 사용 탐지  

### **무결성 관련**

2-13. 외래 키 제약 없이 관계 컬럼을 추가하는 경우 탐지  
2-14. `CASCADE DELETE`의 연쇄 삭제 영향 탐지  
2-15. 롤백 SQL 누락 여부 탐지  
2-16. 트랜잭션 경계(BEGIN/COMMIT) 누락 또는 불완전 구성 탐지  

### 3. 리스크 평가 및 점수화

3-1. 각 탐지 항목에 심각도 부여 (CRITICAL / HIGH / MEDIUM / LOW)  
3-2. 영향을 받는 테이블의 예상 규모 평가  
3-3. 서비스 중단(다운타임) 발생 가능성 판단  
3-4. 데이터 손실의 복구 가능성 평가  

### 4. 안전한 대체 방안 제안

4-1. 각 위험 패턴에 대해 안전한 대안 제시  
4-2. 온라인 DDL (pt-online-schema-change / gh-ost 등) 적용 가능성 평가  
4-3. 단계적 마이그레이션(여러 단계로 분할) 방안 제안  
4-4. Blue-Green 배포 전략과의 연계 방안 제시  

### 5. 롤백 안전성 검증

5-1. DOWN 마이그레이션 존재 여부 확인  
5-2. 롤백 SQL이 실제 데이터 복원이 가능한지 검증  
5-3. 롤백 불가능한 작업 명시  
5-4. 부분 롤백 절차 필요 여부 판단  

### 6. 종합 판정

6-1. 전체 마이그레이션의 안전성 종합 평가 (APPROVE / CONDITIONAL / REJECT)  
6-2. CONDITIONAL인 경우, 승인 조건을 구체적으로 명시  
6-3. 운영 반영 전 추가로 필요한 테스트 항목 나열  

## 출력 포맷

```markdown
# 마이그레이션 리뷰: [파일명]

## 종합 판정: [APPROVE / CONDITIONAL / REJECT]

## 탐지 요약
| 심각도 | 건수 | 주요 내용 |
|--------|------|------------|
| CRITICAL | N건 | [요약] |
| HIGH | N건 | [요약] |
| MEDIUM | N건 | [요약] |
| LOW | N건 | [요약] |

## 탐지 상세

### [CRITICAL] [탐지 항목명]
- **위치**: `file:line` - 해당 SQL 구문
- **리스크**: [구체적인 장애 시나리오]
- **영향**: [다운타임 / 데이터 손실 / 성능 저하]
- **대안**: [안전한 구현 방법]

```sql
-- 위험한 패턴
ALTER TABLE large_table ADD COLUMN new_col VARCHAR(255) NOT NULL DEFAULT '';

-- 권장 대안
-- Step 1: NULL 허용으로 컬럼 추가
ALTER TABLE large_table ADD COLUMN new_col VARCHAR(255) NULL;
-- Step 2: 배치 작업으로 기본값 반영
-- Step 3: NOT NULL 제약 추가
```

### [HIGH] [탐지 항목명]
- **위치**: `file:line` - 해당 SQL 구문
- **리스크**: [구체적인 장애 시나리오]
- **영향**: [영향 범위]
- **대안**: [안전한 구현 방법]

## 롤백 안전성
| 마이그레이션 | 롤백 가능 여부       | 사유   |
| ------ | -------------- | ---- |
| [작업명]  | 가능 / 불가능 / 조건부 | [설명] |

## 승인 조건 (CONDITIONAL인 경우)
1. [수정이 필요한 사항]
2. [추가로 필요한 테스트]
3. [실행 시 제약 조건]

## 권장 액션
- [ ] [구체적인 수정 지시]
- [ ] [추가 테스트 항목]
- [ ] [실행 전 점검 사항]
```

## 안전 수칙

- **실제 SQL을 실행하지 말 것** — 본 스킬은 정적 분석만 수행한다  
- **운영 데이터베이스에 접속하지 말 것**  
- **마이그레이션 파일 내용을 직접 수정하지 말 것** — 리뷰 결과 보고만 수행한다  
- **CRITICAL 항목이 존재할 경우, 파일 상단에 반드시 경고를 명시할 것**  
- **데이터 손실이 포함된 작업은 반드시 백업 절차 명시를 요구할 것**  
- **추정이 아닌, 확실히 판정 가능한 항목만 CRITICAL로 분류할 것**  
- **ORM 전용 마이그레이션 문법도 정확히 분석할 것** (Rails, Django, Alembic, Knex 등)

---

## 종료 조건

- 모든 마이그레이션 파일이 분석되었을 것  
- 위험 패턴 탐지 결과가 심각도와 함께 보고되었을 것  
- 각 탐지 항목에 대해 안전한 대안이 제시되었을 것  
- 롤백 안전성이 평가되었을 것  
- 종합 판정(APPROVE / CONDITIONAL / REJECT)이 명확히 제시되었을 것  
- CONDITIONAL일 경우 승인 조건이 구체적으로 작성되었을 것  

---

## 이 스킬이 적합하지 않은 경우

- **APPROVE를 최종 승인으로 간주하는 경우**: 본 리뷰는 코드 기반 정적 분석 결과다. 실제 데이터 규모, 트래픽 패턴, 복제 구성 등은 반영되지 않으므로 DBA 검토를 생략하면 안 된다.  
- **ORM 런타임 동작에 의존하는 마이그레이션**: 분석은 주로 정적 SQL 기반이다. ORM의 런타임 동작(지연 실행, 훅 등)까지는 완전하게 탐지할 수 없다.