sapiens-web3/scripts

데이터 Export/Import 가이드

📋 개요

이 스크립트들은 SAPIENS 데이터베이스의 모든 데이터를 JSON 파일로 export하고, 다른 PostgreSQL 데이터베이스로 import할 수 있게 해줍니다.

📁 파일 설명

• export-data.ts - 현재 데이터베이스의 모든 데이터를 JSON 파일로 export
• import-data.ts - JSON 파일의 데이터를 새 PostgreSQL 데이터베이스로 import
• README.md - 이 가이드 문서

🚀 사용 방법

1. 데이터 Export (내보내기)

현재 데이터베이스의 모든 데이터를 JSON 파일로 저장합니다.

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 사용)

npx tsx scripts/import-data.ts data-export-2025-10-13.json

방법 2: 새 데이터베이스 URL 직접 지정

npx tsx scripts/import-data.ts data-export-2025-10-13.json "postgresql://user:password@host:5432/database"

예시:

# 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 파일 구조

{
  "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. 대상 데이터베이스에 스키마가 생성되어 있어야 합니다:

   # 새 데이터베이스에서 먼저 실행
   npm run db:push
   

2. 데이터베이스가 비어있거나, 중복을 허용해야 합니다:

   • Import 스크립트는 onConflictDoNothing() 사용
   • 같은 ID의 레코드가 있으면 skip됨

3. 의존성 순서 보장:

   • 스크립트가 자동으로 테이블 간 의존성 순서대로 import
   • Users → Media Outlets → Articles → ... 순서로 진행

데이터 안전성

• ✅ Export는 읽기 전용 (원본 데이터 변경 없음)
• ✅ Import는 onConflictDoNothing() 사용 (기존 데이터 보존)
• ✅ 트랜잭션 없음 (부분 import 가능)
• ✅ 진행 상황 실시간 표시

🔧 문제 해결

Export 실패 시

# 데이터베이스 연결 확인
echo $DATABASE_URL

# 데이터베이스 상태 확인
npm run db:push

Import 실패 시

에러: "No database URL provided"

# DATABASE_URL 환경 변수 설정 후 다시 시도
export DATABASE_URL="postgresql://..."
npx tsx scripts/import-data.ts data-export-2025-10-13.json

에러: "Table does not exist"

# 대상 데이터베이스에 스키마 생성
npm run db:push

에러: "Foreign key constraint"

• 의존성 순서 문제 (스크립트가 자동 처리하지만, 수동 수정 시 발생 가능)
• 테이블을 순서대로 import하는지 확인

📝 사용 예시

시나리오 1: 백업 생성

# 매일 백업 생성
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: 개발 → 프로덕션 데이터 이전

# 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: 데이터베이스 마이그레이션

# 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: 로컬 개발용 데이터 복사

# 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분 소요 (네트워크 속도에 따라 다름)