RAILWAY_POSTGRESQL_SETUP.md

# Railway PostgreSQL 설정 가이드

Railway에서 PostgreSQL 데이터베이스를 생성하고 Hugging Face Spaces에 연결하는 방법입니다.

## 1. Railway에서 PostgreSQL 서비스 생성

### 방법 1: 새 프로젝트에서 PostgreSQL 추가 (권장)

1. **Railway 대시보드 접속**
   - https://railway.app 접속 및 로그인

2. **새 프로젝트 생성**
   - 좌측 상단의 **"+ New Project"** 클릭
   - **"Deploy from GitHub repo"** 또는 **"Empty Project"** 선택
   - 프로젝트 이름 입력 (예: `soy-nv-ai-db`)

3. **PostgreSQL 서비스 추가**
   - 프로젝트 내에서 **"+ New"** 버튼 클릭
   - **"Database"** 선택
   - **"Add PostgreSQL"** 클릭
   - Railway가 자동으로 PostgreSQL 인스턴스를 생성합니다 (약 1-2분 소요)

### 방법 2: 기존 프로젝트에 PostgreSQL 추가

1. 기존 프로젝트 선택
2. **"+ New"** 버튼 클릭
3. **"Database"** > **"Add PostgreSQL"** 선택

## 2. PostgreSQL 연결 정보 확인

PostgreSQL 서비스가 생성되면:

1. **PostgreSQL 서비스 클릭**
   - 프로젝트 내에서 생성된 PostgreSQL 서비스를 클릭

2. **Variables 탭 확인**
   - 상단 메뉴에서 **"Variables"** 탭 클릭
   - 다음 환경 변수들이 자동으로 생성되어 있습니다:
     - `PGHOST`: 호스트 주소
     - `PGPORT`: 포트 번호 (기본값: 5432)
     - `PGDATABASE`: 데이터베이스 이름
     - `PGUSER`: 사용자 이름
     - `PGPASSWORD`: 비밀번호
     - `DATABASE_URL`: 전체 연결 문자열 ⭐ (이것을 사용합니다!)

3. **DATABASE_URL 복사**
   - `DATABASE_URL` 변수의 **값**을 복사합니다
   - 형식: `postgresql://postgres:password@hostname:port/railway`
   - 예시: `postgresql://postgres:abc123@containers-us-west-123.railway.app:5432/railway`

## 3. Hugging Face Spaces에 연결 정보 설정

### 3-1. Hugging Face Spaces 접속

1. https://huggingface.co/spaces 접속
2. 해당 Space 페이지로 이동 (예: `wiizm/soyailabs`)

### 3-2. 환경 변수 추가

1. **Settings 탭 클릭**
   - Space 페이지 상단의 **"Settings"** 탭 클릭

2. **Repository secrets 섹션으로 이동**
   - 좌측 메뉴에서 **"Repository secrets"** 클릭
   - 또는 페이지를 아래로 스크롤하여 **"Repository secrets"** 섹션 찾기

3. **새 환경 변수 추가**
   - **"New secret"** 버튼 클릭
   - 다음 정보 입력:
     - **Key**: `DATABASE_URL`
     - **Value**: Railway에서 복사한 `DATABASE_URL` 값 붙여넣기
       ```
       postgresql://postgres:password@hostname:port/railway
       ```
   - **"Add secret"** 버튼 클릭

4. **확인**
   - `DATABASE_URL`이 secrets 목록에 추가되었는지 확인

## 4. Spaces 재빌드 및 확인

### 4-1. 자동 재빌드

환경 변수를 추가하면 Hugging Face Spaces가 자동으로 재빌드를 시작합니다.

1. **Settings 탭에서 빌드 상태 확인**
   - 또는 **"Logs"** 탭에서 빌드 진행 상황 확인
   - 빌드 완료까지 약 2-5분 소요

### 4-2. 연결 확인

재빌드 완료 후:

**⚠️ 중요: 관리자 계정으로 로그인한 상태에서만 접근 가능합니다.**

1. **관리자 로그인**:
   - 먼저 애플리케이션에 관리자 계정으로 로그인합니다
   - 로그인하지 않은 상태에서는 접근할 수 없습니다

2. **브라우저에서 다음 URL 접속** (GET 요청):
   ```
   https://wiizm-soyailabs.hf.space/api/admin/database/status
   ```
   - ⚠️ **GET 메서드만 지원**: POST나 다른 메서드로 요청하면 "Method Not Allowed" 오류가 발생합니다
   - 브라우저 주소창에 직접 입력하거나, 개발자 도구에서 `fetch()` 사용 시 GET 요청인지 확인하세요

3. **또는 개발자 도구에서 확인**:
   - 브라우저 개발자 도구(F12) 열기
   - Console 탭에서 다음 명령 실행:
   ```javascript
   fetch('/api/admin/database/status', {
       method: 'GET',  // GET 메서드 명시
       credentials: 'include'  // 쿠키 포함 (로그인 세션)
   })
   .then(res => res.json())
   .then(data => console.log('DB 상태:', data));
   ```

4. **응답 확인**:
   ```json
   {
       "config_count": 1,
       "connected": true,
       "error": null,
       "table_count": 11,
       "test_query": "현재 시간: 2025-12-08 17:40:35.168889+00:00",
       "type": "PostgreSQL",
       "uri_masked": "postgresql://***@hopper.proxy.rlwy.net:15569/railway",
       "user_count": 1,
       "version": "PostgreSQL 17.7 (Debian 17.7-3.pgdg13+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) "
   }
   ```

3. **성공 확인 사항**:
   - ✅ `type: "PostgreSQL"` (SQLite가 아님)
   - ✅ `connected: true`
   - ✅ `version`에 PostgreSQL 버전 표시

## 5. 데이터베이스 테이블 자동 생성 확인

애플리케이션이 시작되면 자동으로 필요한 테이블들이 생성됩니다.

1. **Logs 탭 확인**:
   - `[데이터베이스] PostgreSQL 연결 성공!` 메시지 확인
   - `[데이터베이스] 테이블 생성 완료` 메시지 확인

2. **Railway에서 확인** (선택사항):
   - Railway 프로젝트 > PostgreSQL 서비스 > **"Data"** 탭
   - 생성된 테이블 목록 확인

## 6. 설정 저장 테스트

PostgreSQL 연결이 확인되면:

1. **관리자 페이지 접속**
   - https://wiizm-soyailabs.hf.space/admin/settings

2. **Gemini API 키 저장**
   - API 키 입력 후 저장

3. **저장 확인**
   - `/api/admin/database/status`에서 `config_count` 확인
   - `config_count`가 1 이상이면 저장 성공

4. **영구 저장 확인**
   - Spaces를 재시작하거나 업데이트해도
   - `/api/admin/database/status`에서 `config_count`가 유지되는지 확인

## 문제 해결

### Method Not Allowed 오류

**증상**: `/api/admin/database/status` 접속 시 "Method Not Allowed" 오류 발생

**원인**:
- 엔드포인트는 **GET 메서드만** 지원합니다
- POST, PUT, DELETE 등의 다른 메서드로 요청하면 오류가 발생합니다

**해결 방법**:

1. **브라우저 주소창에서 직접 접속**:
   - 브라우저 주소창에 URL을 직접 입력하면 자동으로 GET 요청이 됩니다
   - 예: `https://wiizm-soyailabs.hf.space/api/admin/database/status`

2. **개발자 도구에서 GET 메서드 명시**:
   ```javascript
   fetch('/api/admin/database/status', {
       method: 'GET',  // GET 명시
       credentials: 'include'
   })
   ```

3. **관리자 로그인 확인**:
   - 관리자 계정으로 로그인되어 있는지 확인
   - 로그인하지 않았거나 일반 사용자 계정이면 접근할 수 없습니다

4. **curl 명령어 사용 시**:
   ```bash
   curl -X GET https://wiizm-soyailabs.hf.space/api/admin/database/status
   ```
   - `-X GET` 옵션으로 GET 메서드 명시 (기본값이지만 명시하는 것이 안전)

### PostgreSQL 연결 실패

**증상**: `/api/admin/database/status`에서 `connected: false` 또는 `type: "SQLite"`

**해결 방법**:

1. **환경 변수 확인**:
   - Hugging Face Spaces > Settings > Repository secrets
   - `DATABASE_URL`이 올바르게 설정되었는지 확인
   - 값에 공백이나 줄바꿈이 없는지 확인

2. **연결 문자열 형식 확인**:
   - `postgresql://` 또는 `postgres://`로 시작해야 함
   - 비밀번호에 특수문자가 있으면 URL 인코딩 필요
     - `@` → `%40`
     - `#` → `%23`
     - `%` → `%25`
     - `&` → `%26`

3. **Railway 연결 정보 재확인**:
   - Railway > PostgreSQL 서비스 > Variables 탭
   - `DATABASE_URL` 값을 다시 복사하여 확인

4. **로그 확인**:
   - Hugging Face Spaces > Logs 탭
   - `[데이터베이스] PostgreSQL 연결 실패: ...` 오류 메시지 확인
   - 오류 메시지를 기반으로 문제 해결

### Railway 외부 연결 문제

**증상**: Railway에서 외부 연결이 안 되는 경우

**해결 방법**:

1. **TCP Proxy 확인**:
   - Railway는 기본적으로 TCP Proxy를 활성화합니다
   - PostgreSQL 서비스 > **"Connect"** 탭 확인
   - 외부 연결 정보 확인

2. **네트워크 요금 확인**:
   - Railway는 외부 연결 시 네트워크 송신량에 대한 요금이 부과될 수 있습니다
   - 사용량 모니터링: Railway 대시보드 > Usage 탭

### 여전히 SQLite 사용 중

**증상**: 환경 변수를 설정했는데도 `type: "SQLite"`로 표시됨

**해결 방법**:

1. **재빌드 확인**:
   - 환경 변수 변경 후 Spaces가 재빌드되었는지 확인
   - Settings > Build logs 확인

2. **환경 변수 이름 확인**:
   - 정확히 `DATABASE_URL`인지 확인 (대소문자 구분)
   - 다른 이름으로 설정하지 않았는지 확인

3. **코드 확인**:
   - `app/core/config.py`에서 환경 변수를 올바르게 읽는지 확인
   - (이미 구현되어 있음)

## Railway 추가 기능

### 데이터베이스 백업

1. **Railway 대시보드** > PostgreSQL 서비스
2. **"Backups"** 탭에서 백업 설정
3. 자동 백업 스케줄 설정 가능

### 데이터베이스 모니터링

1. **Railway 대시보드** > PostgreSQL 서비스
2. **"Metrics"** 탭에서 성능 모니터링
3. 연결 수, 쿼리 성능 등 확인 가능

### 데이터베이스 확장 기능

Railway는 다음 PostgreSQL 확장을 지원합니다:
- PostGIS (지리 공간 데이터)
- TimescaleDB (시계열 데이터)
- 기타 PostgreSQL 확장

필요시 Railway 문서를 참고하여 추가하세요.

## 비용 정보

- **Railway 무료 티어**: $5 크레딧/월
- **PostgreSQL**: 무료 티어에서 사용 가능
- **외부 연결**: 네트워크 송신량에 따라 요금 부과 가능
- **사용량 확인**: Railway 대시보드 > Usage 탭

## 참고 자료

- **Railway PostgreSQL 문서**: https://docs.railway.com/guides/postgresql
- **Railway 환경 변수**: https://docs.railway.com/develop/variables
- **PostgreSQL 연결 문자열**: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING

## 확인 체크리스트

PostgreSQL 설정 완료 후:

- [ ] Railway에서 PostgreSQL 서비스 생성 완료
- [ ] `DATABASE_URL` 환경 변수 복사 완료
- [ ] Hugging Face Spaces에 `DATABASE_URL` 환경 변수 추가 완료
- [ ] Spaces 재빌드 완료
- [ ] `/api/admin/database/status`에서 `type: "PostgreSQL"` 확인
- [ ] `connected: true` 확인
- [ ] Gemini API 키 저장 후 `config_count` 증가 확인
- [ ] Spaces 재시작 후에도 데이터 유지 확인

모든 항목이 체크되면 PostgreSQL 설정이 완료된 것입니다! 🎉