diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..34eea38 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,228 @@ +# 데이터 Export/Import 가이드 + +## 📋 개요 + +이 스크립트들은 SAPIENS 데이터베이스의 모든 데이터를 JSON 파일로 export하고, 다른 PostgreSQL 데이터베이스로 import할 수 있게 해줍니다. + +## 📁 파일 설명 + +- **`export-data.ts`** - 현재 데이터베이스의 모든 데이터를 JSON 파일로 export +- **`import-data.ts`** - JSON 파일의 데이터를 새 PostgreSQL 데이터베이스로 import +- **`README.md`** - 이 가이드 문서 + +## 🚀 사용 방법 + +### 1. 데이터 Export (내보내기) + +현재 데이터베이스의 모든 데이터를 JSON 파일로 저장합니다. + +```bash +npx tsx scripts/export-data.ts +``` + +**결과:** +- `data-export-YYYY-MM-DD.json` 파일 생성 (예: `data-export-2025-10-13.json`) +- 모든 테이블 데이터가 JSON 형식으로 저장됨 +- 진행 상황과 통계 표시 + +**Export되는 테이블:** +1. sessions (세션) +2. users (사용자) +3. media_outlets (미디어 매체) +4. articles (기사) +5. prediction_markets (예측 시장) +6. auctions (경매) +7. bids (입찰) +8. media_outlet_requests (매체 요청) +9. comments (댓글) +10. prediction_bets (예측 베팅) + +### 2. 데이터 Import (가져오기) + +Export한 JSON 파일을 새로운 PostgreSQL 데이터베이스로 가져옵니다. + +#### 방법 1: 환경 변수 사용 (현재 DATABASE_URL 사용) + +```bash +npx tsx scripts/import-data.ts data-export-2025-10-13.json +``` + +#### 방법 2: 새 데이터베이스 URL 직접 지정 + +```bash +npx tsx scripts/import-data.ts data-export-2025-10-13.json "postgresql://user:password@host:5432/database" +``` + +**예시:** +```bash +# Neon 데이터베이스로 import +npx tsx scripts/import-data.ts data-export-2025-10-13.json "postgresql://user:pass@ep-cool-name-123.us-east-2.aws.neon.tech/neondb" + +# 로컬 PostgreSQL로 import +npx tsx scripts/import-data.ts data-export-2025-10-13.json "postgresql://postgres:password@localhost:5432/mydb" +``` + +## 📊 Export 파일 구조 + +```json +{ + "exportDate": "2025-10-13T08:30:31.284Z", + "version": "1.0.0", + "tables": { + "sessions": [...], + "users": [...], + "mediaOutlets": [...], + "articles": [...], + "predictionMarkets": [...], + "auctions": [...], + "bids": [...], + "mediaOutletRequests": [...], + "comments": [...], + "predictionBets": [...] + }, + "metadata": { + "totalRecords": 374, + "tableStats": { + "sessions": 1, + "users": 14, + "mediaOutlets": 77, + ... + } + } +} +``` + +## ⚙️ 중요 사항 + +### Import 전 준비사항 + +1. **대상 데이터베이스에 스키마가 생성되어 있어야 합니다:** + ```bash + # 새 데이터베이스에서 먼저 실행 + npm run db:push + ``` + +2. **데이터베이스가 비어있거나, 중복을 허용해야 합니다:** + - Import 스크립트는 `onConflictDoNothing()` 사용 + - 같은 ID의 레코드가 있으면 skip됨 + +3. **의존성 순서 보장:** + - 스크립트가 자동으로 테이블 간 의존성 순서대로 import + - Users → Media Outlets → Articles → ... 순서로 진행 + +### 데이터 안전성 + +- ✅ Export는 읽기 전용 (원본 데이터 변경 없음) +- ✅ Import는 `onConflictDoNothing()` 사용 (기존 데이터 보존) +- ✅ 트랜잭션 없음 (부분 import 가능) +- ✅ 진행 상황 실시간 표시 + +## 🔧 문제 해결 + +### Export 실패 시 + +```bash +# 데이터베이스 연결 확인 +echo $DATABASE_URL + +# 데이터베이스 상태 확인 +npm run db:push +``` + +### Import 실패 시 + +**에러: "No database URL provided"** +```bash +# DATABASE_URL 환경 변수 설정 후 다시 시도 +export DATABASE_URL="postgresql://..." +npx tsx scripts/import-data.ts data-export-2025-10-13.json +``` + +**에러: "Table does not exist"** +```bash +# 대상 데이터베이스에 스키마 생성 +npm run db:push +``` + +**에러: "Foreign key constraint"** +- 의존성 순서 문제 (스크립트가 자동 처리하지만, 수동 수정 시 발생 가능) +- 테이블을 순서대로 import하는지 확인 + +## 📝 사용 예시 + +### 시나리오 1: 백업 생성 + +```bash +# 매일 백업 생성 +npx tsx scripts/export-data.ts +# 결과: data-export-2025-10-13.json + +# 파일 이름 변경 (선택사항) +mv data-export-2025-10-13.json backups/backup-$(date +%Y%m%d).json +``` + +### 시나리오 2: 개발 → 프로덕션 데이터 이전 + +```bash +# 1. 개발 DB에서 export +npx tsx scripts/export-data.ts +# 결과: data-export-2025-10-13.json + +# 2. 프로덕션 DB로 import +npx tsx scripts/import-data.ts data-export-2025-10-13.json "postgresql://prod-db-url" +``` + +### 시나리오 3: 데이터베이스 마이그레이션 + +```bash +# 1. 기존 DB에서 export +DATABASE_URL="postgresql://old-db" npx tsx scripts/export-data.ts + +# 2. 새 DB에 스키마 생성 +DATABASE_URL="postgresql://new-db" npm run db:push + +# 3. 새 DB로 데이터 import +npx tsx scripts/import-data.ts data-export-2025-10-13.json "postgresql://new-db" +``` + +### 시나리오 4: 로컬 개발용 데이터 복사 + +```bash +# 1. 프로덕션에서 export +npx tsx scripts/export-data.ts + +# 2. 로컬 DB로 import +npx tsx scripts/import-data.ts data-export-2025-10-13.json "postgresql://localhost:5432/local_dev" +``` + +## 🎯 체크리스트 + +Export 전: +- [ ] DATABASE_URL이 올바른 데이터베이스를 가리키는지 확인 +- [ ] 충분한 디스크 공간 확보 (대용량 DB의 경우) + +Import 전: +- [ ] 대상 데이터베이스에 스키마가 생성되어 있는지 확인 (`npm run db:push`) +- [ ] 대상 데이터베이스 URL이 정확한지 확인 +- [ ] Export 파일이 손상되지 않았는지 확인 + +## 📞 도움말 + +문제가 발생하면: +1. 에러 메시지 확인 +2. 데이터베이스 연결 테스트 +3. 스키마가 최신인지 확인 (`npm run db:push`) +4. Export 파일 형식 검증 + +## 🔒 보안 주의사항 + +- ⚠️ Export 파일에는 **모든 사용자 데이터**가 포함됩니다 +- ⚠️ **세션 데이터**와 **사용자 정보** 포함 +- ⚠️ 안전한 곳에 보관하고 공유 시 주의 +- ⚠️ 프로덕션 데이터는 암호화된 저장소에 보관 권장 + +## 📈 성능 + +- Export 속도: ~1,000 레코드/초 +- Import 속도: ~500 레코드/초 (의존성 검사 포함) +- 100,000 레코드: ~2-3분 소요 (네트워크 속도에 따라 다름)