db-backfill-plan

name	db-backfill-plan
description	기존 데이터 수정·보완(백필)을 단계적으로 실행하기 위한 계획을 수립한다
argument-hint	대상 테이블명 또는 백필 요구사항 설명
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

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

실행 모드

• 간단 모드 (기본값): 2번(전략 결정), 3번(SQL 설계), 4번(롤백 계획)만 수행하고 간결한 실행 계획을 반환한다
• 상세 모드: 인자에 --detailed 가 포함되면 6단계 전체를 수행하고 포괄적인 결과를 반환한다

$ARGUMENTS 에 --detailed 가 포함되어 있지 않으면 간단 모드로 실행한다.
간단 모드에서는 출력 포맷 중 해당 섹션만 출력한다.

목적

기존 데이터 수정·보완(백필)을 안전하게 수행하기 위한 단계별 실행 계획을 수립한다.
대량 데이터 업데이트로 인한 서비스 영향은 최소화하고,
롤백 가능한 절차를 포함한 실행 계획을 작성한다.

입력

• 대상 테이블명 및 수정·보완 요구사항
• 현재 스키마 정의
• 관련 마이그레이션 파일 (컬럼 추가 등에 따른 백필인 경우)
• 대상 데이터 조건 및 추정 건수
• 비즈니스 규칙 및 변환 로직 명세

절차

1. 현황 분석

1-1. 대상 테이블의 현재 스키마 정의를 확인한다
1-2. 백필 대상 컬럼의 현재 데이터 분포를 확인하는 분석 쿼리를 준비한다
1-3. 대상 레코드 조건과 추정 건수를 명확히 한다
1-4. 연관 테이블 영향(외래키, 트리거, 뷰 등)을 식별한다
1-5. 변환 원본 데이터의 위치와 신뢰도를 확인한다
1-6. 애플리케이션 코드에서 해당 컬럼을 참조하는 지점을 파악한다

2. 백필 전략 결정

2-1. 배치 크기를 결정한다 (권장: 1,000–10,000건/배치)
2-2. 실행 방식을 선택한다:

• 온라인 백필: 서비스 운영 중 단계적 실행
• 점검 시간 실행: 서비스 중단 시간에 일괄 실행
• 백그라운드 작업: 비동기 워커를 통한 단계적 실행 2-3. 스로틀링(배치 간 대기 시간)을 설정한다 (레플리카 지연 고려)
  2-4. 병렬 실행 수를 결정한다 (테이블 락을 피할 범위 내)
  2-5. 전체 예상 소요 시간을 산출한다

3. 백필 SQL 설계

3-1. 배치 범위 지정이 포함된 UPDATE 문을 설계한다
3-2. 데이터 변환 로직을 SQL로 명확히 표현한다
3-3. 진행 상황 추적 방식을 설계한다 (마지막 처리 ID 기록 등)
3-4. 오류 처리 전략을 설계한다:

• 개별 레코드 오류 시 처리(건너뜀/중단)
• 데드락 발생 시 재시도 전략
• 타임아웃 발생 시 재개 절차 3-5. 각 배치 완료 후 데이터 정합성 검증 쿼리를 설계한다

4. 롤백 계획

4-1. 백필 전 데이터 백업 방법을 수립한다:

• _backup_YYYYMMDD 접미사 테이블 생성
• 대상 컬럼의 기존 값을 보존하는 방식 4-2. 롤백 SQL을 설계한다 (백업 테이블 기반 복구)
  4-3. 부분 롤백(특정 배치만 취소) 절차를 정의한다
  4-4. 롤백 판단 기준을 정의한다:
• 오류율 임계값
• 성능 저하 임계값
• 데이터 불일치 탐지 기준

5. 실행 계획 수립

5-1. 사전 준비 체크리스트를 작성한다
5-2. 단계별 실행 절차를 정의한다:

• Step 0: 백업 수행
• Step 1: 소량 테스트(10–100건)
• Step 2: 중규모 테스트(1,000건)
• Step 3: 전체 배치 실행
• Step 4: 검증 및 완료 확인 5-3. 각 단계의 성공 기준을 정의한다
  5-4. 모니터링 지표를 정의한다 (레플리카 지연, CPU 사용률, 락 대기 등)
  5-5. 긴급 중단 절차를 정의한다
  5-6. 실행 후 정리 절차를 정의한다 (백업 테이블 보관/삭제 등)

6. 애플리케이션 연계

6-1. 백필 중 애플리케이션 동작 영향 분석
6-2. 신·구 데이터 혼재 기간의 처리 전략 수립
6-3. 백필 완료 후 애플리케이션 변경 사항 식별 (예: NOT NULL 제약 추가)
6-4. 필요 시 기능 플래그와의 연계 전략 수립

출력 형식

# 백필 계획: [대상테이블].[대상컬럼]

## 개요
| 항목 | 내용 |
|------|------|
| 대상 테이블 | `table_name` |
| 대상 컬럼 | `column_name` |
| 백필 사유 | [컬럼 추가 / 데이터 정정 / 정규화 등] |
| 추정 대상 건수 | 약 N건 |
| 예상 소요 시간 | 약 N시간 |
| 실행 방식 | 온라인 / 점검 시간 / 백그라운드 |
| 서비스 영향 | 있음(경미) / 없음 |

## 데이터 분석 쿼리
```sql
-- 현재 데이터 분포 확인
SELECT column_name, COUNT(*) FROM table_name GROUP BY column_name;

-- 백필 대상 건수 확인
SELECT COUNT(*) FROM table_name WHERE column_name IS NULL;

백업 절차

-- 백업 테이블 생성
CREATE TABLE table_name_backup_20240601 AS
SELECT id, column_name FROM table_name WHERE column_name IS NULL;

-- 백업 건수 확인
SELECT COUNT(*) FROM table_name_backup_20240601;

백필 SQL

Step 1: 소량 테스트 (10건)

UPDATE table_name
SET column_name = [변환 로직]
WHERE column_name IS NULL
  AND id IN (SELECT id FROM table_name WHERE column_name IS NULL LIMIT 10);

-- 검증
SELECT * FROM table_name WHERE id IN (...);

Step 2: 중규모 테스트 (1000건)

UPDATE table_name
SET column_name = [변환 로직],
    updated_at = NOW()
WHERE column_name IS NULL
  AND id BETWEEN :start_id AND :end_id
LIMIT 1000;

Step 3: 전체 배치 실행

-- 배치 루프 (의사코드)
-- batch_size = 5000
-- sleep_interval = 2 seconds (레플리카 지연 고려)

UPDATE table_name
SET column_name = [변환 로직],
    updated_at = NOW()
WHERE column_name IS NULL
  AND id > :last_processed_id
ORDER BY id
LIMIT :batch_size;

-- 진행 상황 기록
INSERT INTO backfill_progress (table_name, last_id, batch_count, updated_at)
VALUES ('table_name', :last_processed_id, :batch_num, NOW())
ON CONFLICT (table_name) DO UPDATE
SET last_id = EXCLUDED.last_id, batch_count = EXCLUDED.batch_count;

롤백 SQL

-- 백업 테이블 기반 복구
UPDATE table_name t
JOIN table_name_backup_20240601 b ON t.id = b.id
SET t.column_name = b.column_name;

모니터링 지표

지표	정상 범위	경고 임계값	중단 임계값
레플리카 지연	< 1초	> 5초	> 30초
CPU 사용률	< 50%	> 70%	> 90%
락 대기 스레드	0	> 5	> 20
배치 처리 시간	< 10초	> 30초	> 60초
오류율	0%	> 0.1%	> 1%

실행 체크리스트

사전 준비

• 백업 테이블 생성 완료
• 백업 건수와 대상 건수 일치 확인
• 테스트 환경에서 동일 절차 검증 완료
• 레플리카 지연 0초 확인
• 모니터링 대시보드 확인
• 롤백 SQL 즉시 실행 가능 상태

실행 중

• 배치 완료 후 레플리카 지연 확인
• 오류 발생 시 즉시 중단 후 원인 분석
• 진행 상황 기록 유지

실행 후

• 전체 대상 레코드 업데이트 확인
• 데이터 정합성 검증 쿼리 실행
• 애플리케이션 동작 확인
• 백업 테이블 보관 기간 결정 (권장: 7일)
• 관련 마이그레이션 실행 시점 검토

긴급 중단 절차

1. 배치 작업 즉시 중단
2. 현재 트랜잭션 완료 대기
3. 마지막 처리 ID 확인
4. 필요 시 롤백 SQL 실행
5. 원인 분석 후 계획 수정

과도기 애플리케이션 대응

단계	column_name 상태	애플리케이션 대응
백필 전	NULL 존재	NULL 허용 코드 유지
백필 중	NULL/비NULL 혼재	NULL 허용 유지
백필 후	전부 비NULL	NOT NULL 제약 추가 → 코드 정리

## 안전 주의사항

- **실제 SQL을 실행하지 말 것** — 본 문서는 계획 수립용이다  
- **운영 DB에 접속하지 말 것**
- **백업 없는 백필은 절대 계획하지 말 것**
- 대량 UPDATE는 반드시 배치 분할 전략을 포함할 것
- 레플리카 지연을 고려한 스로틀링을 반드시 포함할 것
- 되돌릴 수 없는(비가역적) 데이터 변환은 반드시 경고할 것
- 운영 데이터의 실제 값은 문서에 기재하지 말 것 (플레이스홀더 사용)

## 종료 조건

- 대상 조건 및 추정 건수가 명확하다  
- 배치 크기와 스로틀링이 결정되었다  
- 백업 및 롤백 전략이 정의되었다  
- 배치 기반 백필 SQL이 설계되었다  
- 단계별 실행 계획이 정의되었다  
- 모니터링 지표 및 임계값이 정의되었다  
- 체크리스트 및 긴급 중단 절차가 포함되었다  
- 과도기 애플리케이션 대응이 정리되었다  

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

- **1,000만 건 이상 대규모 백필**: 본 계획은 초안 수준이다. 반드시 DBA와 협의하고 부하 테스트 후 실행할 것  
- **실시간 쓰기 빈도가 높은 테이블**: 락 경합 및 레플리카 지연을 실측 후 판단할 것