POSTGRESQL_SETUP_GUIDE.md

PostgreSQL 설정 가이드

현재 SQLite를 사용 중이며, 컨테이너 재시작 시 데이터가 삭제될 수 있습니다. PostgreSQL로 전환하면 데이터가 영구적으로 보존됩니다.

무료 PostgreSQL 서비스 선택

1. Supabase (권장)

• URL: https://supabase.com/
• 무료 티어: 500MB 데이터베이스, 자동 백업
• 장점: 사용하기 쉬움, 자동 백업, 대시보드 제공

2. Neon

• URL: https://neon.tech/
• 무료 티어: 3GB 데이터베이스, 서버리스
• 장점: 빠른 성능, 자동 스케일링

3. Railway

• URL: https://railway.app/
• 무료 티어: $5 크레딧/월
• 장점: 간단한 설정, 다양한 서비스 통합

Supabase 설정 방법 (예시)

1. Supabase 프로젝트 생성

1. https://supabase.com/ 접속 및 로그인
2. "New Project" 클릭
3. 프로젝트 정보 입력:
   • Name: 원하는 프로젝트 이름
   • Database Password: 강력한 비밀번호 생성 (저장해두세요!)
   • Region: 가장 가까운 지역 선택
4. "Create new project" 클릭 (약 2분 소요)

2. 연결 정보 확인

프로젝트 생성 후:

1. Settings > Database 메뉴로 이동
2. Connection string 섹션에서 URI 복사
   • 형식: postgresql://postgres:[YOUR-PASSWORD]@db.xxxxx.supabase.co:5432/postgres
   • [YOUR-PASSWORD]를 실제 비밀번호로 교체

3. Hugging Face Spaces에 환경 변수 설정

1. Hugging Face Spaces 페이지로 이동
2. Settings 탭 클릭
3. Repository secrets 섹션으로 스크롤
4. New secret 클릭
5. 다음 정보 입력:
   • Key: DATABASE_URL
   • Value: Supabase에서 복사한 연결 문자열 (비밀번호 포함)

     postgresql://postgres:your_password@db.xxxxx.supabase.co:5432/postgres
     

6. Add secret 클릭

4. Spaces 재빌드

환경 변수를 설정하면 Spaces가 자동으로 재빌드됩니다 (약 2-5분 소요).

5. 연결 확인

재빌드 완료 후:

1. 브라우저에서 다음 URL 접속:

   https://wiizm-soyailabs.hf.space/api/admin/database/status
   

2. 응답 확인:

   {
       "connected": true,
       "type": "PostgreSQL",  // ✅ PostgreSQL 확인
       "version": "PostgreSQL 15.x...",
       "config_count": 1,
       "user_count": 1
   }
   

Neon 설정 방법 (예시)

1. Neon 프로젝트 생성

1. https://neon.tech/ 접속 및 로그인
2. "Create a project" 클릭
3. 프로젝트 정보 입력:
   • Name: 원하는 프로젝트 이름
   • Region: 가장 가까운 지역 선택
4. "Create project" 클릭

2. 연결 정보 확인

프로젝트 생성 후:

1. 프로젝트 대시보드에서 Connection string 복사
   • 형식: postgresql://user:password@ep-xxxxx.region.aws.neon.tech/neondb
   • 또는 Connection Details에서 개별 정보 확인

3. Hugging Face Spaces에 환경 변수 설정

1. Hugging Face Spaces > Settings > Repository secrets
2. New secret 클릭
3. 다음 정보 입력:
   • Key: DATABASE_URL
   • Value: Neon 연결 문자열
4. Add secret 클릭

4. Spaces 재빌드 및 확인

위와 동일하게 재빌드 후 /api/admin/database/status로 확인

데이터 마이그레이션 (선택사항)

PostgreSQL로 전환하면 기존 SQLite 데이터는 자동으로 마이그레이션되지 않습니다. 필요시:

1. 기존 데이터 백업 (SQLite):

   # 로컬에서 실행
   sqlite3 instance/finance_analysis.db .dump > backup.sql
   

2. PostgreSQL로 복원 (복잡함, 수동 작업 필요)

참고: 대부분의 경우 새로 시작하는 것이 더 간단합니다. 사용자 계정과 설정만 다시 입력하면 됩니다.

문제 해결

PostgreSQL 연결 실패

1. 연결 문자열 확인:

   • 비밀번호에 특수문자가 있으면 URL 인코딩 필요
   • 예: @ → %40, # → %23

2. 방화벽 확인:

   • Supabase/Neon은 기본적으로 모든 IP 허용
   • 특정 IP만 허용하도록 설정했다면 Hugging Face IP 추가

3. 로그 확인:

   • Hugging Face Spaces > Logs 탭
   • [데이터베이스] PostgreSQL 연결 실패: ... 오류 메시지 확인

여전히 SQLite 사용 중

1. 환경 변수 확인:

   • Settings > Repository secrets에서 DATABASE_URL 존재 확인
   • 값이 올바른지 확인 (비밀번호 포함)

2. 재빌드 확인:

   • 환경 변수 변경 후 Spaces가 재빌드되었는지 확인
   • Settings > Build logs 확인

3. 코드 확인:

   • app/core/config.py에서 DATABASE_URL 환경 변수를 올바르게 읽는지 확인
   • (이미 구현되어 있음)

확인 체크리스트

PostgreSQL 전환 후 다음을 확인하세요:

• /api/admin/database/status에서 type: "PostgreSQL" 확인
• connected: true 확인
• Gemini API 키 저장 후 config_count 증가 확인
• 컨테이너 재시작 후에도 데이터 유지 확인

추가 정보

• Supabase 문서: https://supabase.com/docs/guides/database
• Neon 문서: https://neon.tech/docs
• PostgreSQL 연결 문자열 형식: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING