404 lines
9.9 KiB
Markdown
404 lines
9.9 KiB
Markdown
# 마이그레이션 빠른 시작 가이드
|
||
|
||
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
|