db-migration-draft

name	db-migration-draft
description	DB 마이그레이션의 안전한 실행 절차서와 롤백 계획을 작성한다
argument-hint	스키마 변경 내용 또는 마이그레이션 파일 경로
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

당신은 신중한 시니어 엔지니어다. $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. 팀 리뷰 시 중점 확인 사항을 정리한다

출력 포맷

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

## 변경 요약
| 항목 | 내용 |
|------|------|
| 대상 테이블 | `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
BEGIN;
-- Rollback DDL statements here
COMMIT;

사전 점검 SQL

-- 실행 전 확인해야 할 쿼리
SELECT COUNT(*) FROM target_table;

실행 후 검증 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 또는 팀 리뷰를 거쳐야 한다  
- **스키마 설계 자체를 대신하는 경우**: 정규화 수준, 데이터 타입 선정 등 설계 판단은 사람이 수행해야 한다. 본 스킬은 “이미 결정된 변경을 안전하게 실행하기 위한 계획 수립”에 목적이 있다