penti/docs/QUICKSTART_MIGRATION.md

# 마이그레이션 빠른 시작 가이드

make-quant-py의 MySQL 데이터를 PostgreSQL로 마이그레이션하는 실행 가이드입니다.

## 1️⃣ 사전 확인

### MySQL 정보 확인

make-quant-py 프로젝트의 MySQL 연결 정보를 확인하세요:

```bash
# make-quant-py 디렉토리로 이동
cd C:\Users\zephy\workspace\quant\make-quant-py

# .env 또는 설정 파일 확인
# MySQL 호스트, 사용자, 비밀번호, 데이터베이스명 메모
```

필요한 정보:
- MySQL 호스트: (예: `localhost` 또는 `127.0.0.1`)
- MySQL 포트: (기본값: `3306`)
- MySQL 사용자: (예: `root`)
- MySQL 비밀번호
- MySQL 데이터베이스: (예: `quant`)

### PostgreSQL 준비

```bash
# pension-quant-platform 디렉토리로 이동
cd C:\Users\zephy\workspace\quant\pension-quant-platform

# Docker 서비스 시작
docker-compose up -d postgres

# 데이터베이스 마이그레이션 (테이블 생성)
docker-compose exec backend alembic upgrade head
```

## 2️⃣ Python 환경 준비

### 옵션 A: 로컬에서 실행 (권장)

```bash
# pension-quant-platform 디렉토리에서
cd C:\Users\zephy\workspace\quant\pension-quant-platform

# 가상환경 활성화 (있는 경우)
# Windows:
# .venv\Scripts\activate
# Linux/Mac:
# source .venv/bin/activate

# 필요한 패키지 설치
pip install pymysql pandas tqdm sqlalchemy psycopg2-binary

# 또는 requirements 사용
pip install -r backend/requirements.txt
```

### 옵션 B: Docker 컨테이너에서 실행

```bash
# Docker 백엔드 컨테이너에 접속
docker-compose exec backend bash

# 컨테이너 내부에서 실행 (패키지는 이미 설치됨)
```

## 3️⃣ 마이그레이션 실행

### 방법 1: 테스트 마이그레이션 (일부 데이터만)

먼저 소량의 데이터로 테스트해보는 것을 권장합니다:

```bash
# Windows (CMD)
python scripts\migrate_mysql_to_postgres.py ^
  --mysql-host localhost ^
  --mysql-user root ^
  --mysql-password YOUR_PASSWORD ^
  --mysql-database quant ^
  --price-limit 10000 ^
  --fs-limit 10000

# Windows (PowerShell)
python scripts/migrate_mysql_to_postgres.py `
  --mysql-host localhost `
  --mysql-user root `
  --mysql-password YOUR_PASSWORD `
  --mysql-database quant `
  --price-limit 10000 `
  --fs-limit 10000

# Linux/Mac
python scripts/migrate_mysql_to_postgres.py \
  --mysql-host localhost \
  --mysql-user root \
  --mysql-password YOUR_PASSWORD \
  --mysql-database quant \
  --price-limit 10000 \
  --fs-limit 10000
```

**설명**:
- `--price-limit 10000`: 주가 데이터 10,000건만 마이그레이션
- `--fs-limit 10000`: 재무제표 데이터 10,000건만 마이그레이션
- 종목 데이터는 전체 마이그레이션 (보통 2,000-3,000개)

**예상 소요 시간**: 5-10분

### 방법 2: 전체 마이그레이션

테스트가 성공하면 전체 데이터 마이그레이션:

```bash
# Windows (CMD)
python scripts\migrate_mysql_to_postgres.py ^
  --mysql-host localhost ^
  --mysql-user root ^
  --mysql-password YOUR_PASSWORD ^
  --mysql-database quant

# Windows (PowerShell)
python scripts/migrate_mysql_to_postgres.py `
  --mysql-host localhost `
  --mysql-user root `
  --mysql-password YOUR_PASSWORD `
  --mysql-database quant

# Linux/Mac
python scripts/migrate_mysql_to_postgres.py \
  --mysql-host localhost \
  --mysql-user root \
  --mysql-password YOUR_PASSWORD \
  --mysql-database quant
```

**예상 소요 시간**:
- 100만 레코드: 30분-1시간
- 500만 레코드: 2-3시간
- 1,000만+ 레코드: 4-6시간

### 방법 3: Docker 컨테이너에서 실행

호스트의 MySQL에 접근하는 경우:

```bash
# Docker 컨테이너 접속
docker-compose exec backend bash

# 컨테이너 내부에서 실행
python /app/scripts/migrate_mysql_to_postgres.py \
  --mysql-host host.docker.internal \
  --mysql-user root \
  --mysql-password YOUR_PASSWORD \
  --mysql-database quant
```

**주의**: `host.docker.internal`은 Docker Desktop (Windows/Mac)에서 호스트를 가리킵니다.

## 4️⃣ 진행 상황 확인

마이그레이션이 실행되면 다음과 같은 출력을 볼 수 있습니다:

```
============================================================
MySQL → PostgreSQL 데이터 마이그레이션 시작
시작 시간: 2025-01-29 15:30:00
============================================================

=== 종목 데이터 마이그레이션 시작 ===
MySQL에서 2,547개 종목 데이터 읽기 완료
종목 데이터 저장: 100%|████████████| 2547/2547 [00:18<00:00, 141.50it/s]
종목 데이터 마이그레이션 완료: 2,547개

=== 주가 데이터 마이그레이션 시작 ===
전체 주가 레코드 수: 4,832,156개
배치 1: 10,000개 레코드 처리 중...
주가 데이터 저장: 100%|████████████| 10000/10000 [01:25<00:00, 117.15it/s]
배치 2: 10,000개 레코드 처리 중...
...
```

## 5️⃣ 마이그레이션 검증

마이그레이션 완료 후 데이터를 확인하세요:

### 방법 1: API로 확인

```bash
# 데이터베이스 통계 조회
curl http://localhost:8000/api/v1/data/stats

# 응답 예시:
{
  "ticker_count": 2547,
  "price_count": 4832156,
  "financial_count": 2145789,
  "sector_count": 0
}
```

### 방법 2: PostgreSQL 직접 확인

```bash
# PostgreSQL 접속
docker-compose exec postgres psql -U postgres -d pension_quant

# 테이블 레코드 수 확인
SELECT 'assets' as table_name, COUNT(*) FROM assets
UNION ALL
SELECT 'price_data', COUNT(*) FROM price_data
UNION ALL
SELECT 'financial_statements', COUNT(*) FROM financial_statements;

# 종료
\q
```

### 방법 3: 샘플 데이터 확인

```sql
-- 종목 샘플 조회
SELECT ticker, name, market, sector
FROM assets
LIMIT 10;

-- 최근 주가 데이터
SELECT ticker, timestamp, close
FROM price_data
ORDER BY timestamp DESC
LIMIT 10;

-- 재무제표 샘플
SELECT ticker, account, base_date, value
FROM financial_statements
LIMIT 10;
```

## 6️⃣ 문제 해결

### 연결 오류

**오류**: `Can't connect to MySQL server`

**해결**:
```bash
# MySQL 서버 실행 확인
# Windows (MySQL이 서비스로 실행 중인 경우)
sc query MySQL80  # 또는 MySQL 서비스명

# 또는 MySQL Workbench로 연결 테스트
```

### 비밀번호 오류

**오류**: `Access denied for user`

**해결**:
- MySQL 사용자명과 비밀번호 확인
- make-quant-py 설정 파일에서 확인

### Python 모듈 없음

**오류**: `ModuleNotFoundError: No module named 'pymysql'`

**해결**:
```bash
pip install pymysql pandas tqdm sqlalchemy psycopg2-binary
```

### PostgreSQL 연결 오류

**오류**: `could not connect to server`

**해결**:
```bash
# PostgreSQL 컨테이너 상태 확인
docker-compose ps postgres

# PostgreSQL 재시작
docker-compose restart postgres
```

### 중단 후 재시작

마이그레이션이 중단되었다면:
- **걱정 마세요!** UPSERT 방식이므로 재실행 가능
- 같은 명령어를 다시 실행하면 이어서 진행됩니다
- 기존 데이터는 업데이트, 신규 데이터는 삽입

## 7️⃣ 실제 예시

### 예시 1: 로컬 MySQL → Docker PostgreSQL

```bash
# 1. PostgreSQL 준비
docker-compose up -d postgres
docker-compose exec backend alembic upgrade head

# 2. 테스트 마이그레이션 (10,000건)
python scripts/migrate_mysql_to_postgres.py \
  --mysql-host localhost \
  --mysql-user root \
  --mysql-password mypassword \
  --mysql-database quant \
  --price-limit 10000 \
  --fs-limit 10000

# 3. 검증
curl http://localhost:8000/api/v1/data/stats

# 4. 성공하면 전체 마이그레이션
python scripts/migrate_mysql_to_postgres.py \
  --mysql-host localhost \
  --mysql-user root \
  --mysql-password mypassword \
  --mysql-database quant
```

### 예시 2: 실제 make-quant-py 데이터

```bash
# make-quant-py의 실제 설정 사용
cd C:\Users\zephy\workspace\quant\pension-quant-platform

python scripts/migrate_mysql_to_postgres.py \
  --mysql-host localhost \
  --mysql-user root \
  --mysql-password YOUR_ACTUAL_PASSWORD \
  --mysql-database quant

# 예상 출력:
# ============================================================
# MySQL → PostgreSQL 데이터 마이그레이션 시작
# 시작 시간: 2025-01-29 16:00:00
# ============================================================
#
# === 종목 데이터 마이그레이션 시작 ===
# MySQL에서 2,547개 종목 데이터 읽기 완료
# 종목 데이터 저장: 100%|████████████| 2547/2547
# 종목 데이터 마이그레이션 완료: 2,547개
#
# === 주가 데이터 마이그레이션 시작 ===
# 전체 주가 레코드 수: 4,832,156개
# ...
# 주가 데이터 마이그레이션 완료: 4,832,156개
#
# === 재무제표 데이터 마이그레이션 시작 ===
# 전체 재무제표 레코드 수: 2,145,789개
# ...
# 재무제표 데이터 마이그레이션 완료: 2,145,789개
#
# ============================================================
# 마이그레이션 완료!
# 종료 시간: 2025-01-29 18:15:00
# 소요 시간: 2:15:00
# ============================================================
```

## 8️⃣ 다음 단계

마이그레이션 완료 후:

1. **백테스트 실행**:
   ```bash
   curl -X POST http://localhost:8000/api/v1/backtest/run \
     -H "Content-Type: application/json" \
     -d @samples/backtest_config.json
   ```

2. **포트폴리오 생성**:
   ```bash
   curl -X POST http://localhost:8000/api/v1/portfolios/ \
     -H "Content-Type: application/json" \
     -d @samples/portfolio_create.json
   ```

3. **Frontend 확인**:
   - http://localhost:3000

## 📌 체크리스트

마이그레이션 전:
- [ ] MySQL 연결 정보 확인
- [ ] PostgreSQL Docker 실행 중
- [ ] Alembic 마이그레이션 완료
- [ ] Python 패키지 설치

마이그레이션 중:
- [ ] 진행 상황 모니터링
- [ ] 에러 발생 시 로그 확인

마이그레이션 후:
- [ ] 데이터 개수 확인
- [ ] 샘플 데이터 조회
- [ ] 백테스트 테스트
- [ ] MySQL 데이터 백업 (원본 보존)

---

**문서 버전**: v1.0.0
**최종 업데이트**: 2025-01-29