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. 응답 확인:
   ```json
   {
       "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):
   ```bash
   # 로컬에서 실행
   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