quant/penti
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
penti/QUICKSTART_MIGRATION.md

9.9 KiB
Raw Blame History

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

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

1️⃣ 사전 확인

MySQL 정보 확인

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

# 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 준비

# 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: 로컬에서 실행 (권장)

# 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 컨테이너에서 실행

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

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

3️⃣ 마이그레이션 실행

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

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

# 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: 전체 마이그레이션

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

# 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에 접근하는 경우:

# 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로 확인

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

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

방법 2: PostgreSQL 직접 확인

# 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: 샘플 데이터 확인

-- 종목 샘플 조회
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

해결:

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

# 또는 MySQL Workbench로 연결 테스트

비밀번호 오류

오류: Access denied for user

해결:

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

Python 모듈 없음

오류: ModuleNotFoundError: No module named 'pymysql'

해결:

pip install pymysql pandas tqdm sqlalchemy psycopg2-binary

PostgreSQL 연결 오류

오류: could not connect to server

해결:

# PostgreSQL 컨테이너 상태 확인
docker-compose ps postgres

# PostgreSQL 재시작
docker-compose restart postgres

중단 후 재시작

마이그레이션이 중단되었다면:

  • 걱정 마세요! UPSERT 방식이므로 재실행 가능
  • 같은 명령어를 다시 실행하면 이어서 진행됩니다
  • 기존 데이터는 업데이트, 신규 데이터는 삽입

7️⃣ 실제 예시

예시 1: 로컬 MySQL → Docker PostgreSQL

# 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 데이터

# 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. 백테스트 실행:

    curl -X POST http://localhost:8000/api/v1/backtest/run \
  -H "Content-Type: application/json" \
  -d @samples/backtest_config.json

  2. 포트폴리오 생성:

    curl -X POST http://localhost:8000/api/v1/portfolios/ \
  -H "Content-Type: application/json" \
  -d @samples/portfolio_create.json

  3. Frontend 확인:

📌 체크리스트

마이그레이션 전:

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

마이그레이션 중:

  • 진행 상황 모니터링
  • 에러 발생 시 로그 확인

마이그레이션 후:

  • 데이터 개수 확인
  • 샘플 데이터 조회
  • 백테스트 테스트
  • MySQL 데이터 백업 (원본 보존)

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