feat: Alembic 초기 마이그레이션 설정

- Dockerfile에 alembic.ini 및 alembic 디렉토리 복사 추가
- 초기 마이그레이션 생성 (items 테이블)
- plan.md에 Alembic 기본 개념 및 사용법 문서화
  - 핵심 개념: Migration, Revision, upgrade/downgrade
  - 주요 명령어 정리
  - 마이그레이션 파일 구조 설명
  - 환경 설정 방법

학습 내용:
- Alembic은 SQLAlchemy 기반 DB 마이그레이션 도구
- revision --autogenerate로 모델 변경 자동 감지
- upgrade/downgrade로 스키마 버전 관리
- 각 마이그레이션은 고유 revision ID로 추적

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

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

Author: f-lab-piz

Dockerfile

@@ -11,8 +11,10 @@ RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
-# 애플리케이션 코드 복사 (app 디렉토리만)
+# 애플리케이션 코드 복사
 COPY app ./app
+COPY alembic.ini .
+COPY alembic ./alembic
 
 # 포트 8000 노출
 EXPOSE 8000

alembic/versions/0fee3ec0c79f_initial_migration_create_items_table.py

@@ -0,0 +1,39 @@
+"""Initial migration: create items table
+
+Revision ID: 0fee3ec0c79f
+Revises: 
+Create Date: 2025-10-10 02:45:22.418966
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '0fee3ec0c79f'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('items',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('name', sa.String(), nullable=True),
+    sa.Column('description', sa.String(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=True),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=True),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_items_id'), 'items', ['id'], unique=False)
+    op.create_index(op.f('ix_items_name'), 'items', ['name'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_items_name'), table_name='items')
+    op.drop_index(op.f('ix_items_id'), table_name='items')
+    op.drop_table('items')
+    # ### end Alembic commands ###

plan.md

@@ -51,8 +51,70 @@ locust
   - DeploymentTestUser: 무중단 배포 검증
   - StressTestUser: 스트레스 테스트
 
+### 6단계: Alembic 데이터베이스 마이그레이션 ⏳
+#### 6-1. Alembic 기본 개념 ✅
+Alembic은 SQLAlchemy를 위한 데이터베이스 마이그레이션 도구입니다.
+
+**핵심 개념:**
+- **마이그레이션 (Migration)**: 데이터베이스 스키마 변경을 추적하는 버전 관리 시스템
+- **Revision**: 각 마이그레이션의 고유 ID (예: 0fee3ec0c79f)
+- **upgrade()**: 스키마를 최신 버전으로 업데이트하는 함수
+- **downgrade()**: 이전 버전으로 롤백하는 함수
+
+**주요 명령어:**
+```bash
+# 마이그레이션 파일 자동 생성 (모델 변경 감지)
+alembic revision --autogenerate -m "설명"
+
+# 데이터베이스에 마이그레이션 적용
+alembic upgrade head
+
+# 한 단계 롤백
+alembic downgrade -1
+
+# 현재 마이그레이션 상태 확인
+alembic current
+
+# 마이그레이션 히스토리 확인
+alembic history
+```
+
+**마이그레이션 파일 구조:**
+- `alembic/versions/` 디렉토리에 생성됨
+- 파일명: `{revision_id}_{message}.py`
+- upgrade() 함수: 스키마 변경 적용
+- downgrade() 함수: 변경 사항 되돌리기
+
+**환경 설정:**
+- `alembic/env.py`: Alembic 환경 설정 (DB 연결 등)
+- `alembic.ini`: Alembic 설정 파일
+- DATABASE_URL 환경변수로 DB 연결 정보 제공
+
+**초기 마이그레이션 생성:**
+1. Dockerfile에 alembic 파일 복사 추가
+2. 로컬에서 마이그레이션 생성: `python3 -m alembic revision --autogenerate -m "Initial migration"`
+3. 생성된 파일 확인: `alembic/versions/0fee3ec0c79f_initial_migration_create_items_table.py`
+
+**생성된 마이그레이션 내용:**
+- items 테이블 생성
+- id (PK), name, description 컬럼
+- created_at, updated_at 타임스탬프
+- name, id에 인덱스 생성
+
+#### 6-2. 스키마 변경 실습
+- [ ] Item 모델에 컬럼 추가 (price, stock)
+- [ ] 마이그레이션 생성 및 적용
+- [ ] upgrade/downgrade 테스트
+
+#### 6-3. 무중단 배포 통합
+- [ ] deploy.sh에 마이그레이션 자동화
+- [ ] 배포 전 마이그레이션 실행
+- [ ] 실패 시 롤백 로직
+
+#### 6-4. 데이터 마이그레이션
+- [ ] 데이터 변환 마이그레이션 작성
+- [ ] op.execute() 사용법
+
 ### 다음 단계 계획
-- [ ] 데이터베이스 마이그레이션 자동화
-- [ ] 배포 스크립트 개선 (롤백 기능)
 - [ ] 모니터링 및 로깅 추가
 - [ ] 실제 배포 테스트 및 문서화