# DB Migration Draft

> DB 마이그레이션의 안전한 실행 절차서와 롤백 계획을 작성한다

- Skill: `gaebalai-claude-code-kit-ko/db-migration-draft` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/db-migration-draft`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/db-migration-draft/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- 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-21
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/db-migration-draft

---


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

## 목적

데이터베이스 마이그레이션의 안전한 실행 절차서를 작성한다.  
스키마 변경의 영향 범위를 분석하고, 단계별 실행 계획과 롤백 절차를 포함한 포괄적인 마이그레이션 문서를 작성한다.  
운영(프로덕션) 환경에서의 장애를 사전에 방지하는 것을 최우선으로 한다.

## 입력

- 대상 테이블명 또는 스키마 변경 내용 설명
- 기존 마이그레이션 파일(존재하는 경우)
- 관련 모델 정의 또는 ORM 파일
- 현재 스키마 정의 파일 (schema.sql, schema.rb, models.py 등)

## 절차

### 1. 현재 스키마 파악

1-1. 프로젝트 내 스키마 정의 파일을 검색한다  
1-2. 대상 테이블의 현재 컬럼 구성, 제약 조건, 인덱스를 확인한다  
1-3. 외래 키(Foreign Key) 제약에 의해 의존하는 테이블을 식별한다  
1-4. 기존 마이그레이션 이력을 통해 테이블 변경 내역을 추적한다  

### 2. 변경 영향 분석

2-1. 변경 대상 컬럼을 참조하는 쿼리를 코드베이스 전체에서 검색한다  
2-2. ORM 모델 정의에서 해당 컬럼을 사용하는 위치를 특정한다  
2-3. 뷰(View), 저장 프로시저(Stored Procedure), 트리거(Trigger)에 미치는 영향을 확인한다  
2-4. 외래 키 제약의 연쇄 영향(CASCADE / RESTRICT)을 평가한다  
2-5. 기존 데이터 건수를 확인하여 테이블 락(LOCK) 시간 추정에 반영한다  

### 3. 마이그레이션 SQL 작성

3-1. UP 마이그레이션(적용) SQL을 작성한다  
3-2. DOWN 마이그레이션(롤백) SQL을 작성한다  
3-3. DEFAULT 값 또는 NOT NULL 제약을 추가하는 경우, 기존 데이터 보정(데이터 채움) 절차를 포함한다  
3-4. 대규모 테이블(100만 행 이상)의 경우, 온라인 DDL 기법(pt-online-schema-change 등)을 반드시 제안한다  
3-5. 마이그레이션 실행 전 사전 점검 SQL을 작성한다  

### 4. 롤백 계획 수립

4-1. 롤백 SQL의 타당성을 검증한다 (데이터 손실이 없는지 확인)  
4-2. 롤백 판단 기준(타임아웃 기준, 오류율 기준)을 정의한다  
4-3. 롤백 실행 시 애플리케이션 측 대응 절차를 문서화한다  
4-4. 롤백이 불가능한 변경(컬럼 삭제, 데이터 타입 축소 등)을 명확히 표시한다  

### 5. 실행 계획 수립

5-1. 권장 점검/작업 시간대(유지보수 시간)를 제안한다  
5-2. 실행 전 체크리스트(백업 확인, 복제 지연 확인 등)를 작성한다  
5-3. 단계적 배포 절차(마이그레이션 → 애플리케이션 배포 → 검증)를 정리한다  
5-4. 실행 후 검증 쿼리(데이터 정합성 확인)를 작성한다  

### 6. 리뷰 관점 정리

6-1. 파괴적 변경 여부를 요약한다  
6-2. 서비스 중단(다운타임) 발생 여부 및 예상 시간을 명시한다  
6-3. 팀 리뷰 시 중점 확인 사항을 정리한다  

## 출력 포맷

```markdown
# 마이그레이션 초안: [변경 개요]

## 변경 요약
| 항목 | 내용 |
|------|------|
| 대상 테이블 | `table_name` |
| 변경 유형 | ADD COLUMN / ALTER COLUMN / DROP TABLE 등 |
| 예상 영향 행 수 | 약 N 건 |
| 서비스 중단(다운타임) | 있음(약 N 분) / 없음 |
| 파괴적 변경 | 있음 / 없음 |

## 영향 범위
- **참조 코드**: `file_path:line` - 수정이 필요한 위치 설명
- **의존 테이블**: `related_table` - 외래 키 제약 상세
- **ORM 모델**: `model_file:line` - 수정이 필요한 모델 정의

## UP 마이그레이션
```sql
-- 적용 SQL
BEGIN;
-- DDL statements here
COMMIT;
```

## DOWN 마이그레이션 (롤백)
```sql
-- 롤백 SQL
BEGIN;
-- Rollback DDL statements here
COMMIT;
```

## 사전 점검 SQL
```sql
-- 실행 전 확인해야 할 쿼리
SELECT COUNT(*) FROM target_table;
```

## 실행 후 검증 SQL
```sql
-- 실행 후 데이터 정합성 확인
SELECT column_name, COUNT(*) FROM target_table GROUP BY column_name;
```

## 롤백 계획
| 판단 기준    | 임계값    | 대응    |
| -------- | ------ | ----- |
| 실행 시간 초과 | N 분 이상 | 롤백 실행 |
| 오류율 증가   | N% 이상  | 롤백 실행 |
| 데이터 불일치  | 발견 즉시  | 롤백 실행 |

## 실행 체크리스트
- [ ] 데이터베이스 백업 완료
- [ ] 복제 지연(Replica Lag) 0초 확인
- [ ] 유지보수 시간 사전 공지 완료
- [ ] 롤백 SQL 사전 테스트 완료
- [ ] 관련 애플리케이션 배포 준비 완료

## 리뷰 중점 사항
1. [확인해야 할 핵심 항목]
2. [잠재적 리스크]
```

## 안전 수칙

- **실제 SQL을 실행하지 말 것** — 본 스킬은 초안 작성만 수행한다  
- **운영 데이터베이스에 직접 연결하지 말 것**  
- **DROP / TRUNCATE / DELETE를 포함하는 변경은 반드시 롤백 불가로 명시할 것**  
- **100만 행 초과 테이블의 ALTER TABLE은 온라인 DDL 방식을 필수로 제안할 것**  
- **데이터 타입 축소 변경은 암묵적 데이터 손실 가능성을 반드시 경고할 것**  
- **NOT NULL 제약 추가 시 기존 NULL 데이터 처리 절차를 반드시 포함할 것**  
- **외래 키 제약 변경 시 참조 무결성 영향 분석을 반드시 수행할 것**

---

## 종료 조건

- UP / DOWN 마이그레이션 SQL이 모두 작성되어 있을 것  
- 영향을 받는 코드 위치가 모두 식별되어 있을 것  
- 롤백 계획에 판단 기준과 절차가 포함되어 있을 것  
- 실행 전 체크리스트가 작성되어 있을 것  
- 실행 후 검증 쿼리가 작성되어 있을 것  
- 파괴적 변경 여부가 명확히 표시되어 있을 것  

---

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

- **운영 환경에 직접 적용하는 경우**: 작성된 SQL을 그대로 운영 DB에 실행하지 말 것. 반드시 DBA 또는 팀 리뷰를 거쳐야 한다  
- **스키마 설계 자체를 대신하는 경우**: 정규화 수준, 데이터 타입 선정 등 설계 판단은 사람이 수행해야 한다. 본 스킬은 “이미 결정된 변경을 안전하게 실행하기 위한 계획 수립”에 목적이 있다