feat: 데이터 마이그레이션 작성

- NULL 값을 기본값으로 변환하는 데이터 마이그레이션 추가
- op.execute()를 사용한 직접 SQL 실행 예제
- plan.md에 데이터 마이그레이션 작성법 상세 문서화

마이그레이션 내용:
- stock이 NULL인 행을 0으로 업데이트
- price가 NULL인 행을 1000.00으로 업데이트

학습 내용:
- 스키마 마이그레이션 vs 데이터 마이그레이션 차이
- op.execute()로 복잡한 SQL 실행 가능
- 데이터 마이그레이션은 --autogenerate 없이 수동 작성
- downgrade 작성의 어려움과 백업의 중요성

op.execute() 사용 예시:
1. 직접 SQL 실행
2. 멀티라인 쿼리
3. 여러 SQL 문 순차 실행
4. 조건부 실행 (connection.execute)

주의사항:
- 대용량 데이터는 배치 처리 고려
- Alembic 트랜잭션 내에서 실행되어 실패 시 자동 롤백
- 프로덕션 적용 전 스테이징 환경에서 반드시 테스트

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: f-lab-piz

alembic/versions/f25407aec7a2_set_default_values_for_existing_items.py

@@ -0,0 +1,38 @@
+"""Set default values for existing items
+
+Revision ID: f25407aec7a2
+Revises: 211d1fe6d912
+Create Date: 2025-10-10 02:55:21.896633
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = 'f25407aec7a2'
+down_revision = '211d1fe6d912'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 기존 아이템의 stock이 NULL인 경우 0으로 설정
+    op.execute("""
+        UPDATE items
+        SET stock = 0
+        WHERE stock IS NULL
+    """)
+
+    # 기존 아이템의 price가 NULL인 경우 1000.00으로 설정 (예시 기본값)
+    op.execute("""
+        UPDATE items
+        SET price = 1000.00
+        WHERE price IS NULL
+    """)
+
+
+def downgrade() -> None:
+    # downgrade 시에는 데이터를 되돌리지 않음
+    # 실제 프로덕션에서는 신중하게 결정해야 함
+    pass

plan.md

@@ -234,9 +234,114 @@ docker-compose run --rm app1 alembic current
 - nullable 컬럼으로 하위 호환성 유지
 - 실패 시 자동 중단으로 안전성 확보
 
-#### 6-4. 데이터 마이그레이션
-- [ ] 데이터 변환 마이그레이션 작성
-- [ ] op.execute() 사용법
+#### 6-4. 데이터 마이그레이션 ✅
+스키마 변경이 아닌 데이터 변환을 위한 마이그레이션을 작성했습니다.
+
+**시나리오:**
+- 이전 마이그레이션에서 price, stock 컬럼을 nullable로 추가
+- 기존 데이터에는 NULL 값이 들어있음
+- 이 마이그레이션에서 기본값을 설정
+
+**마이그레이션 생성:**
+```bash
+# --autogenerate 없이 수동 생성 (데이터 변환이므로)
+alembic revision -m "Set default values for existing items"
+```
+
+**작성한 데이터 마이그레이션 (f25407aec7a2):**
+```python
+def upgrade() -> None:
+    # 기존 아이템의 stock이 NULL인 경우 0으로 설정
+    op.execute("""
+        UPDATE items
+        SET stock = 0
+        WHERE stock IS NULL
+    """)
+
+    # 기존 아이템의 price가 NULL인 경우 1000.00으로 설정
+    op.execute("""
+        UPDATE items
+        SET price = 1000.00
+        WHERE price IS NULL
+    """)
+
+
+def downgrade() -> None:
+    # downgrade 시에는 데이터를 되돌리지 않음
+    # 실제 프로덕션에서는 신중하게 결정해야 함
+    pass
+```
+
+**op.execute() 사용법:**
+
+1. **직접 SQL 실행**
+   ```python
+   op.execute("UPDATE items SET stock = 0 WHERE stock IS NULL")
+   ```
+
+2. **복잡한 쿼리 (멀티라인)**
+   ```python
+   op.execute("""
+       UPDATE items
+       SET price = CASE
+           WHEN category = 'premium' THEN 5000
+           ELSE 1000
+       END
+       WHERE price IS NULL
+   """)
+   ```
+
+3. **여러 SQL 문 실행**
+   ```python
+   op.execute("INSERT INTO logs (message) VALUES ('Migration started')")
+   op.execute("UPDATE items SET status = 'active'")
+   op.execute("INSERT INTO logs (message) VALUES ('Migration completed')")
+   ```
+
+4. **조건부 실행**
+   ```python
+   from sqlalchemy import text
+
+   connection = op.get_bind()
+   result = connection.execute(text("SELECT COUNT(*) FROM items"))
+   count = result.scalar()
+
+   if count > 0:
+       op.execute("UPDATE items SET stock = 0 WHERE stock IS NULL")
+   ```
+
+**데이터 마이그레이션 vs 스키마 마이그레이션:**
+
+| 구분 | 스키마 마이그레이션 | 데이터 마이그레이션 |
+|------|---------------------|---------------------|
+| 목적 | 테이블/컬럼 구조 변경 | 데이터 변환/정제 |
+| 생성 방법 | --autogenerate | 수동 작성 |
+| 예시 | CREATE TABLE, ADD COLUMN | UPDATE, INSERT |
+| 롤백 | 자동 생성 | 수동 작성 필요 |
+
+**주의사항:**
+
+1. **성능 고려**
+   - 대용량 데이터는 배치 처리 고려
+   - 인덱스가 없는 컬럼 업데이트 시 느릴 수 있음
+
+2. **트랜잭션**
+   - Alembic은 기본적으로 트랜잭션 안에서 실행
+   - 실패 시 자동 롤백됨
+
+3. **downgrade 작성**
+   - 데이터 마이그레이션의 downgrade는 복잡
+   - 실제로는 백업 후 복원하는 것이 안전
+
+4. **테스트**
+   - 프로덕션 적용 전 반드시 스테이징 환경에서 테스트
+   - 데이터 양에 따른 실행 시간 측정
+
+**학습 포인트:**
+- op.execute()로 직접 SQL 실행 가능
+- 스키마 변경과 데이터 변환을 분리하는 것이 안전
+- 데이터 마이그레이션은 수동 작성이 필요
+- downgrade는 항상 가능한 것은 아님 (특히 데이터 삭제 시)
 
 ### 다음 단계 계획
 - [ ] 모니터링 및 로깅 추가