# DB Backfill Plan

> 기존 데이터 수정·보완(백필)을 단계적으로 실행하기 위한 계획을 수립한다

- Skill: `gaebalai-claude-code-kit-ko/db-backfill-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/db-backfill-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/db-backfill-plan/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-backfill-plan

---


당신은 신중한 시니어 엔지니어다. $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. 필요 시 기능 플래그와의 연계 전략 수립  

## 출력 형식

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

## 개요
| 항목 | 내용 |
|------|------|
| 대상 테이블 | `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;
```

## 백업 절차
```sql
-- 백업 테이블 생성
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건)
```sql
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건)
```sql
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: 전체 배치 실행
```sql
-- 배치 루프 (의사코드)
-- 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
```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와 협의하고 부하 테스트 후 실행할 것  
- **실시간 쓰기 빈도가 높은 테이블**: 락 경합 및 레플리카 지연을 실측 후 판단할 것